参数化 Topdown 建筑工坊（网页版）

把参数化 3D 建筑一键渲染成 2D 俯视像素图的本地网页工具。

• 内置 10 种建筑风格、46 种建筑类型，支持正交 / 透视、多角度、精灵表导出。
• 纯前端、零依赖、不联网：不依赖 Godot，不需要启动服务器，双击即可用。
• 配套 Godot 插件 addons/hd2d_scene_tools（v5/v6 配方），按相同几何与参数移植。

普通出图不需要 Node.js、Python，也不需要任何 npm install。js/atlases.js 体积较大（约 7.6 MB）是因为内嵌了 10 套图集，目的是让你在 file:// 下双击也能读到像素数据。

使用 Chrome 或 Edge（推荐）。少数浏览器在 file:// 下会限制内嵌数据解码，改用本地服务器即可（见「常见问题」）。

方式 A：双击打开（最简单）

1. 下载并解压整个项目文件夹。
2. 双击 启动工具.bat（或 index.html），会用默认浏览器打开工具。
3. 推荐窗口分辨率 1600×1000 以上。

方式 B：本地服务器（如遇到空白页）

cd 参数化topdown建筑
python -m http.server 8000
:: 浏览器访问 http://localhost:8000/

打开后：

• 左侧选「风格」和「建筑类型」，右侧实时预览。
• 滚轮缩放、拖拽平移、双击复位预览画面。

1. 选风格 / 建筑

   • 左侧「风格」下拉选 10 种内置风格之一（江南古镇、欧式、日式町屋、中式宫阙、哥特、蒸汽工业……）。
   • 下方选建筑类型与参数（宽 / 深 / 楼层 / 坡度 / 窗列 / 屋顶形态等），或点「随机建筑」。

2. 调视角

   • 投影：正交（无透视）或透视（设 FOV）。
   • 俯角、方向数（1/2/4/8）、画面尺寸、留白、描边、背景等按需调整。

3. 导出

   • 「② 导出当前方向」：存单张 PNG。
   • 「③ 导出全部方向」：打包 ZIP，内含 dir_0.png … dir_N.png、sheet.png（精灵表）、recipe.json（配方）。
   • 「下载图集模板」：导出当前风格 4×4 图集，方便画师重绘后重新导入。
   • v1.1 起，导出的每张 PNG 都内嵌生成参数（工具版本 + 完整配方，写在 PNG 文本块里，不影响像素）。
   • 「导入图片配方」：选一张本工具（网页或命令行）导出的 PNG，就能把当时的风格、建筑、种子、参数、视角、描边与部件覆盖恢复成界面配置；命令行侧对应 inspect / rec apply，见「七、命令行」。

4. 自定义风格（风格工坊）

   • 点顶部「风格工坊」，上传自己的 4×4 图集（或逐角色单图 / 调色板），另存为新风格。
   • 点预览画面的任意部位，可查看该部件纹理、单独染色 / 换图 / 描边 / 重置，并写进配方。

所有参数会自动保存在浏览器 localStorage，刷新不丢。

• 正方形 PNG，边长能被 4 整除，建议 512（128px/格） 或 1024（256px/格）。
• 4×4 = 16 格，顺序固定：

• 可平铺角色（除 door/window/sign/shutter/wall_base/roof_edge 外）需四方连续。
• 用像素块表达明暗，不要依赖平滑渐变；透明像素会露底，请补满 alpha。
• 上传时会自动校验：是否正方形、是否能被 4 整除、每格是否为空 / 接近纯色。

双击后浏览器空白 / 脚本不执行？ 请用 Chrome 或 Edge；或在目录里运行 python -m http.server 8000 后访问 http://localhost:8000/。

样式保存在哪里？ 保存在浏览器 localStorage。换浏览器或清理数据会丢，请用「导出全部风格」备份成 JSON（含内嵌图集），可在另一台机器「导入风格包」。

为什么像素风看起来有点软？ 关掉「抗锯齿」，并把画面尺寸设成与最终放大倍数匹配的值（例如 256 再整数放大 3×）。

种子和 Godot 里不一样？ 几何参数完全一致，但随机序列实现不同（PCG32 播种细节不同）。要与 Godot 完全一致，请以本工具导出的 recipe.json 为准重建。

能批量出图吗？ 网页端一次导出当前建筑的全部方向；多建筑批量用命令行版一条命令即可（见「七、命令行」）：

node cli/tb.js batch jobs.json

