emulator-architecture

name	emulator-architecture
description	Prime context for architectural discussions about SvelteBoy's design patterns, component interactions, timing model, and trade-offs vs. general emulator approaches

Main loop (assembly/emulator.ts)

Emulator.Tick(): CPU-driven catch-up per instruction.

cycles = Cpu.Tick()
Timer.Tick(cycles)
Ppu.Tick() × cycles   (1 dot/T-cycle)
Dma.Tick() if active

Run(timeMs) / RunFrames(n) loop on Tick() until GetStopReason() != None.

Component sync strategies

CPU/PPU/Timer/DMA: instruction-boundary catch-up; tightly coupled via returned cycle count.

APU: decoupled event-queue. CPU writes to audio registers → AudioRender.EnqueueEvent(type, val) with timestamp (CycleCount - init) * SAMPLE_RATE / CYCLES_PER_SECOND. End-of-frame AudioRender.Render() replays queue, synthesizing between event timestamps. Decouples synthesis from emulation speed.

PPU (assembly/io/video/ppu.ts)

Full pixel FIFO pipeline, not scanline-at-end. State machine: OAMScan (80 dots) → Transfer (172–289 dots, variable due to sprite/window stalls) → HBlank → VBlank (lines 144–153). Variable Mode 3 duration captures mid-scanline effects correctly.

Timer (assembly/io/timer.ts)

16-bit internalDiv increments every T-cycle. TIMA increments on watched-bit 1→0 transition:

TAC	bit	freq
00	9	4 kHz
01	3	256 kHz
10	5	64 kHz
11	7	16 kHz

Writing DIV resets internalDiv to 0 — can spuriously increment TIMA if watched bit was 1.

Memory bus (assembly/memory/memoryMap.ts)

• Raw load/store for VRAM/WRAM/OAM/HRAM (precomputed WASM offsets, no dispatch)
• GBload/GBstore dispatched gate for IO/cartridge/bootrom → io.ts routes by address
• MBC1/2/3 in assembly/memory/mbc*.ts behind common interface

Component model

All components (Cpu, Ppu, Apu, Timer, MemoryMap, AudioRender) are @final static classes — no instantiation. Circular references (CPU↔MMU↔PPU) are direct static calls. Static fields at known WASM offsets; cache-friendly.

Timing accuracy

• PPU ticked 4×/M-cycle (required for STAT interrupt timing)
• Conditional branches return actual cycles taken
• EI delay: Cpu.isEnablingIME — IME takes effect after next instruction
• Interrupts: all components call Interrupt.Request(IntType.X); CPU polls Interrupt.HandleInterrupts() each tick
• Register writes land immediately; Transfer reads current values — raster effects work correctly

Per-frame call counts (~69,905 T-cycles, ~17,476 instructions)

Ppu.Tick() dominates (~69,905 calls). Most OAMScan/HBlank calls are no-ops (dot increment only).

$ARGUMENTS