SuperAPI AI 工具集

tinyworld-single-file

编程与开发

查看项目

更新于 10-30 13:08

技能介绍

用途

该技能用于编辑 Tiny World Builder 仓库,尤其是 tiny-world-builder.html,确保不破坏静态经典脚本式 Three.js r185 应用的既有结构和本地依赖约定。当改动影响其他长期约定时,也需同步更新 index.html、vendor/three/、publish.sh、检查脚本、文档或技能。

核心规则

  • 保持构建器应用在运行时为单文件:内联 CSS、内联 JS,不使用打包器,不引入 npm 运行时包。
  • 根目录 index.html 是静态落地页入口;构建器仍可通过 /tiny-world-builder 和 /tiny-world-builder.html 访问。
  • random-island-preview.html 是独立的本地开发控制壳,用于随机岛屿揭示/卡片迭代。它内嵌 /tiny-world-builder?randomIslandPreview=1,使可见岛屿为真实的 Three.js 游戏渲染器,并通过 postMessage 与主应用通信以生成、加载和导出 JSON。生产 Netlify 通过私有 netlify/functions/random-island-preview.mjs 路由共享它,而不是把 HTML 复制为公开静态文件。
  • 若存在 tiny-world-builder BACKUP.html,不要改动。
  • 保持代码风格:2 空格缩进、分号、单引号字符串、类似 // -------- tools -------- 的分段注释。
  • 通过 setCell(x, z, opts) 变更棋盘状态,不要在初始化之外的直接写 world[x][z]。
  • Three.js 固定在 r185 并自托管于 vendor/three/;不要重新引入 CDN 运行时脚本。应用使用 vendor/three/tinyworld-three.r185.min.js,这是由 three@0.185.0 生成的传统全局包;改动 three 或加载器接线后,用 npm run vendor:three 重新生成。
  • 若修改源码后浏览器堆栈指向 tiny-world-builder / dist/LandscapeEngine.js 的行号,先运行 npm run build 重新生成 dist/index.html、dist/tiny-world-builder.html 和 dist/LandscapeEngine.js,再判断运行时行为。

本地开发嵌入限制

Cluso 的页内嵌入仅允许在本地开发中使用,由 tools/dev-server.js 在运行时注入,绝不写入已提交的 HTML 或 dist/。其资源位于被 gitignore 的 cluso/ 目录,publish.sh 会排除该目录,因此扫描发布 HTML 的 tools/check.js / tools/smoke-static.js 仍可通过。不要在 tiny-world-builder.html 或任何已提交/发布的 HTML 中添加 cluso/cluso-embed.{js,css} 引用——生产环境绝不能加载它。

材质约定

M.* 中的共享材质不得按实例修改;需要独特透明度/材质行为时应先克隆,并在 disposeGroup 中释放克隆材质。

验证方式

  • 运行 npm test:对内联应用脚本做语法检查、解析 world.schema.json、验证内嵌 schema 一致性、检查本地脚本/链接资源,并运行无浏览器冒烟检查。
  • 定向解析检查可运行:perl -0ne 'print $1 if m#<script>\s*(.?)\s</script>#s' tiny-world-builder.html | node --check。
  • 优先在 http://localhost:3000/tiny-world-builder 进行浏览器验证。
  • 视觉/UI 改动后检查控制台错误。

内联 <script> 注意事项

tools/check.js 使用正则 html.match(/<script>([\s\S]?)</script>\s</body>/); 提取主应用脚本。它会从第一个普通 <script> 贪婪匹配到最后一个 </script></body>。若在主应用之上新增内联 <script> 块(例如默认值引导),必须带有 HTML 属性,否则 check.js 会把两个脚本及字面分隔符合并为一个解析目标并抛出 Unexpected token '<'。示例:<script id="my-bootstrap">...</script> 可被正则跳过;无属性的 <script>...</script> 则会被并入主应用。

关联系统

  • 持久化运行时状态(默认值管线、音频、相机、面板位置、功能开关)参见 .codex/skills/tinyworld-runtime-state。
  • 岛屿布局、赞助横幅、飞机/农用喷洒机飞行路径参见 .codex/skills/tinyworld-island-and-planes。