参数化topdown建筑/
├─ index.html              页面骨架（参数面板 / 预览 / 风格工坊）
├─ 启动工具.bat            用默认浏览器打开 index.html
├─ AGENTS.md               AI agent 起始指引（精简版，先读这个）
├─ tb.cmd                  命令行版快捷入口（= node cli\tb.js，需 Node 18+）
├─ css/app.css             界面样式
├─ js/                     核心逻辑（几何 / 材质 / 光栅化 / 界面）
├─ cli/                    命令行版（给 AI agent / 脚本用，见「七」）
├─ samples/                示例输出与界面截图
└─ tools/                  开发自测（不影响普通使用，见下）

同一套几何 / 材质 / 光栅化，多一个命令行出口，零依赖（Node 18+，不用 npm install）。 完整说明见 cli/README.md，这里只列最短路径：

:: 出图（默认 512、俯角 45、单方向、正交）
node cli/tb.js render forest inn -o out/inn.png

:: 8 方向 + 精灵表 + ZIP + 配方
node cli/tb.js render jiangnan inn -d 8 --sheet --zip -o out/inn8

:: 让 agent 一次摸清全部参数与枚举
node cli/tb.js schema

:: 单进程批量（图集只解析一次）
node cli/tb.js batch jobs.json

:: 读回图片里的生成参数（v1.1 起默认内嵌）
node cli/tb.js inspect out/inn.png

:: PNG 直接当配方用：按图片里的参数重画一遍
node cli/tb.js rec apply out/inn.png -o out/again

为 agent 做的几件事：

• 默认只回一行 JSON 摘要：version / canvas / dirs / tris / ink / bbox / ms / meta / files，ink 与 bbox 能直接判断「是不是空白、构图是否偏移」；--quiet 只回路径，--thumb 附缩略图。
• 不需要读源码：list styles|types|params|roles|enums 与 schema 给出全部可选值与参数范围。
• 少打字：render forest inn -o a.png 就够；常用组合可 preset save pixel 后只写 --preset pixel。
• 可复现：--recipe 吃网页导出的 recipe.json；v1.1 起每张 PNG 自带配方，inspect 回读、rec apply <png> 直接重画（--save-recipe 写出的配方也能拖回网页）。
• 全功能对齐：多方向 / 精灵表 / 三套描边 / 部件级染色换图 / 自定义风格包导入导出 / 图集校验与模板，命令行都能做。
• Godot 预制体：--godot-prefab + --godot-texture 额外输出纯内置节点的 .tscn（碰撞层 = 地基投影，遮挡层 = 每块外轮廓），普通 PNG 输出不变（详见下文）。
• 快：图集解码结果缓存在 cli/.cache/，单次渲染约 0.4s；batch 复用同一进程。

每张导出的 PNG（含精灵表、缩略图、ZIP 内的帧）默认写入三个 PNG 文本块，像素数据一个字节都不改，任何看图软件都不受影响：

node cli/tb.js inspect out/inn.png                    :: 版本 + 视角/建筑参数
node cli/tb.js inspect out/inn.png --full              :: 连完整配方一起看
node cli/tb.js inspect out/inn.png --save-recipe a.json
node cli/tb.js rec apply out/inn.png -o out/again      :: 按图片参数重画
node cli/tb.js render forest inn --no-meta             :: 不要内嵌（默认写入）

• 内嵌数据不含时间戳：同一组参数渲染出的 PNG 逐字节相同。
• 部件贴图是数据量大的 dataURL，入图时剥离，只保留来源文件名、字节数与 crc32 指纹；inspect 会给出提示，复现时重新指定 --part <角色>:texture=<文件> 即可。
• 网页版与命令行版写的是同一套块名和结构，互相都能读：网页预览下方的「导入图片配方」等价于 inspect + rec apply，命令行 inspect 也能读网页导出的图（网页写的配方未压缩，CLI 一样解析）。

普通 PNG 输出链路完全不变；需要时额外导出可直接放进 Godot 工程的预制体：

node cli/tb.js render forest inn --size auto --scale fixed --ppm 64 --no-aa ^
  --godot-project D:/YourGodotProject ^
  --godot-texture res://prefab/village/inn.png ^
  --godot-prefab  res://prefab/village/inn.tscn ^
  -o out/inn.png

产物：

• out/inn.png：原来的整张画布 PNG（不受影响）。
• res://prefab/village/inn.png：预制体专用的裁剪 PNG（不透明边界 + --godot-margin，默认 6px）。
• res://prefab/village/inn.tscn：纯内置节点预制体。

