Tinyworld Single File
Developmenttinyworld-single-fileTinyworld Single File is an Agent Skill for development published in the jasonkneen/tiny-world-builder repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Use when editing the Tiny World Builder repo, especially tiny-world-builder.html, to preserve the static classic-script Three.js r185 app structure and local edit/reload workflow.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/jasonkneen/tiny-world-builder/blob/HEAD/.codex/skills/tinyworld-single-file/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/tinyworld-single-file, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Tiny World Single-File Workflow
Work mainly in tiny-world-builder.html; also update index.html, vendor/three/, publish.sh, checks, docs, or skills when a change affects those durable contracts.
Core rules:
- Keep the builder app single-file at runtime: inline CSS, inline JS, no bundler, no npm runtime packages.
- Root
index.htmlis a static landing page entry point; the builder remains available at/tiny-world-builderand/tiny-world-builder.html. random-island-preview.htmlis a standalone local-dev control shell for random-island reveal/card iteration. It embeds/tiny-world-builder?randomIslandPreview=1so the visible island is the real Three.js game renderer, then talks to the app bypostMessageto generate, load, and export reveal/game JSON. Production Netlify shares it through the privatenetlify/functions/random-island-preview.mjsroute instead of copying the HTML as a public static file.- Do not touch
tiny-world-builder BACKUP.htmlif present. - Preserve style: 2-space indent, semicolons, single-quoted strings, section comments like
// -------- tools --------. - Mutate board state through
setCell(x, z, opts), not directworld[x][z]writes outside initialization. - Keep Three.js pinned to r185 and self-hosted under
vendor/three/; do not reintroduce CDN runtime scripts. The app consumesvendor/three/tinyworld-three.r185.min.js, a generated classic-global bundle made from[email protected]; regenerate it withnpm run vendor:threeafter changingthreeor loader wiring. - If browser stack traces point at
tiny-world-builder/dist/LandscapeEngine.jsline numbers after source edits, runnpm run buildsodist/index.html,dist/tiny-world-builder.html, anddist/LandscapeEngine.jsare regenerated before judging the runtime. - Cluso's in-page embed is allowed in LOCAL DEV ONLY, injected at runtime by
tools/dev-server.js(never written into the committed HTML ordist/). The assets live under gitignoredcluso/andpublish.shexcludes that dir, sotools/check.js/tools/smoke-static.js(which scan the shipped HTML) stay green. Do NOT addcluso/cluso-embed.{js,css}references totiny-world-builder.htmlor any committed/shipped HTML — production must never load it. (Owner-approved override of the prior "no Cluso, even local" rule.) - Shared materials in
M.*must not be mutated per instance; clone first for unique opacity/material behavior and dispose cloned materials indisposeGroup.
Validation:
- Run
npm test(syntax-checks the inline app script, parsesworld.schema.json, verifies embedded schema parity, checks local script/link assets, and runs the no-browser smoke guard). - For targeted parser checks, run
perl -0ne 'print $1 if m#<script>\s*(.*?)\s*</script>#s' tiny-world-builder.html | node --check. - Prefer browser validation at
http://localhost:3000/tiny-world-builder. - Check console errors after visual/UI changes.
Inline <script> gotcha (has burned us twice)
tools/check.js extracts the main app script with this regex:
html.match(/<script>([\s\S]*?)<\/script>\s*<\/body>/);
It greedily matches from the first plain <script> through to the last
</script></body>. If you add another inline <script> block above the main
app (e.g. a defaults bootstrap), it MUST carry an HTML attribute or check.js
conflates the two scripts plus the literal </script><script> separator into
one parse target and throws Unexpected token '<'.
<script id="my-bootstrap">...</script> <!-- ✓ regex skips this -->
<script>...</script> <!-- ✗ becomes part of main app -->
Related durable systems
For persisted runtime state (defaults pipeline, audio, camera, panel
positions, feature flags) see .codex/skills/tinyworld-runtime-state.
For island layout, sponsor banner, plane/crop-duster flight paths see
.codex/skills/tinyworld-island-and-planes.