# MapForge 地图生成网站 · 立项评估与 MVP 方案

> 日期：2026-10-05 ｜ 触发：boss 点题立项（原话见下）
> 本轮交付物**只有文档，零代码、零新依赖**（boss 原话：「你先把文档弄好，不需要立即开发……前期先简单弄一个 mvp，功能一点一点加上去，一块一块补充」）
> boss 原话需求：「我要做一个地图生成网站 https://watabou.github.io/ 和 https://jaconir.online/tools/procedural-level-generator?seed=bn23kt ，快速生成地图，支持下载，我 godot 导入即可，因此我需要你定义一些标准格式，或则说 godot 有标准格式，那就使用标准格式」

## 0. TLDR（三行）

1. **标准格式已定稿**：`mapforge-map/v1`（引擎无关正典）+ Tiled JSON `.tmj` 投影 + zip 包协议 `mapforge-pack/v1`。Godot 侧不发明新格式——用业内标准 Tiled JSON，实测由活跃第三方插件 **YATI**（MIT，v2.2.9 需 Godot 4.3+，README 自证跑到 4.7.2）导入。正本：`D:/code/work/lin/mapforge/docs/EXPORT-STANDARD.md`。
2. **一条硬边界**：网站永不吐 `.tscn`/`.tres`。Godot 4.3 的 `TileMap→TileMapLayer` 断代，连第三方导入器都被逼成分版本双线发布；网页侧手拼引擎序列化文本 = 产品绑死某个 Godot 小版本。真要「拖进去就出场景」，M2 做的是 **Godot 插件**（引擎 API 落盘，`npc_plugin` 同型打法），不是网站文本生成。
3. **下一步 = M0**：先拿一个 4×3 手工夹具把 Godot 导入通路**真跑一遍**，再写任何生成器——那条通路决定整个产品承诺成不成立，跑不通就改路线而不是硬推。

## 1. 产品定位

浏览器里点一下，拿到**能直接进 Godot 工程用**的 2D 游戏地图（地牢/洞穴/地形三族），种子即链接、下载即用。

竞品链条拆解出的空位（完整论证在 `docs/竞品分析/2026-10-05-程序化地图生成对标与Godot引擎互通路线.md`）：watabou 只出「给人看的图」（页面原文：Realm/Cave/Dwelling = "PNG and SVG export"，City/Village/Dungeon 多的那份 JSON 是它自己的再编辑存档，喂不进引擎）；Godot 引擎内插件能出可用数据但要开引擎且多为停更 demo；jaconir 是唯一声称三段全通的（页面原文含 "Tiled TMX + tileset PNG"、"Godot 4 .tscn scene export"），但它的 `.tscn` 直出恰是绑版本那条不可核的路。**「网页生成 → 开放标准 → 引擎当天能用」这条链没人同时做实。**

自家第一个用户也已就位：英魂无双统一 Godot 4.7.1（boss 09-19 拍板），正落在 YATI 2.x 的支持区间内。

## 2. 核心能力拆解（MVP 需要什么轮子，全部实测选型）

| 能力 | 选型 | 证据（2026-10-05 npm `last-week` 读数） |
|---|---|---|
| 可复现随机 | `seedrandom`（唯一随机出口，禁 `Math.random()`） | 11 431 920/周 |
| 地形噪声 | `simplex-noise` | 431 485/周（`noisejs` 仅 9 634，少数派） |
| 打包下载 | `fflate` | 111 899 778/周（`jszip` 56 621 113，fflate 更快更小） |
| 生成算法 | **自研**，不用 `rot`（rot.js） | `rot` 仅 **291 次/周** = 事实弃用；且算法本体是产品护城河，外包给库=交底 |
| 前端 | React 19 + TS + Vite + Tailwind v4 | 公司 09-20 拍板产品前端一律 React+TS |
| 托管 | Cloudflare Pages 纯静态零后端 | 公司 09-06「静态站能不引入后端就不引入」 |

新增依赖合计 3 个，零安装零费用，gzip 后 20 KB 级；后端零。

## 3. 开发难度评估（单人 + agent，给区间不给保证）

- **M0 骨架 + Godot 通路验证**：1 天工。风险最集中的一步（YATI 能否吃我们的包结构、4.7 实测导入），失败即改路线。
- **M1 MVP（三族 + 导出 + 双语 + 部署）**：3~5 天工。三族共用一个网格模型与一个导出出口，边际成本主要是算法调参和图集（先用程序画的 16px 占位）。
- **M2 自研 Godot 导入件 + 多 tileset**：3~5 天工，且要背 Godot 版本兼容的长期维护义务（这是把护城河成本真正付掉的时刻，所以排在需求被验证之后）。
- 观感分水岭不在参数多，在**边缘过渡瓦片与装饰层**（DESIGN §4.2）；第一版就要有，否则导出率低时没法定位是算法丑还是没做完。

## 4. 开源与合规清单（可借鉴 / 禁复用，边界写死）

| 对象 | 许可 | 我们的动作 |
|---|---|---|
| Azgaar Fantasy Map Generator | **MIT**（LICENSE 首行实测），6 052★，推送 2026-10-05（当日活跃） | 想读实现读它——网页地图生成的**干净**开源参照 |
| `Kiamo2/YATI` | MIT，推送 2026-10-04 | 用户侧装它，我们不 fork 不分发（包内 README 只给下载指引） |
| `heygleeson/godot-ldtk-importer` | MIT，推送 2025-02 | P2 候选通路 |
| Watabou 全部生成器 | **闭源**（FAQ 原文「unless I am done with a project I don't make its code public」），栈 Haxe+OpenFL | 只学产品形态与导出选择，不碰代码 |
| `watabou/TownGeneratorOS`、`pixel-dungeon` | GPL-3.0 | 不搬（搬即传染开源，与公司 09-22「开源信任战略暂缓」冲突） |
| `CompassOS`/`RuneGeneratorOS` 等 | 无 license 文件 = 默认全权保留 | 不可复用，连读都不必要 |
| Watabou **产物** | 可自由商用（署名感激但不要求），但作者「强烈反对把生成的地图拿去卖」 | 卖点永远是工具与素材包，**不写「卖生成的地图」**（已写进 PRD §8 与合规线） |

