Mirror pokeemerald PR#1329 & PR#1335 to pokeruby

The `externalReservedData` field has been split up into `externalEventData` and `externalEventFlags`, which have their own structs. The new structs deal with interconnectivity between external games/peripherals and RS. US & JP Colosseum Bonus Discs', Colosseum and XD's, Pokémon Channel's, and PokémonBox: Ruby & Sapphire's interactions with these fields has been documented.

The `giftRibbon#` fields in `PokemonSubstruct3` have also been renamed to their appropriate ribbons, and commented with distribution info if applicable. All relevant constants and functions dealing with the Pokémon data structure were renamed with these changes in mind.

3 files changed, 64 insertions, 26 deletions

diff --git a/include/constants/pokemon.h b/include/constants/pokemon.h
index 5d1539179..f5a9f4a6e 100644
--- a/include/constants/pokemon.h
+++ b/include/constants/pokemon.h
@@ -73,14 +73,14 @@
 #define MON_DATA_VICTORY_RIBBON    69
 #define MON_DATA_ARTIST_RIBBON     70
 #define MON_DATA_EFFORT_RIBBON     71
-#define MON_DATA_GIFT_RIBBON_1     72
-#define MON_DATA_GIFT_RIBBON_2     73
-#define MON_DATA_GIFT_RIBBON_3     74
-#define MON_DATA_GIFT_RIBBON_4     75
-#define MON_DATA_GIFT_RIBBON_5     76
-#define MON_DATA_GIFT_RIBBON_6     77
-#define MON_DATA_GIFT_RIBBON_7     78
-#define MON_DATA_FATEFUL_ENCOUNTER 79
+#define MON_DATA_MARINE_RIBBON     72
+#define MON_DATA_LAND_RIBBON       73
+#define MON_DATA_SKY_RIBBON        74
+#define MON_DATA_COUNTRY_RIBBON    75
+#define MON_DATA_NATIONAL_RIBBON   76
+#define MON_DATA_EARTH_RIBBON      77
+#define MON_DATA_WORLD_RIBBON      78
+#define MON_DATA_EVENT_LEGAL       79
 #define MON_DATA_KNOWN_MOVES       80
 #define MON_DATA_RIBBON_COUNT      81
 #define MON_DATA_RIBBONS           82
diff --git a/include/global.h b/include/global.h
index d207f1cd4..e5114c396 100644
--- a/include/global.h
+++ b/include/global.h
@@ -585,6 +585,50 @@ struct ContestWinner
     /*0x16*/ u8 trainerName[8];
 };
 
+// For external event data storage. The majority of these may have never been used.
+struct ExternalEventData
+{
+    u8 unknownExternalDataFields1[7]; // if actually used, may be broken up into different fields.
+    u32 unknownExternalDataFields2:8;
+    u32 currentPokeCoupons:24; // PokéCoupons stored by Pokémon Colosseum and XD from Mt. Battle runs. Earned PokéCoupons are also added to totalEarnedPokeCoupons. Colosseum/XD caps this at 9,999,999, but will read up to 16,777,215.
+    u32 gotGoldPokeCouponTitleReward:1; // Master Ball from Jp Colosseum Bonus Disc; for reaching 30,000 totalEarnedPokeCoupons
+    u32 gotSilverPokeCouponTitleReward:1; // Light Ball Pikachu from JP Colosseum Bonus Disc; for reaching 5000 totalEarnedPokeCoupons
+    u32 gotBronzePokeCouponTitleReward:1; // PP Max from JP Colosseum Bonus Disc; for reaching 2500 totalEarnedPokeCoupons
+    u32 receivedAgetoCelebi:1; // from JP Colosseum Bonus Disc
+    u32 unknownExternalDataFields3:4;
+    u32 totalEarnedPokeCoupons:24; // Used by the JP Colosseum bonus disc. Determines PokéCoupon rank to distribute rewards. Unread in International games. Colosseum/XD caps this at 9,999,999.
+    u8 unknownExternalDataFields4[5]; // if actually used, may be broken up into different fields.
+} __attribute__((packed)); /*size = 0x14*/
+
+// For external event flags. The majority of these may have never been used.
+struct ExternalEventFlags
+{
+    u8 usedBoxRS:1; // Set by Pokémon Box: Ruby & Sapphire; denotes whether this save has connected to it and triggered the free False Swipe Swablu Egg giveaway.
+    u8 boxRSEggsUnlocked:2; // Set by Pokémon Box: Ruby & Sapphire; denotes the number of Eggs unlocked from deposits; 1 for ExtremeSpeed Zigzagoon (at 100 deposited), 2 for Pay Day Skitty (at 500 deposited), 3 for Surf Pichu (at 1500 deposited)
+    u8 padding:5;
+    u8 unknownFlag1;
+    u8 receivedGCNJirachi; // Both the US Colosseum Bonus Disc and PAL/AUS Pokémon Channel use this field. One cannot receive a WISHMKR Jirachi and CHANNEL Jirachi with the same savefile.
+    u8 unknownFlag3;
+    u8 unknownFlag4;
+    u8 unknownFlag5;
+    u8 unknownFlag6;
+    u8 unknownFlag7;
+    u8 unknownFlag8;
+    u8 unknownFlag9;
+    u8 unknownFlag10;
+    u8 unknownFlag11;
+    u8 unknownFlag12;
+    u8 unknownFlag13;
+    u8 unknownFlag14;
+    u8 unknownFlag15;
+    u8 unknownFlag16;
+    u8 unknownFlag17;
+    u8 unknownFlag18;
+    u8 unknownFlag19;
+    u8 unknownFlag20;
+
+} __attribute__((packed));/*size = 0x15*/
+
 // there should be enough flags for all 412 slots
 // each slot takes up 8 flags
 // if the value is not divisible by 8, we need to account for the reminder as well