碰撞/遮挡多边形是按这张裁剪 PNG 的尺寸与原点计算的，.tscn 里的 ext_resource 必须指向同一张图；换成旧图（尺寸/裁切不同）会整体错位。建议给裁剪图单独留路径（例如 res://prefab/architecture/inn.png），不要指向旧的村庄贴图。网页端导出的 ZIP 已按你填写的 res:// 目录结构打包，直接解压到工程根目录即可。

节点结构与口径：

StaticBody2D (collision_layer=1, collision_mask=0)
├─ CollisionPolygon2D   ← 地基台基（w+0.24 × d+0.24）按当前相机投影后的四边形
├─ Sprite2D             ← offset 让世界原点（地基中心）落在节点原点
└─ 遮挡层 (Area2D)
   └─ CollisionPolygon2D × N ← 不透明覆盖填掉内部镂空、扣除碰撞区，只保留基点（地基中心）以上，每块连通区域的外轮廓

• 不挂任何脚本，不含 StippleShadow；碰撞/遮挡都交给项目现有的 scene_object.gd 或你自己的节点去接。
• 俯角 45° 时，进深在 2D 平面上会被压缩为 d×sin45°，与导出的精灵底座严格对齐；随机朝向 / 透视同样支持。
• 预制体取第 1 个方向（网页端为当前预览方向）；需透明背景；俯角过低导致地基投影退化为线时会直接报错。
• 网页端：预览下方「导出 Godot 预制体」按钮，导出 ZIP（裁剪 PNG + .tscn），填写贴图 res:// 路径即可。
• 说明：Godot 的 CollisionPolygon2D 不支持孔洞。若某块地基被不透明像素完全包围，遮挡层会按「外轮廓」规则把该区域一并覆盖；该区域本身被碰撞挡住，实际不可达。

普通用户可忽略本节。以下脚本仅用于维护 / 验证源码，需要对应运行时：

:: 几何 / 渲染 / 采样自测（需要 Node 18+）
node tools/selftest.js
node tools/test_nearest.js
node tools/test_all_types.js
node tools/test_views.js
node tools/ui_test.js        :: 需要本机 Chrome / Edge

:: 命令行版端到端自测（需要 Node 18+）
node cli/selftest.js

:: 从 Godot 插件重新生成目录与图集（需要 Python + Pillow）
pip install Pillow
python tools/build_assets.py
:: 也可指定插件目录：
python tools/build_assets.py --addon "<插件>\addons\hd2d_scene_tools"

tools/ 下的脚本不参与出图，删掉也不影响普通用户使用。

• 欢迎 Issue / Pull Request。提交代码前请先跑一遍 tools/ 自测确保无回归。
• 本项目为 Godot 插件 hd2d_scene_tools 的网页移植版，引用其几何与参数规范，请遵守其相应许可。
• 图集素材如涉及第三方版权，请在使用 / 分发前自行确认授权。

• Godot 预制体导出：render 新增 --godot-prefab / --godot-texture / --godot-project / --godot-margin / --godot-name，用同一视角的 3D 网格与相机变换算出「地基投影碰撞层」和「不透明覆盖扣除碰撞区、只保留基点（地基中心）以上」的每块外轮廓，生成纯内置节点的 .tscn（StaticBody2D + CollisionPolygon2D + Sprite2D + Area2D），不含脚本与 StippleShadow；额外落一张裁剪 PNG，普通 PNG 输出链路不变。预制体取第 1 个方向（网页端为当前预览方向）。
• 网页端：预览下方新增「导出 Godot 预制体」，ZIP 按填写的 res:// 目录结构打包（裁剪 PNG + .tscn）。
• 几何层新增 mesh.footprint（地基台基尺寸），供碰撞层计算；不影响任何渲染结果。
• 版本号升至 1.2。

• 命令行版：新增 cli/（render / batch / list / schema / rec / styles / atlas / preset），零依赖、单进程批量、与网页的配方/预设/风格包互通。
• 图片内嵌元信息：网页版与命令行导出的 PNG 默认写入「工具版本 + 完整配方」（PNG 文本块，不影响像素）；新增 inspect 读回，rec apply <png> / render --recipe <png> 可直接按图片参数重画；--no-meta 可关闭。
• 网页导入图片：预览下方新增「导入图片配方」，选一张导出的 PNG 即可恢复完整配置（风格 / 建筑 / 种子 / 参数 / 视角 / 描边 / 部件覆盖），与 CLI 的 inspect / rec apply 对应。
• 输出摘要新增 version / meta 字段；同一参数渲染出的 PNG 逐字节一致。

• 网页版首个版本：10 种风格、46 种建筑类型、正交/透视、多方向与精灵表导出、风格工坊与部件级覆盖。

祝出图愉快 🏯