ascii-city-engine

ASCII City Engine

通过三层构建可移植的城市体验：引擎、城市提供方契约和城市包。不要将特定城市的信息写入引擎代码。

工作流

1. 定义城市包边界和基于米的本地 CRS。
2. 从公开来源获取高程、建筑物和道路／路径数据。
3. 转换数据前，验证下载内容、许可证、单位和来源信息。
4. 将所有几何数据重投影到本地米制坐标系，并生成清单和世界瓦片。
5. 离线验证城市包：

   python3 scripts/validate-city-pack.py path/to/city-pack
   

6. 在 assets/ascii-city-engine.html 中加载城市包的第一个瓦片，并测试移动、坡度跟随和实体轮廓。
7. 记录数据局限性和人工验收证据。

必需的不变量

• 根据地形计算 feet_z，根据脚部高度加眼高计算 eye_z。
• 拒绝地形数据为空、坡度过大的步进，以及触碰实体轮廓的移动。
• 使用确定性的建筑物颜色，并在每一帧清除未命中的射线。
• v1 将每个 (x, y) 列视为只有一个地面高度；预留曲面图，但暂不实现。
• 保持引擎独立于任何城市、供应商、Agent 框架或私有基础设施。
• 不要提交大型或全分辨率源数据。只提交小型、可再分发的样本；其余数据的获取方式须记录在文档中。

参考指南

• 阅读 references/engine-architecture.md，了解世界坐标计算、渲染、碰撞和脚手架契约。
• 创建或验证提供方时，请阅读 references/city-provider-contract.md。
• 下载或转换 GIS 数据源之前，请阅读 references/gis-ingestion.md。
• 阅读 references/raleigh-poc.md，了解可复现的 Raleigh 概念验证。
• 使用 templates/city-pack-manifest.schema.json 和 templates/world.schema.json 作为权威数据契约。

可用脚本

此技能包含一个脚本；没有其他脚本。

脚本	用途	调用方式
scripts/validate-city-pack.py	城市包离线验证器：根据架构契约检查清单并验证世界瓦片。在工作流第 5 步运行，即生成清单和瓦片之后、在引擎中加载任何内容之前——验证通过后才能继续引擎内测试。	python3 scripts/validate-city-pack.py path/to/city-pack

先决条件

• Python 3，仅使用标准库；验证器不需要第三方软件包。
• 按照数据摄取工作流生成的城市包：清单加上重投影到本地米制坐标系的世界瓦片（参见 references/gis-ingestion.md）。
• 引擎本身是独立的 HTML 文件（assets/ascii-city-engine.html），可在任何现代浏览器中运行；无需构建步骤或服务器。

局限性

• v1 支持每个 (x, y) 列只有一个地面高度：不支持室内区域、下方有可通行空间的桥梁、隧道或多层几何结构（预留了曲面图，但尚未实现）。
• 引擎使用 CPU 进行软件渲染，绘制到 canvas 上——不支持 WebGL／GPU 渲染或移动设备控制。
• 此技能不包含全分辨率 GIS 存档；城市包需基于公开来源以可复现的方式构建，只提交小型、可再分发的样本。
• 验证器离线运行，仅检查结构：验证通过不能替代在引擎中进行人工移动测试（工作流第 6 步）。

边界

对于 WebGL／GPU 渲染、移动设备控制、战斗、室内区域、下方有可通行空间的桥梁、隧道或通用地理空间分析，请改用其他技能或实现方案。如果有人要求将此技能专门适配某个 Agent 运行时，请保留可移植核心，并将运行时集成放在此技能之外。如果有人要求提交大型 GIS 二进制文件，请拒绝，并改为提供可复现的下载／转换命令。