Doc equips usage (inventory, current and player-specific constants) (#1142)

* Doc equips usage (inventory, current and player-specific constants)

* Improve some comments

* `currentSword`(`Item`) -> `currentSwordItemId`

* Comments on the right in `D_801261F8`

* Improve `sDebugSaveInventory.equipment` formatting with extra parentheses

* Use constants for `sNewSaveInventory.equipment`

* Run formatter

* Make comments in z64save.h header a single line even if very long

* `CHECK_OWNED_EQUIP_ALT`

* One more use of `CHECK_OWNED_EQUIP`

* `OWNED_EQUIP_FLAG`

* `OWNED_EQUIP_FLAG_ALT`

* Improve (?) giving sword by item id

* "half-byte" -> "nibble"

* Improve equips for setting kokiri sword

* Improve (?) checking boots by item id

* Improve (?) checking equips by item id

* Fixup one spot assuming `EQUIP_TYPE_SWORD == 0`

* Comments on the right in `sBootDListGroups`

include/macros.h

@@ -41,7 +41,15 @@
 
 #define ALL_EQUIP_VALUE(equip) ((s32)(gSaveContext.inventory.equipment & gEquipMasks[equip]) >> gEquipShifts[equip])
 #define CUR_EQUIP_VALUE(equip) ((s32)(gSaveContext.equips.equipment & gEquipMasks[equip]) >> gEquipShifts[equip])
-#define CHECK_OWNED_EQUIP(equip, value) ((gBitFlags[value] << gEquipShifts[equip]) & gSaveContext.inventory.equipment)
+#define OWNED_EQUIP_FLAG(equip, value) (gBitFlags[value] << gEquipShifts[equip])
+#define OWNED_EQUIP_FLAG_ALT(equip, value) ((1 << (value)) << gEquipShifts[equip])
+#define CHECK_OWNED_EQUIP(equip, value) (OWNED_EQUIP_FLAG(equip, value) & gSaveContext.inventory.equipment)
+#define CHECK_OWNED_EQUIP_ALT(equip, value) (gBitFlags[(value) + (equip) * 4] & gSaveContext.inventory.equipment)
+
+#define SWORD_EQUIP_TO_PLAYER(swordEquip) (swordEquip)
+#define SHIELD_EQUIP_TO_PLAYER(shieldEquip) (shieldEquip)
+#define TUNIC_EQUIP_TO_PLAYER(tunicEquip) ((tunicEquip) - 1)
+#define BOOTS_EQUIP_TO_PLAYER(bootsEquip) ((bootsEquip) - 1)
 
 #define CUR_UPG_VALUE(upg) ((s32)(gSaveContext.inventory.upgrades & gUpgradeMasks[upg]) >> gUpgradeShifts[upg])
 #define CAPACITY(upg, value) gUpgradeCapacities[upg][value]

include/z64item.h

@@ -2,12 +2,74 @@
 #define Z64ITEM_H
 
 typedef enum {
-    /* 0x00 */ EQUIP_SWORD,
-    /* 0x01 */ EQUIP_SHIELD,
-    /* 0x02 */ EQUIP_TUNIC,
-    /* 0x03 */ EQUIP_BOOTS
+    /* 0 */ EQUIP_TYPE_SWORD,
+    /* 1 */ EQUIP_TYPE_SHIELD,
+    /* 2 */ EQUIP_TYPE_TUNIC,
+    /* 3 */ EQUIP_TYPE_BOOTS,
+    /* 4 */ EQUIP_TYPE_MAX
 } EquipmentType;
 
+// `EquipInv*` enums are for Inventory.equipment (for example used in the `CHECK_OWNED_EQUIP` macro)
+
+typedef enum {
+    /* 0 */ EQUIP_INV_SWORD_KOKIRI,
+    /* 1 */ EQUIP_INV_SWORD_MASTER,
+    /* 2 */ EQUIP_INV_SWORD_BGS,
+    /* 3 */ EQUIP_INV_SWORD_BROKENGIANTKNIFE
+} EquipInvSword;
+
+typedef enum {
+    /* 0 */ EQUIP_INV_SHIELD_DEKU,
+    /* 1 */ EQUIP_INV_SHIELD_HYLIAN,
+    /* 2 */ EQUIP_INV_SHIELD_MIRROR
+} EquipInvShield;
+
+typedef enum {
+    /* 0 */ EQUIP_INV_TUNIC_KOKIRI,
+    /* 1 */ EQUIP_INV_TUNIC_GORON,
+    /* 2 */ EQUIP_INV_TUNIC_ZORA
+} EquipInvTunic;
+
+typedef enum {
+    /* 0 */ EQUIP_INV_BOOTS_KOKIRI,
+    /* 1 */ EQUIP_INV_BOOTS_IRON,
+    /* 2 */ EQUIP_INV_BOOTS_HOVER
+} EquipInvBoots;
+
+// `EquipValue*` enums are for ItemEquips.equipment (for example used in the `CUR_EQUIP_VALUE` macro)
+
+typedef enum {
+    /* 0 */ EQUIP_VALUE_SWORD_NONE,
+    /* 1 */ EQUIP_VALUE_SWORD_KOKIRI,
+    /* 2 */ EQUIP_VALUE_SWORD_MASTER,
+    /* 3 */ EQUIP_VALUE_SWORD_BGS,
+    /* 4 */ EQUIP_VALUE_SWORD_MAX
+} EquipValueSword;
+
+typedef enum {
+    /* 0 */ EQUIP_VALUE_SHIELD_NONE,
+    /* 1 */ EQUIP_VALUE_SHIELD_DEKU,
+    /* 2 */ EQUIP_VALUE_SHIELD_HYLIAN,
+    /* 3 */ EQUIP_VALUE_SHIELD_MIRROR,
+    /* 4 */ EQUIP_VALUE_SHIELD_MAX
+} EquipValueShield;
+
+typedef enum {
+    /* 0 */ EQUIP_VALUE_TUNIC_NONE,
+    /* 1 */ EQUIP_VALUE_TUNIC_KOKIRI,
+    /* 2 */ EQUIP_VALUE_TUNIC_GORON,
+    /* 3 */ EQUIP_VALUE_TUNIC_ZORA,
+    /* 4 */ EQUIP_VALUE_TUNIC_MAX
+} EquipValueTunic;
+
+typedef enum {
+    /* 0 */ EQUIP_VALUE_BOOTS_NONE,
+    /* 1 */ EQUIP_VALUE_BOOTS_KOKIRI,
+    /* 2 */ EQUIP_VALUE_BOOTS_IRON,
+    /* 3 */ EQUIP_VALUE_BOOTS_HOVER,
+    /* 4 */ EQUIP_VALUE_BOOTS_MAX
+} EquipValueBoots;
+
 typedef enum {
     /* 0x00 */ UPG_QUIVER,
     /* 0x01 */ UPG_BOMB_BAG,

include/z64player.h

@@ -6,6 +6,14 @@
 
 struct Player;
 
+typedef enum {
+    /* 0 */ PLAYER_SWORD_NONE,
+    /* 1 */ PLAYER_SWORD_KOKIRI,
+    /* 2 */ PLAYER_SWORD_MASTER,
+    /* 3 */ PLAYER_SWORD_BGS,
+    /* 4 */ PLAYER_SWORD_MAX
+} PlayerSword;
+
 typedef enum {
     /* 0x00 */ PLAYER_SHIELD_NONE,
     /* 0x01 */ PLAYER_SHIELD_DEKU,
@@ -22,13 +30,13 @@ typedef enum {
 } PlayerTunic;
 
 typedef enum {
-    /* 0x00 */ PLAYER_BOOTS_NORMAL,
+    /* 0x00 */ PLAYER_BOOTS_KOKIRI,
     /* 0x01 */ PLAYER_BOOTS_IRON,
     /* 0x02 */ PLAYER_BOOTS_HOVER,
     /* Values below are only relevant when setting regs in Player_SetBootData */
     /* 0x03 */ PLAYER_BOOTS_INDOOR,
     /* 0x04 */ PLAYER_BOOTS_IRON_UNDERWATER,
-    /* 0x05 */ PLAYER_BOOTS_NORMAL_CHILD,
+    /* 0x05 */ PLAYER_BOOTS_KOKIRI_CHILD,
     /* 0x06 */ PLAYER_BOOTS_MAX
 } PlayerBoots;
 
@@ -457,7 +465,7 @@ typedef void (*PlayerFuncA74)(struct GlobalContext*, struct Player*);
 typedef struct Player {
     /* 0x0000 */ Actor      actor;
     /* 0x014C */ s8         currentTunic; // current tunic from `PlayerTunic`
-    /* 0x014D */ s8         currentSword; // current sword Item ID
+    /* 0x014D */ s8         currentSwordItemId;
     /* 0x014E */ s8         currentShield; // current shield from `PlayerShield`
     /* 0x014F */ s8         currentBoots; // current boots from `PlayerBoots`
     /* 0x0150 */ s8         heldItemButton; // Button index for the item currently used

include/z64save.h

@@ -7,13 +7,13 @@
 typedef struct {
     /* 0x00 */ u8 buttonItems[4];
     /* 0x04 */ u8 cButtonSlots[3];
-    /* 0x08 */ u16 equipment;
+    /* 0x08 */ u16 equipment; // a mask where each nibble corresponds to a type of equipment `EquipmentType`, and each nibble is a piece `EquipValue*`
 } ItemEquips; // size = 0x0A
 
 typedef struct {
     /* 0x00 */ u8 items[24];
     /* 0x18 */ s8 ammo[16];
-    /* 0x28 */ u16 equipment;
+    /* 0x28 */ u16 equipment; // a mask where each nibble corresponds to a type of equipment `EquipmentType`, and each bit to an owned piece `EquipInv*`
     /* 0x2C */ u32 upgrades;
     /* 0x30 */ u32 questItems;
     /* 0x34 */ u8 dungeonItems[20];