Introduction to Link Cable

Introduction to Link Cable

Link Cable is a cross-server data sync mod for multi-server Fabric networks running Cobblemon. It keeps player state — both the Cobblemon-side data and the underlying Minecraft player data — moving cleanly between servers, with backed-up persistence, hot-cache handoffs, restore tooling, and a proper admin surface for inspecting what is actually stored.

If you run a network where players move between backends — a hub server, a survival server, a competitive battle server, etc. — Link Cable is what makes their party, PC, inventory, XP, hunger, and almost any other player-attached mod data travel with them.

What Link Cable Syncs

Link Cable owns six sync lanes per player. Four are Cobblemon-side, one is the per-player Molang state, and one is the broader player-core lane that covers vanilla Minecraft player data plus most third-party mod attachments.

Cobblemon lanes:

• Party — the active 6-Pokémon team (PlayerPartyCollection in Cobblemon’s storage)
• PC — every box in the storage system (PCCollection)
• General — Cobblemon’s general player data: battle counts, current state, etc. (PlayerDataCollection). This is Cobblemon’s general player data, not the Minecraft player data — those live in the player-core lane below.
• Pokedex — caught/seen state and progress (PokeDexCollection)

Per-player state:

• Molang — per-player Molang variables Cobblemon and other mods stash on the player

Player-core (the broad one):

• Player-core — a NBT-allowlist snapshot of the Minecraft player. Every transfer carries:

  • Inventory (all 41 slots) and the currently selected hotbar slot
  • Ender chest contents
  • Health and absorption
  • Full hunger state — food level, saturation, exhaustion, tick timer
  • Full XP state — level, progress, total XP, XP seed
  • Game mode and previous game mode
  • Player abilities — fly speed, walk speed, may-fly, instabuild, etc.
  • Recipe book contents and settings
  • Score and credits-seen flag
  • Cardinal Components data — anything other mods stored on the player via the Cardinal Components API
  • Fabric Attachment API data — anything other mods stored on the player via Fabric’s modern attachment API

The last two are the broad ones. Many mods that attach data to the player on Fabric 1.21 do so through one of those two APIs, and that data carries along automatically through the player-core lane. In practice this means most “modded player progression” — accessories slots, levelable systems, custom currencies, mod-tracked stats — syncs across servers without Link Cable having to know anything specific about the mod.

All six lanes are written together as a single versioned snapshot per player. Transfers move the whole snapshot at once; partial states aren’t visible to other servers.

Architecture in One Picture

Link Cable installs as a single jar on every backend server. One backend is the orchestrator; the rest are participants. There’s no separate proxy plugin — the proxy stays vanilla Velocity (or whatever you’re using) and Link Cable handles cross-server coordination at the backend level.

              ┌──────────────────┐
              │     Velocity     │  (or BungeeCord, Waterfall, etc.)
              └────────┬─────────┘
                       │
        ┌──────────────┼──────────────┐
        │              │              │
┌───────▼──────┐ ┌─────▼────┐ ┌───────▼──────┐
│  hub server  │ │ survival │ │ battles svr  │   (every backend has Link Cable installed)
│ ORCHESTRATOR │ │ partic.  │ │ participant  │
└───────┬──────┘ └─────┬────┘ └───────┬──────┘
        │              │              │
        └──────┬───────┴──────┬───────┘
               │              │
         ┌─────▼────┐    ┌────▼───┐
         │  Redis   │    │ Mongo  │
         └──────────┘    └────────┘

Redis holds the distributed locks, owner-epoch fencing, and hot-cache that make per-player handoffs safe. MongoDB holds the canonical snapshot data through Ceremony’s persistence layer. Cobblemon stays on its own normal Mongo-backed setup — Link Cable uses Cobblemon’s own collections as canonical storage for the Pokémon-side lanes (party, PC, general, Pokedex) and stores its own data alongside for ownership state, backups, player-core sync, Molang sync, and migration metadata.

Key Features

Cross-server ownership and handoff control : Every player has a single canonical owner server at any moment. Transfers go through a distributed lock and an owner-epoch fence so stale writers can’t land state after ownership has moved. Fast-switch joins retry through a short settle window instead of immediately kicking the player.

Backups and restore : Full-snapshot backups for every sync lane, with create, list, browse, inspect, restore, delete, export, and import. Restores are offline-only and automatically take a pre-restore backup before overwriting state. Backup chat output is clickable and there are ConfigGUI-backed browsers for inspecting party and PC contents inside a backup.

Player-core sync : A wide allowlist of Minecraft player NBT travels with the player — inventory, ender chest, full health/hunger/XP state, abilities, recipe book, game mode, plus anything other mods have attached via Cardinal Components or the Fabric Attachment API. UltraSync migration imports into this same lane (covering the subset UltraSync stored).

Molang sync : Per-player Molang variables stay attached to the player across servers. Anything stored under Cobblemon’s player Molang surface is included.

UltraSync migration : One command imports every UltraSync player record straight from MongoDB into the player-core lane. Existing Cobblemon data on the target side is preserved; pre-migration backups are taken automatically.

Pasture safety : Tethered Pokémon can’t be moved, swapped, sorted, or party-withdrawn out of the PC, with snapshot caching from the source server so they stay resolvable on the destination after transfer.

Admin command surface : Player and backup autocomplete (including offline players), clickable backup output, restore safety guards, and an opt-in dev tooling section for forced transfers, mutate-bounce tests, state audit, and pasture audit on staging networks.

What You Need

On every backend server:

• Minecraft 1.21.1 (Fabric)
• Java 21+
• Cobblemon (compatible build)
• Ceremony (provides the persistence layer)
• Fabric API
• Fabric Language Kotlin
• The Link Cable jar

Network services:

• A Redis deployment that every backend can reach
• A MongoDB deployment that every backend can reach (Cobblemon already needs this)

Recommended:

• LuckPerms / fabric-permissions-api for the linkcable.command.admin node

Where To Go Next

1. Installation — drop the jar in, point everything at the same Redis and Mongo, pick an orchestrator.
2. Configuration — the full config.json field reference.
3. Validation Checklist — the test pass to run before opening the network.
4. Backups — the backup command suite.
5. UltraSync Migration — importing existing UltraSync player data.
6. Beta and Production Rollout — the hardening notes for production traffic.

Stage on a two-server test setup first

Reproducing real network flows on two staging backends behind a proxy before opening to players catches almost every config and timing issue you’d otherwise hit in production. Validate one full transfer cycle, one backup/restore round-trip, and (if applicable) one UltraSync test record before pointing live players at the config.