Battle flow
The field sets request code 3, the main state machine enters its battle state, and that state loads the battle overlay and hands every frame to Battle_Update. This page covers the triggers, the per-frame code and archives, and the exit. Battler rows, enemy records, status words and the reprisal exchange are in battle records.
| Term | Meaning |
|---|---|
| Encounter | A random battle: g_BattleEncounter == 0. The enemies come from the area’s formation table (area format). |
| Scripted battle | g_BattleEncounter != 0, a record index of s_BattleModeRecords. The enemies and a boss module come from an archive that the record names. |
| Mode | g_BattleMode (0x801462E0): one of 6 rows of g_BattlePhases. |
| Step, sub-step | g_BattleStep (0x801462E1) and g_BattleSubStep (0x801462E2): the second and third index inside a mode. |
| UI step | g_BattleUiStep (0x801462E3): the index the BATL_END and BATL_OVR overlays dispatch on. |
| Entry substate | g_GameEntrySubstate while g_GameEntryState == 5: index into g_GameModeHandlers[8] (0x801C7B54). One entry runs Battle_Update. |
| Boss module | The code image of a BOSSnnn.EMI archive, loaded at 0x800C1800. It publishes three hooks. |
Starting a battle
Section titled “Starting a battle”Random encounter
Section titled “Random encounter”The player’s field step handler func_801B146C counts steps and asks Area_CanStartEncounter (emi/etc/game/00@0x801B3EB0) on every move. A yes sets the party actor’s step byte to 5 and clears its state. The two-entry table D_801CD118 (the step-5 state table [inferred]) then runs func_801B2AB4 and func_801B2B6C; the second writes g_GameStateIndex = 3.
Area_CanStartEncounter returns 0 (no battle) when any of these holds:
| Test | Meaning |
|---|---|
g_GameFlags & 0x20 |
A script flag switched encounters off. |
The zone’s rate byte gives threshold 0 |
Town or safe zone. |
Step counter D_80143F22 (scaled by 7/10 when D_80145FAC < 4) is below D_80145FB8 |
Not enough steps yet. |
D_80145FBC & 1 |
Another state suppresses it. |
Not on the world map and D_80143EFC >= 0xF1 |
A gate on a game counter. [unknown] meaning. |
A party battler row has flags_00 bit 0x40 (hidden) |
A party member is off screen. |
Area_BuildEncounter(4, 0) fails, or a party member has no free cell (func_801C472C) |
No enemy fits around the party. |
The step threshold comes from the area’s zone list. func_801B3C3C finds the rectangle that holds the party’s cell. Area_RollEncounterThreshold (emi/etc/game/00@0x801B3CCC) reads the rectangle’s byte 4, rate:
threshold = base[rate] + min(rand() & 0x1F, cap[rate])The pair (base, cap) comes from s_EncounterStepThresholds (emi/etc/game/00@0x801CD1B8). The total doubles when any party member has trait (3, 0x15) (func_801C38F4) and halves when any has trait (3, 0x14). Which abilities those traits belong to is [unknown]. Pair per rate:
rate |
0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 |
|---|---|---|---|---|---|---|---|---|
| base | 0 | 120 | 96 | 72 | 24 | 16 | 8 | 0 |
| cap | 0 | 60 | 48 | 36 | 12 | 8 | 4 | 0 |
A base of 0 means no encounters. Higher rate values give shorter walks between battles.
Formation and enemies
Section titled “Formation and enemies”Area_BuildEncounter (emi/etc/game/00@0x801C60E0) rolls a formation, copies the enemy list, tests each party cell and clears every enemy that does not fit. It returns 1 only when the gate passes and at least one enemy remains.
Area_PickEncounterrolls(rand() & 0xF) + 1and walks the eight 9-byte formation records at0x800E4000, adding byte 8 (the weight) until the running sum reaches the roll. A roll past all eight weights gives formation 0.Area_RollEncounterEnemiescopies the record’s 8 enemy ids intoD_801463DC(8EncounterEnemyof 12 bytes). An id other than0xFFstays when(rand() & 0xF) + 1 <= s_EntitySpawnChances[slot]. The chances are16, 16, 16, 10, 8, 6, 4, 2, so slots 0 to 2 always stay and slot 7 stays 2 times in 16. If no enemy stays, there is no battle.Area_PlaceEncounterEnemiesplaces each remaining enemy. Fornactive enemies the offset comes fromD_801CD620[n(n-1)/2 + placed], which is why the table has1 + 2 + ... + 8 = 36entries. The code then tries up to 49 cells froms_EntitySpawnOffsetsaround the party untilfunc_801C7518andfunc_801C6EE0accept one. An enemy with no cell is dropped.func_801C6DCCandArea_SetEncounterCameraadjust positions for the scroll directiong_BattleScrollDir. The cell tests in step 3 are[inferred].
The enemy record layout (0x800E4048 + id * 0x88, 8 records) is in the area format.
Scripted battle
Section titled “Scripted battle”Battle_StartScripted (emi/etc/game/00@0x801C7A54) takes a record index. It stores it in g_BattleEncounter, clears g_BattleSurprise, copies byte 0 of s_BattleModeRecords[index * 4] to g_BattleOptions, and sets bit 12 (0x1000) of g_AreaWalkFlags. The table has 56 records of 4 bytes at 0x801CD78C. Byte 3 of the record is the archive column used at stream time (see the next section). The caller then sets g_GameStateIndex = 3 [inferred].
The known caller is func_801FA7D8 in emi/scenario/scena00/00; other scenario overlays are not searched. The entry and exit substates test these g_BattleOptions bits:
| Bits | Meaning |
|---|---|
| 0 | Skip the camera pitch change. |
| 1 | Skip the scroll restore at exit. |
| 4 | Skip the BPLU or BPLD character sprites stream. |
| 6 | Keep the field BGM. |
Entry state 5
Section titled “Entry state 5”Game_UpdateField case 3 zeroes g_BattleMode, g_BattleStep and g_BattleSubStep, increments g_BattleCount, and sets g_GameEntryState = 5 and g_GameEntrySubstate = 0. Game_UpdateBattle (emi/etc/game/00@0x80197A24) then calls g_GameModeHandlers[g_GameEntrySubstate] once per frame:
| Substate | Function (emi/etc/game/00) |
Work |
|---|---|---|
| 0 | func_80197A60 |
func_801BEDD0, field redraw, advance. |
| 1 | Battle_LoadPartySprites |
Wait for the field to be ready, change the camera pitch, stream BPLU (scroll direction bit 1) or BPLD character sprites, advance. |
| 2 | func_80197C1C |
Wait for the loader and the camera. |
| 3 | Battle_LoadBattleArchive |
Pause BGM, save the sequence table, stream the battle archive, reset the battle bytes. |
| 4 | func_80197E54 |
Wait for the archive and set g_BattlePartyCount = Party_CountOrder(1). |
| 5 | Battle_Update (emi/battle/battle/03@0x801D1014) |
The battle itself, every frame. |
| 6 | func_80197EFC |
Field-side redraw, advance. |
| 7 | func_80197F48 |
Restore BGM and scroll, clear g_BattleOptions and g_BattleEncounter, return to state 2. |
Battle_LoadBattleArchive picks the archive to stream. For a scripted battle it is g_BossArchiveSlots[s_BattleModeRecords[g_BattleEncounter * 4 + 3]]. For a random battle it is slot 6 (BATTLE) when g_SceneState.scenario_id < 8 and slot 7 (BATTLE2) otherwise. g_BossArchiveSlots has 42 u16 entries: slot 6, then the BOSS slots 0x1B3 to 0x1DA in a game-specific order, then 0xFFFF.
Unless g_BattleOptions & 0x40 is set, substate 3 copies 1,376 bytes of the sequence table (D_80148A50 to D_8018E268) away, and substate 7 copies them back (audio).
Battle_Update never changes the entry substate. The advance from 5 to 6 happens in Battle_WriteBackParty (mode 5, step 4, sub-step 2).
The battle state machine
Section titled “The battle state machine”Battle_Update runs once per frame in a fixed order:
Battle_DispatchMode, but only wheng_BattleStatebit0x0002(boss window busy) is clear, no panel task 0 is live (or the mode is 5), andg_BattleEventFlags & 2is clear (or the mode is 5).Battle_UpdateParty,Battle_UpdateEnemies,Battle_UpdateEvents,Area_UpdateCamera,Battle_UpdateEffects.Battle_UpdatePartyActors,Battle_UpdateEnemyActors.func_801A0514(scripted battle) orfunc_801A061C(random battle): the battle scene draw.Area_UpdateParty,Actor_DispatchAll,GFX_UpdatePaletteAnimations,func_8019625C,Menu_UpdatePanelTasks,Area_DrawScene.
Battle_DispatchMode (emi/battle/battle/03@0x801D112C) first calls g_BossBattleEventHook(3) when g_BattleEncounter != 0 and the mode is not 0. Then it calls g_BattlePhases[g_BattleMode]. Mode 0 calls Battle_DispatchStep. Modes 1 to 5 read a step table by g_BattleStep, and some steps read a sub-table by g_BattleSubStep.
A battle runs set-up and entrance once, then rounds of commands (mode 1), turn order (2), actions (3) and round end (4), then the result (5). Mode 0 goes to 1 in Battle_EnterIntro; 1 to 2 in func_801D1D10 or on an armed command; 2 to 3 in func_801D2A24; 3 to 4 in func_801D43EC or func_801D2B58; 4 goes back to 1 in func_801D656C when the result is 0 and to 5 otherwise; 5 ends in Battle_WriteBackParty, which moves the entry substate to 6.
| Mode | Handler (emi/battle/battle/03) |
Steps | Step table |
|---|---|---|---|
| 0 | Battle_DispatchStep |
2 | func_801D1228 (reset), Battle_DispatchEntrance (4 sub-steps) |
| 1 | func_801D1C54 |
5 | D_801EABB8. Steps 3 and 4 use sub-tables D_801EABD8[3] and D_801EABE4[8]. |
| 2 | Battle_UpdateTurnSetup |
3 | D_801EAC04 |
| 3 | Battle_UpdateTurns |
5 | D_801EAC10. Sub-tables D_801EAC24[2], D_801EAC2C[6], D_801EACA4, D_801EACB0[3]. |
| 4 | Battle_UpdateRoundEnd |
3 | D_801EACBC. Sub-table D_801EACC8[3]. |
| 5 | Battle_UpdateResult |
5 | D_801EACD4. Sub-tables D_801EACE8, D_801EACF4, D_801EAD00, D_801EAD0C, D_801EAD20. |
The mode names are [inferred] from the step shapes and from func_801D656C, which returns to mode 1 or leaves for mode 5. Mode 3 also clears g_BattleState bit 0x0010 (command armed) when a button in D_80145AC4 is held. Some step functions, for example Battle_WaitUiMode and Battle_ReloadMusicBank, advance their sub-step through a pointer that is written during the wait.
Mode 0: reset and entrance
Section titled “Mode 0: reset and entrance”Step 0, func_801D1228, clears the battle state block, counts living party slots, copies the party stat blocks, and uploads palettes 0x1A and 0x1B. For a random battle it streams slot 0x9 + g_GameAreaId (the area’s enemy archive). For a scripted battle it calls g_BossBattleEventHook(6) instead. It then increments g_BattleStep.
Step 1, Battle_DispatchEntrance (emi/battle/battle/03@0x801D17C4), runs four sub-steps from g_BattleEntrances (0x801D0C1C):
Battle_OpenPanelsarms the selection panels and writes the initiative text wheng_BattleSurpriseis 1 or 2.Battle_WaitUiModewaits for the UI mode byte to read 1.Battle_InitPanelspresets the seven panel widths.Battle_EnterIntrowaits forEMI_IsReadyand the intro helper, callsfunc_801D93E4with 1 (2 wheng_BattleSurprise >= 2) andfunc_801D9428(2), zeroes step and sub-step, and setsg_BattleModeto 1.
Modes 1 to 4: one round
Section titled “Modes 1 to 4: one round”The mode 1 sub-table D_801EABE4 points partly into the second battle overlay at 0x800968xx (func_80096A74, func_80096F00, func_8009834C, func_800980A8), so the command menus live in battle/battle/15 [inferred].
func_801D656C ends mode 4: it waits until the 8 bytes D_8018E140[16..23] are zero. In a scripted battle it then calls g_BossBattleEventHook(2), and returns early while the hook answers 0xFF. A nonzero g_BattleResult sets mode 5, step 0. Otherwise it streams slot 8 (COMN_SE, when no command is armed), marks free party slots as step 2, clears g_BattleSurprise, and returns to mode 1.
The boss hook takes seven event codes; their meaning is [unknown].
| Code | Caller |
|---|---|
| 0 | func_801D43EC (mode 3, last step) |
| 1 | func_801D2FC0 (mode 3, step 0, sub-step 1) |
| 2 | func_801D656C (mode 4, round end) |
| 3 | Battle_DispatchMode (every frame in modes 1 to 5) |
| 4 | Battle_FinishEffectLoad (mode 3) |
| 5 | func_801D43EC (mode 3, last step) |
| 6 | func_801D1228 (reset) |
Mode 5: result and exit
Section titled “Mode 5: result and exit”| Step | Sub-table | Role |
|---|---|---|
| 0 | D_801EACE8 |
The third sub-step is Battle_LoadEndOverlay, the chooser. |
| 1 | D_801EACF4 |
Ends in func_801EEC58, the BATL_END entry (victory). |
| 2 | D_801EAD00 |
Ends in func_801EEC04, the BATL_OVR entry (defeat). |
| 3 | D_801EAD0C |
Reloads the area slot (0x2AB + area), then sets step 4. |
| 4 | D_801EAD20 |
Exit: free battlers, stream slot 0x256 (AFLDKWA), restore BGM, Battle_WriteBackParty, wait for the window. |
The chooser, Battle_LoadEndOverlay (emi/battle/battle/03@0x801D6A14), waits until no party row has bit 0x2000 and g_BattleRowCursor == g_BattlePartyCount. If the result is not defeat, it ANDs every party member’s status with 0xBF5F, which keeps KO (0x4000), poison (0x80) and confusion (0x20). A member with status bit 0x800 first gets HP, AP and willpower set to their maximums. For a random battle it then sets step 2 on defeat (g_BattleResult bit 0) or step 1 on victory (bit 1). It calls g_BattleChooseEndingHook and SND_SetBankLayout(0), and streams slot 1 (BATL_END) for step 1 or slot 2 (BATL_OVR) for step 2. In a scripted battle, g_BattleChooseEndingHook sets the step. That the boss hook does this is [inferred].
Victory. BATL_END runs at 0x801EEC00. Its entry is the image head plus 0x58, and it dispatches on g_BattleUiStep. Battle_GrantQueuedItems (emi/battle/batl_end/00@0x801EF870) grants the queued items (D_80146327: a count, 16 item words, 16 levels) through Party_AddItem and sets g_BattleStep = 4. The experience and money payout code lives in the same image and is not traced [unknown].
Defeat. BATL_OVR also runs at 0x801EEC00. Its entry is the image head plus 4. Battle_UpdateGameOver (emi/battle/batl_ovr/00@0x801EF0A8) fades the screen, frees the palette rows, clears g_BattleEncounter, g_BattleOptions and the mode bytes, then runs SND_Exit and CallbackReplace(SYS_StartFrontend). The game returns to the first load and the title.
Exit. Step 4, sub-step 2 is Battle_WriteBackParty (emi/battle/battle/03@0x801D7350). It revives party rows with status bit 0x4000 (KO): current HP and willpower become 1, fatigue rises by 1 while it is below 5, the status loses bit 0x4000, and the flag byte loses bit 0x04. Living rows are untouched. It then zeroes every battle byte and increments g_GameEntrySubstate to 6. Substate 7 hands control back to the field (g_GameEntryState = 2).
Default hooks. For a random battle func_801E320C (the first enemy step handler, D_801EB3B0[0]) installs Battle_HandleDesertDefeat as g_BattleChooseEndingHook and func_801E57C8 as g_BattleEndHook. In area 0xBD (D_80143F04 == 0xBD) a defeat does not go to game over. The hooks request a scene (D_80146875 = 0x19) and a screen effect. What the scene is, is [unknown].
Boss modules
Section titled “Boss modules”A scripted boss battle runs extra code from a boss module, the code entry of a BOSSnnn.EMI archive. It sits at 0x800C1800 and is entry 16 of the archive (entry 13 for boss001, boss004, boss022, boss025 and boss031). Random battles do not load one.
Boss_InstallBattleHooks stores three function pointers: Boss_ChooseBattleEnding into g_BattleChooseEndingHook (0x801463A4), Boss_EndBattle into g_BattleEndHook (0x801463A8) and Boss_HandleBattleEvent into g_BossBattleEventHook (0x801463AC). Each of the 35 boss modules has its own copy. A jal never calls it. Battle_UpdateEnemies runs, for each of the 8 enemy slots, D_801EB298[enemy->unk_F0]() in a scripted battle and D_801EB294[enemy->unk_F0]() (one entry, func_801E31C8) otherwise. D_801EB298 has 63 entries, and the targets lie in the boss window (func_800C1804 onward). For boss015 the target Boss_InstallBattleHooks is the installer’s address, so the installer runs as the per-frame enemy handler of a boss whose kind index matches. That every module is reached this way is [inferred]; the table-to-module match for the other 34 is [unknown].
Installer addresses in the boss window, by module. A module that has more than one installer publishes variants of the three hooks.
| Installer | Modules and addresses |
|---|---|
...Hooks |
boss015, boss029 0x800C18F0; boss037, boss042 0x800C18FC; boss050 0x800C1908; boss054 0x800C1930; boss023 0x800C1984; boss017 0x800C19C4; boss031, boss032 0x800C19C8; boss030 0x800C19DC; boss014, boss024 0x800C19E8; boss040, boss049 0x800C19F4; boss022 0x800C1A08; boss007 0x800C1A0C; boss051 0x800C1A14; boss021 0x800C1AD0; boss052 0x800C1B0C; boss028 0x800C1B40; boss035 0x800C1B4C; boss012 0x800C1B68; boss038 0x800C1B7C; boss004 0x800C1C0C; boss002 0x800C1D50; boss033 0x800C1D70; boss036 0x800C1D78; boss001 0x800C1E50; boss008 0x800C1F9C; boss013 0x800C200C; boss018 0x800C2114; boss034 0x800C2340; boss055 0x800C24A0; boss025 0x800C2B60 |
...Hooks2 |
boss040, boss049 0x800C1A88; boss014 0x800C1A94; boss024 0x800C1AB0; boss035 0x800C1C70; boss036 0x800C1E0C; boss002 0x800C1E3C; boss004 0x800C1FB0; boss008 0x800C2088; boss018 0x800C23F8; boss025 0x800C2710 |
...Hooks3 |
boss002 0x800C1F08; boss008 0x800C2184; boss004 0x800C234C; boss018 0x800C26DC |
BATL_END and BATL_OVR follow the same code-entry head convention: a word that equals the table of contents’ cached first word, then the entries named above.
Archives in a battle
Section titled “Archives in a battle”| Archive (slot) | Loaded by | Window |
|---|---|---|
BPLU 0x1EE or BPLD 0x1DB family |
entry substate 1 (EMI_GetArchiveId) |
character sprites |
BATTLE 6, BATTLE2 7, BOSS 0x1B3+ |
entry substate 3 (Battle_LoadBattleArchive) |
battle overlay; boss module at 0x800C1800 |
ENEMY 0x9 + area |
func_801D1228 (random battle) |
enemy archive |
BATL_SE 5 |
func_801D277C, func_801D25A0, func_8009B488 |
sound bank |
BATL_RET 4, BATL_RE2 3 |
func_801D3E80; several sites in battle/battle/15 |
effect archives |
BATL_DRA 0 |
Battle_LoadDraArchive (battle/battle/15) |
effect archive |
COMN_SE 8 |
func_801D656C |
sound bank |
BATL_END 1 or BATL_OVR 2 |
Battle_LoadEndOverlay |
0x801EEC00 |
AREA 0x2AB + area, AFLDKWA 0x256 |
mode 5 steps 3 and 4 | area image, field sound |
The loader streams one archive at a time (loading); the windows are in memory.
Data and limits
Section titled “Data and limits”Battler rows and enemy record fields are in battle records; the encounter block is in the area format.
| Limit | Value | Source |
|---|---|---|
| Formation weights | Roll 1 to 16 against the running sum of the eight weights | Area_PickEncounter; a roll above the total gives formation 0 |
| Step threshold | Base 0 to 120, random part capped by the pair’s second byte | s_EncounterStepThresholds[16] |
Zone rate |
0 to 7 (index rate * 2 into a 16-byte table) |
Area_RollEncounterThreshold |
| Encounter zone lists | 200 lists over 666 records of 8 bytes | D_80181164[200], g_AreaEncounterZones[666] |
| End-of-battle item queue | 16 entries (member sizes 32 and 16 bytes) [inferred] |
PartyGrantQueue in Battle_GrantQueuedItems |
| Target pick tables | Partial party {9,7}, {12,4}, {8,8}; full party six rows of 3 |
s_BattlePartialPartyTargetWeights, s_BattleFullPartyTargetWeights |
| Random ability pools | 32 slots each (Recall, MagicShuffle) |
g_BattleRecallAbilities, g_BattleMagicShuffleAbilities |
An edit must keep these limits:
- Formation weights. Make the eight weights total 16. A lower total sends high rolls to formation 0. A higher total makes the last formations unreachable.
- Enemy slots. A formation with no enemy id in slots 0 to 2 can roll no active enemy, and the field step then continues without a battle.
- Zone rate. Keep
rateat 7 or less. - New scripted battle. It needs a record in
s_BattleModeRecords, an archive column that exists ing_BossArchiveSlots, and a boss module in theBOSSarchive when its enemies use a boss handler.
Open questions
Section titled “Open questions”| Question | What would settle it |
|---|---|
Mode-5 step 3 writer (D_801EAD0C: area reload) is not reached by a read |
Search the batl_end and boss overlays for g_BattleStep = 3. |
| Meaning of the seven boss event codes | Read Boss_HandleBattleEvent in several modules. |
Per-boss D_801EB298 index to module mapping (34 of 35) |
Read each module’s head for the installer address, match to the table. |
Reward payout (experience, money, drops) in BATL_END |
Read the BATL_END functions after Battle_GrantQueuedItems. |
Trait ids (3, 0x14) and (3, 0x15) for the step threshold |
Read func_801C38F4 and the ability trait table. |
Meaning of the D_80143EFC >= 0xF1 gate |
Find its writers in the field engine. |
Scene 0x19 requested by the area 0xBD defeat hook |
Read the scenario that owns it. |
| Mode names (party commands, turn order, actions, round end, result) | Read the mode 1 to 4 steps in full, or an emulator trace. |
| Scripted-battle starts in scenario overlays not read | Search the scenario overlays for calls to Battle_StartScripted. |
Sources and confidence
Section titled “Sources and confidence”- Confidence: medium. The start paths, the entry substates, the mode dispatch, the formation roll and the exit are read in the code. The mode names, the boss event codes, the reward payout and most boss-module links are
[inferred]or[unknown]. - Evidence:
emi/etc/game/00,emi/battle/battle/03,BATL_END,BATL_OVR, the boss module installers, and the encounter block read from RAM.
Related
Section titled “Related”- Battle records: battler rows, enemy records, status words.
- Game phases: entry states and request codes.
- Areas and the field: the zone list behind the step threshold.
- Area formats: the encounter block and enemy record.
- Loading: archive streaming.