## 5. 建议设计（只给指针，不重复内容）

- 协议正本：`mapforge/docs/EXPORT-STANDARD.md` — 字段表、投影到 Tiled 的映射（含 GID/翻转位、tag 双写规则）、zip 结构、§7 三条验收通路。
- 意图层：`mapforge/docs/PRD.md` — 定位/用户/四场景/六约束/非目标（附重启条件）/四个指标（含导出率 ≥8% 这类可验口径）。
- 架构与门禁：`mapforge/docs/DESIGN.md` — 模块边界（`core/`+`export/` 禁 import DOM，同一份代码 node 与浏览器双宿主）、8 条不变量（I1–I8 含「200 seed 双跑字节相同」）、三族算法步骤与已知坑、三层测试门禁 L1/L2/L3。
- 路线与退路：`mapforge/docs/ROADMAP.md` — M0→M4、待办池、5 条风险各配触发信号与退路（含「三族同批拖太久就砍成两族先行」这条，boss 选的这批更重的方案也留了闸门）。

关键取舍一句话：**语义靠受控标签词表（`terrain:*`/`property:*`/`role:*`）自动翻成 Godot 的碰撞与标记节点，词表封闭、新词必须同时补实跑判据**——这是「导进去就能撞墙」的唯一自动化路径，也是不给「同一语义两处判据」留口子。

## 6. 风险与合规

| 风险 | 现状 | 处置 |
|---|---|---|
| 主通路依赖第三方（YATI） | 它活着（2026-10-04 推送），但停更/改协议是真实可能 | M2 自研导入件就是对冲；v1 的正典 JSON 保证「即使插件死了数据不废」 |
| 竞品不可核（jaconir 仓库/许可/直出质量） | 标未核实 | 上线后复扫一次；不把它的宣称当市场证据，只当需求存在信号 |
| 用户抱怨零样本（§3 第①问留空） | 按纪律不编造 | M1 上线后第一批要补的账：真实反馈 ≥3 独立来源才立需求 |
| 新品线撞「流量优先、产品降速」主线（09-22） | 本产品是**产品迭代**，不是新获客战线 | 排工上属 boss 直投 P?；M1 后 30 天用导出率判定继续/降速，不达线就不进 M2 |
| 治理膨胀（新闸门/新规则要挂在真实业务闭环上收租，10-01 口径） | 本线只新增 3 条机检（I8 双跑、L2 导出对账、L3 headless 导入） | 全部挂在自己的发版判据上，不往 company ops 加新闸门 |
| 隐私/数据 | 零后端、不存用户内容、不接第三方广告分析 | 界面只说功能事实（「浏览器里算完，不上传」），不喊「我们绝不作恶」（09-26 负面自证红线） |

## 7. 分阶段路线（详表在产品仓，这里只列块）

M0 骨架与通路验证 → M1 MVP 三族同批（含部署与官网页）→ M2 自研 Godot 导入件 + 多 tileset/素材工坊打通 + 批量出图 → M3 分享画廊与语种铺量（走 AI 翻译产线）→ M4 变现（tileset 包/CLI 授权/私有部署白标；**不卖生成的地图**）。

## 8. 本轮交付动作（已完成，可核）

| 动作 | 产物 |
|---|---|
| 竞品与互通路线 L3 调研 | `docs/竞品分析/2026-10-05-程序化地图生成对标与Godot引擎互通路线.md` |
| 立项评估与方案（本文件） | `docs/业务规划/2026-10-05-MapForge地图生成网站-立项评估与MVP方案.md` |
| 导出格式标准定稿 | `D:/code/work/lin/mapforge/docs/EXPORT-STANDARD.md` |
| PRD / DESIGN / ROADMAP / README | `D:/code/work/lin/mapforge/{README.md,docs/PRD.md,docs/DESIGN.md,docs/ROADMAP.md}` |
| 产品登记 | `ops/products/mapforge.yaml`（boss 点题立项当天登记；`checks.page`/`skill` 留真缺口，install/feed 按 Web 工具写 `waive` 带理由） |
| 端口登记 | `python ops/ports.py alloc mapforge web` → 块 3070，dev 端口 3071（`ops/ports.json`） |
| 台账 | `ops/data/research.jsonl` 记 `digest`（source=boss, L3, 产物指针）；`ops/worklog/2026-10-05.md` 加排工行 + 认领行 |
| 驾驶舱 | `products.py check` 后即时刷新部署（新产品登记是 boss 可见状态变化） |

## 9. 需 boss 配合（只剩品味与授权格）

1. **建仓授权**：是否现在建 git 仓并推 NAS（`xlkj/mapforge`）。建议 M1 开工当天建（本轮只是文档，仓是普通目录）。
2. **域名形态**：`pinnadash.com/tools/mapforge` 子路径 vs 独立子域。建议子路径起步——新域名零权重那条线你 09-27 已拍过，子路径直接继承主域外链资产。
3. **首发 tileset 美术**：程序画 16px 占位先行 vs 先走素材工坊出正式。建议占位先行，正式美术等导出率成立再投。
4. **排工位置**：M0/M1 什么时候开工（当前主线是流量优先 + 三条已 accepted 的需求票在前）。给一个字即开工。