@@ -667,16 +711,10 @@ struct SaveBlock1 /* 0x02025734 */
     /*0x2EFC*/ struct ContestWinner museumPortraits[5];
     /*0x2F9C*/ struct DayCare daycare;
     /*0x30B8*/ struct LinkBattleRecord linkBattleRecords[5];
-    struct {
-        /*0x3108*/ u8 unknown1[8];
-        /*0x3110*/ u8 giftRibbons[11];
-        /*0x311B*/ u8 unknown2[8];
-        /*0x3123*/ u32 currentPokeCoupons;
-        /*0x3127*/ u32 totalEarnedPokeCoupons;
-        /*0x312B*/ u8 unknown3[6];
-        /*0x3131*/ u8 receivedWishmakerJirachi;
-        /*0x3132*/ u8 unknown4[18];
-    } __attribute__((packed)) externalReservedData;
+    /*0x3108*/ u8 filler_3108[8];
+    /*0x3110*/ u8 giftRibbons[11];
+    /*0x311B*/ struct ExternalEventData externalEventData;
+    /*0x312F*/ struct ExternalEventFlags externalEventFlags;
     /*0x3144*/ struct Roamer roamer;
     /*0x3160*/ struct EnigmaBerry enigmaBerry;
     /*0x3690*/ struct RamScript ramScript;
diff --git a/include/pokemon.h b/include/pokemon.h
index c8e7ce719..d2ab1335c 100644
--- a/include/pokemon.h
+++ b/include/pokemon.h
@@ -111,14 +111,14 @@ struct PokemonSubstruct3
     /*0x0A*/ u32 victoryRibbon:1;
     /*0x0A*/ u32 artistRibbon:1;
     /*0x0A*/ u32 effortRibbon:1;
-    /*0x0A*/ u32 giftRibbon1:1;
-    /*0x0A*/ u32 giftRibbon2:1;
-    /*0x0A*/ u32 giftRibbon3:1;
-    /*0x0A*/ u32 giftRibbon4:1;
-    /*0x0B*/ u32 giftRibbon5:1;
-    /*0x0B*/ u32 giftRibbon6:1;
-    /*0x0B*/ u32 giftRibbon7:1;
-    /*0x0B*/ u32 fatefulEncounter:5; // unused in Ruby/Sapphire, but the high bit must be set for Mew/Deoxys to obey in FR/LG/Emerald
+    /*0x0A*/ u32 marineRibbon:1; // never distributed
+    /*0x0A*/ u32 landRibbon:1; // never distributed
+    /*0x0A*/ u32 skyRibbon:1; // never distributed
+    /*0x0A*/ u32 countryRibbon:1; // distributed during Pokémon Festa '04 and '05 to tournament winners
+    /*0x0B*/ u32 nationalRibbon:1;
+    /*0x0B*/ u32 earthRibbon:1;
+    /*0x0B*/ u32 worldRibbon:1; // distributed during Pokémon Festa '04 and '05 to tournament winners
+    /*0x0B*/ u32 eventLegal:5; // high bit controls Mew & Deoxys obedience in FRLGE; if set, Pokémon is a fateful encounter in FRLG & Gen 4+ summary screens; set for in-game event island legendaries, some distributed events, and Pokémon from XD: Gale of Darkness.
 };
 
 union PokemonSubstruct