document game.h

asm/beanstalkSubtask.s

@@ -37,7 +37,7 @@ sub_08019698: @ 0x08019698
 	bl SetLocalFlagByBank
 	ldrh r0, [r4]
 	ldrh r1, [r4, #2]
-	bl LoadCutsceneRoom
+	bl LoadAuxiliaryRoom
 	ldr r5, _0801972C @ =gRoomControls
 	ldrh r0, [r4, #6]
 	ldrh r1, [r5, #0xa]

asm/code_0805436C.s

@@ -138,7 +138,7 @@ sub_08054974: @ 0x08054974
 	beq _080549BC
 	ldrb r0, [r6, #2]
 	ldrb r1, [r6, #3]
-	bl LoadCutsceneRoom
+	bl LoadAuxiliaryRoom
 	b _080549CE
 	.align 2, 0
 _080549B0: .4byte gUnk_080FE320

include/entity.h

@@ -9,7 +9,7 @@
 #define MAX_ENTITIES 71
 
 /** Kinds of Entity's supported by the game. */
-enum EntityKind {
+typedef enum {
     PLAYER = 1,      /**< There is only one id assigned to the Player kind.
                       * The player Entity shares much of its code with LTTP GBA, however the game only supports
                       * one player Entity active at a time, assigned to the global #gPlayerEntity.
@@ -32,16 +32,16 @@ enum EntityKind {
                       * Examples: drawing clouds, ezlo hints, playing cutscenes.
                       * Updates independently of other entities, and does not add to maximum entity count.
                       */
-};
+} EntityKind;
 
 /** Entity flags. */
-enum EntityFlags {
+typedef enum {
     ENT_DID_INIT = 0x1, /**< Graphics and other data loaded. */
     ENT_SCRIPTED = 0x2, /**< Execute in a scripted environment. */
     ENT_DELETED = 0x10, /**< Queue deletion next frame. */
     ENT_PERSIST = 0x20, /**< Persist between rooms. */
     ENT_COLLIDE = 0x80, /**< Collide with other Entity's. */
-};
+} EntityFlags;
 
 /** Priority level to determine what events will block an Entity from updating. */
 typedef enum {
@@ -56,20 +56,20 @@ typedef enum {
 } Priority;
 
 /** Animation state. */
-enum AnimationState {
+typedef enum {
     IdleNorth = 0x0, /**< Idle facing north. */
     IdleEast = 0x2,  /**< Idle facing east. */
     IdleSouth = 0x4, /**< Idle facing south. */
     IdleWest = 0x6,  /**< Idle facing west. */
-};
+} AnimationState;
 
 /** Direction. */
-enum Direction {
+typedef enum {
     DirectionNorth = 0x00, /**< North. */
     DirectionEast = 0x08,  /**< East. */
     DirectionSouth = 0x10, /**< South. */
     DirectionWest = 0x18,  /**< West. */
-};
+} Direction;
 
 typedef struct {
     void* entity1;
@@ -509,3 +509,4 @@ extern u8 gManagerCount;
 ///@}
 
 #endif // ENTITY_H
+// clang-format on

include/game.h

@@ -4,61 +4,259 @@
 #include "global.h"
 #include "area.h"
 
+/**
+ * Change the light level of the room.
+ *
+ * @param level The new light level.
+ */
 void ChangeLightLevel(s32 level);
+
+/**
+ * Set the dislayed popup state
+ *
+ * @param type The popup type.
+ * @param choice_idx The choice index.
+ */
 void SetPopupState(u32 type, u32 choice_idx);
 
+/**
+ * Check if an area is overworld (not dungeon or inside).
+ *
+ * @param area The area to check.
+ * @return True if the area is overworld.
+ */
 bool32 CheckAreaOverworld(u32 area);
+
+/**
+ * Check if the current area is overworld.
+ *
+ * @return True if the current area is overworld.
+ */
 bool32 AreaIsOverworld(void);
+
+/**
+ * Check if the current area is a dungeon.
+ *
+ * @return True if the current area is a dungeon.
+ */
 bool32 AreaIsDungeon(void);
+
+/**
+ * Check if the current area has enemies.
+ *
+ * @return True if the current area has enemies.
+ */
 bool32 AreaHasEnemies(void);
+
+/**
+ * Check if the current area has no enemies.
+ *
+ * @return True if the current area has no enemies.
+ */
 bool32 AreaHasNoEnemies(void);
+
+/**
+ * Check if the current area has a map
+ *
+ * @return True if the current area has a map.
+ */
 bool32 AreaHasMap(void);
+
+/**
+ * Check if current area has keys.
+ *
+ * @return True if the current area has keys.
+ */
 bool32 AreaHasKeys(void);
 
 #ifndef EU
-// This function was introduced to allow warping from indoor areas (palace of winds).
+/**
+ * This function was introduced to allow warping from indoor areas (palace of winds).
+ *
+ * @return True if the current area allows warping.
+ */
 u32 AreaAllowsWarp(void);
 
-// related to a music bug?
+/**
+ * Related to a music bug?
+ */
 void sub_08052878(void);
 #endif
 
 void sub_080526F8(s32 a1);
+
+/**
+ * Check if the current dungeon has a map item.
+ *
+ * @return True if the current dungeon has a map item.
+ */
 bool32 HasDungeonMap(void);
+
+/**
+ * Check if the current dungeon has a compass item.
+ *
+ * @return True if the current dungeon has a compass item.
+ */
 bool32 HasDungeonCompass(void);
+
+/**
+ * Check if the current dungeon has a big key item.
+ *
+ * @return True if the current dungeon has a big key item.
+ */
 bool32 HasDungeonBigKey(void);
+
+/**
+ * Check if the current dungeon has a small key item.
+ *
+ * @return True if the current dungeon has a small key item.
+ */
 bool32 HasDungeonSmallKey(void);
 
+/**
+ * @brief Check if item is a sword.
+ *
+ * @param item The item to check.
+ * @return True if the item is a sword.
+ */
 bool32 ItemIsSword(u32 item);
+
+/**
+ * Check if item is a shield.
+ *
+ * @return True if the item is a shield.
+ */
 bool32 ItemIsShield(u32 item);
+
+/**
+ * @brief Get the index of the bottle containing the specified item.
+ *
+ * @param item The item to check.
+ * @return Bottle index, or 0 if the item is not in a bottle.
+ */
 u32 GetBottleContaining(u32 item);
+
+/**
+ * Put an item in A or B slot.
+ *
+ * @param item The item to put.
+ */
 void PutItemOnSlot(u32 item);
-s32 GetItemPrice(u32 item);
+
-u32 GetSaleItemConfirmMessageID(u32 item);
+/**
+ * Force equip an item.
+ *
+ * @param item The item to equip.
+ * @param slot The slot to equip the item in.
+ */
 void ForceEquipItem(u32 item, u32 slot);
 
+/**
+ * Get item price.
+ *
+ * @param item The item to get the price of.
+ * @return The price of the item.
+ */
+s32 GetItemPrice(u32 item);
+
+/**
+ * Get the item purchase enquiry message.
+ *
+ * @param item The item to get the message for.
+ * @return The message index.
+ */
+u32 GetSaleItemConfirmMessageID(u32 item);
+
+/**
+ * Automatically load overworld graphics groups.
+ */
 void LoadGfxGroups(void);
-void LoadCutsceneRoom(u32 room, u32 area);
+/**
+ * Load an auxiliary room (no player present).
+ *
+ * @param area Area index.
+ * @param room Room index.
+ */
+void LoadAuxiliaryRoom(u32 area, u32 room);
+
+/**
+ * Initialize a loaded room.
+ */
 void InitRoom(void);
+
+/**
+ * Initialize a parachute room.
+ */
 void InitParachuteRoom(void);
 
+/**
+ * Register a manager for room changes.
+ *
+ * @param mgr Manager to register.
+ * @param onEnter Room enter callback.
+ * @param onExit Room exit callback.
+ */
 void RegisterTransitionManager(void* mgr, void (*onEnter)(void*), void (*onExit)(void*));
+
+/**
+ * Call the room exit callback.
+ */
 void RoomExitCallback(void);
 
+/**
+ * Restore the game task from a subtask.
+ *
+ * @param a1
+ */
 void RestoreGameTask(u32 a1);
 
+/**
+ * Check if an Ezlo message can be displayed.
+ *
+ * @return True if an Ezlo message can be displayed.
+ */
 bool32 CanDispEzloMessage(void);
+
+/**
+ * Display an Ezlo message.
+ */
 void DisplayEzloMessage(void);
 
+/**
+ * Set the player's world map position.
+ *
+ * @param area Area index.
+ * @param room Room index.
+ * @param x X position.
+ * @param y Y position.
+ */
 void SetWorldMapPos(u32 area, u32 room, u32 x, u32 y);
+
+/**
+ * Set the player's dungeon map position.
+ *
+ * @param area Area index.
+ * @param room Room index.
+ * @param x X position.
+ * @param y Y position.
+ */
 void SetDungeonMapPos(u32 area, u32 room, u32 x, u32 y);
 
 /**
- * @brief Get bank offset for area
+ * Get flag bank offset for area
+ *
+ * @param idx Area index.
+ * @return Flag bank offset.
  */
 u32 GetFlagBankOffset(u32 idx);
 
+/**
+ * Retrieve information about the current room.
+ *
+ * @return RoomResInfo object.
+ */
 RoomResInfo* GetCurrentRoomInfo(void);
+
 void sub_08052EA0(void);
 void sub_08053250(void);
 void sub_080533CC(void);
@@ -67,14 +265,16 @@ void sub_08053494(void);
 void sub_080534AC(void);
 void InitBiggoronTimer(void);
 
-enum {
+/** Game tasks states */
+typedef enum {
     GAMETASK_TRANSITION, /* transition from fileselect task */
     GAMETASK_INIT,
     GAMETASK_MAIN,
     GAMETASK_EXIT, /* gameover task or reset */
-};
+} EGameTaskState;
 
-enum {
+/** game task main substates */
+typedef enum {
     GAMEMAIN_INITROOM,
     GAMEMAIN_CHANGEROOM,
     GAMEMAIN_UPDATE,
@@ -83,12 +283,10 @@ enum {
     GAMEMAIN_BARRELUPDATE, /* barrel in deepwood shrine */
     GAMEMAIN_RESERVED,
     GAMEMAIN_SUBTASK,
-};
+} EGameMainState;
 
-/**
+/** Subtasks override the game task for short periods */
- * @brief Subtasks override the game task for short periods
+typedef enum {
- */
-enum {
     SUBTASK_EXIT,
     SUBTASK_PAUSEMENU,
     SUBTASK_EXIT2,
@@ -100,9 +298,13 @@ enum {
     SUBTASK_WORLDEVENT,
     SUBTASK_FASTTRAVEL,
     SUBTASK_LOCALMAPHINT,
-};
+} ESubtask;
 
 typedef void(Subtask)(void);
+
+/** @name Subtask entrypoints */
+///@{
+/** Subtask entrypoint. */
 Subtask Subtask_Exit;
 Subtask Subtask_PauseMenu;
 Subtask Subtask_Exit;
@@ -114,5 +316,6 @@ Subtask Subtask_FigurineMenu;
 Subtask Subtask_WorldEvent;
 Subtask Subtask_FastTravel;
 Subtask Subtask_LocalMapHint;
+///@}
 
 #endif // GAME_H

include/main.h

@@ -3,11 +3,16 @@
 
 #include "global.h"
 
+/** File signature */
 #define SIGNATURE 'MCZ3'
+/** Maximum message speed. */
 #define MAX_MSG_SPEED 3
+/** Number of save slots */
 #define NUM_SAVE_SLOTS 3
+/** Maximum brightness. */
 #define MAX_BRIGHTNESS 3
 
+/** Supported game languages. */
 typedef enum {
     LANGUAGE_JP,
     LANGUAGE_EN,
@@ -24,36 +29,44 @@ typedef enum {
 #define GAME_LANGUAGE LANGUAGE_JP
 #endif
 
-enum {
+/** Program tasks. */
-    TASK_TITLE,
+typedef enum {
-    TASK_FILE_SELECT,
+    TASK_TITLE,       /**< Title task. This is the first task to be entered. */
-    TASK_GAME,
+    TASK_FILE_SELECT, /**< File selection task. */
-    TASK_GAMEOVER,
+    TASK_GAME,        /**< Gameplay task. Overworld, menus, cutscenes are all contained here. */
-    TASK_STAFFROLL,
+    TASK_GAMEOVER,    /**< Gameover task. */
-    TASK_DEBUG,
+    TASK_STAFFROLL,   /**< Staffroll task. Only accessible through the script played during the game ending. */
-};
+    TASK_DEBUG,       /**< Debug task. Inaccessible in normal gameplay. */
+} Task;
 
-enum {
+/** System sleep status. */
+typedef enum {
     DEFAULT,
     SLEEP,
-};
+} SleepStatus;
 
+/**
+ * Main system structure.
+ */
 typedef struct {
     vu8 interruptFlag;
     u8 sleepStatus;
-    u8 task;
+    u8 task;     /**< Current #Task. */
-    u8 state;
+    u8 state;    /**< State of the current #Task. */
-    u8 substate;
+    u8 substate; /**< Substate of the current #Task. */
     u8 field_0x5;
-    u8 muteAudio;
+    u8 muteAudio; /**< Mute audio. */
     u8 field_0x7;
-    u8 pauseFrames;
+    u8 pauseFrames;   /**< Number of frames to pause. */
-    u8 pauseCount;
+    u8 pauseCount;    /**< Number of pauses to make. */
-    u8 pauseInterval;
+    u8 pauseInterval; /**< Number of frames to play between each pause. */
     u8 pad;
-    union SplitHWord ticks;
+    union SplitHWord ticks; /**< Current time. */
 } Main;
 
+/**
+ * HUD structure.
+ */
 typedef struct {
     /*0x00*/ u8 nextToLoad;
     /*0x01*/ u8 _1;
@@ -69,34 +82,62 @@ typedef struct {
 } UI;
 static_assert(sizeof(UI) == 0x3b4);
 
-extern Main gMain;
+extern Main gMain;       /**< Main instance. */
-extern UI gUnk_02032EC0;
+extern UI gUnk_02032EC0; /**< UI instance. */
 
 /**
- * @brief Begin a subroutine.
+ * Program entry point.
  */
-void SetTask(u32 screen);
+void AgbMain(void);
 
+/**
+ * Begin a new task.
+ *
+ * @param task #Task to begin.
+ */
+void SetTask(u32 task);
+
+/**
+ * Initialize the DMA system.
+ */
 void InitDMA(void);
 
-void sub_0805622C(void* a1, u32 a2, u32 a3);
+/**
+ * Soft reset the system.
+ */
+void DoSoftReset(void);
 
+/**
+ * Put the system into sleep mode.
+ */
+void SetSleepMode(void);
+
+extern void sub_0805622C(void* a1, u32 a2, u32 a3);
 extern void sub_08056208(void);
 extern void ResetPalettes(void);
-
-extern void DoSoftReset(void);
-extern void SetSleepMode(void);
 extern void VBlankIntrWait();
-extern void FadeMain(void);
-
-extern u8 gUnk_03003DE4;
-
-extern void SetBrightness(u32);
-extern u16 gPaletteBuffer[];
 extern void VBlankInterruptWait(void);
 extern void DisableInterruptsAndDMA(void);
 extern void EnableVBlankIntr(void);
 extern void sub_08056250(void);
 extern void sub_08056208(void);
 
+/** @name Task entrypoints */
+///@{
+/** Task entrypoint. */
+extern void TitleTask(void);
+extern void FileSelectTask(void);
+extern void GameTask(void);
+extern void GameOverTask(void);
+extern void StaffrollTask(void);
+extern void DebugTask(void);
+
+#ifdef DEMO_USA
+extern void DemoTask(void);
+#endif
+/// @}
+
+extern u8 gUnk_03003DE4;
+extern u16 gPaletteBuffer[];
+
 #endif

src/game.c

@@ -525,7 +525,7 @@ static void AuxCutscene_Init(void) {
     LoadGfxGroups();
     gArea.localFlagOffset = GetFlagBankOffset(gRoomControls.area);
     SetCurrentRoomPropertyList(p->area, p->room);
-    LoadCutsceneRoom(p->area, p->room);
+    LoadAuxiliaryRoom(p->area, p->room);
     gRoomControls.scroll_x = gRoomControls.origin_x + p->x;
     gRoomControls.scroll_y = gRoomControls.origin_y + p->y;
     gMenu.field_0x0 = p->_2;
@@ -1441,7 +1441,7 @@ static void UpdateFakeScroll(void) {
     } while (++ll < gEntityLists + 9);
 }
 
-void LoadCutsceneRoom(u32 area, u32 room) {
+void LoadAuxiliaryRoom(u32 area, u32 room) {
     sub_08052FF4(area, room);
     gRoomControls.camera_target = NULL;
     sub_0807C860();

src/main.c

@@ -9,14 +9,6 @@
 
 extern u32 gRand;
 
-extern void TitleTask(void);
-extern void FileSelectTask(void);
-extern void DemoTask(void);
-extern void GameTask(void);
-extern void GameOverTask(void);
-extern void StaffrollTask(void);
-extern void DebugTask(void);
-
 static void InitOverlays(void);
 static bool32 SoftResetKeysPressed(void);
 static u32 CheckHeaderValid(void);