Scenario engine
The story runs as 20 overlay programs, SCENA00 to SCENA19, and one is active at a time. The active scenario sets how each area behaves and what each step into a cell does; a story flag it sets opens a door in areas and the field. The resident field code in emi/etc/game/00 loads the scenario into a fixed RAM window and calls it at fixed points of the frame loop. The story meaning of each scenario is not established.
The event stage, a smaller layer, runs one-off handlers selected by an event id. This page covers both layers and the story flags. Overlay placement: memory, loading.
Starting a scenario
Section titled “Starting a scenario”Scene_Start (emi/etc/game/00@0x801A7704) takes a scenario number n and does four things:
- Writes
ntog_SceneState.scenario_idand zeroes the rest of the state (mode_02,state_04,step_05,timer_06,flags_01). - Clears the first 32 flags of scenario
n’s flag word and pointsg_SceneFlagsat that word. - Streams the scenario’s code from EMI slot
n + 0x295(Scene_LoadOverlay), waiting withCallbackWait(1)untilEMI_IsReadyreports done. During the wait it callsfunc_801992B8each frame once an area is loaded and the game state index is not 5. - Runs
Game_UpdateScenarioonce.
Game_UpdateField (emi/etc/game/00@0x80197378) runs Game_UpdateScenario once per field frame, then g_SceneStates[D_801448EA]() runs the event stage. func_80199230 and Game_UpdateMenuFrame also call it. Game_UpdateScenario calls g_SceneScenes[n]->entry_00().
Three places start a scenario:
| Caller | Argument | When |
|---|---|---|
Game_StartSelectedGame (emi/etc/game/01@0x801D0E54) |
16 | The title selection ends. It also registers Game_UpdateMain in callback slot 0. |
Menu_StartNewGame (emi/etc/start/08@0x801E2584) |
0 | New Game. It sets D_801448EA = 0, g_GameAreaId = 0xFFFF, clears the 20 flag words, then CallbackReplace(Game_UpdateMain). |
func_8019FAA0 (emi/etc/game/00@0x8019FAA0) |
scenario_id + 1, skipping 16 |
Chapter advance, below. |
The controller overlay
Section titled “The controller overlay”g_SceneScenes (emi/etc/game/00@0x801C8454) is a table of 20 absolute pointers, one per scenario, into the window 0x801F6C00..0x801FEA80 (32,384 bytes). Every scenario is built for that window, so each pointer is fixed. The SCENA00 handler block sits at 0x801FC9FC, the SCENA16 block at 0x801F8538.
The first word of each loaded image is its module id, 0x105 + n (0x105 for SCENA00, 0x118 for SCENA19). The type-0 loader checks it against the archive table of contents (loading).
The pointer in g_SceneScenes leads to a handler block of five code pointers. The resident code calls them through the wrapper named in the Evidence column.
| Offset | Type | Name | Meaning | Evidence |
|---|---|---|---|---|
0x00 |
void* |
entry_00 |
Per-frame controller. SCENA00 and SCENA16 read mode_02 and jump through a mode table. |
Game_UpdateScenario |
0x04 |
void* |
entry_04 |
void (record). The player talks to or touches an entity whose callback_index is set. |
Game_DispatchScenarioRecord |
0x08 |
void* |
entry_08 |
s8 (x, y). A nonzero result blocks the step into the cell. Zero falls back to func_801A8728, a switch on the area id. |
func_801B0E44 through Area_IsStepBlocked |
0x0C |
void* |
entry_0C |
s8 (x, y). A nonzero result overrides the cell test. Zero falls back to func_801A8B84. |
func_801B146C through func_801A79A4 |
0x10 |
void* |
entry_10 |
s8 (a, b), optional. A negative or null result falls back to Game_CallAreaHandler, which reads the area hook table D_801C86F8. |
func_801B6258 through Game_CallScenarioHandler |
The wrappers are Area_IsStepBlocked (emi/etc/game/00@0x801A7914), func_801A79A4, Game_CallScenarioHandler (emi/etc/game/00@0x801A7A34) and Game_DispatchScenarioRecord (emi/etc/game/00@0x801A7878). A scenario overrides only what differs from the default; the fallbacks cover the rest.
In SCENA00 the five words are at 0x801FC9FC and the mode table follows at 0x801FCA10. entry_00 (0x801F913C) loads D_80146872 (mode_02) and jumps through that table. SCENA16 stores its handler block as one array: slots 0 to 4, then mode handlers from index 5, then state handlers from index 8, then three (record, state) event handlers. The other 18 controllers are not decoded. That their entry_00 starts with a mode_02 jump is [inferred].
Scenario state
Section titled “Scenario state”g_SceneState (0x80146870, 16 bytes) is the controller’s working memory. The table lists its fields by offset.
| Offset | Type | Name | Meaning |
|---|---|---|---|
0x00 |
s8 |
scenario_id |
Index into g_SceneScenes and the EMI slot offset. |
0x01 |
u8 |
flags_01 |
Bit 0x80 requests a chapter advance. Bit 0x20 is set by func_8019A904; no reader is known. |
0x02 |
u8 |
mode_02 |
Dispatch byte of the controller. |
0x04 |
s8 |
state_04 |
Second-level state, used by SCENA16 and others. |
0x05 |
u8 |
step_05 |
Third-level step. |
0x06 |
u16 |
timer_06 |
Countdown for the step. |
typedef struct SceneState { s8 scenario_id; /* 0x00 */ u8 flags_01; /* 0x01 */ u8 mode_02; /* 0x02 */ u8 unk_03; /* 0x03 */ s8 state_04; /* 0x04 */ u8 step_05; /* 0x05 */ u16 timer_06; /* 0x06 */ u16 unk_08; /* 0x08 */ u8 pad_0A[6]; /* 0x0A */} SceneState;Source: include/scenario/state.h
SAVE_RunLoadRestore (emi/etc/start/08@0x801E5FD4) copies 16 bytes from D_801448D8 into g_SceneState on load. The flag words (block +0x5B0) and the event-flag block (block +0x650) lie inside the persistent block (state), so the card file carries both (saving). g_SceneState itself lies outside the block; the save copies it into the block’s first 16 bytes.
Chapter advance
Section titled “Chapter advance”Scene_RequestChapterAdvance (emi/etc/game/00@0x801A78F8) sets bit 0x80 of flags_01; a controller calls it when its chapter is done. On the next area load, func_8019FAA0 sees the bit, increments scenario_id (16 becomes 17), and calls Scene_Start, which clears flags_01, so one request advances one chapter. The test is at 0x8019FD18..0x8019FD68.
func_8019FAA0 also sets mode_02 = 1 just before it calls Game_UpdateScenario, so a controller sees mode 1 on every arrival in a new area.
SCENA00 to SCENA15 each call Scene_RequestChapterAdvance; SCENA16 to SCENA19 do not. The result is a linear chain SCENA00 to SCENA15, then SCENA17. The title selection starts SCENA16 directly.
Scenarios on the disc
Section titled “Scenarios on the disc”All 20 images are scenario/scenaNN entries. The largest, SCENA08, fills the 32,384-byte window. The table lists the decoded ones.
| Scenario | What is established |
|---|---|
SCENA00 |
New Game start. Calls Game_RequestAreaChange(9, 0x570000, 0x40000, 7) (phases). |
SCENA07, SCENA08 |
Stream slots 0x254 (A085SE2) and 0x255 (A108SE2). |
SCENA10 |
Streams slot 0x290 (SCE10EFF) into 0x801D0C00, waits 30 frames (g_SceneState.timer_06 = 0x1E), then calls Message_StartAreaMessage. |
SCENA15 |
Streams slots 0x291, 0x292 and 0x294, the SCE15EF* effect overlays. |
SCENA16 |
Started by the title selection. Enters area 4 at (0x1A0000, 0x88000) with BGM 6. Mode 1 branches on the area id (2, 4 or 31). Three-level mode_02, state_04, step_05 machine. Its role as the title attract or intro scene is [inferred]. |
SCENA17 |
Streams 0x260 (ENDKANJI) and 0x266 (SHOP). Its role as the ending is [inferred]. |
SCENA18, SCENA19 |
Stubs: mode setters and an empty handler. |
| others | [unknown]; not decoded. |
The effect overlays run in the shared window at 0x801D0C00. Scene_UpdateEffect (emi/scenario/sce10eff/00@0x801D0C10) picks one of three handlers (begin, end, run) by byte 1 of g_SpadWork. The begin handler stages scene objects of type 0x69 through Actor_FindFreeSlot (emi/etc/game/00@0x8019601C). The call site that enters Scene_UpdateEffect is [unknown].
Event stage
Section titled “Event stage”The event stage is a two-state machine that sits beside the controller. Game_UpdateScene (emi/etc/game/00@0x801A7BF0) indexes the two-entry table g_SceneStates by D_801448EA.
- State 0 is
Scene_ResetEventState (emi/etc/game/00@0x801A7C2C). It setsD_801448EA = 1, clears the event bytesD_801448E8..F0, and reloads the first 16 bytes ofg_SceneEventFlagsfroms_EventFlagsReset(08 00 00 0A, then zeros). - State 1 is
Scene_UpdateEvent (emi/etc/game/00@0x801A7CAC). It callsg_SceneEvents[D_801448EB].
D_801448EB is the event id. Field code writes it (func_801B6674 writes 0x37 and 0x1B). Handler 0, func_801A7CE8, is the idle handler, so id 0 means no event. Each active handler returns the stage to idle by clearing D_801448EB, and keeps its own sub-step in D_801448EC.
g_SceneEvents has 64 entries. The ones known:
| Event id | Handler | Reading |
|---|---|---|
| 0 | func_801A7CE8 |
Idle [inferred]. |
| 4 | Menu_OpenMaster |
Master screen: streams SISYOU, then Menu_UpdateMaster, and restores the party archive. |
| 5, 6, 10, 27, 44, 55 | func_801A7E54, Message_RunAreaMessage, Scene_StartShopSave, func_801A839C, func_801A83DC, func_801A852C |
Resident event handlers. Roles [unknown]. |
| others | Addresses in 0x801F.... |
Code at fixed addresses inside the scenario window. |
Scene_DispatchObject (emi/etc/game/00@0x801A86D4) does the same for entities: it runs g_SceneObjects[callback_index](record, g_SceneEventFlags), which Game_DispatchScenarioRecord uses when unk_7C & 0x4000 is set in the record. g_SceneObjects has 66 entries. The setup stream writes callback_index with opcode D (area).
Story state lives in three bit arrays. All are read with SYS_TestFlag (exe/slus_004_22@0x8015B5D4), whose bit argument is a u8: it indexes at most 256 bits, 32 bytes, from the array start.
| Array | Address | Type | Size | Use |
|---|---|---|---|---|
g_SceneFlagWords |
0x80144E88 |
u8[160] |
20 words of 8 bytes | One word per scenario. Scene_Start clears bits 0 to 31 of the started word. |
g_SceneFlags |
0x8014686C |
u32* |
pointer | The active scenario’s word. Controllers use SYS_SetFlag(g_SceneFlags, bit). |
g_SceneEventFlags |
0x80144F28 |
u8[40] |
40 bytes | Event flags. Scene_ResetEventState resets the first 16 bytes. |
An exit door can test any scenario’s word: func_801A0048 reads SYS_TestFlag(g_SceneFlagWords + (b << 3), bit) for the scenario byte b of a door row (area).
A scenario word has 64 bits. The test does not check the bit against the word, so bit 64 or above reads the next scenario’s word, and the words run straight into the event flags.
Limits on an edit
Section titled “Limits on an edit”- Handler block address.
g_SceneScenes[n]holds an absolute address: the block must sit there, or the table must change. The first word of the image stays0x105 + n. - Window size. The image fits 32,384 bytes.
- Handler addresses. A handler address in
g_SceneEventsorg_SceneObjectsthat lies in the area window runs whatever the loaded area program places there (area). - Slot range. Scenario code uses EMI slots
0x295-0x2A8. The effect overlays use0x290-0x294. - Save compatibility.
scenario_id, the flag words and the event flags are part of the saved block and are restored on load (saving).
Open questions
Section titled “Open questions”| Question | What would settle it |
|---|---|
| Story meaning of each scenario and each flag bit | Read each controller’s mode table and the SYS_SetFlag sites. |
| Mode and state counts of the 18 undecoded controllers | Read the five-word block and the table after it for each. |
Caller that enters Scene_UpdateEffect, and the SCE15EF* overlays |
Find the call into 0x801D0C10 from SCENA10 and SCENA15. |
Purpose of SCENA16 and SCENA17 |
Trace the title idle path and the ending path. |
Roles of event ids 5, 6, 10, 27, 44, 55 and the 0x801F.... handlers |
Read each handler and the writers of D_801448EB (func_801B6674 and others). |
Reader of the flags_01 & 0x20 bit set by func_8019A904 |
Find its readers. |
Sources and confidence
Section titled “Sources and confidence”- Confidence: medium. The loader, the handler block, the wrappers, the event stage and the flag arrays are read in the code. Two of the 20 controllers are decoded, and the story meaning of every scenario and flag is not established.
- Evidence: the functions named above in
emi/etc/game/00, the handler blocks and mode tables ofSCENA00andSCENA16, the module ids and stream calls in the other scenario images, and the table of contents of the scenario slots.
Related
Section titled “Related”- Areas and the field: the area load that advances a chapter, and the doors that test scenario flags.
- Game phases: where the scenario entry sits among the entry states.
- Persistent state: the block that holds the flag words and
g_SceneState. - Loading: how the scenario slots stream into the window.
- Edit maps and scripts: what to keep when you change a scenario.
- Area formats: the script and scene tables a scenario reads.
- EMI container: the archive and entry types that carry a scenario.