How jasonkneen/tiny-world-builder works
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: 10-world-data.js World state · 01-render-core.js Render core · 02-cameras-lighting.js Scene systems · 11-vehicle-crowd.js Runtime sims
Components 21
Browser runtime
Static browser app that renders, edits, and simulates the world.
- World app · Browser-first entry point for the 3D world-builder.
tiny-world-builder.html - Render core · Bootstraps the Three.js scene, render loop, and top-level world composition.
engine/world/01-render-core.js - Scene systems · Cameras, lighting, geometry, materials, textures, tile rendering, and scene picking.
engine/world/02-cameras-lighting.js - World state · Owns cell intent/state and the mesh cache; setCell drives rebuilds and adjacency updates.
engine/world/10-world-data.js - Content factory · Builds tiles, houses, voxel stamps, model stamps, and procedural object variants.
engine/world/05-tile-factory.js - Landscape engine · Chunking, noise, shaders, geometry, water, and landscape integration.
engine/landscape/chunks.js - Editing tools · Selection, place/erase, transforms, toolbars, palettes, and radial menu interaction.
engine/world/12-selection-tool.js - UI wiring · Connects UI panels, tool controls, layers, and late boot wiring.
engine/world/30-ui-boot-wiring.js - Runtime sims · Shared gameplay systems layered on the same world and scene contract.
engine/world/11-vehicle-crowd.js - Flight combat · Aircraft combat, shields, and flight-specific gameplay logic.
engine/world/41-flight-combat.js - Persistence API · Client-side save slots, schema-aware import/export, and persistence hooks.
engine/world/29-persistence-api.js - AI generation · 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 · Collaborative state syncing and command relay over PartyKit.
party/index.js - Netlify API · Backend functions for assets, builds, profiles, preferences, sharing, players, wallet, and tokens.
netlify/functions/assets.mjs - API libs · 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 · Default island and baseline configuration used by the app and generators.
default_island.json - World schema · Validation contract for world data and AI-generated sparse worlds.
world.schema.json - Media assets · 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 · Static deployment packaging into dist/ for hosted builds.
publish.sh - Validation tools · Schema, smoke, performance, i18n, model-stamp, and helper checks used during development.
tools/check.js - Design docs · Architecture notes, plans, and specs that guide subsystem boundaries and maintenance.
docs/superpowers/specs/2026-06-03-object-inspector-design.md
Connections 24
- 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.