Document Magic (zeldaret#1199)

* Magic docs WIP

* More docs, first round finished

* Better docs

* More renaming

* Simpler name

* Another small adjustment

* rm if(1)

* Better names again after in-game testing

* Change comments

* change comment

* Big rename based on all the suggestions

* Small touch-up

* More PR Suggestions

* RESTORE_IDLE -> RESET

* More docs

* Capitalization

* PR suggestions

* Make declaration consistent

* Health_ChangeBy (amount)

* PR Suggestions

* Missed one

* More PR Suggestions

* Change comment

* Add another clarity comment

* Discord discussions on `magicFillTarget`

* Comments

* grammar

* More comment clarity

* Another bad comment

* PR suggestions, improved comments

* One more comment

* one more thing

* bar -> meter

assets/xml/textures/parameter_static.xml

@@ -53,8 +53,8 @@
         <Texture Name="gAmmoDigit8Tex" OutName="ammo_digit_8" Format="ia8" Width="8" Height="8" Offset="0x37C0"/>
         <Texture Name="gAmmoDigit9Tex" OutName="ammo_digit_9" Format="ia8" Width="8" Height="8" Offset="0x3800"/>
         <Texture Name="gUnusedAmmoDigitHalfTex" OutName="unused_ammo_digit_half" Format="ia8" Width="16" Height="8" Offset="0x3840"/>
-        <Texture Name="gMagicBarEndTex" OutName="magic_bar_end" Format="ia8" Width="8" Height="16" Offset="0x38C0"/>
-        <Texture Name="gMagicBarMidTex" OutName="magic_bar_mid" Format="ia8" Width="24" Height="16" Offset="0x3940"/>
-        <Texture Name="gMagicBarFillTex" OutName="magic_bar_fill" Format="ia8" Width="8" Height="8" Offset="0x3AC0"/>
+        <Texture Name="gMagicMeterEndTex" OutName="magic_meter_end" Format="ia8" Width="8" Height="16" Offset="0x38C0"/>
+        <Texture Name="gMagicMeterMidTex" OutName="magic_meter_mid" Format="ia8" Width="24" Height="16" Offset="0x3940"/>
+        <Texture Name="gMagicMeterFillTex" OutName="magic_meter_fill" Format="ia8" Width="8" Height="8" Offset="0x3AC0"/>
     </File>
 </Root>

include/functions.h

@@ -1026,12 +1026,12 @@ s32 Inventory_ConsumeFairy(PlayState* play);
 void Interface_SetDoAction(PlayState* play, u16 action);
 void Interface_SetNaviCall(PlayState* play, u16 naviCallState);
 void Interface_LoadActionLabelB(PlayState* play, u16 action);
-s32 Health_ChangeBy(PlayState* play, s16 healthChange);
+s32 Health_ChangeBy(PlayState* play, s16 amount);
 void Rupees_ChangeBy(s16 rupeeChange);
 void Inventory_ChangeAmmo(s16 item, s16 ammoChange);
 void Magic_Fill(PlayState* play);
-void func_800876C8(PlayState* play);
-s32 func_80087708(PlayState* play, s16 arg1, s16 arg2);
+void Magic_Reset(PlayState* play);
+s32 Magic_RequestChange(PlayState* play, s16 amount, s16 type);
 void func_80088AA0(s16 arg0);
 void func_80088AF0(PlayState* play);
 void func_80088B34(s16 arg0);

include/regs.h

@@ -95,9 +95,9 @@
 #define R_A_ICON_Y                  XREG(19)
 #define R_A_ICON_X                  XREG(20)
 #define R_A_BTN_COLOR(i)            XREG(22 + i)
-#define R_MAGIC_BAR_SMALL_Y         XREG(48)
-#define R_MAGIC_BAR_X               XREG(49)
-#define R_MAGIC_BAR_LARGE_Y         XREG(50)
+#define R_MAGIC_METER_Y_HIGHER      XREG(48)
+#define R_MAGIC_METER_X             XREG(49)
+#define R_MAGIC_METER_Y_LOWER       XREG(50)
 #define R_MAGIC_FILL_X              XREG(51)
 #define R_ENV_LIGHT1_DIR(i)         cREG(3 + i)
 #define R_ENV_LIGHT2_DIR(i)         cREG(6 + i)

include/z64.h

@@ -610,7 +610,7 @@ typedef struct {
     /* 0x022A */ s16    beatingHeartOscillator;
     /* 0x022C */ s16    beatingHeartOscillatorDirection;
     /* 0x022E */ s16    unk_22E;
-    /* 0x0230 */ s16    unk_230;
+    /* 0x0230 */ s16    lensMagicConsumptionTimer; // When lens is active, 1 unit of magic is consumed every time the timer reaches 0
     /* 0x0232 */ s16    counterDigits[4]; // used for key and rupee counters
     /* 0x023A */ u8     numHorseBoosts;
     /* 0x023C */ u16    unk_23C;

include/z64save.h

@@ -4,6 +4,32 @@
 #include "ultra64.h"
 #include "z64math.h"
 
+typedef enum {
+    /* 0x0 */ MAGIC_STATE_IDLE, // Regular gameplay
+    /* 0x1 */ MAGIC_STATE_CONSUME_SETUP, // Sets the speed at which magic border flashes
+    /* 0x2 */ MAGIC_STATE_CONSUME, // Consume magic until target is reached or no more magic is available
+    /* 0x3 */ MAGIC_STATE_METER_FLASH_1, // Flashes border and freezes Dark Link
+    /* 0x4 */ MAGIC_STATE_METER_FLASH_2, // Flashes border and draws yellow magic to preview target consumption
+    /* 0x5 */ MAGIC_STATE_RESET, // Reset colors and return to idle
+    /* 0x6 */ MAGIC_STATE_METER_FLASH_3, // Flashes border with no additional behaviour
+    /* 0x7 */ MAGIC_STATE_CONSUME_LENS, // Magic slowly consumed by lens. 
+    /* 0x8 */ MAGIC_STATE_STEP_CAPACITY, // Step `magicCapacity` to full capacity
+    /* 0x9 */ MAGIC_STATE_FILL, // Add magic until magicFillTarget is reached.
+    /* 0xA */ MAGIC_STATE_ADD // Add requested magic
+} MagicState;
+
+typedef enum {
+    /* 0 */ MAGIC_CONSUME_NOW, // Consume Magic immediately without preview
+    /* 1 */ MAGIC_CONSUME_WAIT_NO_PREVIEW, // Sets consume target but waits to consume. No yellow magic preview to target consumption. Unused
+    /* 2 */ MAGIC_CONSUME_NOW_ALT, // Identical behaviour to MAGIC_CONSUME_NOW. Unused
+    /* 3 */ MAGIC_CONSUME_LENS, // Lens consumption
+    /* 4 */ MAGIC_CONSUME_WAIT_PREVIEW, // Sets consume target but waits to consume. Draws yellow magic to target consumption
+    /* 5 */ MAGIC_ADD // Sets a target to add magic
+} MagicChangeType;
+
+#define MAGIC_NORMAL_METER 0x30
+#define MAGIC_DOUBLE_METER (2 * MAGIC_NORMAL_METER)
+
 typedef struct {
     /* 0x00 */ u8 buttonItems[4];
     /* 0x04 */ u8 cButtonSlots[3];
@@ -87,14 +113,14 @@ typedef struct {
     /* 0x002C */ s16 n64ddFlag;
     /* 0x002E */ s16 healthCapacity; // "max_life"
     /* 0x0030 */ s16 health; // "now_life"
-    /* 0x0032 */ s8 magicLevel;
-    /* 0x0033 */ s8 magic;
+    /* 0x0032 */ s8 magicLevel; // 0 for no magic/new load, 1 for magic, 2 for double magic
+    /* 0x0033 */ s8 magic; // current magic available for use
     /* 0x0034 */ s16 rupees;
     /* 0x0036 */ u16 swordHealth;
     /* 0x0038 */ u16 naviTimer;
-    /* 0x003A */ u8 magicAcquired;
+    /* 0x003A */ u8 isMagicAcquired;
     /* 0x003B */ char unk_3B[0x01];
-    /* 0x003C */ u8 doubleMagic;
+    /* 0x003C */ u8 isDoubleMagicAcquired;
     /* 0x003D */ u8 doubleDefense;
     /* 0x003E */ u8 bgsFlag;
     /* 0x003F */ u8 ocarinaGameRoundNum;
@@ -156,11 +182,11 @@ typedef struct {
     /* 0x13EA */ u16 unk_13EA; // also alpha type?
     /* 0x13EC */ u16 unk_13EC; // alpha type counter?
     /* 0x13EE */ u16 unk_13EE; // previous alpha type?
-    /* 0x13F0 */ s16 unk_13F0; // magic related
-    /* 0x13F2 */ s16 unk_13F2; // magic related
-    /* 0x13F4 */ s16 unk_13F4; // magic related
-    /* 0x13F6 */ s16 unk_13F6; // magic related
-    /* 0x13F8 */ s16 unk_13F8; // magic related
+    /* 0x13F0 */ s16 magicState; // determines magic meter behavior on each frame
+    /* 0x13F2 */ s16 prevMagicState; // used to resume the previous state after adding or filling magic
+    /* 0x13F4 */ s16 magicCapacity; // maximum magic available
+    /* 0x13F6 */ s16 magicFillTarget; // target used to fill magic. Target can either be full capacity (Magic_Fill, magic upgrades), or the saved magic amount (loading a file, game over)
+    /* 0x13F8 */ s16 magicTarget; // target for magic to step to when adding or consuming magic
     /* 0x13FA */ u16 eventInf[4]; // "event_inf"
     /* 0x1402 */ u16 mapIndex; // intended for maps/minimaps but commonly used as the dungeon index
     /* 0x1404 */ u16 minigameState;

src/code/z_actor.c

@@ -1950,7 +1950,7 @@ void func_80030488(PlayState* play) {
 void Actor_DisableLens(PlayState* play) {
     if (play->actorCtx.lensActive) {
         play->actorCtx.lensActive = false;
-        func_800876C8(play);
+        Magic_Reset(play);
     }
 }
 

src/code/z_construct.c

@@ -18,7 +18,7 @@ void func_801109B0(PlayState* play) {
     interfaceCtx->unk_1FA = interfaceCtx->unk_261 = interfaceCtx->unk_1FC = 0;
     interfaceCtx->unk_1EC = interfaceCtx->unk_1EE = interfaceCtx->unk_1F0 = 0;
     interfaceCtx->unk_22E = 0;
-    interfaceCtx->unk_230 = 16;
+    interfaceCtx->lensMagicConsumptionTimer = 16;
     interfaceCtx->unk_1F4 = 0.0f;
     interfaceCtx->unk_228 = XREG(95);
     interfaceCtx->minimapAlpha = 0;
@@ -382,9 +382,9 @@ void func_80111070(void) {
     XREG(45) = 36;
     XREG(46) = 16;
     XREG(47) = 8;
-    R_MAGIC_BAR_SMALL_Y = 34;
-    R_MAGIC_BAR_X = 18;
-    R_MAGIC_BAR_LARGE_Y = 42;
+    R_MAGIC_METER_Y_HIGHER = 34;
+    R_MAGIC_METER_X = 18;
+    R_MAGIC_METER_Y_LOWER = 42;
     R_MAGIC_FILL_X = 26;
     XREG(52) = 0;
     XREG(53) = 1;

src/code/z_elf_message.c

@@ -54,7 +54,7 @@ u32 ElfMessage_CheckCondition(ElfMessage* msg) {
                     return ((msg->byte0 & 1) == 1) ==
                            (CHECK_QUEST_ITEM(msg->byte3 - ITEM_MEDALLION_FOREST + QUEST_MEDALLION_FOREST) != 0);
                 case (ELF_MSG_CONDITION_MAGIC << 4):
-                    return ((msg->byte0 & 1) == 1) == (((void)0, gSaveContext.magicAcquired) != 0);
+                    return ((msg->byte0 & 1) == 1) == (((void)0, gSaveContext.isMagicAcquired) != 0);
             }
     }
 

src/code/z_kaleido_setup.c

@@ -15,7 +15,8 @@ void KaleidoSetup_Update(PlayState* play) {
     if (pauseCtx->state == 0 && pauseCtx->debugState == 0 && play->gameOverCtx.state == GAMEOVER_INACTIVE &&
         play->transitionTrigger == TRANS_TRIGGER_OFF && play->transitionMode == TRANS_MODE_OFF &&
         gSaveContext.cutsceneIndex < 0xFFF0 && gSaveContext.nextCutsceneIndex < 0xFFF0 && !Play_InCsMode(play) &&
-        play->shootingGalleryStatus <= 1 && gSaveContext.unk_13F0 != 8 && gSaveContext.unk_13F0 != 9 &&
+        play->shootingGalleryStatus <= 1 && gSaveContext.magicState != MAGIC_STATE_STEP_CAPACITY &&
+        gSaveContext.magicState != MAGIC_STATE_FILL &&
         (play->sceneNum != SCENE_BOWLING || !Flags_GetSwitch(play, 0x38))) {
 
         if (CHECK_BTN_ALL(input->cur.button, BTN_L) && CHECK_BTN_ALL(input->press.button, BTN_CUP)) {