document game.h

3 files changed, 300 insertions, 55 deletions

diff --git a/include/entity.h b/include/entity.h
index 1e5f8f41..0d4be294 100644
--- a/include/entity.h
+++ b/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
diff --git a/include/game.h b/include/game.h
index 81dd794b..2b4f950e 100644
--- a/include/game.h
+++ b/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);
+
+/**
+ * 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);
-void ForceEquipItem(u32 item, u32 slot);
 
+/**
+ * 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;
 
-/**
- * @brief Subtasks override the game task for short periods
- */
-enum {
+/** Subtasks override the game task for short periods */
+typedef 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
diff --git a/include/main.h b/include/main.h
index 7b0abd05..f7ab29c4 100644
--- a/include/main.h
+++ b/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 {
-    TASK_TITLE,
-    TASK_FILE_SELECT,
-    TASK_GAME,
-    TASK_GAMEOVER,
-    TASK_STAFFROLL,
-    TASK_DEBUG,
-};
-
-enum {
+/** Program tasks. */
+typedef enum {
+    TASK_TITLE,       /**< Title task. This is the first task to be entered. */
+    TASK_FILE_SELECT, /**< File selection task. */
+    TASK_GAME,        /**< Gameplay task. Overworld, menus, cutscenes are all contained here. */
+    TASK_GAMEOVER,    /**< Gameover task. */
+    TASK_STAFFROLL,   /**< Staffroll task. Only accessible through the script played during the game ending. */
+    TASK_DEBUG,       /**< Debug task. Inaccessible in normal gameplay. */
+} Task;
+
+/** System sleep status. */
+typedef enum {
     DEFAULT,
     SLEEP,
-};
+} SleepStatus;
 
+/**
+ * Main system structure.
+ */
 typedef struct {
     vu8 interruptFlag;
     u8 sleepStatus;
-    u8 task;
-    u8 state;
-    u8 substate;
+    u8 task;     /**< Current #Task. */
+    u8 state;    /**< State of the current #Task. */
+    u8 substate; /**< Substate of the current #Task. */
     u8 field_0x5;
-    u8 muteAudio;
+    u8 muteAudio; /**< Mute audio. */
     u8 field_0x7;
-    u8 pauseFrames;
-    u8 pauseCount;
-    u8 pauseInterval;
+    u8 pauseFrames;   /**< Number of frames to pause. */
+    u8 pauseCount;    /**< Number of pauses to make. */
+    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 UI gUnk_02032EC0;
+extern Main gMain;       /**< Main instance. */
+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