This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Link compatibility

Link compatibility is selected and enforced by the launcher. This page is for mod and cart authors who need to prepare a linkable release. Players can follow Link Play without reading these implementation details.

The launcher rule

Link play supports the approved cart choices shown by the launcher:

• a vanilla cart; or
• a sealed custom cart prepared for link play.

Mods included in a sealed custom cart are part of that approved setup. Do not enable arbitrary loose mods alongside it. A custom cart is a named, version-pinned bundle whose contents the launcher can identify; it is not the same thing as turning on an installed mod from the ordinary mod list. If a player has enabled mods outside the selected cart, return to the launcher, choose the intended sealed cart, and retry with those loose mods disabled.

The launcher is the source of the player-facing compatibility decision. It may refuse a session before a room opens when the two selected carts do not meet the current link policy. Read and share the exact refusal text when troubleshooting rather than guessing from a mod list.

For a sealed custom cart, both sides must use the same cart identity and published contents. If the launcher reports cart differs, cart version differs, or cart hash differs, import the same sealed cart release on both machines. The selected cart must also target the game chosen in the wizard.

Preparing a custom cart

Use Cartkit to create the cart and pin its release inputs. Keep the cart's id and version stable for the release you ask two players to use. Test the finished .g1rcart by importing it into the launcher and starting link play with the cart selected. The launcher should identify the cart on both sides before either player starts the room.

Cart authors should document three things in the cart README:

1. the exact cart version each player should import;
2. whether the cart is intended for battle, trade, or both; and
3. that the cart must remain sealed and loose mods must be disabled for link play.

Do not tell players to copy a mod list by hand. If a mod is part of the approved sealed custom cart, pin it in the cart and publish the cart as a unit.

What mod authors need to know

An ordinary mod release is not a link permission. A content change may be perfectly safe in single-player and still be unsuitable for a linkable cart. If your work should be included in a custom cart, publish a versioned release with a clear README and test that cart through the launcher. Put the player instructions in the cart documentation; keep registry and hook details in their specialist guides.

Online rooms boot a clean simulation. A vanilla room turns every mod off except verified translations; a cart room loads only the cart’s pinned mods. What counts as staying out of the way:

Game	What stays on online
Red, Blue, Yellow, Gold, Silver, Crystal	A mod with "language": true, "affects_link": false, no permissions, that only writes text, strings or font and subscribes no hooks or events.
FireRed, LeafGreen, Ruby, Sapphire, Emerald	Any mod with no permissions, no hooks, no events and no migrations whose writes are cosmetic: text, rom_text, strings, font, sprites, palettes, icons, battle_anims, render_pipelines, music, sfx, cries, audio, map_songs, battle_sprite_scales, transitions, or a patch of only a name, description or dex entry on pokemon, moves and items.

The language flag is only a claim; the engine checks the ops the mod actually registered. The affects_link manifest field and the fingerprint machinery are implementation details and are not a way for players to make loose mods linkable.

What the profile pins

Every lobby and room carries a profile, compared field by field. The launcher greys out a row and prints the first field that differs:

Text	Meaning
engine differs	Gen 1, 2 and 3 battle engines do not mix in one room
engine version differs	the two builds are different releases
mod api differs	the two builds have a different mod API major (currently 3)
arena kind differs	one side is vanilla, the other a cart
ruleset differs	the host-dealt rulebook is not the same
data differs	the merged game data hash differs
cart differs, cart version differs, cart hash differs	the sealed cart is not the same release

Link protocol and mod API are separate numbers: the link protocol (currently 3) is the wire handshake, and the mod API (currently 3) is the manifest api level. Both are stamped in src/core/Version.lua. On the local-network handshake, mismatched link protocols or generations are refused outright, and mismatched engine releases may still trade but not battle.

API 3 mods and link

Putting "api": 3 in a manifest does not change any of this. A portable mod is judged by what it registers, on whichever generation the room runs.

Troubleshooting

• If link play is unavailable, select the launcher’s approved vanilla or sealed custom cart and disable all loose mods before retrying.
• If the two sides disagree, compare the cart id, version, and seal state shown by the launcher. Reimport the published sealed cart if either side has a different file.
• If a sealed custom cart cannot start, use Install required mods on its cart page, then retry. Do not break the cart seal merely to make a link session start; record the missing or mismatched pin and fix the cart installation.
• If the launcher shows a refusal message, capture the exact text and the selected carts. The message is more useful than a general claim that the network or a loose mod is at fault.

Observing link play

The launcher and room screen provide the player-visible state: ONLINE or OFFLINE, the selected cart, the room code, and the room status. Use the room’s Copy control to share the code. Events such as link.connected, link.ended, trade.completed, and pokemon.received remain useful to instrumentation, but they do not override the launcher’s cart policy.

Scope note

This guide intentionally documents the current launcher/cart rule. Older notes that describe direct UDP host addresses, arbitrary loose-mod pairing, or player-facing fingerprint verdicts are not a supported setup path. Local network linking from the in-game Cable Club on Red, Blue and Yellow still exists; it negotiates by comparing both sides’ fingerprints. Verify any future compatibility text against the launcher before publishing it.

Check and recover

The author checkpoint is a sealed cart that imports on both machines and is identified by the launcher before the room starts. If the launcher reports a cart mismatch, publish or reimport the same cart release and retry; do not ask players to repair compatibility by copying loose mod lists.