Adding Support for Connectivity with Other Hacks Whilst Maintaining Connectivity with Vanilla

Credits to Citrus Bolt for this. Without them, this wouldn't be possible.

When making a hack, you may or may not want to preserve link features. This tutorial will walk you through how to add a new identifier that gets sent through the link whilst also being able to keep compatibility with vanilla Pokémon games.

First, we want to open include/constants/global.h and add the following defines:

+ // Version ID modifiers used for identifying unofficial games.
+ // The idea is that each unofficial game will have its own number they can use in conjunction with one of the official origin game IDs
+ // so that they do not have to requisition a new ID for every project
+ #define MODIFIER_NONE             0 // official games
+ #define MODIFIER_HELIODOR         1 // 3-1 is Heliodor
+ #define MODIFIER_DX               2 // 4-2 is FireRed DX and 5-2 is LeafGreen DX
+ #define MODIFIER_CITRUS_BOLT      3 // Reserved for on-the-fly loading CrystalDust into this system
+ #define MODIFIER_JAIZU            4 // 3-4 is Emerald Cross
+ #define MODIFIER_TOBA             222 // Reserved by AquaticTyphoon#7935 for their TOBA region.

These are constant values for the different possible IDs we're gonna use. 1 and 2 have already been reserved but the tutorial will allow for 255 different IDs. Think of a number and define it like the following:

#define VERSION_MODIFIER (MODIFIER_DX)

For this tutorial, I will be using MODIFIER_DX but as mentioned previously, you can use any value you want.

So next, we want to open include/link.h and include/link_rfu.h as we will be editing a couple structs. In include/link.h, we need to find struct LinkPlayer and make the following change:

struct LinkPlayer
{
    /* 0x00 */ u16 version;
    /* 0x02 */ u16 lp_field_2;
    /* 0x04 */ u32 trainerId;
    /* 0x08 */ u8 name[PLAYER_NAME_LENGTH + 1];
    /* 0x10 */ u8 progressFlags; // (& 0x0F) is hasNationalDex, (& 0xF0) is hasClearedGame
-    /* 0x11 */ u8 neverRead;
+    /* 0x11 */ u8 versionModifier;
    /* 0x12 */ u8 progressFlagsCopy;
    /* 0x13 */ u8 gender;
    /* 0x14 */ u32 linkType;
    /* 0x18 */ u16 id; // battler id in battles
    /* 0x1A */ u16 language;
};

And in include/link_rfu.h, we need to find struct __attribute__((packed, aligned(2))) RfuGameData and make the following change:

struct __attribute__((packed, aligned(2))) RfuGameData
{
    struct RfuGameCompatibilityData compatibility;
    u8 partnerInfo[RFU_CHILD_MAX]; 
    u16 tradeSpecies:10;
    u16 tradeType:6;
    u8 activity:7;
    u8 startedActivity:1;
    u8 playerGender:1;
    u8 tradeLevel:7;
-    u8 padding;
+    u8 versionModifier;
};

If you notice, we now have a versionModifier in both structs which we will be using to signal hacks that the game is in fact an unofficial game.

Next, we want to open src/link.c and find the function labelled InitLocalLinkPlayer and make the following change:

static void InitLocalLinkPlayer(void)
{
    gLocalLinkPlayer.trainerId = gSaveBlock2Ptr->playerTrainerId[0] | (gSaveBlock2Ptr->playerTrainerId[1] << 8) | (gSaveBlock2Ptr->playerTrainerId[2] << 16) | (gSaveBlock2Ptr->playerTrainerId[3] << 24);
    StringCopy(gLocalLinkPlayer.name, gSaveBlock2Ptr->playerName);
    gLocalLinkPlayer.gender = gSaveBlock2Ptr->playerGender;
    gLocalLinkPlayer.linkType = gLinkType;
    gLocalLinkPlayer.language = gGameLanguage;
    gLocalLinkPlayer.version = gGameVersion + 0x4000;
+    gLocalLinkPlayer.versionModifier = VERSION_MODIFIER;
    gLocalLinkPlayer.lp_field_2 = 0x8000;
    gLocalLinkPlayer.progressFlags = IsNationalPokedexEnabled();
    if (FlagGet(FLAG_IS_CHAMPION))
    {
        gLocalLinkPlayer.progressFlags |= 0x10;
    }
}

Here, VERSION_MODIFIER is our specific number we set in include/constants/global.h. In that same file (src/link.c), go to the function labelled ProcessRecvCmds, find the following and change:

