Skip to content

Architecture Overview ​

The project is split into a few clear concerns:

  • rust/: emulator core logic, memory model, GPU, APU, saves, and test suite
  • src/: browser application code and wasm bridge
  • public/: generated wasm assets (public/wasm/), featured cover art, and app icons
  • doc/: public project documentation built with VitePress
  • scripts/: maintenance scripts, such as fetching cover art

System at a glance ​

Pecten is a single-page React app that runs the emulator as a WebAssembly module in the same browser tab. The React shell owns everything the player sees and touches; the Rust core owns the machine. They meet only at the WasmEmulator API (WASM Boundary).

Build pipeline ​

Two toolchains produce one static site. wasm-pack compiles the Rust crate to WebAssembly and writes the module and its JavaScript glue into public/wasm/. Vite then builds the React app; it copies public/ as-is, and wasmBridge.ts imports wasm/pecten.js at runtime (/* @vite-ignore */), so the wasm module is never bundled. VitePress builds this documentation separately, and the deploy workflow places it under /docs/. The commands are listed in Development Workflow.

pnpm build runs the first three steps in order (wasm:build, tsc -b, vite build); pnpm dev runs wasm:build and then the Vite dev server, so a core change needs pnpm wasm:build (or a restart) to reach the page. On every push to main, .github/workflows/deploy-docs.yml installs Rust with the wasm32-unknown-unknown target and wasm-pack, runs pnpm build and pnpm docs:build, and publishes dist/.

Inside the core ​

GbaCore owns three parts: the CPU, the memory map, and the renderer. MemoryMap owns every memory region and every device that is clocked with memory, so the CPU advances all of them through one call, advance_video_cycles. The browser never reaches past WasmEmulator.

CPU, HLE BIOS, and interrupts ​

Each call to ThumbCpu::step_with_cycles does exactly one unit of work and returns the cycles it took, which MemoryMap then spends on timers, the APU, display timing, and DMA triggers. GbaCore::step_frame repeats it until the display enters VBlank, rendering each scanline as soon as its HBlank begins (GPU Pipeline).

No real BIOS runs. The generated image only holds the exception vectors and the hardware IRQ dispatcher, so a game's interrupt handler is entered exactly as on hardware, while SWI calls are answered by Rust code in a single step (HLE BIOS):

Separation of responsibilities ​

Emulator core ​

The Rust crate owns simulation correctness: reading and writing memory, processing rendering state, and modeling game-system behavior. It has no dependency on the browser.

ModuleResponsibilityDocs
lib.rsGbaCore (frame stepping, save states) and the wasm_bindgen exportsWASM Boundary
cpu/ARM7TDMI interpreter (mod.rs core state, arm.rs, thumb.rs, alu.rs flags and shifter) and HLE BIOS services (bios_hle.rs)ARM7TDMI CPU, HLE BIOS
bios.rsGenerated BIOS image: vectors and IRQ dispatcherHLE BIOS
memory/Bus, I/O registers, and the video clock (mod.rs), DMA (dma.rs), and timers (timers.rs)Memory Map
cartridge.rsCartridge header validationMemory Map
backup.rsSRAM, Flash, and EEPROM save memoryMemory Map
gpu.rsScanline rendererGPU Core
apu.rsSound channels and mixingAudio
state.rsSave-state serializationWASM Boundary

Browser layer ​

The app shell owns user experience: controls, canvas presentation, input handling, and the browser-specific environment.

ModuleResponsibility
App.tsxRoutes (home, play, library), the frame loop, settings, and the Saves and Settings dialogs
wasmBridge.tsLoads and types the generated bindings
keypad.ts, TouchControls.tsx, haptics.tsKeyboard and touch input, haptic ticks
audio.tsAudioWorklet output at the game speed
backupStorage.ts, savedGames.tsIndexedDB storage for saves and states, and for the ROM library
CoverFlow.tsx, coverFlowMotion.ts, featuredGames.tsHome page cover flow
touchThemes.tsTouch-control colour themes (palettes in App.css)
InstallPrompt.tsxPWA install prompt

WASM boundary ​

The boundary between the browser and the Rust core is intentionally narrow. The app loads the wasm module and calls small exported functions that return plain data structures like bytes or basic values. See WASM Boundary.