# mandalorian007/thunderclap-engine architecture

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

- Interactive diagram: https://gitdiagram.com/mandalorian007/thunderclap-engine
- Repository: https://github.com/mandalorian007/thunderclap-engine

## Overview

ThunderClap is a WebGPU game engine, accompanied by Rust crates for authoritative multiplayer simulation and serving. A game developer boots a game through `createGame`, builds game-specific scenes and rules, and the engine runs frames while coordinating rendering, input, UI, audio, saves and host lifecycle. For networked games, a separate server accepts WebSocket sessions and hands requests to the simulation. The README documents engine capabilities; sampled Rust excerpts show server/session and live-query boundaries, but not every connection between them.

Main entry points: [`src/core/game.ts`](https://github.com/mandalorian007/thunderclap-engine/blob/main/src/core/game.ts) (Game bootstrap), [`crates/tc-net/src/session.rs`](https://github.com/mandalorian007/thunderclap-engine/blob/main/crates/tc-net/src/session.rs) (Client session), [`src/render/renderer.ts`](https://github.com/mandalorian007/thunderclap-engine/blob/main/src/render/renderer.ts) (WebGPU renderer), [`src/input/input.ts`](https://github.com/mandalorian007/thunderclap-engine/blob/main/src/input/input.ts) (Input and gestures)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_engine["Game runtime"]
  node_boot["Game bootstrap<br/>[game.ts]"]
  node_frame["Frame loop<br/>[loop.ts]"]
  node_host["Platform host"]
end

subgraph group_graphics["Graphics and content"]
  node_render["WebGPU renderer<br/>[renderer.ts]"]
  node_postfx["Post processing<br/>[post-stack.ts]"]
  node_worldfx["World effects"]
  node_content["Game content"]
  node_voxel["Voxel worlds<br/>[world.ts]"]
  node_nav["Navigation<br/>[query-queue.ts]"]
end

subgraph group_interaction["Player experience"]
  node_input["Input and gestures<br/>[input.ts]"]
  node_xr["XR controls<br/>[controller.ts]"]
  node_ui["HUD and overlays<br/>[hud.ts]"]
  node_audio["Audio system<br/>[audio.ts]"]
  node_save[("Save system<br/>[store.ts]")]
end

subgraph group_multiplayer["Multiplayer server"]
  node_wsserver["WebSocket server<br/>[server.rs]"]
  node_session["Client session<br/>[session.rs]"]
  node_envelope["Wire protocol<br/>[envelope.rs]"]
  node_auth["Connection auth<br/>[auth.rs]"]
end

subgraph group_simulation["Authoritative simulation"]
  node_game["Game simulation<br/>[game.rs]"]
  node_queries["Live queries<br/>[query.rs]"]
  node_sync["Query synchronization<br/>[mod.rs]"]
end

node_developer(("Game developer"))

node_developer -->|"boots game"| node_boot
node_boot -->|"starts loop"| node_frame
node_boot -->|"creates renderer"| node_render
node_boot -->|"sets up post"| node_postfx
node_boot -->|"sets up input"| node_input
node_boot -->|"sets up overlay"| node_ui
node_boot -->|"sets up audio"| node_audio
node_boot -->|"sets up save"| node_save
node_boot -->|"sets up host"| node_host
node_render -->|"feeds post stack"| node_postfx
node_developer -->|"defines models"| node_content
node_developer -->|"builds voxel worlds"| node_voxel
node_developer -->|"requests paths"| node_nav
node_input -->|"supports XR input"| node_xr
node_wsserver -->|"runs sessions"| node_session
node_session -->|"verifies token"| node_auth
node_session -->|"decodes messages"| node_envelope
node_session -->|"hands requests"| node_game
node_game -->|"defines queries"| node_queries
node_sync -->|"refreshes queries"| node_queries

click node_boot "https://github.com/mandalorian007/thunderclap-engine/blob/main/src/core/game.ts"
click node_frame "https://github.com/mandalorian007/thunderclap-engine/blob/main/src/core/loop.ts"
click node_host "https://github.com/mandalorian007/thunderclap-engine/tree/main/src/host"
click node_render "https://github.com/mandalorian007/thunderclap-engine/blob/main/src/render/renderer.ts"
click node_postfx "https://github.com/mandalorian007/thunderclap-engine/blob/main/src/post/post-stack.ts"
click node_worldfx "https://github.com/mandalorian007/thunderclap-engine/tree/main/src/fx"
click node_content "https://github.com/mandalorian007/thunderclap-engine/tree/main/src/models"
click node_voxel "https://github.com/mandalorian007/thunderclap-engine/blob/main/src/voxel/world.ts"
click node_input "https://github.com/mandalorian007/thunderclap-engine/blob/main/src/input/input.ts"
click node_xr "https://github.com/mandalorian007/thunderclap-engine/blob/main/src/xr/controller.ts"
click node_ui "https://github.com/mandalorian007/thunderclap-engine/blob/main/src/ui/hud.ts"
click node_audio "https://github.com/mandalorian007/thunderclap-engine/blob/main/src/audio/audio.ts"
click node_save "https://github.com/mandalorian007/thunderclap-engine/blob/main/src/save/store.ts"
click node_nav "https://github.com/mandalorian007/thunderclap-engine/blob/main/src/nav/query-queue.ts"
click node_wsserver "https://github.com/mandalorian007/thunderclap-engine/blob/main/crates/tc-net/src/server.rs"
click node_session "https://github.com/mandalorian007/thunderclap-engine/blob/main/crates/tc-net/src/session.rs"
click node_envelope "https://github.com/mandalorian007/thunderclap-engine/blob/main/crates/tc-net/src/envelope.rs"
click node_auth "https://github.com/mandalorian007/thunderclap-engine/blob/main/crates/tc-net/src/auth.rs"
click node_game "https://github.com/mandalorian007/thunderclap-engine/blob/main/crates/tc-sim/src/game.rs"
click node_queries "https://github.com/mandalorian007/thunderclap-engine/blob/main/crates/tc-sim/src/query.rs"
click node_sync "https://github.com/mandalorian007/thunderclap-engine/blob/main/crates/tc-sim/src/sync/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_boot,node_frame,node_host toneBlue
class node_render,node_postfx,node_worldfx,node_content,node_voxel,node_nav toneAmber
class node_input,node_xr,node_ui,node_audio,node_save toneMint
class node_wsserver,node_session,node_envelope,node_auth toneRose
class node_game,node_queries,node_sync,node_developer toneIndigo
```

## Components

### Game runtime

- [Game bootstrap](https://github.com/mandalorian007/thunderclap-engine/blob/main/src/core/game.ts): `src/core/game.ts`
- [Frame loop](https://github.com/mandalorian007/thunderclap-engine/blob/main/src/core/loop.ts): `src/core/loop.ts`
- [Platform host](https://github.com/mandalorian007/thunderclap-engine/tree/main/src/host): `src/host`

### Graphics and content

- [WebGPU renderer](https://github.com/mandalorian007/thunderclap-engine/blob/main/src/render/renderer.ts): `src/render/renderer.ts`
- [Post processing](https://github.com/mandalorian007/thunderclap-engine/blob/main/src/post/post-stack.ts): `src/post/post-stack.ts`
- [World effects](https://github.com/mandalorian007/thunderclap-engine/tree/main/src/fx): `src/fx`
- [Game content](https://github.com/mandalorian007/thunderclap-engine/tree/main/src/models): `src/models`
- [Voxel worlds](https://github.com/mandalorian007/thunderclap-engine/blob/main/src/voxel/world.ts): `src/voxel/world.ts`
- [Navigation](https://github.com/mandalorian007/thunderclap-engine/blob/main/src/nav/query-queue.ts): `src/nav/query-queue.ts`

### Player experience

- [Input and gestures](https://github.com/mandalorian007/thunderclap-engine/blob/main/src/input/input.ts): `src/input/input.ts`
- [XR controls](https://github.com/mandalorian007/thunderclap-engine/blob/main/src/xr/controller.ts): `src/xr/controller.ts`
- [HUD and overlays](https://github.com/mandalorian007/thunderclap-engine/blob/main/src/ui/hud.ts): `src/ui/hud.ts`
- [Audio system](https://github.com/mandalorian007/thunderclap-engine/blob/main/src/audio/audio.ts): `src/audio/audio.ts`
- [Save system](https://github.com/mandalorian007/thunderclap-engine/blob/main/src/save/store.ts): `src/save/store.ts`

### Multiplayer server

- [WebSocket server](https://github.com/mandalorian007/thunderclap-engine/blob/main/crates/tc-net/src/server.rs): `crates/tc-net/src/server.rs`
- [Client session](https://github.com/mandalorian007/thunderclap-engine/blob/main/crates/tc-net/src/session.rs): `crates/tc-net/src/session.rs`
- [Wire protocol](https://github.com/mandalorian007/thunderclap-engine/blob/main/crates/tc-net/src/envelope.rs): `crates/tc-net/src/envelope.rs`
- [Connection auth](https://github.com/mandalorian007/thunderclap-engine/blob/main/crates/tc-net/src/auth.rs): `crates/tc-net/src/auth.rs`

### Authoritative simulation

- [Game simulation](https://github.com/mandalorian007/thunderclap-engine/blob/main/crates/tc-sim/src/game.rs): `crates/tc-sim/src/game.rs`
- [Live queries](https://github.com/mandalorian007/thunderclap-engine/blob/main/crates/tc-sim/src/query.rs): `crates/tc-sim/src/query.rs`
- [Query synchronization](https://github.com/mandalorian007/thunderclap-engine/blob/main/crates/tc-sim/src/sync/mod.rs): `crates/tc-sim/src/sync/mod.rs`

### Other components

- **Game developer**

## Connections

- Game developer → Game bootstrap: boots game
- Game bootstrap → Frame loop: starts loop
- Game bootstrap → WebGPU renderer: creates renderer
- Game bootstrap → Post processing: sets up post
- Game bootstrap → Input and gestures: sets up input
- Game bootstrap → HUD and overlays: sets up overlay
- Game bootstrap → Audio system: sets up audio
- Game bootstrap → Save system: sets up save
- Game bootstrap → Platform host: sets up host
- WebGPU renderer → Post processing: feeds post stack
- Game developer → Game content: defines models
- Game developer → Voxel worlds: builds voxel worlds
- Game developer → Navigation: requests paths
- Input and gestures → XR controls: supports XR input
- WebSocket server → Client session: runs sessions (evidence: `crates/tc-net/src/server.rs`)
- Client session → Connection auth: verifies token (evidence: `crates/tc-net/src/session.rs`)
- Client session → Wire protocol: decodes messages (evidence: `crates/tc-net/src/session.rs`)
- Client session → Game simulation: hands requests
- Game simulation → Live queries: defines queries (evidence: `crates/tc-sim/src/game.rs`)
- Query synchronization → Live queries: refreshes queries (evidence: `crates/tc-sim/src/query.rs`)