if ((linkPlayer->version & 0xFF) == VERSION_RUBY || (linkPlayer->version & 0xFF) == VERSION_SAPPHIRE)
                        {
    linkPlayer->progressFlagsCopy = 0;
-    linkPlayer->neverRead = 0;
    linkPlayer->progressFlags = 0;
}

This removes the reference to linkPlayer->neverRead, which was changed to our new versionModifier label. Don't worry, that byte is written to but never read hence it being named neverRead.

Now, we need to open src/link_rfu_3 and find the function named InitHostRFUtgtGnameand make changes as follows:

void InitHostRfuGameData(struct RfuGameData *data, u8 activity, bool32 startedActivity, s32 partnerInfo)
{
    s32 i;

    for (i = 0; i < (s32)ARRAY_COUNT(data->compatibility.playerTrainerId); i++)
        data->compatibility.playerTrainerId[i] = gSaveBlock2Ptr->playerTrainerId[i];

    for (i = 0; i < RFU_CHILD_MAX; i++)
    {
        data->partnerInfo[i] = partnerInfo;
        partnerInfo >>= 8; // Each element is 1 byte
    }
    data->playerGender = gSaveBlock2Ptr->playerGender;
    data->activity = activity;
    data->started = started;
+    data->versionModifier = VERSION_MODIFIER;
    data->compatibility.language = GAME_LANGUAGE;
    data->compatibility.version = GAME_VERSION;
    data->compatibility.hasNews = FALSE;
    data->compatibility.hasCard = FALSE;
    data->compatibility.unknown = FALSE;
    data->compatibility.isChampion = FlagGet(FLAG_IS_CHAMPION);
    data->compatibility.hasNationalDex = IsNationalPokedexEnabled();
    data->compatibility.gameClear = FlagGet(FLAG_SYS_GAME_CLEAR);
}

Now, our game will send our versionModifier ID through both wireless and cable link. Now, we need to make a few edits to the trainer card. This is probably the most difficult step in this tutorial so follow carefully.

Okay so, we need to open include/trainer_card.h and find struct TrainerCard. In that struct, make the following change:

struct TrainerCard
{
    /*0x00*/ u8 gender;
    /*0x01*/ u8 stars;
    /*0x02*/ bool8 hasPokedex;
    /*0x03*/ bool8 caughtAllHoenn;
    /*0x04*/ bool8 hasAllPaintings;
    /*0x06*/ u16 hofDebutHours;
    /*0x08*/ u16 hofDebutMinutes;
    /*0x0A*/ u16 hofDebutSeconds;
    /*0x0C*/ u16 caughtMonsCount;
    /*0x0E*/ u16 trainerId;
    /*0x10*/ u16 playTimeHours;
    /*0x12*/ u16 playTimeMinutes;
    /*0x14*/ u16 linkBattleWins;
    /*0x16*/ u16 linkBattleLosses;
    /*0x18*/ u16 battleTowerWins;
    /*0x1A*/ u16 battleTowerStraightWins;
    /*0x1C*/ u16 contestsWithFriends;
    /*0x1E*/ u16 pokeblocksWithFriends;
    /*0x20*/ u16 pokemonTrades;
    /*0x24*/ u32 money;
    /*0x28*/ u16 easyChatProfile[TRAINER_CARD_PROFILE_LENGTH];
    /*0x30*/ u8 playerName[PLAYER_NAME_LENGTH + 1];
    /*0x38*/ u8 version;
    /*0x3A*/ bool16 linkHasAllFrontierSymbols;
    /*0x3C*/ union {
                u32 berryCrush;
                u32 frontier;
             } linkPoints; // This field is used differently by FRLG vs Emerald
    /*0x40*/ u32 unionRoomNum;
    /*0x44*/ u8 filler[8];
    /*0x4C*/ bool8 shouldDrawStickers; // FRLG only
    /*0x4D*/ u8 unused;
    /*0x4E*/ u8 monIconTint; // FRLG only
    /*0x4F*/ u8 facilityClass;
    /*0x50*/ u8 stickers[TRAINER_CARD_STICKER_TYPES]; // FRLG only
+    /*0x53*/ u8 versionModifier;
    /*0x54*/ u16 monSpecies[PARTY_SIZE]; // FRLG only
             // Note: Link players use linkHasAllFrontierSymbols, not the field below,
             // which they use for a Wonder Card flag id instead (see CreateTrainerCardInBuffer)
    /*0x60*/ bool16 hasAllFrontierSymbols;
    /*0x62*/ u16 frontierBP;
};

This is so the game can use the versionModifier value when loading the trainer card. Next, find the definition of CopyTrainerCardData and change it to the following:

void CopyTrainerCardData(struct TrainerCard *dst, struct TrainerCard *src, u8 gameVersion, u8 versionModifier);

