# jasonkneen/tiny-world-builder architecture

> Architecture diagram of the GitHub repository jasonkneen/tiny-world-builder, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jasonkneen/tiny-world-builder
- Repository: https://github.com/jasonkneen/tiny-world-builder

## Overview

1. **Overall shape**
   - This repo is a static 3D world-builder game/app with a browser-first runtime. The main entry is `tiny-world-builder.html`, backed by a large Three.js-based JavaScript runtime and a set of modular engine files under `engine/`.
   - Deploy targets are static hosts (Vercel/Netlify), with `publish.sh` producing `dist/` and Three.js self-hosted under `vendor/three/`.

2. **Core client runtime**
   - The app’s central responsibility is rendering and editing a voxel/terrain world in the browser.
   - The README calls out the key state boundary: `world[x][z]` holds intent/state per cell, and `cellMeshes['x,z']` holds the rendered Three.js objects for that cell.
   - `setCell(...)` is the main mutation entry point: it updates model state, rebuilds the affected cell, and re-renders neighbors when adjacency rules matter.

3. **Rendering and scene composition**
   - Rendering is split across engine subsystems such as `engine/world/01-render-core.js`, `02-cameras-lighting.js`, `03-geometry-materials.js`, `04-textures.js`, and `17-tile-renderers.js`.
   - Landscape generation has its own layer in `engine/landscape/*` for chunks, noise, shaders, water, and geometry.
   - The scene is assembled from terrain tiles plus object meshes, with adjacency-aware visuals for roads, shores, fences, houses, bridges, and rocks.

4. **Editing and interaction pipeline**
   - User input flows through tools and selection modules like `12-selection-tool.js`, `19-tools-toolbar.js`, `20-input-place-erase.js`, `21-object-transform-voxel-build.js`, `33-radial-menu.js`, and `35-tool-palette.js`.
   - The editor supports place/erase, terrain raise/lower, camera toggles, and tool switching. These interactions are all routed through the same world mutation contract so rendering stays consistent.

5. **Content generation and object factories**
   - World content is built from tile/object factories and specialized renderers in `05-tile-factory.js`, `06-history-object-factories.js`, `07-house-primitives.js`, `08-voxel-stamp-renderer.js`, `09-model-stamp-loader.js`, and `09b-voxel-build-factories.js`.
   - The design is intentionally data-driven: imported models, voxel stamps, and procedural primitives all end up as cell-level world intent before becoming meshes.

6. **Runtime systems layered on top of the same world**
   - Several subsystems share the same world state and rendering pipeline: vehicles/crowd, flight simulation, combat, weather/atmosphere, particles/clouds, audio, crop duster banners, moorings, ghost generation, and sub-object editing.
   - These are implemented as separate engine modules (`11-vehicle-crowd.js`, `34-flight-sim.js`, `41-flight-combat.js`, `22-audio.js`, `23-particles-clouds.js`, `39-atmosphere-effects.js`, etc.) but they all consume the same scene/world contract.

7. **World persistence and schema**
   - World data is validated against `world.schema.json`, and the app also ships default/preset content in `default_island.json` and `tinyworld-defaults.json`.
   - The README notes browser-local slots for multiple named saves, plus AI generation paths that validate sparse worlds against the embedded schema.
   - This makes the persistence boundary primarily client-side for normal gameplay, with schema-backed import/export and save slots.

8. **Backend API boundary on Netlify**
   - The repo includes a serverless API under `netlify/functions/` for assets, builds, profiles, preferences, share links, players, wallet, wallet payments, and LiveKit token issuance.
   - Supporting code in `netlify/functions/lib/` handles auth, DB access, HTTP utilities, profile logic, and Solana integration.
   - This backend is separate from the world renderer; it exists for account/state/payment/share features rather than the core 3D editor loop.

