🛠️ System Architecture Blueprint
An ultra-low-latency, distributed network netplay processing engine built as a Cargo workspace with two components: contra_core (Rust emulation engine) and contra_ui (Flutter cross-platform UI). This system coordinates high-frequency cross-platform NES emulation frames between isolated desktop and mobile operating environments, linked via flutter_rust_bridge FFI.
Workspace Structure
| Component | Location | Description |
|---|---|---|
contra_core | /contra_core | Rust emulator engine + network stack (12 modules) |
contra_ui | /contra_ui | Flutter cross-platform UI (Android, iOS, Linux, macOS, Web, Windows) |
Core Module Map
Verified from actual lib.rs — 11 public modules:
| Module | Role |
|---|---|
api | Public interface layer |
emulator | Core NES emulation via RollbackEmulator wrapping tetanes_core’s ControlDeck |
clock | Frame timing and synchronization (60Hz NTSC / 50Hz PAL) |
input_system | NES controller state capture and bitmask encoding |
ffi | C-ABI Foreign Function Interface for Flutter bridge |
network | Peer-to-peer networking orchestration |
packet | 10-byte wire packet struct definition and serialization |
rollback | Predictive state synchronization engine |
transport | Transport abstraction — iroh_native (desktop/mobile) and wasm (web) |
voice | Real-time audio capture and streaming via Opus codec |
bridge_generated | Auto-generated flutter_rust_bridge bindings |
🎮 Core Emulation Engine
The emulator is built on tetanes-core (v0.14.2), a cycle-accurate NES emulation framework:
- Frame Buffer:
FRAME_WIDTH = 256,FRAME_HEIGHT = 240,FRAME_BUFFER_SIZE = 245,760(256 × 240 × 4 bytes RGBA) - CPU: Full 6502 instruction set with precise cycle timing via
tetanes_core::Cpu - PPU: Pixel-accurate Picture Processing Unit rendering
- APU: Authentic audio synthesis for all 5 NES sound channels
- Cartridge: Mapper support via
tetanes_corecartridge system - Error Handling: Custom
EmulatorErrorenum covering ROM loading, snapshot failures, and frame execution errors
🔄 Data Flow Matrix
The engine coordinates multi-threaded frame ticks across an asynchronous FFI boundary using zero-copy state swapping structures:
- Hardware Event Capture: The Flutter UI framework samples high-frequency sensor streams (gyroscope, multi-touch panels) natively via
flutter_rust_bridge(v1.82.4). - Polymorphic Mapping: Analog telemetry vectors are encoded directly into compact 16-bit binary input bitmasks via
input_system. - FFI Translation Layer: Raw bits are piped across a low-overhead C-ABI Foreign Function Interface directly into Rust native memory spaces.
- Lock-Free State Swap: The Rust core drops heavy OS-level mutexes, utilizing atomic primitives (
AtomicU16) via therollbackmodule to swap frame states instantly. - Encrypted Transport: Asynchronous background Tokio (v1.35,
fullfeatures) tasks extract 10-bytebincode-serialized (v2.0.1, withserde) wire packets and stream them over Iroh (v1.0.0,tls-ring) QUIC-based P2P tunnels with NAT traversal and relay fallback.
🎙️ Voice Communication
- Opus Codec (v0.3.1): Low-latency, high-quality audio encoding/decoding integrated with the P2P transport layer
voice.rsmodule handles real-time audio capture, Opus encoding, network streaming, and jitter buffer management
📋 Integration Test Suite (5 Phases)
| Phase | Module | Scope |
|---|---|---|
| Phase 1 | phase1_core.rs | CPU instruction accuracy, memory map validation |
| Phase 2 | phase2_emulator.rs | Full-system boot ROM, PPU frame rendering at 60FPS |
| Phase 3 | phase3_transport.rs | P2P connection establishment, packet serialization round-trip |
| Phase 4 | phase4_integration.rs | Netplay synchronization, rollback correctness under latency |
| Phase 5 | phase5_voice.rs | Audio capture pipeline, Opus encode/decode cycle |
🌍 Platform Targets
- Desktop: Windows, Linux, macOS — native Iroh P2P via
transport::iroh_native - Mobile: Android, iOS — Flutter UI + Rust FFI via
flutter_rust_bridge - Web: WASM32 target via
getrandomwithwasm_jsfeature,transport::wasmmodule
⚙️ Build Profile Optimization
Dependencies compiled at opt-level = 3 even in debug builds ([profile.dev.package."*"]) to maintain 60 FPS emulation during development iteration.
⚡ Use-Case Engineering Rationale
When coordinating real-time inputs at a locked 60Hz (16.6ms window), thread contention can cause catastrophic frame stutters. By executing decentralized P2P transport tunnels via Iroh and replacing thread locks with bare CPU atomic instructions, this engine reads, updates, and transmits frame states safely within the frame budget. The Contra Force (USA).nes ROM is included as the primary test target.