Okay, now we actually need to use that new byte! Open src/trainer_card.c and find the functions CopyTrainerCardData, TrainerCard_GenerateCardForLinkPlayer and TrainerCard_GenerateCardForPlayer. In CopyTrainerCardData, make the following changes:

- void CopyTrainerCardData(struct TrainerCard *dst, struct TrainerCard *src, u8 gameVersion)
+ void CopyTrainerCardData(struct TrainerCard *dst, struct TrainerCard *src, u8 gameVersion, u8 versionModifier)
{
    memset(dst, 0, sizeof(struct TrainerCard));
    dst->version = gameVersion;

-    switch (VersionToCardType(gameVersion))
+    switch (VersionToCardType(gameVersion, versionModifier))
    {
    case CARD_TYPE_FRLG:
        memcpy(dst, src, 0x60);
        break;
    case CARD_TYPE_RS:
        memcpy(dst, src, 0x38);
        break;
    case CARD_TYPE_EMERALD:
        memcpy(dst, src, 0x60);
        dst->linkPoints.frontier = 0;
        dst->hasAllFrontierSymbols = src->linkHasAllFrontierSymbols;
        dst->frontierBP = *((u16*)&src->linkPoints.frontier);
        break;
    }
}

In TrainerCard_GenerateCardForLinkPlayer, make the following changes:

static void TrainerCard_GenerateCardForLinkPlayer(struct TrainerCard *trainerCard)
{
    memset(trainerCard, 0, sizeof(struct TrainerCard));
    trainerCard->version = GAME_VERSION;
+    trainerCard->versionModifier = VERSION_MODIFIER;
-    SetPlayerCardData(trainerCard, CARD_TYPE_EMERALD);
+    SetPlayerCardData(trainerCard, VersionToCardType(GAME_VERSION, VERSION_MODIFIER));
    trainerCard->hasAllSymbols = HasAllFrontierSymbols();
    trainerCard->frontierBP = gSaveBlock2Ptr->frontier.cardBattlePoints;
    if (trainerCard->hasAllSymbols)
        trainerCard->stars++;

    if (trainerCard->gender == FEMALE)
        trainerCard->facilityClass = gLinkPlayerFacilityClasses[(trainerCard->trainerId % NUM_FEMALE_LINK_FACILITY_CLASSES) + NUM_MALE_LINK_FACILITY_CLASSES];
    else
        trainerCard->facilityClass = gLinkPlayerFacilityClasses[trainerCard->trainerId % NUM_MALE_LINK_FACILITY_CLASSES];
}

In TrainerCard_GenerateCardForPlayer, make the following changes:

void TrainerCard_GenerateCardForPlayer(struct TrainerCard *trainerCard)
{
    memset(trainerCard, 0, sizeof(struct TrainerCard));
    trainerCard->version = GAME_VERSION;
+    trainerCard->versionModifier = VERSION_MODIFIER;
-    SetPlayerCardData(trainerCard, CARD_TYPE_EMERALD);
+    SetPlayerCardData(trainerCard, VersionToCardType(GAME_VERSION, VERSION_MODIFIER));
    trainerCard->hasAllFrontierSymbols = HasAllFrontierSymbols();
    trainerCard->frontierBP = gSaveBlock2Ptr->frontier.cardBattlePoints;
    if (trainerCard->hasAllFrontierSymbols)
        trainerCard->stars++;

    if (trainerCard->gender == FEMALE)
        trainerCard->facilityClass = gLinkPlayerFacilityClasses[(trainerCard->trainerId % NUM_FEMALE_LINK_FACILITY_CLASSES) + NUM_MALE_LINK_FACILITY_CLASSES];
    else
        trainerCard->facilityClass = gLinkPlayerFacilityClasses[trainerCard->trainerId % NUM_MALE_LINK_FACILITY_CLASSES];
}

Now, we need to go to the function GetSetCardType. You can use custom cardtype IDs but for demonstration purposes, we're gonna use the vanilla ones with one example. So in GetSetCardType, make the following change:

static u8 GetSetCardType(void)
{
    if (sData == NULL)
    {
        if (gGameVersion == VERSION_FIRE_RED || gGameVersion == VERSION_LEAF_GREEN)
            return CARD_TYPE_FRLG;
        else if (gGameVersion == VERSION_EMERALD)
            return CARD_TYPE_EMERALD;
        else
            return CARD_TYPE_RS;
    }
    else
    {
        if (sData->trainerCard.version == VERSION_FIRE_RED || sData->trainerCard.version == VERSION_LEAF_GREEN)
        {
            sData->isHoenn = FALSE;
            if (sData->trainerCard.versionModifier == MODIFIER_DX)
                return CARD_TYPE_EMERALD;
            else
                return CARD_TYPE_FRLG;
        }
        else if (sData->trainerCard.version == VERSION_EMERALD)
        {
            sData->isHoenn = TRUE;
            return CARD_TYPE_EMERALD;
        }
        else
        {
            sData->isHoenn = TRUE;
            return CARD_TYPE_RS;
        }
    }
}

