# nixxou/zaxnes architecture

> Architecture diagram of the GitHub repository nixxou/zaxnes, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nixxou/zaxnes
- Repository: https://github.com/nixxou/zaxnes

## Overview

Zaxnes is a desktop and handheld NES emulator whose distinctive result is an interactive 3D rendering of NES frames, with optional widescreen gameplay. The user launches the app, selects a ROM, and plays; the emulator core produces frames that the 3D engine converts for rendering and the app presents alongside audio and controls. Profiles, save states, movies, shaders, and RetroAchievements extend that loop. The graph combines README-described capabilities with sampled source and index references; links for unsampled subsystems are documented rather than inferred from their names.

Main entry points: [`rust/crates/zax-app/src/emulation/host/mod.rs`](https://github.com/nixxou/zaxnes/blob/main/rust/crates/zax-app/src/emulation/host/mod.rs) (Emulation host), [`rust/crates/zax-app/src/application.rs`](https://github.com/nixxou/zaxnes/blob/main/rust/crates/zax-app/src/application.rs) (Application loop), [`rust/crates/zax-nes/src/nes_core.rs`](https://github.com/nixxou/zaxnes/blob/main/rust/crates/zax-nes/src/nes_core.rs) (NES core), [`rust/crates/zax-app/src/ui`](https://github.com/nixxou/zaxnes/tree/main/rust/crates/zax-app/src/ui) (Menus and UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Application and input"]
  node_app["Application loop<br/>[application.rs]"]
  node_ui["Menus and UI"]
  node_input["Input routing<br/>[routing.rs]"]
  node_roms["ROM library<br/>[game_catalog.rs]"]
end

subgraph group_emulation["NES emulation"]
  node_host["Emulation host<br/>[mod.rs]"]
  node_core["NES core<br/>[nes_core.rs]"]
  node_cartridges["Cartridges and mappers<br/>[mod.rs]"]
  node_widescreen["Widescreen hacks<br/>[wide.rs]"]
  node_audio["Audio output<br/>[stream.rs]"]
end

subgraph group_scene["3D scene and display"]
  node_profiles["3D profiles"]
  node_scene_engine["3D conversion<br/>[engine.rs]"]
  node_renderer["Graphics renderer<br/>[renderer.rs]"]
  node_shaders["Shader support<br/>[shader_panel.rs]"]
end

subgraph group_features["Player features"]
  node_persistence[("Settings and saves")]
  node_movies["Movie recording<br/>[movie.rs]"]
  node_scripting["Profile scripting"]
  node_mcp["Editor MCP<br/>[server.rs]"]
  node_achievements["RetroAchievements<br/>[mod.rs]"]
end

subgraph group_integrations["External services"]
  node_ra_service(("RetroAchievements service"))
end

node_player(("Player"))

node_player -->|"launches"| node_app
node_player -.->|"operates"| node_ui
node_ui -->|"plugs into"| node_app
node_app -->|"runs"| node_host
node_player -.->|"selects ROM"| node_roms
node_host -->|"uses catalog"| node_roms
node_input -->|"encodes controls"| node_core
node_host -.->|"runs frames"| node_core
node_core -->|"dispatches mapper"| node_cartridges
node_core -.->|"applies hacks"| node_widescreen
node_host -.->|"converts frames"| node_scene_engine
node_profiles -.->|"defines scene"| node_scene_engine
node_app -.->|"draws scene"| node_renderer
node_app -->|"pumps audio"| node_audio
node_app -->|"samples input"| node_input
node_host -.->|"uses save states"| node_persistence
node_host -.->|"records and replays"| node_movies
node_app -->|"requests shaders"| node_shaders
node_host -->|"bridges scripts"| node_scripting
node_mcp -.->|"exposes harness"| node_scripting
node_host -->|"updates progress"| node_achievements
node_achievements -.->|"requests service"| node_ra_service
node_player -.->|"imports profiles"| node_profiles

click node_app "https://github.com/nixxou/zaxnes/blob/main/rust/crates/zax-app/src/application.rs"
click node_ui "https://github.com/nixxou/zaxnes/tree/main/rust/crates/zax-app/src/ui"
click node_input "https://github.com/nixxou/zaxnes/blob/main/rust/crates/zax-app/src/input/routing.rs"
click node_roms "https://github.com/nixxou/zaxnes/blob/main/rust/crates/zax-app/src/emulation/game_catalog.rs"
click node_profiles "https://github.com/nixxou/zaxnes/blob/main/rust/crates/zax-profiles/src/catalogue/profile_catalogue.rs"
click node_host "https://github.com/nixxou/zaxnes/blob/main/rust/crates/zax-app/src/emulation/host/mod.rs"
click node_core "https://github.com/nixxou/zaxnes/blob/main/rust/crates/zax-nes/src/nes_core.rs"
click node_cartridges "https://github.com/nixxou/zaxnes/blob/main/rust/crates/zax-nes/src/cartridges/mod.rs"
click node_widescreen "https://github.com/nixxou/zaxnes/blob/main/rust/crates/zax-nes/src/wide.rs"
click node_scene_engine "https://github.com/nixxou/zaxnes/blob/main/rust/crates/zax-engine3d/src/engine.rs"
click node_renderer "https://github.com/nixxou/zaxnes/blob/main/rust/crates/zax-render/src/renderer.rs"
click node_shaders "https://github.com/nixxou/zaxnes/blob/main/rust/crates/zax-app/src/ui/shader_panel.rs"
click node_audio "https://github.com/nixxou/zaxnes/blob/main/rust/crates/zax-app/src/audio/stream.rs"
click node_persistence "https://github.com/nixxou/zaxnes/tree/main/rust/crates/zax-app/src/persistence"
click node_movies "https://github.com/nixxou/zaxnes/blob/main/rust/crates/zax-nes/src/movie.rs"
click node_scripting "https://github.com/nixxou/zaxnes/blob/main/rust/crates/zax-app/src/scene_script_bridge.rs"
click node_mcp "https://github.com/nixxou/zaxnes/blob/main/rust/crates/zax-app/src/mcp/server.rs"
click node_achievements "https://github.com/nixxou/zaxnes/blob/main/rust/crates/zax-app/src/achievements/mod.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_ui,node_input,node_roms toneBlue
class node_host,node_core,node_cartridges,node_widescreen,node_audio toneAmber
class node_profiles,node_scene_engine,node_renderer,node_shaders toneMint
class node_persistence,node_movies,node_scripting,node_mcp,node_achievements toneRose
class node_ra_service,node_player toneIndigo
```

## Components

### Application and input

- [Application loop](https://github.com/nixxou/zaxnes/blob/main/rust/crates/zax-app/src/application.rs): `rust/crates/zax-app/src/application.rs`
- [Menus and UI](https://github.com/nixxou/zaxnes/tree/main/rust/crates/zax-app/src/ui): `rust/crates/zax-app/src/ui`
- [Input routing](https://github.com/nixxou/zaxnes/blob/main/rust/crates/zax-app/src/input/routing.rs): `rust/crates/zax-app/src/input/routing.rs`
- [ROM library](https://github.com/nixxou/zaxnes/blob/main/rust/crates/zax-app/src/emulation/game_catalog.rs): `rust/crates/zax-app/src/emulation/game_catalog.rs`

### NES emulation

- [Emulation host](https://github.com/nixxou/zaxnes/blob/main/rust/crates/zax-app/src/emulation/host/mod.rs): `rust/crates/zax-app/src/emulation/host/mod.rs`
- [NES core](https://github.com/nixxou/zaxnes/blob/main/rust/crates/zax-nes/src/nes_core.rs): `rust/crates/zax-nes/src/nes_core.rs`
- [Cartridges and mappers](https://github.com/nixxou/zaxnes/blob/main/rust/crates/zax-nes/src/cartridges/mod.rs): `rust/crates/zax-nes/src/cartridges/mod.rs`
- [Widescreen hacks](https://github.com/nixxou/zaxnes/blob/main/rust/crates/zax-nes/src/wide.rs): `rust/crates/zax-nes/src/wide.rs`
- [Audio output](https://github.com/nixxou/zaxnes/blob/main/rust/crates/zax-app/src/audio/stream.rs): `rust/crates/zax-app/src/audio/stream.rs`

### 3D scene and display

- [3D profiles](https://github.com/nixxou/zaxnes/blob/main/rust/crates/zax-profiles/src/catalogue/profile_catalogue.rs): `rust/crates/zax-profiles/src/catalogue/profile_catalogue.rs`
- [3D conversion](https://github.com/nixxou/zaxnes/blob/main/rust/crates/zax-engine3d/src/engine.rs): `rust/crates/zax-engine3d/src/engine.rs`
- [Graphics renderer](https://github.com/nixxou/zaxnes/blob/main/rust/crates/zax-render/src/renderer.rs): `rust/crates/zax-render/src/renderer.rs`
- [Shader support](https://github.com/nixxou/zaxnes/blob/main/rust/crates/zax-app/src/ui/shader_panel.rs): `rust/crates/zax-app/src/ui/shader_panel.rs`

### Player features

- [Settings and saves](https://github.com/nixxou/zaxnes/tree/main/rust/crates/zax-app/src/persistence): `rust/crates/zax-app/src/persistence`
- [Movie recording](https://github.com/nixxou/zaxnes/blob/main/rust/crates/zax-nes/src/movie.rs): `rust/crates/zax-nes/src/movie.rs`
- [Profile scripting](https://github.com/nixxou/zaxnes/blob/main/rust/crates/zax-app/src/scene_script_bridge.rs): `rust/crates/zax-app/src/scene_script_bridge.rs`
- [Editor MCP](https://github.com/nixxou/zaxnes/blob/main/rust/crates/zax-app/src/mcp/server.rs): `rust/crates/zax-app/src/mcp/server.rs`
- [RetroAchievements](https://github.com/nixxou/zaxnes/blob/main/rust/crates/zax-app/src/achievements/mod.rs): `rust/crates/zax-app/src/achievements/mod.rs`

### External services

- **RetroAchievements service**

### Other components

- **Player**

## Connections

- Player → Application loop: launches
- Player → Menus and UI: operates (evidence: `README.md`)
- Menus and UI → Application loop: plugs into (evidence: `rust/crates/zax-app/src/application.rs`)
- Application loop → Emulation host: runs (evidence: `rust/crates/zax-app/src/application.rs`)
- Player → ROM library: selects ROM (evidence: `README.md`)
- Emulation host → ROM library: uses catalog (evidence: `rust/crates/zax-app/src/emulation/host/mod.rs`)
- Input routing → NES core: encodes controls (evidence: `rust/crates/zax-app/src/input/routing.rs`)
- Emulation host → NES core: runs frames (evidence: `README.md`)
- NES core → Cartridges and mappers: dispatches mapper (evidence: `rust/crates/zax-nes/src/cartridges/mod.rs`)
- NES core → Widescreen hacks: applies hacks (evidence: `README.md`)
- Emulation host → 3D conversion: converts frames (evidence: `rust/crates/zax-engine3d/src/engine.rs`)
- 3D profiles → 3D conversion: defines scene (evidence: `README.md`)
- Application loop → Graphics renderer: draws scene (evidence: `rust/crates/zax-app/src/application.rs`)
- Application loop → Audio output: pumps audio (evidence: `rust/crates/zax-app/src/application.rs`)
- Application loop → Input routing: samples input (evidence: `rust/crates/zax-app/src/application.rs`)
- Emulation host → Settings and saves: uses save states (evidence: `README.md`)
- Emulation host → Movie recording: records and replays (evidence: `README.md`)
- Application loop → Shader support: requests shaders (evidence: `rust/crates/zax-app/src/application.rs`)
- Emulation host → Profile scripting: bridges scripts (evidence: `rust/crates/zax-app/src/application.rs`)
- Editor MCP → Profile scripting: exposes harness (evidence: `README.md`)
- Emulation host → RetroAchievements: updates progress (evidence: `rust/crates/zax-app/src/emulation/host/mod.rs`)
- RetroAchievements → RetroAchievements service: requests service (evidence: `README.md`)
- Player → 3D profiles: imports profiles (evidence: `README.md`)
