# meshy-dev/threert architecture

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

- Interactive diagram: https://gitdiagram.com/meshy-dev/threert
- Repository: https://github.com/meshy-dev/threert

## Overview

ThreeRT is a three.js-style scene and game runtime backed by a real-time GPU path tracer. The main workflow is to author a scene or game, bind its scene graph to an engine, and render it in a native or browser runtime; gameplay and voxel systems extend that workflow. The README documents these capabilities, while sampled source confirms the scene-binding and browser-engine boundaries. Several renderer and gameplay internals are unsampled, so their connections are shown only where the index or README supports them.

Main entry points: [`renderer/src/lib.rs`](https://github.com/meshy-dev/threert/blob/main/renderer/src/lib.rs) (Renderer Runtime), [`packages/scene/src/core.ts`](https://github.com/meshy-dev/threert/blob/main/packages/scene/src/core.ts) (Scene API), [`packages/scene/src/engine.ts`](https://github.com/meshy-dev/threert/blob/main/packages/scene/src/engine.ts) (Scene Binding), [`packages/gameplay/src/game.ts`](https://github.com/meshy-dev/threert/blob/main/packages/gameplay/src/game.ts) (Gameplay Runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Scene and Gameplay"]
  node_scene_api["Scene API<br/>[core.ts]"]
  node_scene_binding["Scene Binding<br/>[engine.ts]"]
  node_scene_math["Scene Math<br/>[math.ts]"]
  node_gameplay["Gameplay Runtime<br/>[game.ts]"]
  node_game_world["World Handlers<br/>[world.ts]"]
  node_game_host["Game Host<br/>[host.ts]"]
end

subgraph group_rendering["Rendering Engine"]
  node_renderer["Renderer Runtime<br/>[lib.rs]"]
  node_gpu["GPU Path Tracer<br/>[gpu.rs]"]
  node_render_scene["Render Scene<br/>[scene.rs]"]
  node_render_script["Embedded Script<br/>[script.rs]"]
  node_render_world["Render World<br/>[world.rs]"]
  node_physics_core["Physics World<br/>[world.rs]"]
  node_renderer_voxel["Voxel Rendering<br/>[voxel.rs]"]
end

subgraph group_voxel["Voxel Systems"]
  node_voxel_api["Voxel Toolkit<br/>[native.ts]"]
  node_voxel_mesh["Voxel Geometry<br/>[geometry.ts]"]
  node_voxel_explosions["Voxel Destruction<br/>[explosions.ts]"]
end

subgraph group_clients["Runtime Clients"]
  node_web_engine["Browser Engine Adapter<br/>[engine.ts]"]
  node_web_wasm["WebAssembly Engine<br/>[lib.rs]"]
  node_native_client["Native Renderer Client<br/>[main.rs]"]
  node_playground["Playground Editor<br/>[main.rs]"]
  node_playground_ui["Editor UI<br/>[main.tsx]"]
  node_three_adapter["Three.js Adapter<br/>[engine.ts]"]
end

subgraph group_examples["Scenes and Games"]
  node_scene_examples["Scenes<br/>[sun-room.ts]"]
  node_game_examples["Games<br/>[light-room.game.ts]"]
  node_voxel_game["Voxel Level Demo"]
end

node_scene_author(("Scene Author"))
node_render_output["Rendered Frames"]

node_scene_author -->|"authors"| node_scene_examples
node_scene_examples -->|"uses API"| node_scene_api
node_game_examples -->|"uses API"| node_scene_api
node_game_examples -->|"uses runtime"| node_gameplay
node_scene_api -->|"uses math"| node_scene_math
node_scene_binding -->|"syncs graph"| node_scene_api
node_scene_binding -->|"calls engine"| node_render_script
node_gameplay -.->|"uses handlers"| node_game_world
node_gameplay -.->|"runs through"| node_game_host
node_voxel_game -->|"uses toolkit"| node_voxel_api
node_voxel_game -->|"uses runtime"| node_gameplay
node_voxel_api -.->|"uses geometry"| node_voxel_mesh
node_voxel_api -.->|"supports blasts"| node_voxel_explosions
node_renderer -->|"uses GPU"| node_gpu
node_renderer -->|"uses scene"| node_render_scene
node_renderer -->|"uses scripts"| node_render_script
node_renderer -->|"uses world"| node_render_world
node_renderer -->|"uses voxels"| node_renderer_voxel
node_renderer -.->|"uses physics"| node_physics_core
node_render_script -->|"installs engine for"| node_scene_binding
node_web_engine -->|"dispatches calls"| node_web_wasm
node_scene_binding -.->|"uses browser binding"| node_web_engine
node_native_client -.->|"runs runtime"| node_renderer
node_playground -->|"uses renderer"| node_renderer
node_playground_ui -.->|"sends commands"| node_playground
node_three_adapter -->|"implements API"| node_scene_api
node_gpu -->|"traces frames"| node_render_output

click node_scene_api "https://github.com/meshy-dev/threert/blob/main/packages/scene/src/core.ts"
click node_scene_binding "https://github.com/meshy-dev/threert/blob/main/packages/scene/src/engine.ts"
click node_scene_math "https://github.com/meshy-dev/threert/blob/main/packages/scene/src/math.ts"
click node_gameplay "https://github.com/meshy-dev/threert/blob/main/packages/gameplay/src/game.ts"
click node_game_world "https://github.com/meshy-dev/threert/blob/main/packages/gameplay/src/world.ts"
click node_game_host "https://github.com/meshy-dev/threert/blob/main/packages/gameplay/src/host.ts"
click node_voxel_api "https://github.com/meshy-dev/threert/blob/main/packages/voxel/src/native.ts"
click node_voxel_mesh "https://github.com/meshy-dev/threert/blob/main/packages/voxel/src/geometry.ts"
click node_voxel_explosions "https://github.com/meshy-dev/threert/blob/main/packages/voxel/src/explosions.ts"
click node_renderer "https://github.com/meshy-dev/threert/blob/main/renderer/src/lib.rs"
click node_gpu "https://github.com/meshy-dev/threert/blob/main/renderer/src/gpu.rs"
click node_render_scene "https://github.com/meshy-dev/threert/blob/main/renderer/src/scene.rs"
click node_render_script "https://github.com/meshy-dev/threert/blob/main/renderer/src/script.rs"
click node_render_world "https://github.com/meshy-dev/threert/blob/main/renderer/src/world.rs"
click node_physics_core "https://github.com/meshy-dev/threert/blob/main/renderer/physics-core/src/world.rs"
click node_renderer_voxel "https://github.com/meshy-dev/threert/blob/main/renderer/src/voxel.rs"
click node_web_engine "https://github.com/meshy-dev/threert/blob/main/renderer/web/www/engine.ts"
click node_web_wasm "https://github.com/meshy-dev/threert/blob/main/renderer/web/src/lib.rs"
click node_native_client "https://github.com/meshy-dev/threert/blob/main/renderer/src/main.rs"
click node_playground "https://github.com/meshy-dev/threert/blob/main/playground/host/src/main.rs"
click node_playground_ui "https://github.com/meshy-dev/threert/blob/main/playground/ui/main.tsx"
click node_three_adapter "https://github.com/meshy-dev/threert/blob/main/tools/three/engine.ts"
click node_scene_examples "https://github.com/meshy-dev/threert/blob/main/scenes/sun-room.ts"
click node_game_examples "https://github.com/meshy-dev/threert/blob/main/games/light-room/light-room.game.ts"
click node_voxel_game "https://github.com/meshy-dev/threert/blob/main/games/voxel-level/level-destruction.game.ts"

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_scene_api,node_scene_binding,node_scene_math,node_gameplay,node_game_world,node_game_host toneBlue
class node_renderer,node_gpu,node_render_scene,node_render_script,node_render_world,node_physics_core,node_renderer_voxel toneAmber
class node_voxel_api,node_voxel_mesh,node_voxel_explosions toneMint
class node_web_engine,node_web_wasm,node_native_client,node_playground,node_playground_ui,node_three_adapter toneRose
class node_scene_examples,node_game_examples,node_voxel_game,node_scene_author,node_render_output toneIndigo
```

## Components

### Scene and Gameplay

- [Scene API](https://github.com/meshy-dev/threert/blob/main/packages/scene/src/core.ts): `packages/scene/src/core.ts`
- [Scene Binding](https://github.com/meshy-dev/threert/blob/main/packages/scene/src/engine.ts): `packages/scene/src/engine.ts`
- [Scene Math](https://github.com/meshy-dev/threert/blob/main/packages/scene/src/math.ts): `packages/scene/src/math.ts`
- [Gameplay Runtime](https://github.com/meshy-dev/threert/blob/main/packages/gameplay/src/game.ts): `packages/gameplay/src/game.ts`
- [World Handlers](https://github.com/meshy-dev/threert/blob/main/packages/gameplay/src/world.ts): `packages/gameplay/src/world.ts`
- [Game Host](https://github.com/meshy-dev/threert/blob/main/packages/gameplay/src/host.ts): `packages/gameplay/src/host.ts`

### Rendering Engine

- [Renderer Runtime](https://github.com/meshy-dev/threert/blob/main/renderer/src/lib.rs): `renderer/src/lib.rs`
- [GPU Path Tracer](https://github.com/meshy-dev/threert/blob/main/renderer/src/gpu.rs): `renderer/src/gpu.rs`
- [Render Scene](https://github.com/meshy-dev/threert/blob/main/renderer/src/scene.rs): `renderer/src/scene.rs`
- [Embedded Script](https://github.com/meshy-dev/threert/blob/main/renderer/src/script.rs): `renderer/src/script.rs`
- [Render World](https://github.com/meshy-dev/threert/blob/main/renderer/src/world.rs): `renderer/src/world.rs`
- [Physics World](https://github.com/meshy-dev/threert/blob/main/renderer/physics-core/src/world.rs): `renderer/physics-core/src/world.rs`
- [Voxel Rendering](https://github.com/meshy-dev/threert/blob/main/renderer/src/voxel.rs): `renderer/src/voxel.rs`

### Voxel Systems

- [Voxel Toolkit](https://github.com/meshy-dev/threert/blob/main/packages/voxel/src/native.ts): `packages/voxel/src/native.ts`
- [Voxel Geometry](https://github.com/meshy-dev/threert/blob/main/packages/voxel/src/geometry.ts): `packages/voxel/src/geometry.ts`
- [Voxel Destruction](https://github.com/meshy-dev/threert/blob/main/packages/voxel/src/explosions.ts): `packages/voxel/src/explosions.ts`

### Runtime Clients

- [Browser Engine Adapter](https://github.com/meshy-dev/threert/blob/main/renderer/web/www/engine.ts): `renderer/web/www/engine.ts`
- [WebAssembly Engine](https://github.com/meshy-dev/threert/blob/main/renderer/web/src/lib.rs): `renderer/web/src/lib.rs`
- [Native Renderer Client](https://github.com/meshy-dev/threert/blob/main/renderer/src/main.rs): `renderer/src/main.rs`
- [Playground Editor](https://github.com/meshy-dev/threert/blob/main/playground/host/src/main.rs): `playground/host/src/main.rs`
- [Editor UI](https://github.com/meshy-dev/threert/blob/main/playground/ui/main.tsx): `playground/ui/main.tsx`
- [Three.js Adapter](https://github.com/meshy-dev/threert/blob/main/tools/three/engine.ts): `tools/three/engine.ts`

### Scenes and Games

- [Scenes](https://github.com/meshy-dev/threert/blob/main/scenes/sun-room.ts): `scenes/sun-room.ts`
- [Games](https://github.com/meshy-dev/threert/blob/main/games/light-room/light-room.game.ts): `games/light-room/light-room.game.ts`
- [Voxel Level Demo](https://github.com/meshy-dev/threert/blob/main/games/voxel-level/level-destruction.game.ts): `games/voxel-level/level-destruction.game.ts`

### Other components

- **Scene Author**
- **Rendered Frames**

## Connections

- Scene Author → Scenes: authors (evidence: `README.md`)
- Scenes → Scene API: uses API (evidence: `README.md`)
- Games → Scene API: uses API (evidence: `README.md`)
- Games → Gameplay Runtime: uses runtime (evidence: `README.md`)
- Scene API → Scene Math: uses math (evidence: `packages/scene/src/core.ts`)
- Scene Binding → Scene API: syncs graph (evidence: `packages/scene/src/engine.ts`)
- Scene Binding → Embedded Script: calls engine (evidence: `packages/scene/src/engine.ts`)
- Gameplay Runtime → World Handlers: uses handlers
- Gameplay Runtime → Game Host: runs through
- Voxel Level Demo → Voxel Toolkit: uses toolkit (evidence: `games/voxel-level/level-destruction.game.ts`)
- Voxel Level Demo → Gameplay Runtime: uses runtime (evidence: `games/voxel-level/level-destruction.game.ts`)
- Voxel Toolkit → Voxel Geometry: uses geometry
- Voxel Toolkit → Voxel Destruction: supports blasts
- Renderer Runtime → GPU Path Tracer: uses GPU (evidence: `renderer/src/lib.rs`)
- Renderer Runtime → Render Scene: uses scene (evidence: `renderer/src/lib.rs`)
- Renderer Runtime → Embedded Script: uses scripts (evidence: `renderer/src/lib.rs`)
- Renderer Runtime → Render World: uses world (evidence: `renderer/src/lib.rs`)
- Renderer Runtime → Voxel Rendering: uses voxels (evidence: `renderer/src/lib.rs`)
- Renderer Runtime → Physics World: uses physics
- Embedded Script → Scene Binding: installs engine for (evidence: `packages/scene/src/engine.ts`)
- Browser Engine Adapter → WebAssembly Engine: dispatches calls (evidence: `renderer/web/www/engine.ts`)
- Scene Binding → Browser Engine Adapter: uses browser binding
- Native Renderer Client → Renderer Runtime: runs runtime
- Playground Editor → Renderer Runtime: uses renderer (evidence: `playground/host/src/main.rs`)
- Editor UI → Playground Editor: sends commands
- Three.js Adapter → Scene API: implements API (evidence: `tools/three/engine.ts`)
- GPU Path Tracer → Rendered Frames: traces frames (evidence: `README.md`)