z_parameter: Main (#1157)

* main docs

* formatting and bss issues

* PR Suggestions

* missed enums

* better macros/enums

* restrictions improvement, still wip

* fix name, more common restriction patterns

* more restrictions cleanup

* rm comment

include/z64interface.h

@@ -4,6 +4,60 @@
 #include "ultra64.h"
 #include "z64view.h"
 
+typedef enum {
+    /* 0 */ A_BTN_STATE_0,
+    /* 1 */ A_BTN_STATE_1,
+    /* 2 */ A_BTN_STATE_2,
+    /* 3 */ A_BTN_STATE_3,
+    /* 4 */ A_BTN_STATE_4
+} AButtonState;
+
+typedef enum {
+    /* 0x00 */ DO_ACTION_ATTACK,
+    /* 0x01 */ DO_ACTION_CHECK,
+    /* 0x02 */ DO_ACTION_ENTER,
+    /* 0x03 */ DO_ACTION_RETURN,
+    /* 0x04 */ DO_ACTION_OPEN,
+    /* 0x05 */ DO_ACTION_JUMP,
+    /* 0x06 */ DO_ACTION_DECIDE,
+    /* 0x07 */ DO_ACTION_DIVE,
+    /* 0x08 */ DO_ACTION_FASTER,
+    /* 0x09 */ DO_ACTION_THROW,
+    /* 0x0A */ DO_ACTION_NONE,  // in do_action_static, the texture at this position is NAVI, however this value is in practice the "No Action" value
+    /* 0x0B */ DO_ACTION_CLIMB,
+    /* 0x0C */ DO_ACTION_DROP,
+    /* 0x0D */ DO_ACTION_DOWN,
+    /* 0x0E */ DO_ACTION_QUIT,
+    /* 0x0F */ DO_ACTION_SPEAK,
+    /* 0x10 */ DO_ACTION_NEXT,
+    /* 0x11 */ DO_ACTION_GRAB,
+    /* 0x12 */ DO_ACTION_STOP,
+    /* 0x13 */ DO_ACTION_PUTAWAY,
+    /* 0x14 */ DO_ACTION_REEL,
+    /* 0x15 */ DO_ACTION_INFO,
+    /* 0x16 */ DO_ACTION_WARP,
+    /* 0x17 */ DO_ACTION_SNAP,
+    /* 0x18 */ DO_ACTION_EXPLODE,
+    /* 0x19 */ DO_ACTION_DANCE,
+    /* 0x1A */ DO_ACTION_MARCH,
+    /* 0x1B */ DO_ACTION_1,
+    /* 0x1C */ DO_ACTION_2,
+    /* 0x1D */ DO_ACTION_3,
+    /* 0x1E */ DO_ACTION_4,
+    /* 0x1F */ DO_ACTION_5,
+    /* 0x20 */ DO_ACTION_6,
+    /* 0x21 */ DO_ACTION_7,
+    /* 0x22 */ DO_ACTION_8,
+    /* 0x23 */ DO_ACTION_CURL,
+    /* 0x24 */ DO_ACTION_SURFACE,
+    /* 0x25 */ DO_ACTION_SWIM,
+    /* 0x26 */ DO_ACTION_PUNCH,
+    /* 0x27 */ DO_ACTION_POUND,
+    /* 0x28 */ DO_ACTION_HOOK,
+    /* 0x29 */ DO_ACTION_SHOOT,
+    /* 0x2A */ DO_ACTION_MAX
+} DoAction;
+
 typedef enum {
     /*  0 */ MINIGAME_STATE_NONE,
     /*  1 */ MINIGAME_STATE_COUNTDOWN_SETUP_3,
@@ -39,6 +93,27 @@ typedef enum {
 #define PERFECT_LETTERS_NUM_LETTERS 8
 #define PERFECT_LETTERS_ANGLE_PER_LETTER (0x10000 / PERFECT_LETTERS_NUM_LETTERS)
 
+typedef enum {
+    /* 0 */ STORY_DMA_IDLE,
+    /* 1 */ STORY_DMA_LOADING,
+    /* 2 */ STORY_DMA_DONE
+} StoryLoadStatus;
+
+typedef enum {
+    /* 0 */ STORY_STATE_OFF,
+    /* 1 */ STORY_STATE_INIT,
+    /* 2 */ STORY_STATE_IDLE,
+    /* 3 */ STORY_STATE_DESTROY,
+    /* 4 */ STORY_STATE_SETUP_IDLE,
+    /* 5 */ STORY_STATE_FADE_OUT,
+    /* 6 */ STORY_STATE_FADE_IN
+} StoryState;
+
+typedef enum {
+    /* 0 */ STORY_TYPE_MASK_FESTIVAL,
+    /* 1 */ STORY_TYPE_GIANTS_LEAVING
+} StoryType;
+
 typedef struct {
     /* 0x000 */ View view;
     /* 0x168 */ Vtx* actionVtx;
@@ -47,17 +122,16 @@ typedef struct {
     /* 0x174 */ u8* doActionSegment;
     /* 0x178 */ u8* iconItemSegment;
     /* 0x17C */ u8* mapSegment;
-    /* 0x180 */ u8* unk_180;
-    /* 0x184 */ DmaRequest dmaRequest_184;
-    /* 0x1A4 */ DmaRequest dmaRequest_1A4;
-    /* 0x1C4 */ DmaRequest dmaRequest_1C4;
+    /* 0x180 */ u8* unk_180; // unused segment?
+    /* 0x184 */ DmaRequest dmaRequest;
+    /* 0x1A4 */ UNK_TYPE1 unk_1A4[0x40]; // likely 2 DmaRequest
     /* 0x1E4 */ OSMesgQueue loadQueue;
     /* 0x1FC */ OSMesg loadMsg;
     /* 0x200 */ Viewport viewport;
-    /* 0x210 */ s16 unk_210;
+    /* 0x210 */ s16 aButtonState;
     /* 0x212 */ u16 unk_212;
-    /* 0x214 */ u16 unk_214;
-    /* 0x218 */ f32 unk_218;
+    /* 0x214 */ u16 aButtonDoAction;
+    /* 0x218 */ f32 aButtonRoll;
     /* 0x21C */ s16 unk_21C;
     /* 0x21E */ s16 bButtonDoAction;
     /* 0x220 */ s16 unk_220;
@@ -74,7 +148,7 @@ typedef struct {
     /* 0x246 */ s16 heartsEnvG[2];
     /* 0x24A */ s16 heartsEnvB[2];
     /* 0x24E */ s16 health;
-    /* 0x250 */ s16 unkTimer;
+    /* 0x250 */ s16 healthTimer;
     /* 0x252 */ s16 lifeSizeChange;
     /* 0x254 */ s16 lifeSizeChangeDirection; // 1 means shrinking, 0 growing
     /* 0x256 */ s16 unk_256;
@@ -84,7 +158,7 @@ typedef struct {
     /* 0x25E */ u16 minigameHiddenPoints; // Points to add to the secondary set of minigame points not displayed. Reset to 0 every frame.
     /* 0x260 */ u16 minigameAmmo;
     /* 0x262 */ u16 minigameUnusedPoints; // Associated with other minigame points, unused
-    /* 0x264 */ s16 unk_264;
+    /* 0x264 */ s16 screenFillAlpha;
     /* 0x266 */ s16 aAlpha;
     /* 0x268 */ s16 bAlpha;
     /* 0x26A */ s16 cLeftAlpha;
@@ -116,27 +190,27 @@ typedef struct {
     /* 0x30A */ s16 perfectLettersColorTimer;
     /* 0x30C */ s16 perfectLettersTimer;
     struct {
-        /* 0x30E */ u8 unk_30E; // "h_gauge"
+        /* 0x30E */ u8 hGauge;
         /* 0x30F */ u8 bButton;
         /* 0x310 */ u8 aButton;
-        /* 0x311 */ u8 tradeItems;
-        /* 0x312 */ u8 unk_312;
-        /* 0x313 */ u8 unk_313;
-        /* 0x314 */ u8 unk_314;
+        /* 0x311 */ u8 tradeItems; // Includes deed trade quest, anju/kafei trade quest, bottles, and ocarina
+        /* 0x312 */ u8 songOfTime;
+        /* 0x313 */ u8 songOfDoubleTime;
+        /* 0x314 */ u8 invSongOfTime;
         /* 0x315 */ u8 songOfSoaring;
         /* 0x316 */ u8 songOfStorms;
-        /* 0x317 */ u8 unk_317;
-        /* 0x318 */ u8 pictographBox;
+        /* 0x317 */ u8 masks;
+        /* 0x318 */ u8 pictoBox;
         /* 0x319 */ u8 all;     // "another"; enables all item restrictions
     } restrictions; // size = 0xC
     /* 0x31A */ u8 storyState;
     /* 0x31B */ u8 storyType;
-    /* 0x31C */ u8 unk_31C;
-    /* 0x320 */ OSMesgQueue unk_320;
-    /* 0x338 */ OSMesg unk_338;
-    /* 0x33C */ void* unk_33C;
-    /* 0x340 */ u32 unk_340;
-    /* 0x344 */ u32 unk_344;
+    /* 0x31C */ u8 storyDmaStatus;
+    /* 0x320 */ OSMesgQueue storyMsgQueue;
+    /* 0x338 */ OSMesg storyMsgBuf;
+    /* 0x33C */ u8* storySegment;
+    /* 0x340 */ uintptr_t storyAddr;
+    /* 0x344 */ size_t storySize;
 } InterfaceContext; // size = 0x348
 
 #endif