CPU

CPU

The CPU is the glue. It doesn't execute machine code or anything like that — it just sets everything up, owns the other hardware components, and keeps the loop running.

---

What it does on startup

1. Sets the window to 512×512 and centers it on screen
2. Creates the PPU and APU as child nodes
3. Loads the ROM and injects ppu, apu, and cpu references into it
4. Starts calling rom.tick(delta) every frame

The reference injection happens automatically — as long as your ROM has variables named ppu, apu, and cpu, the CPU will fill them in before anything runs.

---

The loop

Every frame, the CPU calls rom.tick(delta). That's it. Everything your program does happens inside that function.

The loop stops if the CPU is halted or crashed. In both cases tick just doesn't get called until the state changes (or at all, in the case of a crash).

---

Halting

Halting is a pause. Press Enter to toggle it on and off.

When halted:

• tick stops being called
• The screen freezes on whatever was last drawn
• The APU keeps running (audio doesn't stop)
• Press Enter again to resume exactly where you left off

Nothing resets. It's just a pause.

---

Panicking

A panic is a permanent crash. Once it happens, the CPU is done — tick never runs again and you have to restart the project to recover.

You can trigger one from your ROM:

cpu.panic("SHORT MESSAGE")
# or with a separate longer explanation
cpu.panic("SHORT MESSAGE", "More detail about what went wrong")

When panic is called, the CPU:

1. Sets crashed = true and halted = true
2. Waits one frame for the scene to settle
3. Draws a black overlay on the current screen using the PPU
4. Renders "ILLEGAL INSTRUCTION" at the top, then your short reason below it, then the full reason below that
5. Emits a cpu_panic signal in case anything external needs to react

The panic screen looks like this:

ILLEGAL INSTRUCTION
SHORT MESSAGE
full reason here

It also fires automatically if the PPU tries to draw a character that isn't in the font — though that usually means something went wrong upstream.