Frontend Architecture

Frontend Architecture

Specification: docs/frontend.md. User guide: docs/user-guide/. Crate: crates/rustynes-frontend (binary rustynes).

The frontend provides windowing, rendering, audio, input and the user interface, and keeps all of it outside the deterministic core.

Stack

winit for windows and events (X11, Wayland, macOS, Windows and the browser), wgpu for rendering (Vulkan, Metal, DX12, or WebGPU / WebGL2 in the browser), cpal for audio, egui for the interface, and gilrs for gamepads. Exact versions are in the workspace Cargo.toml.

Design points

• An always-on egui shell. egui runs every frame to draw the menu bar, status bar and settings window; the debugger panels are layered on top when toggled. Menu interactions return an action that is dispatched after the egui pass, so the shell never holds the emulator lock inside the UI closure.
• A dedicated emulation thread (native, on by default). The emulator produces frames on its own thread behind a shared handle, reading input from a lock-free structure published by the UI thread; the UI thread handles events, builds the interface and presents. Netplay and RetroAchievements run on the UI thread, and the emulation thread pauses while a netplay session is active.
• Pacing and audio rate control live here, not in the core. Display-synced, VRR and wall-clock pacing, dynamic audio rate control, speed control and fast-forward are frontend concerns, which keeps the core's output deterministic.
• Run-ahead removes a game's own input lag by running hidden frames from a snapshot each visible frame and rolling back. The persistent timeline stays identical to a plain run, so saves, rewind, movies and achievements see the real timeline.
• Display options are off the core's path. NTSC composite filtering, CRT shaders, upscalers and palettes post-process the framebuffer and do not change it.

Features built on top

Save states and rewind, battery saves (including IndexedDB in the browser), TAStudio and movie import, the debugger, cheats, HD packs, A/V recording and Lua scripting (Scripting-Engine). The README's features section is the current list; several are opt-in Cargo features, and since v2.9.7 the release binaries include every native feature.