# lindblum/grid-game-threejs architecture

> Architecture diagram of the GitHub repository lindblum/grid-game-threejs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lindblum/grid-game-threejs
- Repository: https://github.com/lindblum/grid-game-threejs

## Overview

Grid Game is a browser and WebXR creative building app: users aim at a body-centred-cubic cell, place or delete colored truncated-octahedron blocks, and manage scenes through New, Load and Save. React presents the HUD and menu while the Three.js Engine owns interaction, rendering and XR behavior; World holds the editable scene and JSON representation. Save-file listing and writing are supported alongside a file-import/export fallback. The graph follows documented capabilities and sampled call sites; some feature wiring is represented only at its documented module boundary.

Main entry points: [`src/game/Engine.js`](https://github.com/lindblum/grid-game-threejs/blob/main/src/game/Engine.js) (Game engine), [`src/App.jsx`](https://github.com/lindblum/grid-game-threejs/blob/main/src/App.jsx) (React app), [`src/game/world.js`](https://github.com/lindblum/grid-game-threejs/blob/main/src/game/world.js) (Block world), [`src/game/saves.js`](https://github.com/lindblum/grid-game-threejs/blob/main/src/game/saves.js) (Save client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User interface"]
  node_app["React app<br/>[App.jsx]"]
  node_menu["Menu model<br/>[menu.js]"]
  node_controls["Input mappings<br/>[controls.js]"]
end

subgraph group_runtime["Game runtime"]
  node_engine["Game engine<br/>[Engine.js]"]
  node_audio["Sound effects<br/>[audio.js]"]
end

subgraph group_domain["World model"]
  node_toolset["Block tools<br/>[tools.js]"]
  node_lattice["BCC lattice<br/>[lattice.js]"]
  node_world["Block world<br/>[world.js]"]
  node_geometry["Block geometry<br/>[geometry.js]"]
end

subgraph group_persistence["Scene persistence"]
  node_saves["Save client<br/>[saves.js]"]
  node_saveapi["Save API<br/>[saves-api.js]"]
  node_savefiles[("Save files")]
end

subgraph group_xr["XR experience"]
  node_xrpanels["XR panels<br/>[xrPanels.js]"]
end

node_player(("Builder"))
node_browser(("Browser runtime"))
node_webxr(("WebXR session"))

node_player -->|"uses"| node_app
node_app -->|"creates"| node_engine
node_app -->|"renders from"| node_menu
node_app -->|"displays"| node_controls
node_app -->|"shows tools"| node_toolset
node_engine -->|"edits and renders"| node_world
node_engine -->|"targets cells"| node_lattice
node_world -->|"validates neighbors"| node_lattice
node_world -->|"builds meshes"| node_geometry
node_engine -->|"reads model"| node_menu
node_engine -->|"selects tools"| node_toolset
node_engine -->|"lists and writes"| node_saves
node_saves -.->|"requests files"| node_saveapi
node_saveapi -->|"reads and writes"| node_savefiles
node_engine -->|"plays effects"| node_audio
node_engine -->|"updates panels"| node_xrpanels
node_browser -->|"hosts"| node_app
node_engine -.->|"requests session"| node_webxr
node_app -->|"sends actions"| node_engine

click node_app "https://github.com/lindblum/grid-game-threejs/blob/main/src/App.jsx"
click node_menu "https://github.com/lindblum/grid-game-threejs/blob/main/src/game/menu.js"
click node_controls "https://github.com/lindblum/grid-game-threejs/blob/main/src/game/controls.js"
click node_toolset "https://github.com/lindblum/grid-game-threejs/blob/main/src/game/tools.js"
click node_engine "https://github.com/lindblum/grid-game-threejs/blob/main/src/game/Engine.js"
click node_lattice "https://github.com/lindblum/grid-game-threejs/blob/main/src/game/lattice.js"
click node_world "https://github.com/lindblum/grid-game-threejs/blob/main/src/game/world.js"
click node_geometry "https://github.com/lindblum/grid-game-threejs/blob/main/src/game/geometry.js"
click node_saves "https://github.com/lindblum/grid-game-threejs/blob/main/src/game/saves.js"
click node_saveapi "https://github.com/lindblum/grid-game-threejs/blob/main/saves-api.js"
click node_savefiles "https://github.com/lindblum/grid-game-threejs/tree/main/saves"
click node_xrpanels "https://github.com/lindblum/grid-game-threejs/blob/main/src/game/xrPanels.js"
click node_audio "https://github.com/lindblum/grid-game-threejs/blob/main/src/game/audio.js"

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_menu,node_controls,node_browser toneBlue
class node_engine,node_audio toneAmber
class node_toolset,node_lattice,node_world,node_geometry toneMint
class node_saves,node_saveapi,node_savefiles toneRose
class node_xrpanels,node_player,node_webxr toneIndigo
```

## Components

### User interface

- [React app](https://github.com/lindblum/grid-game-threejs/blob/main/src/App.jsx): `src/App.jsx`
- [Menu model](https://github.com/lindblum/grid-game-threejs/blob/main/src/game/menu.js): `src/game/menu.js`
- [Input mappings](https://github.com/lindblum/grid-game-threejs/blob/main/src/game/controls.js): `src/game/controls.js`

### Game runtime

- [Game engine](https://github.com/lindblum/grid-game-threejs/blob/main/src/game/Engine.js): `src/game/Engine.js`
- [Sound effects](https://github.com/lindblum/grid-game-threejs/blob/main/src/game/audio.js): `src/game/audio.js`

### World model

- [Block tools](https://github.com/lindblum/grid-game-threejs/blob/main/src/game/tools.js): `src/game/tools.js`
- [BCC lattice](https://github.com/lindblum/grid-game-threejs/blob/main/src/game/lattice.js): `src/game/lattice.js`
- [Block world](https://github.com/lindblum/grid-game-threejs/blob/main/src/game/world.js): `src/game/world.js`
- [Block geometry](https://github.com/lindblum/grid-game-threejs/blob/main/src/game/geometry.js): `src/game/geometry.js`

### Scene persistence

- [Save client](https://github.com/lindblum/grid-game-threejs/blob/main/src/game/saves.js): `src/game/saves.js`
- [Save API](https://github.com/lindblum/grid-game-threejs/blob/main/saves-api.js): `saves-api.js`
- [Save files](https://github.com/lindblum/grid-game-threejs/tree/main/saves): `saves`

### XR experience

- [XR panels](https://github.com/lindblum/grid-game-threejs/blob/main/src/game/xrPanels.js): `src/game/xrPanels.js`

### Other components

- **Builder**
- **Browser runtime**
- **WebXR session**

## Connections

- Builder → React app: uses
- React app → Game engine: creates
- React app → Menu model: renders from
- React app → Input mappings: displays
- React app → Block tools: shows tools
- Game engine → Block world: edits and renders
- Game engine → BCC lattice: targets cells
- Block world → BCC lattice: validates neighbors
- Block world → Block geometry: builds meshes
- Game engine → Menu model: reads model
- Game engine → Block tools: selects tools
- Game engine → Save client: lists and writes
- Save client → Save API: requests files
- Save API → Save files: reads and writes
- Game engine → Sound effects: plays effects
- Game engine → XR panels: updates panels
- Browser runtime → React app: hosts
- Game engine → WebXR session: requests session
- React app → Game engine: sends actions