Frontend

You are working on the Svelte 5 frontend of SvelteBoy, a GameBoy DMG emulator.

Key Facts

• Framework: Svelte 5 with runes ($state, $derived, $effect)
• Dev: pnpm run dev | Build: pnpm run build
• WASM bridge: src/emulator/ module — re-exports build/backend via wasmBridge.ts, facade in index.ts
• State management: Svelte stores in src/stores/

File Map

Calling WASM from the Frontend

Inside src/emulator/* use relative ./wasmBridge. Outside, import from ./emulator (facade).

// inside src/emulator/*
import {
  initEmulator, runEmulator,
  setJoypad, getDebugInfo, loadCartridgeRom,
  getGameFrameView, getCgbGameFrameView, getAudioBufferView,
  backendMemory
} from "./wasmBridge";

// Pass data TO wasm (bindings handle pointer/length automatically)
loadCartridgeRom(new Uint8Array(romArrayBuffer));

// Zero-copy frame view (helper wraps backendMemory + ptr)
const frame = getGameFrameView();   // Uint8Array(160*144) palette indices
// or RGBA (CGB): getCgbGameFrameView() — Uint16Array RGB555

// Get managed objects (copy via bindings)
const info = getDebugInfo();   // → plain JS object matching DebugInfo shape

Audio Pipeline

// Called in postRun after each emulation step
const count = getAudioBuffersToReadCount();
for (let i = 0; i < count; i++) {
  const leftPtr  = getAudioBufferToReadPointer(0);
  const rightPtr = getAudioBufferToReadPointer(1);
  const size = getAudioBuffersSize();
  // Zero-copy typed array views
  const left  = new Float32Array(backendMemory.buffer, leftPtr,  size);
  const right = new Float32Array(backendMemory.buffer, rightPtr, size);
  // Feed to Web Audio API
  const buf = audioCtx.createBuffer(2, size, getAudioSampleRate());
  buf.copyToChannel(left,  0);
  buf.copyToChannel(right, 1);
  const src = audioCtx.createBufferSource();
  src.buffer = buf;
  src.connect(audioCtx.destination);
  src.start(nextAudioTime);
  nextAudioTime += buf.duration;
}
markAudioBuffersRead(count);

Emulation Loop Pattern

Loop logic in src/emulator/loop.ts. Audio postRun registered via addPostRunCallback from audio.ts. Render callbacks fire when ≥1 GB frame advanced this rAF tick.

// loop.ts
function run(time: number) {
  accumulator += wallDt * get(EmulatorSpeed);
  while (accumulator >= GB_FRAME_MS && framesThisTick < MAX_CATCHUP) {
    preRun();                          // setJoypad(inputBits)
    LastStopReason.set(runEmulator(GB_FRAME_MS));
    postRun();                         // fetchLogs, GameFrames++, debug snapshot, AutoSave, postRunCallbacks
    accumulator -= GB_FRAME_MS; framesThisTick++;
  }
  if (framesThisTick > 0) renderCallbacks.forEach(cb => cb());
  if (!get(EmulatorPaused)) requestAnimationFrame(run);
}

Emulator.AddRenderCallback / AddPostRunCallback for components (Player, AudioDebug) to hook in.

Svelte 5 Runes Patterns Used Here

<script lang="ts">
  // Reactive state (replaces writable store in component)
  let frame = $state<Uint8ClampedArray | null>(null);

  // Derived (replaces $: reactive declaration)
  let isRunning = $derived(frame !== null);

  // Side effects (replaces onMount + $: with cleanup)
  $effect(() => {
    const unsub = someStore.subscribe(v => { ... });
    return () => unsub();
  });
</script>

Stores: When to Use Which

InputType Bitmask (src/inputs.ts)

// Combined with bitwise OR, passed to setJoypad(keys)
Right=1, Left=2, Up=4, Down=8, A=16, B=32, Select=64, Start=128

$ARGUMENTS