Skip to content

Frame loop

After boot, SYS_Main (exe/slus_004_22@0x8014AAC8) never returns. Every frame, from the title to the credits, is one pass through this loop. The loop owns the display, the controller read and the CD loader tick; game logic runs in the four callback threads of the scheduler. Primitive layouts: rendering.

The display is double-buffered. Each buffer has a 144-byte render record at g_GfxDisplayFrames (exe/slus_004_22@0x80143D48). A record holds the display and draw environments, an 8-word ordering table and the arena in which the frame’s primitives are built. VRAM holds two 320 x 240 frame buffers, one at y = 0 and one at y = 0xF0. Each record draws into one buffer and displays the other.

While the GPU draws frame N from one record, the CPU builds frame N + 1 in the other. g_FrameBufferIndex (exe/slus_004_22@0x80143D44) selects the record being built and flips once per pass. The GPU starts early in the pass and runs in parallel with the controller read, the callbacks and the loader tick. The pass ends by waiting for the GPU. A picture appears one pass after the logic that built it.

Game code reaches the primitive arena through GFX_AddPrim (exe/slus_004_22@0x8014E5A0). Each call appends one primitive to one of eight layer chains. At the end of the pass SYS_SubmitFrame (exe/slus_004_22@0x8014B0F0) splices the eight chains into the record’s ordering table.

CallbackRun (exe/slus_004_22@0x8014B73C) is the only place game code runs: up to four cooperative kernel threads, one per callback slot. Each runs until it calls CallbackWait (resume after n passes) or CallbackExit; control then returns to CallbackRun, which moves to the next slot. Nothing pre-empts a thread, so a thread that never yields freezes the game. Slot assignments: scheduler.

SYS_Main runs these steps in order once per pass. The GPU work that step 5 starts overlaps steps 6 to 11; step 12 waits for it.

Step Call Effect
1 VSync(2) wait until two vertical blanks have passed since the previous VSync call
2 rand() advance the PsyQ random state once
3 PutDispEnv, PutDrawEnv apply the environments of the record that the previous pass built
4 GFX_UploadPalette, GFX_UpdateTransferQueue copy the staged palette and the queued images to VRAM
5 DrawOTag start the GPU on the ordering table that the previous pass built
6 SYS_UpdateKeyState read controller 1
7 SND_UpdateVoiceStatus (exe/slus_004_22@0x8015D044) refresh the status bytes of the 24 SPU voices
8 flip g_FrameBufferIndex; ClearOTagR; SYS_PrepareFrame select the other record and reset its table, layer chains and primitive cursor
9 reset-combo check on g_InputHeld request the soft reset when Select and Start have been held long enough
10 CallbackRun run every active callback thread until it yields
11 EMI_Update tick the CD loader or the XA audio player
12 g_SysLastVSync = VSync(1); DrawSync(0); SYS_SubmitFrame; g_FrameCount++ wait for the GPU, then link the new layer chains into the ordering table; count the pass

VSync(2) caps the loop at one pass per two vertical blanks. On an NTSC display, which SYS_InitHardware (exe/slus_004_22@0x8014AD28) selects, that is 30 passes per second. A longer pass slows the game; frames are not dropped. [inferred] from the PsyQ VSync contract and the NTSC mode. The play clock agrees: Game_UpdateClock (emi/etc/game/00@0x80198CAC) adds one tick per main-loop pass and rolls 30 ticks into one second.

The GPU overlap with steps 6 to 11 follows from the PsyQ contract that DrawOTag starts a DMA and returns. [inferred]

Fields of one 144-byte render record that the loop addresses:

Offset Size Type Meaning
0x00 20 DISPENV the display environment
0x14 92 DRAWENV the draw environment
0x70 32 u32[8] ordering table, 8 words, cleared in reverse by ClearOTagR
0x8C 4 u32 the last word of the table, the address that DrawOTag receives

SYS_PrepareFrame (exe/slus_004_22@0x8014B020) resets the record that is about to be built. For buffer index b it:

  • sets the primitive cursor g_GfxPrimCursor to 0x80020000 + b * 0x9000;
  • seeds the eight layer chain heads from the packet table, b * 0x20 bytes in;
  • resets 56 cell records of 48 bytes at D_80142CC0 [inferred], which the area map engine uses;
  • sets D_801459F8 to 0x800E4800 and D_801459FC to 0x800F5000, the area work window and the area code base.

GFX_AddPrim appends a primitive only while the cursor plus the primitive size stays below 0x80028FCC + b * 0x9000, so the arena of one buffer is 36,812 bytes. When it is full the call returns silently and the primitive is lost. Every sprite, window, glyph and map cell of a frame draws from this arena.

SYS_UpdateKeyState (exe/slus_004_22@0x8014AFC0) calls PadRead(0), which returns both ports in one 32-bit word. It stores the held buttons of each half, keeps the previous values, and computes the newly pressed bits as pad & (pad ^ previous). The rest of the game reads g_InputHeld (exe/slus_004_22@0x80145AA4) and g_InputPressed (exe/slus_004_22@0x80145AA8), which are the port 1 words. The port 2 half is stored, and no reader of it is known. [unknown]

Holding Select and Start together returns the game to the first boot callback. The test is (g_InputHeld & (PADselect | PADstart)) == 0x900. A counter g_SysResetHoldFrames (exe/slus_004_22@0x80143F44) counts the passes in which it holds and clears when it stops. On the 61st pass in a row (about 2 seconds), and only if EMI_IsReady is true, the loop runs SND_Exit and CallbackStopAll, then CallbackRegister(0, SYS_StartFrontend). The game reloads FIRST.EMI and GAME.EMI and returns to the title without the logo. If the loader is busy, the reset waits.

EMI_Update (exe/slus_004_22@0x80163010) looks at g_EmiServiceMode. In mode 1 it runs EMI_UpdateStream, the disc read for overlays and data. In mode 2 it runs SND_UpdateXA, the XA audio player. In any other mode it does nothing (loading, audio system).

A random encounter does not start in a frame whose drawing ended late. SYS_CaptureDrawTime (exe/slus_004_22@0x8014B17C) is the DrawSync callback and stores VSync(1) in D_80143EFC. Area_CanStartEncounter (emi/etc/game/00@0x801B3EB0) returns 0 when D_80143EFC >= 0xF1 and g_GameRequestFlags bit 0 is clear. By the PsyQ contract VSync(1) returns the horizontal blanks elapsed since the last VSync call, so the limit is about 240 scan lines. [inferred]

Question What would settle it
Whether a 21st queued VRAM upload overflows the 20-entry queue Read the producers of D_80145A00 for a bound check
Any use of the port 2 controller Search for readers of the high halves that SYS_UpdateKeyState writes
Real frame time and the CPU and GPU overlap A timed run; static reading cannot measure it
The unit of D_80143EFC The PsyQ VSync documentation, then compare with 0xF1
  • Confidence: medium. The order of the pass, the records and the limits are read in the code, but the frame rate, the GPU overlap and the unit of the late-frame value are [inferred] from the PsyQ contract.
  • Evidence: the code of SYS_Main, SYS_PrepareFrame, SYS_SubmitFrame, GFX_AddPrim, GFX_UpdateTransferQueue, SYS_UpdateKeyState, CallbackRun and EMI_Update; the play clock of Game_UpdateClock.
  • Scheduler and tasks: what runs in each callback thread.
  • Rendering: primitive layouts, layer order and drawing.
  • Loading: what the loader tick does with a stream.
  • Boot: how the first pass starts.