Merge pull request #114 from lhearachel/battle-dev

Finish documenting battle_lib.c

include/overlay016/ov16_0225177C.h → include/battle/battle_lib.h

@@ -1,5 +1,7 @@
-#ifndef POKEPLATINUM_OV16_0225177C_H
-#define POKEPLATINUM_OV16_0225177C_H
+#ifndef POKEPLATINUM_BATTLE_BATTLE_LIB_H
+#define POKEPLATINUM_BATTLE_BATTLE_LIB_H
+
+#include "constants/sound.h"
 
 #include "pokemon.h"
 #include "struct_decls/battle_system.h"
@@ -440,9 +442,34 @@ void Battler_UnlockMoveChoice(BattleSystem *battleSys, BattleContext *battleCtx,
  * @return A value representing the battler's status non-volatile status.
  */
 enum StatusEffect Battler_StatusCondition(BattleContext *battleCtx, int battler);
-BOOL BattleSystem_CheckTrainerMessage(BattleSystem * param0, BattleContext * param1);
-void BattleContext_Init(BattleContext * param0);
-void BattleContext_InitCounters(BattleSystem * param0, BattleContext * param1);
+
+/**
+ * @brief Check if the given trainer has a trainer message to be shown.
+ * 
+ * If a trainer message is to be shown, then the respective battler will be
+ * updated with the appropriate flag, and battleCtx->msgTemp will be loaded
+ * with the type of message to be shown.
+ * 
+ * @param battleSys 
+ * @param battleCtx 
+ * @return TRUE if a message should be shown, else FALSE.
+ */
+BOOL BattleSystem_CheckTrainerMessage(BattleSystem *battleSys, BattleContext *battleCtx);
+
+/**
+ * @brief Initialize the BattleContext structure with start-of-turn state.
+ * 
+ * @param battleCtx 
+ */
+void BattleContext_Init(BattleContext *battleCtx);
+
+/**
+ * @brief Initialize standard counters for the BattleContext structure.
+ * 
+ * @param battleSys 
+ * @param battleCtx 
+ */
+void BattleContext_InitCounters(BattleSystem *battleSys, BattleContext *battleCtx);
 
 /**
  * @brief Update relevant buffers for a battler after a switch.
@@ -1204,7 +1231,7 @@ BOOL BattleSystem_PluckBerry(BattleSystem *battleSys, BattleContext *battleCtx,
  * @return TRUE if a follow-up subsequence should be run to apply the item's
  * Fling effect; FALSE if no such follow-up is needed.
  */
-BOOL BattleSystem_FlingItem(BattleSystem * param0, BattleContext * param1, int param2);
+BOOL BattleSystem_FlingItem(BattleSystem *battleSys, BattleContext *battleCtx, int battler);
 
 /**
  * @brief Update the count for the Metronome held item.
@@ -1221,7 +1248,18 @@ void BattleSystem_UpdateMetronomeCount(BattleSystem *battleSys, BattleContext *b
  * @param battleCtx 
  */
 void BattleSystem_VerifyMetronomeCount(BattleSystem *battleSys, BattleContext *battleCtx);
-int ov16_022599D0(BattleContext * param0, int param1, int param2, int param3);
+
+/**
+ * @brief Determine what modulating effect to apply to a battler's cry
+ * whenever they are sent into battle.
+ * 
+ * @param battleCtx 
+ * @param battler 
+ * @param battlerType 
+ * @param encounter     TRUE if this is a start-of-battle cry.
+ * @return The type of modulating effect applied to the battler's cry.
+ */
+enum PokemonCryMod Battler_CryModulation(BattleContext *battleCtx, int battler, int battlerType, BOOL encounter);
 
 /**
  * @brief Check if a battler can choose their action for the turn.
@@ -1232,7 +1270,17 @@ int ov16_022599D0(BattleContext * param0, int param1, int param2, int param3);
  * if not.
  */
 BOOL Battler_CanPickCommand(BattleContext *battleSys, int battler);
-void ov16_02259A5C(BattleSystem * param0, BattleContext * param1, Pokemon * param2);
+
+/**
+ * @brief Set the catch-data for a newly-caught Pokemon.
+ * 
+ * This will set the met-location and Poke Ball for the newly-caught Pokemon.
+ * 
+ * @param battleSys 
+ * @param battleCtx 
+ * @param mon 
+ */
+void BattleSystem_SetPokemonCatchData(BattleSystem *battleSys, BattleContext *battleCtx, Pokemon *mon);
 
 /**
  * @brief Get the top byte of the IO buffer for the given battler.
@@ -1283,7 +1331,14 @@ BOOL BattleSystem_PokemonIsOT(BattleSystem *battleSys, Pokemon *mon);
  * be loaded for execution, FALSE otherwise.
  */
 BOOL BattleSystem_TriggerFormChange(BattleSystem *battleSys, BattleContext *battleCtx, int *subscript);
-void ov16_0225A1B0(BattleSystem * param0, BattleContext * param1);
+
+/**
+ * @brief Initialize the party order buffer.
+ * 
+ * @param battleSys 
+ * @param battleCtx 
+ */
+void BattleSystem_InitPartyOrder(BattleSystem *battleSys, BattleContext *battleCtx);
 
 /**
  * @brief Switch the party order by swapping the battler in the given party slot
@@ -1468,7 +1523,18 @@ BOOL BattleSystem_TriggerHeldItemOnPivotMove(BattleSystem *battleSys, BattleCont
  * @param defender 
  */
 void BattleSystem_DecPPForPressure(BattleContext *battleCtx, int attacker, int defender);
-BOOL BattleSystem_RecordingStopped(BattleSystem * param0, BattleContext * param1);
+
+/**
+ * @brief Check if the recording for a battle has finished playing.
+ * 
+ * If the recording has finished, then the controller will be set to a
+ * SCREEN_WIPE command.
+ * 
+ * @param battleSys 
+ * @param battleCtx 
+ * @return TRUE if the recording has stopped, FALSE otherwise.
+ */
+BOOL Battle_RecordingStopped(BattleSystem *battleSys, BattleContext *battleCtx);
 
 /**
  * @brief Get an accessible field from the BattleContext struct.
@@ -1513,7 +1579,15 @@ void BattleContext_Set(BattleSystem *battleSys, BattleContext *battleCtx, enum B
  * @return The party slot of the Pokemon to be switched in.
  */
 int BattleAI_PostKOSwitchIn(BattleSystem *battleSys, int battler);
-int ov16_0225BE28(BattleSystem * param0, int param1);
+
+/**
+ * @brief Get the switched-to slot determined by the AI for a given battler.
+ * 
+ * @param battleSys 
+ * @param battler 
+ * @return The AI's switched-to slot for the battler.
+ */
+int BattleAI_SwitchedSlot(BattleSystem *battleSys, int battler);
 
 /**
  * @brief Compute the variable-type of a move, given its use by a given Pokemon.
@@ -1529,4 +1603,4 @@ int ov16_0225BE28(BattleSystem * param0, int param1);
  */
 int Move_CalcVariableType(BattleSystem *battleSys, BattleContext *battleCtx, Pokemon *mon, int move);
 
-#endif // POKEPLATINUM_OV16_0225177C_H
+#endif // POKEPLATINUM_BATTLE_BATTLE_LIB_H

include/constants/battle.h

@@ -43,6 +43,7 @@
 #define BATTLE_TYPE_2vs2_TAG                (BATTLE_TYPE_2vs2 | BATTLE_TYPE_TAG)
 #define BATTLE_TYPE_ALWAYS_CATCH            (BATTLE_TYPE_PAL_PARK | BATTLE_TYPE_CATCH_TUTORIAL)
 #define BATTLE_TYPE_RESTORE_ITEMS_AFTER     (BATTLE_TYPE_LINK | BATTLE_TYPE_FRONTIER)
+#define BATTLE_TYPE_NO_TRAINER_MESSAGES     (BATTLE_TYPE_LINK | BATTLE_TYPE_FRONTIER)
 
 #define MAX_LINK_BATTLERS       4
 #define MAX_BATTLERS            4

include/constants/battle/system_control.h

@@ -13,29 +13,67 @@
 #define SYSCTL_LAST_OF_MULTI_TURN       (1 << 9)
 #define SYSCTL_NONSTANDARD_ACC_CHECK    (1 << 10) // used by Future Sight and OHKO moves
 #define SYSCTL_IGNORE_TYPE_CHECKS       (1 << 11)
+#define SYSCTL_CRASH_DAMAGE             (1 << 12)
 #define SYSCTL_MOVE_HIT                 (1 << 13) // this indicates that the move hit its target(s)
 #define SYSCTL_PLAYED_MOVE_ANIMATION    (1 << 14)
 #define SYSCTL_IGNORE_IMMUNITIES        (1 << 15)
+#define SYSCTL_MULTI_HIT_SKIP_MESSAGE   (1 << 16)
 #define SYSCTL_FAIL_STAT_STAGE_CHANGE   (1 << 17)
+#define SYSCTL_MESSAGE_AFTER_MISS       (1 << 18)
 #define SYSCTL_HIT_DURING_SHADOW_FORCE  (1 << 19)
 #define SYSCTL_REUSE_LAST_MOVE          (1 << 20)
+#define SYSCTL_TURN_OFF_MESSAGES        (1 << 21)
 #define SYSCTL_APPLY_SECONDARY_EFFECT   (1 << 22)
 #define SYSCTL_APPLY_MOLD_BREAKER       (1 << 23)
 #define SYSCTL_MON_FAINTED              ((1 << 24) | (1 << 25) | (1 << 26) | (1 << 27))
 #define SYSCTL_MON_SELFDESTRUCTED       ((1 << 28) | (1 << 29) | (1 << 30) | (1 << 31))
 
+#define SYSCTL_INIT                     (~(SYSCTL_SKIP_ATTACK_MESSAGE \
+                                        | SYSCTL_CHECK_LOOP_ONLY_ONCE \
+                                        | SYSCTL_HIT_DURING_FLY \
+                                        | SYSCTL_HIT_DURING_DIG \
+                                        | SYSCTL_HIT_DURING_DIVE \
+                                        | SYSCTL_FIRST_OF_MULTI_TURN \
+                                        | SYSCTL_SKIP_SPRITE_BLINK \
+                                        | SYSCTL_TRY_SYNCHRONIZE_STATUS \
+                                        | SYSCTL_BATON_PASS \
+                                        | SYSCTL_LAST_OF_MULTI_TURN \
+                                        | SYSCTL_NONSTANDARD_ACC_CHECK \
+                                        | SYSCTL_IGNORE_TYPE_CHECKS \
+                                        | SYSCTL_CRASH_DAMAGE \
+                                        | SYSCTL_MOVE_HIT \
+                                        | SYSCTL_PLAYED_MOVE_ANIMATION \
+                                        | SYSCTL_IGNORE_IMMUNITIES \
+                                        | SYSCTL_MULTI_HIT_SKIP_MESSAGE \
+                                        | SYSCTL_FAIL_STAT_STAGE_CHANGE \
+                                        | SYSCTL_MESSAGE_AFTER_MISS \
+                                        | SYSCTL_HIT_DURING_SHADOW_FORCE \
+                                        | SYSCTL_REUSE_LAST_MOVE \
+                                        | SYSCTL_TURN_OFF_MESSAGES \
+                                        | SYSCTL_APPLY_SECONDARY_EFFECT))
+
 #define SYSCTL_MON_FAINTED_SHIFT        24
 #define SYSCTL_MON_SELFDESTRUCTED_SHIFT 28
 
