Screen fades, window details, top screen settings & in-game timer (#224)

Discoveries made while developing an HUD mod that displays
the current in-game timer. Quite a bit of miscellaneous stuff
that will hopefully be at least somewhat useful and not too
horribly documented/formatted.

CREDITS.txt

@@ -30,6 +30,7 @@ other parts of the project, feel free to add yourself to this file!
 - Adakite
 - tech-ticks
 - Rhokin
+- ShadyGamerX
 - The rest of the contributors to Project Pokémon's technical documentation
   for the NDS Mystery Dungeon games, which can be found here:
   https://projectpokemon.org/home/docs/mystery-dungeon-nds/

headers/data/arm9.h

@@ -14,6 +14,7 @@ extern uint32_t MAX_MONEY_CARRIED;
 extern uint32_t MAX_MONEY_STORED;
 extern struct window_list* WINDOW_LIST_PTR;
 extern struct script_var_value_table* SCRIPT_VARS_VALUES_PTR;
+extern uint32_t MAX_PLAY_TIME;
 extern uint32_t MONSTER_ID_LIMIT;
 extern uint32_t MAX_RECRUITABLE_TEAM_MEMBERS;
 extern int16_t NATURAL_LOG_VALUE_TABLE[2048];

headers/data/overlay29.h

@@ -87,6 +87,7 @@ extern int16_t GUMMI_IQ_STRING_IDS[5];
 extern int16_t DAMAGE_STRING_IDS[27];
 extern struct dungeon* DUNGEON_PTR;
 extern struct dungeon* DUNGEON_PTR_MASTER;
+extern struct top_screen_status* TOP_SCREEN_STATUS_PTR;
 extern struct entity* LEADER_PTR;
 extern struct prng_state DUNGEON_PRNG_STATE;
 extern uint32_t DUNGEON_PRNG_STATE_SECONDARY_VALUES[5];
@@ -99,5 +100,6 @@ extern struct exclusive_item_effect_id_8 EXCL_ITEM_EFFECTS_EVASION_BOOST[8];
 extern struct tile DEFAULT_TILE;
 extern bool HIDDEN_STAIRS_SPAWN_BLOCKED;
 extern void* FIXED_ROOM_DATA_PTR;
+extern struct dungeon_fades* DUNGEON_FADES_PTR;
 
 #endif

headers/functions/arm9.h

@@ -98,6 +98,9 @@ void FileSeek(struct file_stream* file, int offset, int whence);
 void FileClose(struct file_stream* file);
 void UnloadFile(void* ptr);
 void LoadFileFromRom(struct iovec* iov, const char* filepath, uint32_t flags);
+void UpdateFadeStatus(struct screen_fade* fstruct, int param_2, int duration);
+bool HandleFades(struct screen_fade* fstruct);
+int GetFadeStatus(struct screen_fade* fstruct);
 void InitDebug(void);
 void InitDebugFlag(void);
 bool GetDebugFlag(enum debug_flag flag);
@@ -510,11 +513,13 @@ void CopyNStringFromId(char* buf, int string_id, int buf_len);
 void LoadTblTalk(void);
 int GetTalkLine(int personality_idx, int group_id, int restrictions);
 bool IsAOrBPressed(void);
+void DrawTextInWindow(int window_id, int x, int y, char* string);
 struct window* GetWindow(int window_id);
 int NewWindowScreenCheck(struct window_params* params, uint8_t param_2);
 int NewWindow(struct window_params* params, uint8_t param_2);
 void SetScreenWindowsColor(int palette_idx, bool upper_screen);
 void SetBothScreensWindowsColor(int palette_idx);
+void ClearWindow(int window_id);
 void DeleteWindow(int window_id);
 void GetWindowRectangle(int window_id, struct window_rectangle* rect_out);
 void* GetWindowContents(int window_id);
@@ -842,6 +847,9 @@ void SetMainTeamName(char* buf);
 int GetRankupPoints(void);
 enum rank GetRank(void);
 int GetRankStorageSize(void);
+void ResetPlayTimer(struct play_time* igt);
+void PlayTimerTick(struct play_time* igt);
+uint32_t GetPlayTimeSeconds(struct play_time* igt);
 uint32_t SubFixedPoint(uint32_t val_fp, uint32_t dec_fp);
 uint32_t BinToDecFixedPoint(uint32_t* q16);
 int CeilFixedPoint(uint32_t val_fp);

headers/functions/overlay01.h

@@ -4,5 +4,6 @@
 void CreateMainMenus(void);
 void AddMainMenuOption(int action_id, bool enabled);
 void AddSubMenuOption(int action_id, bool enabled);
+void ProcessContinueScreenContents(undefined4 param_1);
 
 #endif

headers/functions/overlay10.h

@@ -21,6 +21,10 @@ int16_t GetTrapAnimation(enum trap_id trap_id);
 int16_t GetItemAnimation1(enum item_id item_id);
 int16_t GetItemAnimation2(enum item_id item_id);
 int GetMoveAnimationSpeed(enum move_id move_id);
+undefined4 DrawTeamStats(undefined4 param_1, int param_2, undefined4 param_3, uint32_t param_4);
+void UpdateTeamStats(void);
+int FreeTeamStats(void);
+int FreeMapAndTeam(void);
 void ProcessTeamStatsLvHp(int idx);
 void ProcessTeamStatsNameGender(int idx);
 bool IsBackgroundTileset(int tileset_id);

headers/functions/overlay11.h

@@ -28,6 +28,7 @@ void GroundMainNextDay(void);
 bool JumpToTitleScreen(int arg);
 bool ReturnToTitleScreen(uint32_t fade_duration);
 void ScriptSpecialProcess0x16(bool param_1);
+bool IsScreenFadeInProgress(void);
 void LoadBackgroundAttributes(struct bg_list_entry* entry, int bg_id);
 void LoadMapType10(void* buf, int map_id, undefined* dungeon_info_str, undefined4 additional_info);
 void LoadMapType11(void* buf, int map_id, undefined* dungeon_info_str, undefined4 additional_info);
@@ -53,9 +54,11 @@ void CloseTeamInfoBox(int window_id);
 bool IsTeamInfoBoxActive(int window_id);
 void UpdateTeamInfoBox(struct window* window);
 void GetExclusiveItemRequirements(undefined param_1, undefined param_2);
+void HandleControlsTopScreenGround(void);
 bool GetDungeonMapPos(struct uvec2* out_pos, enum dungeon_id dungeon);
 void WorldMapSetMode(uint32_t world_map_mode);
 void WorldMapSetCamera(uint32_t map_marker_id);
 void StatusUpdate(void);
+void HandleTeamStatsGround(void);
 
 #endif

headers/functions/overlay29.h

@@ -59,6 +59,16 @@ int MonsterSpawnListPartialCopy(struct monster_spawn_entry* buffer, int current_
 bool IsOnMonsterSpawnList(enum monster_id monster_id);
 enum monster_id GetMonsterIdToSpawn(int spawn_weight);
 uint8_t GetMonsterLevelToSpawn(enum monster_id monster_id);
+void AllocTopScreenStatus(void);
+void FreeTopScreenStatus(void);
+int InitializeTeamStats(void);
+int UpdateTeamStatsWrapper(void);
+int FreeTeamStatsWrapper(void);
+void AssignTopScreenHandlers(void** funcs, top_screen_status_fn_t init_func,
+                             top_screen_status_fn_t update_func, void* param_4,
+                             top_screen_status_fn_t free_func);
+void HandleTopScreenFades(void);
+int FreeTopScreen(void);
 enum direction_id GetDirectionTowardsPosition(struct position* origin, struct position* target);
 int GetChebyshevDistance(struct position* position_a, struct position* position_b);
 bool IsPositionActuallyInSight(struct position* origin, struct position* target,
@@ -662,6 +672,7 @@ void SetShouldBoostHiddenStairsSpawnChance(bool value);
 void UpdateShouldBoostHiddenStairsSpawnChance(void);
 bool IsSecretRoom(void);
 bool IsSecretFloor(void);
+enum hidden_stairs_type GetCurrentHiddenStairsType(void);
 bool HiddenStairsPresent(void);
 void HiddenStairsTrigger(bool show_message);
 undefined4 GetDungeonGenInfoUnk0C(void);
@@ -785,6 +796,9 @@ void RemoveEmptyItemsInBagWrapper(void);
 void GenerateItem(struct item* item, enum item_id item_id, uint16_t quantity,
                   enum gen_item_stickiness sticky_type);
 bool DoesProjectileHitTarget(struct entity* user, struct entity* target);
+void DisplayFloorCard(int duration);
+void HandleFloorCard(enum dungeon_id dungeon_id, uint8_t floor, int duration,
+                     enum hidden_stairs_type hidden_stairs_type);
 bool CheckActiveChallengeRequest(void);
 struct mission_destination_info* GetMissionDestination(void);
 bool IsOutlawOrChallengeRequestFloor(void);
@@ -833,6 +847,11 @@ void InitPortraitDungeon(struct portrait_params* portrait, enum monster_id monst
                          enum portrait_emotion emotion);
 void OpenMessageLog(undefined4 param_1, undefined4 param_2);
 bool RunDungeonMode(undefined4* param_1, undefined4 param_2);
+void StartFadeDungeon(struct dungeon_fade* fstruct, int delta_delta_brightness,
+                      enum fade_status_dungeon fade_type);
+void StartFadeDungeonWrapper(int fade_type, int delta_delta_brightness, enum screen screen);
+void HandleFadesDungeon(enum screen screen);
+void HandleFadesDungeonBothScreens();
 void DisplayDungeonTip(struct message_tip* message_tip, bool log);
 void SetBothScreensWindowColorToDefault(void);
 int GetPersonalityIndex(struct monster* monster);

headers/functions/overlay31.h

@@ -2,6 +2,7 @@
 #define HEADERS_FUNCTIONS_OVERLAY31_H_
 
 void EntryOverlay31(void);
+void DrawDungeonMenuStatusWindow(int param_1);
 void DungeonMenuSwitch(int idx);
 void MovesMenu(struct action_data* action);
 bool HandleMovesMenuWrapper0(undefined* param_1, undefined param_2, undefined param_3,

headers/types/common/common.h

@@ -1213,4 +1213,34 @@ ASSERT_SIZE(struct thread_info, 52); // Could be shorter
 // TODO: Add more data file structures, as convenient or needed, especially if the load address
 // or pointers to the load address are known.
 
+// State of the screen fade in all other modes except dungeon mode
+struct screen_fade {
+    undefined field0_0x0;
+    undefined field1_0x1;
+    undefined field2_0x2;
+    undefined field3_0x3;
+    enum fade_status status; // 0x4
+    int remaining_frames;    // 0x8
+    // 0xC: Initial duration of the fade in frames
+    int duration;
+    // 0x10: What brightness the fade ends at. 256 means fade to white, -256 means fade to black
+    int16_t target_delta_brightness;
+    // 0x12: Max absolute value of the brightness during the fade. 256 means a full fade
+    int16_t max_brightness;
+    // 0x14: Current brightness of the fade. Positive numbers turn the screen white, negative to
+    // black
+    int16_t delta_brightness;
+    int16_t _padding;
+};
+ASSERT_SIZE(struct screen_fade, 24);
+
+// The file timer. Counts every frame spent on the file, except loading, lag, saving and being
+// in the main menu.
+struct play_time {
+    uint32_t seconds; // 0x0
+    uint8_t frames;   // 0x4
+    uint8_t _padding[3];
+};
+ASSERT_SIZE(struct play_time, 8);
+
 #endif

headers/types/common/enums.h

@@ -3872,4 +3872,23 @@ enum debug_log_flag {
     DEBUG_LOG_FLAG_PERFORMANCE = 16,
 };
 
+// Fade status. Fade in means increasing brightness and fade out means decreasing.
+// As a result, fading the screen to white is considered a fade in.
+enum fade_status {
+    FADE_NONE = 0,
+    FADE_COMPLETE = 1,
+    FADE_IN = 2,
+    FADE_OUT = 3,
+};
+
+// The box type of a window.
+enum box_type {
+    BOX_TYPE_NORMAL = 0xFE,
+    BOX_TYPE_INVISIBLE = 0xFB,
+};
+
+#pragma pack(push, 1)
+ENUM_8_BIT(box_type);
+#pragma pack(pop)
+
 #endif

headers/types/common/window.h

@@ -42,9 +42,8 @@ struct window_params {
     uint8_t width;          // 0x6: Window width, divided by 8.
     uint8_t height;         // 0x7: Window height, divided by 8.
     struct screen_8 screen; // 0x8: Screen where the window resides
-    // 0x9: The box type can affect the window frame and/or the backdrop. For example, 0xFA makes
-    // both the frame and backdrop invisible
-    uint8_t box_type;
+    // 0x9: The box type can affect the window frame and/or the backdrop.
+    struct box_type_8 box_type;
     undefined field_0xa;
     undefined field_0xb;
     // 0xC: heap-allocated contents for the window, varying by type.