RetroLink follows a strict contract. These are architectural rules, not preferences. ### Phase Order (Never Changes) - `Simulation -> Snapshot -> Rendering -> Present` - Host only simulates authoritative state. - Clients never simulate, predict, smooth, or invent state. - Rendering is snapshot-only and must be idempotent. ### Deterministic Rendering Rules - Every visible pixel change must come from exactly one simulation tick. - `render()` and draw helpers must not use `millis()`, `micros()`, timers, or randomness. - Rendering must not mutate gameplay state. - No role-based branching in rendering logic. ### Display and Buffer Rules - Always render to back buffer only. - Always present back buffer through RetroGoDisplay SPI DMA queue. - After present: copy back to front, then swap. - Front buffer is safety sync only, never a render target. - Any tearing, flicker, ghosting, or frame desync is a critical defect. ### Interrupt and Networking Safety - No display API calls from ISR or ESP-NOW callbacks. - ISR path may only store packet data and set flags. - Display work is deferred to main loop / task context. - SPI transaction payloads must be stable memory, never stack buffers. ### Memory and Asset Policy - DMA buffers must be internal DMA-capable RAM, not PSRAM. - Large transient decode buffers may use PSRAM. - Core gameplay visuals are tiles and sprites, not full-frame RGB565 assets. - PNG assets are allowed in SPIFFS for UI and loading paths, decoded outside `render()`. ### Why This Works This contract is what keeps multiplayer output deterministic across devices while preserving display stability on constrained hardware. The architecture was shaped by failures (white screens, bus corruption, stack-lifetime DMA bugs, and desync) and is intentionally strict to prevent regressions.