Of course, CARD_TYPE_EMERALD uses different gfx and stuff to CARD_TYPE_FRLG but it was simply to demonstrate how versionModifier could be used in that function. Okay, now we need to go the function VersionToCardType and make the following changes:

- static u8 VersionToCardType(u8 version)
+ static u8 VersionToCardType(u8 version, u8 versionModifier)
{
    if (version == VERSION_FIRE_RED || version == VERSION_LEAF_GREEN)
-        return CARD_TYPE_FRLG;
+    {
+        if (versionModifier == MODIFIER_DX)
+            return CARD_TYPE_EMERALD;
+        else
+            return CARD_TYPE_FRLG;
+    }
    else if (version == VERSION_EMERALD)
        return CARD_TYPE_EMERALD;
    else
        return CARD_TYPE_RS;
}

Same reasoning behind the GetSetCardType changes.

There are some static declarations in src/trainer_card.c. We need to change VersionToCardType's declaration which is static u8 VersionToCardType(u8);, we need to change it to static u8 VersionToCardType(u8, u8);

Next, we need to edit a couple of functions that call CopyTrainerCardData. These changes are required to get version modifier value of the game you're linking to for their trainer card.

In src/cable_club.c, go to Task_LinkupAwaitTrainerCardData and make the following change:

static void Task_LinkupAwaitTrainerCardData(u8 taskId)
{
    u8 index;

    if (CheckLinkErrored(taskId) == TRUE)
        return;

    if (GetBlockReceivedStatus() != GetSavedLinkPlayerCountAsBitFlags())
        return;

    for (index = 0; index < GetLinkPlayerCount(); index++)
    {
-        CopyTrainerCardData(&gTrainerCards[index], (struct TrainerCard *)gBlockRecvBuffer[index], gLinkPlayers[index].version);
+        CopyTrainerCardData(&gTrainerCards[index], (struct TrainerCard *)gBlockRecvBuffer[index], gLinkPlayers[index].version, gLinkPlayers[index].versionModifier);
    }

    SetSuppressLinkErrorMessage(FALSE);
    ResetBlockReceivedFlags();
    FinishLinkup(&gSpecialVar_Result, taskId);
}

And lastly, we need to go to Task_ExchangeCards and make a similar change:

static void Task_ExchangeCards(u8 taskId)
{
    switch (gTasks[taskId].data[0])
    {
    case 0:
        if (GetMultiplayerId() == 0)
            SendBlockRequest(BLOCK_REQ_SIZE_100);
        gTasks[taskId].data[0]++;
        break;
    case 1:
        if (GetBlockReceivedStatus() == GetLinkPlayerCountAsBitFlags())
        {
            s32 i;
            u16 *recvBuff;

            for (i = 0; i < GetLinkPlayerCount(); i++)
            {
                recvBuff = gBlockRecvBuffer[i];
-                CopyTrainerCardData(&gTrainerCards[i], (struct TrainerCard *)recvBuff, gLinkPlayers[i].version);
+                CopyTrainerCardData(&gTrainerCards[i], (struct TrainerCard *)recvBuff, gLinkPlayers[i].version, gLinkPlayers[i].versionModifier);
            }

            if (GetLinkPlayerCount() == 2)
            {
                // Note: hasAllFrontierSymbols is a re-used field.
                // Here it is set by CreateTrainerCardInBuffer.
                // If the player has a saved Wonder Card and it is the same Wonder Card
                // as their partner then mystery gift stats are enabled.
                recvBuff = gBlockRecvBuffer[GetMultiplayerId() ^ 1];
                MysteryGift_TryEnableStatsByFlagId(((struct TrainerCard *)recvBuff)->hasAllFrontierSymbols);
            }
            else
            {
                MysteryGift_DisableStats();
            }

            ResetBlockReceivedFlags();
            DestroyTask(taskId);
        }
        break;
    }
}

With that, the version modifier stuff should be getting checked and being used when it should be.

Once I can get around to it, I'll be updating this tutorial so it will show how to add new card types and show how to update the player graphics for the games you're linking in both the overworld and in battle. But for now, this is all I have. If I didn't mess anything up, your game should now use its own unique identifier when linking!