9. **Realtime multiplayer boundary**
   - Multiplayer is handled through PartyKit: `party/index.js` and `partykit.json`.
   - The README and file tree indicate live collaboration and command relays, so realtime state syncing is a distinct transport layer from the static client and Netlify API.

10. **Assets and external content**
   - The repo carries local asset bundles: models (`models/stunt_plane.glb`, `models/stamp-manifest.json`), sound effects/music, textures, crowd sprites, and reusable world assets.
   - Self-hosted Three.js assets under `vendor/three/` are a deliberate deployment boundary so the app does not depend on runtime CDN availability.

11. **Tooling, checks, and quality gates**
   - Validation is mostly static and repo-local: `tests/` covers schema, math, appearance, PartyKit behavior, and helper utilities; `tools/` includes dev server, perf probes, smoke checks, i18n checks, and model-stamp tooling.
   - This suggests architecture discipline around deterministic builds and contract checks rather than heavyweight runtime services.

12. **Documentation and extension model**
   - The repo is heavily documented with design specs and plans under `docs/` and workflow guidance in `AGENTS.md`, `.claude/`, `.codex/`, and `.agents/`.
   - Those directories are not runtime systems, but they matter architecturally because they encode how new game/editor subsystems are added and how large files are split or maintained.

Main entry points: [`engine/world/10-world-data.js`](https://github.com/jasonkneen/tiny-world-builder/blob/main/engine/world/10-world-data.js) (World state), [`engine/world/01-render-core.js`](https://github.com/jasonkneen/tiny-world-builder/blob/main/engine/world/01-render-core.js) (Render core), [`engine/world/02-cameras-lighting.js`](https://github.com/jasonkneen/tiny-world-builder/blob/main/engine/world/02-cameras-lighting.js) (Scene systems), [`engine/world/11-vehicle-crowd.js`](https://github.com/jasonkneen/tiny-world-builder/blob/main/engine/world/11-vehicle-crowd.js) (Runtime sims)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser runtime"]
  node_entry["World app<br/>html entry"]
  node_render_core["Render core<br/>world renderer<br/>[01-render-core.js]"]
  node_scene_systems["Scene systems<br/>world subsystems"]
  node_world_state[("World state<br/>state boundary<br/>[10-world-data.js]")]
  node_content_factory["Content factory<br/>tile/object factory<br/>[05-tile-factory.js]"]
  node_landscape["Landscape engine<br/>terrain pipeline<br/>[chunks.js]"]
  node_edit_tools["Editing tools<br/>input/editor"]
  node_ui_boot["UI wiring<br/>boot/ui"]
  node_runtime_fx["Runtime sims<br/>simulation layer"]
  node_flight_combat["Flight combat<br/>combat sim"]
  node_persistence[("Persistence API<br/>save/import/export")]
  node_ai_gen["AI generation<br/>world gen"]
end

subgraph group_backend["Server and realtime"]
  node_multiplayer["PartyKit bridge<br/>realtime sync<br/>[index.js]"]
  node_netlify_api["Netlify API<br/>serverless api<br/>[assets.mjs]"]
  node_netlify_lib["API libs<br/>backend helpers<br/>[db.mjs]"]
end

subgraph group_assets["Content and presets"]
  node_default_world["World presets<br/>world data"]
  node_schema["World schema<br/>[world.schema.json]"]
  node_media_assets["Media assets<br/>asset bundle<br/>[stunt_plane.glb]"]
end

subgraph group_tooling["Tooling and checks"]
  node_publish["Publish flow<br/>build script<br/>[publish.sh]"]
  node_checks["Validation tools<br/>dev checks<br/>[check.js]"]
  node_docs["Design docs"]
end

node_entry -->|"boots"| node_render_core
node_render_core -->|"assembles"| node_scene_systems
node_render_core -->|"reads/writes"| node_world_state
node_world_state -->|"rebuilds via"| node_content_factory
node_content_factory -->|"creates meshes"| node_scene_systems
node_scene_systems -->|"renders terrain"| node_landscape
node_edit_tools -->|"mutates"| node_world_state
node_ui_boot -->|"wires"| node_edit_tools
node_ui_boot -->|"initializes"| node_render_core
node_runtime_fx -->|"shares state"| node_world_state
node_runtime_fx -->|"animates"| node_scene_systems
node_flight_combat -->|"extends"| node_runtime_fx
node_persistence -->|"validates"| node_schema
node_ai_gen -->|"conforms to"| node_schema
node_ai_gen -->|"populates"| node_world_state
node_multiplayer -->|"syncs"| node_world_state
node_netlify_api -->|"uses"| node_netlify_lib
node_netlify_api -->|"serves"| node_persistence
node_default_world -->|"seeds"| node_world_state
node_media_assets -->|"feeds"| node_content_factory
node_publish -->|"packages"| node_media_assets
node_checks -->|"verifies"| node_schema
node_docs -.->|"guides"| node_edit_tools
node_docs -.->|"guides"| node_flight_combat

click node_entry "https://github.com/jasonkneen/tiny-world-builder/blob/main/tiny-world-builder.html"
click node_render_core "https://github.com/jasonkneen/tiny-world-builder/blob/main/engine/world/01-render-core.js"
click node_scene_systems "https://github.com/jasonkneen/tiny-world-builder/blob/main/engine/world/02-cameras-lighting.js"
click node_world_state "https://github.com/jasonkneen/tiny-world-builder/blob/main/engine/world/10-world-data.js"
click node_content_factory "https://github.com/jasonkneen/tiny-world-builder/blob/main/engine/world/05-tile-factory.js"
click node_landscape "https://github.com/jasonkneen/tiny-world-builder/blob/main/engine/landscape/chunks.js"
click node_edit_tools "https://github.com/jasonkneen/tiny-world-builder/blob/main/engine/world/12-selection-tool.js"
click node_ui_boot "https://github.com/jasonkneen/tiny-world-builder/blob/main/engine/world/30-ui-boot-wiring.js"
click node_runtime_fx "https://github.com/jasonkneen/tiny-world-builder/blob/main/engine/world/11-vehicle-crowd.js"
click node_flight_combat "https://github.com/jasonkneen/tiny-world-builder/blob/main/engine/world/41-flight-combat.js"
click node_persistence "https://github.com/jasonkneen/tiny-world-builder/blob/main/engine/world/29-persistence-api.js"
click node_ai_gen "https://github.com/jasonkneen/tiny-world-builder/blob/main/engine/world/26-ai-generation.js"
click node_multiplayer "https://github.com/jasonkneen/tiny-world-builder/blob/main/party/index.js"
click node_netlify_api "https://github.com/jasonkneen/tiny-world-builder/blob/main/netlify/functions/assets.mjs"
click node_netlify_lib "https://github.com/jasonkneen/tiny-world-builder/blob/main/netlify/functions/lib/db.mjs"
click node_default_world "https://github.com/jasonkneen/tiny-world-builder/blob/main/default_island.json"
click node_schema "https://github.com/jasonkneen/tiny-world-builder/blob/main/world.schema.json"
click node_media_assets "https://github.com/jasonkneen/tiny-world-builder/blob/main/models/stunt_plane.glb"
click node_publish "https://github.com/jasonkneen/tiny-world-builder/blob/main/publish.sh"
click node_checks "https://github.com/jasonkneen/tiny-world-builder/blob/main/tools/check.js"
click node_docs "https://github.com/jasonkneen/tiny-world-builder/blob/main/docs/superpowers/specs/2026-06-03-object-inspector-design.md"

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_entry,node_render_core,node_scene_systems,node_world_state,node_content_factory,node_landscape,node_edit_tools,node_ui_boot,node_runtime_fx,node_flight_combat,node_persistence,node_ai_gen toneBlue
class node_multiplayer,node_netlify_api,node_netlify_lib toneAmber
class node_default_world,node_schema,node_media_assets toneMint
class node_publish,node_checks,node_docs toneRose
```

## Components

### Browser runtime

Static browser app that renders, edits, and simulates the world.

- [World app](https://github.com/jasonkneen/tiny-world-builder/blob/main/tiny-world-builder.html): html entry · Browser-first entry point for the 3D world-builder. · `tiny-world-builder.html`
- [Render core](https://github.com/jasonkneen/tiny-world-builder/blob/main/engine/world/01-render-core.js): world renderer · Bootstraps the Three.js scene, render loop, and top-level world composition. · `engine/world/01-render-core.js`
- [Scene systems](https://github.com/jasonkneen/tiny-world-builder/blob/main/engine/world/02-cameras-lighting.js): world subsystems · Cameras, lighting, geometry, materials, textures, tile rendering, and scene picking. · `engine/world/02-cameras-lighting.js`
- [World state](https://github.com/jasonkneen/tiny-world-builder/blob/main/engine/world/10-world-data.js): state boundary · Owns cell intent/state and the mesh cache; setCell drives rebuilds and adjacency updates. · `engine/world/10-world-data.js`
- [Content factory](https://github.com/jasonkneen/tiny-world-builder/blob/main/engine/world/05-tile-factory.js): tile/object factory · Builds tiles, houses, voxel stamps, model stamps, and procedural object variants. · `engine/world/05-tile-factory.js`
- [Landscape engine](https://github.com/jasonkneen/tiny-world-builder/blob/main/engine/landscape/chunks.js): terrain pipeline · Chunking, noise, shaders, geometry, water, and landscape integration. · `engine/landscape/chunks.js`
- [Editing tools](https://github.com/jasonkneen/tiny-world-builder/blob/main/engine/world/12-selection-tool.js): input/editor · Selection, place/erase, transforms, toolbars, palettes, and radial menu interaction. · `engine/world/12-selection-tool.js`
- [UI wiring](https://github.com/jasonkneen/tiny-world-builder/blob/main/engine/world/30-ui-boot-wiring.js): boot/ui · Connects UI panels, tool controls, layers, and late boot wiring. · `engine/world/30-ui-boot-wiring.js`
- [Runtime sims](https://github.com/jasonkneen/tiny-world-builder/blob/main/engine/world/11-vehicle-crowd.js): simulation layer · Shared gameplay systems layered on the same world and scene contract. · `engine/world/11-vehicle-crowd.js`
- [Flight combat](https://github.com/jasonkneen/tiny-world-builder/blob/main/engine/world/41-flight-combat.js): combat sim · Aircraft combat, shields, and flight-specific gameplay logic. · `engine/world/41-flight-combat.js`
- [Persistence API](https://github.com/jasonkneen/tiny-world-builder/blob/main/engine/world/29-persistence-api.js): save/import/export · Client-side save slots, schema-aware import/export, and persistence hooks. · `engine/world/29-persistence-api.js`
- [AI generation](https://github.com/jasonkneen/tiny-world-builder/blob/main/engine/world/26-ai-generation.js): world gen · Generation and panel-agent integration for sparse or authored worlds. · `engine/world/26-ai-generation.js`

### Server and realtime

Netlify functions and PartyKit collaboration layer.

- [PartyKit bridge](https://github.com/jasonkneen/tiny-world-builder/blob/main/party/index.js): realtime sync · Collaborative state syncing and command relay over PartyKit. · `party/index.js`
- [Netlify API](https://github.com/jasonkneen/tiny-world-builder/blob/main/netlify/functions/assets.mjs): serverless api · Backend functions for assets, builds, profiles, preferences, sharing, players, wallet, and tokens. · `netlify/functions/assets.mjs`
- [API libs](https://github.com/jasonkneen/tiny-world-builder/blob/main/netlify/functions/lib/db.mjs): backend helpers · Auth, database, HTTP, profiles, and Solana helpers used by the serverless endpoints. · `netlify/functions/lib/db.mjs`

### Content and presets

Local assets, models, sounds, textures, and default world data.

- [World presets](https://github.com/jasonkneen/tiny-world-builder/blob/main/default_island.json): world data · Default island and baseline configuration used by the app and generators. · `default_island.json`
- [World schema](https://github.com/jasonkneen/tiny-world-builder/blob/main/world.schema.json): schema · Validation contract for world data and AI-generated sparse worlds. · `world.schema.json`
- [Media assets](https://github.com/jasonkneen/tiny-world-builder/blob/main/models/stunt_plane.glb): asset bundle · Local models, sounds, textures, crowd sprites, and self-hosted Three.js vendor files. · `models/stunt_plane.glb`

### Tooling and checks

Build, validation, and developer workflow support.

- [Publish flow](https://github.com/jasonkneen/tiny-world-builder/blob/main/publish.sh): build script · Static deployment packaging into dist/ for hosted builds. · `publish.sh`
- [Validation tools](https://github.com/jasonkneen/tiny-world-builder/blob/main/tools/check.js): dev checks · Schema, smoke, performance, i18n, model-stamp, and helper checks used during development. · `tools/check.js`
- [Design docs](https://github.com/jasonkneen/tiny-world-builder/blob/main/docs/superpowers/specs/2026-06-03-object-inspector-design.md): docs · Architecture notes, plans, and specs that guide subsystem boundaries and maintenance. · `docs/superpowers/specs/2026-06-03-object-inspector-design.md`

## Connections

- World app → Render core: boots · The HTML entry loads the core runtime.
- Render core → Scene systems: assembles · Core rendering composes cameras, lighting, geometry, materials, textures, and picking.
- Render core → World state: reads/writes · Rendering is driven by cell intent and mesh cache state.
- World state → Content factory: rebuilds via · Cell mutations route through factories and renderers to rebuild affected cells.
- Content factory → Scene systems: creates meshes · Factories emit the meshes and primitives consumed by scene composition.
- Scene systems → Landscape engine: renders terrain · Landscape contributes terrain chunks, geometry, shaders, and water.
- Editing tools → World state: mutates · Editor actions flow through the world mutation contract.
- UI wiring → Editing tools: wires · UI boot connects tool panels and input affordances.
- UI wiring → Render core: initializes · Boot wiring connects the UI to the runtime.
- Runtime sims → World state: shares state · Crowd, vehicles, effects, and other systems consume the same world contract.
- Runtime sims → Scene systems: animates · Runtime systems add dynamic scene elements and overlays.
- Flight combat → Runtime sims: extends · Combat is a specialized runtime layer on top of shared simulation infrastructure.
- Persistence API → World schema: validates · Saved and generated worlds are checked against the schema boundary.
- AI generation → World schema: conforms to · AI-generated worlds are schema-backed before entering the runtime.
- AI generation → World state: populates · Generation feeds sparse world intent into the same state model.
- PartyKit bridge → World state: syncs · PartyKit collaboration relays world edits and shared commands.
- Netlify API → API libs: uses · Serverless endpoints share auth, DB, HTTP, profile, and Solana helpers.
- Netlify API → Persistence API: serves · Backend endpoints support account and share-related persistence features.
- World presets → World state: seeds · Preset world content initializes or augments the runtime world.
- Media assets → Content factory: feeds · Imported models, sounds, textures, and vendor assets support content generation.
- Publish flow → Media assets: packages · Publishing bundles the static assets for deployment.
- Validation tools → World schema: verifies · Repo checks cover world validation and related contracts.
- Design docs → Editing tools: guides · Specs and plans describe editor and subsystem behavior.
- Design docs → Flight combat: guides · Combat plans and specs shape the flight-combat subsystem.