+#define SYSCTL_UPDATE_STAT_STAGES       (1 << 1)
 #define SYSCTL_ATTACK_MESSAGE_SHOWN     (1 << 2)
 #define SYSCTL_MAGIC_COAT_REFLECTED     (1 << 3)
 #define SYSCTL_UTURN_ACTIVE             (1 << 4)
+#define SYSCTL_FIRST_DAMAGE_MSG_SHOWN   (1 << 5)
 #define SYSCTL_MOVE_SUCCEEDED           (1 << 6) // this only reflects that the move is executed, not whether it hit or missed
+#define SYSCTL_RECOVER_HP_VISUAL        (1 << 8)
 #define SYSCTL_FORM_CHANGE              (1 << 26)
 
 #define SYSCTL_LINK_WAITING             ((1 << 24) | (1 << 25) | SYSCTL_FORM_CHANGE | (1 << 27))
 #define SYSCTL_PAYOUT_EXP               ((1 << 28) | (1 << 29) | (1 << 30) | (1 << 31))
 
+#define SYSCTL_INIT2                    (~(SYSCTL_UPDATE_STAT_STAGES \
+                                        | SYSCTL_ATTACK_MESSAGE_SHOWN \
+                                        | SYSCTL_MAGIC_COAT_REFLECTED \
+                                        | SYSCTL_UTURN_ACTIVE \
+                                        | SYSCTL_MOVE_SUCCEEDED \
+                                        | SYSCTL_RECOVER_HP_VISUAL))
+
 #define SYSCTL_LINK_WAITING_SHIFT       24
 #define SYSCTL_PAYOUT_EXP_SHIFT         28
 

include/constants/sound.h

@@ -0,0 +1,10 @@
+#ifndef POKEPLATINUM_CONSTANTS_SOUND_H
+#define POKEPLATINUM_CONSTANTS_SOUND_H
+
+enum PokemonCryMod {
+    POKECRY_NORMAL = 0,
+
+    POKECRY_PINCH_NORMAL = 11,
+};
+
+#endif // POKEPLATINUM_CONSTANTS_SOUND_H

include/constants/trainer.h

@@ -1,6 +1,10 @@
 #ifndef POKEPLATINUM_TRAINER_H
 #define POKEPLATINUM_TRAINER_H
 
+#define TRMSG_ACTIVE_BATTLER_HALF_HP_FLAG   2
+#define TRMSG_LAST_BATTLER_FLAG             3
+#define TRMSG_LAST_BATTLER_HALF_HP_FLAG     4
+
 enum TrainerClass {
     TRAINER_CLASS_PLAYER_MALE,
     TRAINER_CLASS_PLAYER_FEMALE,
@@ -109,4 +113,11 @@ enum TrainerClass {
     TRAINER_CLASS_DP_PLAYER_FEMALE_2,
 };
 
+enum TrainerMessageType {
+    TRMSG_FIRST_DAMAGE = 13,
+    TRMSG_ACTIVE_BATTLER_HALF_HP,
+    TRMSG_LAST_BATTLER,
+    TRMSG_LAST_BATTLER_HALF_HP,
+};
+
 #endif // POKEPLATINUM_TRAINER_H

include/overlay016/ov16_0223DF00.h

@@ -103,7 +103,15 @@ u16 * ov16_0223E0BC(BattleSystem * param0);
 UnkStruct_ov16_0223E0C8 * ov16_0223E0C8(BattleSystem * param0);
 UnkStruct_0200B358 * ov16_0223E0D0(BattleSystem * param0);
 Strbuf* ov16_0223E0D4(BattleSystem * param0);
-u16 ov16_0223E0D8(BattleSystem * param0, int param1);
+
+/**
+ * @brief Get the trainer ID for a particular battler.
+ * 
+ * @param battleSys
+ * @param battler
+ * @return The battler's trainer ID
+ */
+u16 Battler_TrainerID(BattleSystem *battleSys, int battler);
 TrainerData * BattleSystem_TrainerData(BattleSystem * param0, int param1);
 
 /**
@@ -250,7 +258,7 @@ void ov16_0223F638(BattleSystem * param0, u16 param1, u8 * param2);
 u16 ov16_0223F6E4(BattleSystem * param0);
 int ov16_0223F6F0(BattleSystem * param0, u16 param1);
 u16 BattleSystem_TrainerItems(BattleSystem * param0, int param1, int param2);
-u32 ov16_0223F710(BattleSystem * param0);
+u32 BattleSystem_RecordingStopped(BattleSystem * param0);
 void BattleSystem_SetStopRecording(BattleSystem *battleSys, int flag);
 BOOL ov16_0223F7A4(BattleSystem * param0);
 void BattleSystem_ShowStopPlaybackButton(BattleSystem *battleSys);

include/pokemon.h

@@ -887,7 +887,7 @@ void Pokemon_LoadLevelUpMovesOf(int monSpecies, int monForm, u16 *monLevelUpMove
 void sub_02077D3C(UnkStruct_0202CC84 *param0, int param1, u16 monSpecies, int param3, int param4, int param5, int param6, int param7);
 void sub_02077DB4(UnkStruct_0202CC84 *param0, int param1, u16 monSpecies, int param3, int param4, int param5, int param6, int param7, u8 param8);
 BOOL sub_02077E3C(Pokemon *mon);
-void sub_02077E64(Pokemon *mon, TrainerInfo *param1, int monPokeball, int param3, int param4, int param5);
+void Pokemon_SetCatchData(Pokemon *mon, TrainerInfo *param1, int monPokeball, int param3, int param4, int param5);
 void sub_02077EE4(Pokemon *mon, TrainerInfo *param1, int monPokeball, int param3, int param4, int param5);
 void sub_02077F0C(Pokemon *mon, u32 param1, int param2);
 BOOL Pokemon_CanLearnTM(Pokemon *mon, u8 tmID);

include/trainer_data.h

@@ -1,6 +1,8 @@
 #ifndef POKEPLATINUM_TRAINER_DATA_H
 #define POKEPLATINUM_TRAINER_DATA_H
 
+#include "constants/trainer.h"
+
 #include "strbuf.h"
 #include "struct_defs/trainer_data.h"
 #include "struct_decls/struct_021C0794_decl.h"
@@ -48,8 +50,7 @@ u32 TrainerData_LoadParam(int trainerID, enum TrainerDataParam paramID);
  * @param heapID        Heap on which to allocate archive access.
  * @return TRUE if the trainer has a message of the given type; FALSE if not.
  */
-// TODO: enum?
-BOOL TrainerData_HasMessageType(int trainerID, int msgType, int heapID);
+BOOL TrainerData_HasMessageType(int trainerID, enum TrainerMessageType msgType, int heapID);
 
 /**
  * @brief Load the trainer's message of a given type into the provided Strbuf.
@@ -61,7 +62,7 @@ BOOL TrainerData_HasMessageType(int trainerID, int msgType, int heapID);
  * @param[out] strbuf   Strbuf which will contain the result message.
  * @param heapID        Heap on which to allocate archive access.
  */
-void TrainerData_LoadMessage(int trainerID, int msgType, Strbuf *strbuf, int heapID);
+void TrainerData_LoadMessage(int trainerID, enum TrainerMessageType msgType, Strbuf *strbuf, int heapID);
 
 /**
  * @brief Load data for the requested trainer.

include/unk_0208C098.h

@@ -6,6 +6,15 @@
 
 #include <nnsys.h>
 
+enum BarColor {
+    BARCOLOR_EMPTY = 0,
+    BARCOLOR_RED,
+    BARCOLOR_YELLOW,
+    BARCOLOR_GREEN,
+
+    BARCOLOR_MAX,
+};
+
 int sub_0208C098(int param0);
 u32 sub_0208C0A4(u32 param0, u32 param1);
 
@@ -18,8 +27,26 @@ u32 sub_0208C0A4(u32 param0, u32 param1);
  * @return The number of pixels needed to display cur / max.
  */
 u8 App_PixelCount(u32 cur, u32 max, u8 maxPixels);
-u8 sub_0208C0D4(u32 param0, u32 param1);
-u8 sub_0208C104(u16 param0, u16 param1, u32 param2);
+
+/**
+ * @brief Determine what color should be used for a value represented by a
+ * visual bar, e.g. the health bar in battle.
+ * 
+ * @param cur   The current value of the bar.
+ * @param max   The maximum value of the bar.
+ * @return The color to be used for the bar's current value.
+ */
+u8 App_BarColor(u32 cur, u32 max);
+
+/**
+ * @brief Determine the color of the health bar.
+ * 
+ * @param curHP     The current HP value.
+ * @param maxHP     The maximum HP value.
+ * @param barSize   The size of the health bar, in pixels.
+ * @return The color to be used for the health bar's current value.
+ */
+u8 HealthBar_Color(u16 curHP, u16 maxHP, u32 barSize);
 void sub_0208C120(u8 param0, u32 param1);
 u8 sub_0208C15C(s16 * param0, u16 param1);
 void sub_0208C210(BGL * param0, int param1, NARC * param2, int param3, int param4, int param5, int param6, u16 param7, u16 param8);

platinum.us/main.lsf

@@ -694,7 +694,7 @@ Overlay overlay16
 	Object main.nef.p/src_overlay016_ov16_0223DF00.c.o
 	Object main.nef.p/src_overlay016_battle_script.c.o
 	Object main.nef.p/src_overlay016_battle_controller.c.o
-	Object main.nef.p/src_overlay016_ov16_0225177C.c.o
+	Object main.nef.p/src_overlay016_battle_lib.c.o
 	Object main.nef.p/src_overlay016_ov16_0225BFFC.c.o
 	Object main.nef.p/src_overlay016_ov16_0225CBB8.c.o
 	Object main.nef.p/src_overlay016_ov16_02264798.c.o

src/meson.build

@@ -532,7 +532,7 @@ pokeplatinum_c = files(
     'overlay016/ov16_0223DF00.c',
     'overlay016/battle_script.c',
     'overlay016/battle_controller.c',
-    'overlay016/ov16_0225177C.c',
+    'overlay016/battle_lib.c',
     'overlay016/ov16_0225BFFC.c',
     'overlay016/ov16_0225CBB8.c',
     'overlay016/ov16_02264798.c',