创作方向 · 3 / 7
KML 给出土地；作者在其上编排出山谷，而山谷随时辰与潮汐生息。
山谷是一个真实的地方：Bom Jesus dos Pobres，巴伊亚州 Recôncavo 地区的一个渔村（属 Saubara 市），位于万圣湾畔。地理参考是作者在 Google Earth 中绘制、导出为 KML 的地图——共 26 个要素：12 个点、8 条街道、2 条河流线、3 个区域（庄园、广场和树林），以及框定镜头范围的 Mapa 多边形。数据仍以真实的米为单位；在 Demo 中，Godot 的 1 个单位等于 4 米，垂直夸张系数为 2.0，好让山谷可以步行走遍，又不丢失相对的地理关系。
根据 2026年9月29日的决定，KML 用作导入源和地理参考，而非永久管理所有物件。地形基础（起伏、海岸、河流、街道、区域）可重新生成；创作组合（房屋、命名树木、灯柱、装饰物、NPC、交互点、镜头）可在 Godot 中编辑，任何重新导入都会保留。山谷在此基础上运转：依据当地纬度计算太阳、1887 年的灯火在黄昏点亮、海图水深上有 2.4 米潮差、树林昼夜鸣响、村民按时段就位，并新增十四套按小时作息。
世界构建方向
KML 给出土地；作者在其上编排出山谷，而山谷随时辰与潮汐生息。
山谷是一个真实的地方：Bom Jesus dos Pobres，巴伊亚州 Recôncavo 地区的一个渔村（属 Saubara 市），位于万圣湾畔。地理参考是作者在 Google Earth 中绘制、导出为 KML 的地图——共 26 个要素：12 个点、8 条街道、2 条河流线、3 个区域（庄园、广场和树林），以及框定镜头范围的 Mapa 多边形。数据仍以真实的米为单位；在 Demo 中，Godot 的 1 个单位等于 4 米，垂直夸张系数为 2.0，好让山谷可以步行走遍，又不丢失相对的地理关系。
根据 2026年9月29日的决定，KML 用作导入源和地理参考，而非永久管理所有物件。地形基础（起伏、海岸、河流、街道、区域）可重新生成；创作组合（房屋、命名树木、灯柱、装饰物、NPC、交互点、镜头）可在 Godot 中编辑，任何重新导入都会保留。山谷在此基础上运转：依据当地纬度计算太阳、1887 年的灯火在黄昏点亮、海图水深上有 2.4 米潮差、树林昼夜鸣响、村民按时段就位，并新增十四套按小时作息。
10 条原则
不容商量的事
两个事实来源，各自独立
一边是导入的地理底座（KML 及其衍生数据：地形、海岸、河流、街道、边界和区域），一边是作者编排的内容（可在 Godot 中编辑的场景和资源：房屋、树木、灯柱、道具、NPC、交互点和相机）。重新导入 KML 可以更新底座，但不能删除、覆盖重建，也不能悄悄挪动作者编排的内容；出现冲突时会列出来，交由人工审阅。某个物件在 KML 中不存在，并不意味着可以把它从游戏里删掉。
真实的米，可玩的尺度
KML 保存的是 WGS84 坐标，导入器以广场为原点做局部投影；区域目录规定 1 个单位对应多少米（scale_m_per_unit）。Bom Jesus 采用 1 单位 = 4 米：庄园与广场相距约 220 米，而不是约 890 米。街道、河流和海岸的宽度都设有以单位计的下限，无论缩放系数是多少都能保持可玩（Rua Principal 宽 11 米，观景台街宽 4.2 米，其余街道宽 5 米）。将来每个区域都会有自己的 WGS84 锚点；不会用同一个原点覆盖整个巴西。
世界就是 Mapa 画框：16:9，在大陆上
导入器把手绘的画框调整为精确的 16:9（3,614 × 2,033 米，宽度居中扩展）；地形、海岸、树林和边界都止于画框。画框之外，海图上的陆地以远景地形延续：Bom Jesus 不是岛。边缘由隐形墙封住。海面遵循 DHN 1108 号海图的水深数据（550 × 500 个 10 米见方的网格单元），水位按大潮涨潮时的高度设定，水色由真实水深决定。
山谷随时辰生息
Dia 这个 autoload 记录连续的时间（0–24），并按所选速度推进（暂停、慢、正常、快）；太阳按 9月底南纬 12.8° 的天文位置运行（6 点左右从东方升起，在北方过中天，从西方落下），天空从正午的蓝色变为橙色，再转为深蓝，凌晨雾气渐浓，入夜时升起一轮淡月。1887 年还没有电灯：广场三个街角和小教堂前空地上的油灯柱、门口的煤油灯、院子里的篝火和窗边的蜡烛，会在日光降到 45% 以下时亮起，火光摇曳。
潮汐与大海是这个地方的一部分
潮汐可在“设置 → 场景”中设定：无潮汐、当地周期（半日潮，每个游戏日两次退潮、两次涨潮）、慢速周期，或用于演示的快速模式；真实潮差 2.4 米。涨潮时海水变暗（浑浊）；退潮时，裸露的海底变成泥滩，水洼明亮如镜，独木舟侧倒搁浅，礁盘露出水面，脚步声也变成踩泥、踩水的声音。可以步行走进海里，水深过胸的地方可以游泳，深水区有一条鲨鱼在游弋——但 Pedro 和村民从来不会成为它的目标。
填充植被与作者编排的植被
树林以固定种子（1887）分布于林区，共 3,117 棵背景树，留有突出树木的空地，避开道路、河流、海滩、开阔区与标记。每块 40 单位，镜头外剔除，并按距离切换 LOD。这些植被可为性能保持批量生成。道路、房屋、标志与叙事区域附近的创作植被应可逐棵编辑；生成树一旦成为创作元素，就移出可重新生成的批次，避免下次生成时重复出现。
推断就标明是推断
KML 没有画出完整的海岸线，也没有圈出北面的全部树林：沙滩、海湾水面、建成区和大片植被都是根据截图推断出来的，归入场景层，并且可以识别出是近似处理。有两个 POI 落在推断出的陆地之外（一个 Rio 点和 Pier 点），于是从岸边各架了一条窄栈道——这是为了可玩而做的诠释，不是 Google Earth 上的描线。河流和海洋只是表面呈现，不是水文模拟。名称和线路都是作者的标注，不是官方测绘。
代码负责系统性的工作，不隐藏视觉决策
迁移之后，代码仍然负责导入地理数据、让物件贴合地形、按距离加载、应用 LOD、生成碰撞、驱动昼夜循环，以及批量实例化。房屋、灯柱、作者编排的树木和叙事点的位置，不应再以 Vector3 的形式散落在 world_builder.gd 里：生成器读取的是已保存的编排。成功的标准是：作者打开 Godot，按名称找到一个物件，挪动它，保存，然后在游戏里看到变化——既不用改坐标，也不用依赖 AI。
2D 与山谷不一致时，以山谷为准
现有的地理是真实的来源，以 KML 测得，不会为了迁就 2D 的图形而更改；要调整的是任务步骤，因为玩家看到的是地点，而步骤只是文字。战役已在山谷里落实了高地、桥、山脊、巨石、庄园和宅邸废墟；浅滩已不复存在（大河很深，只能走桥过河），畜栏变成了鸡舍，待建地点的清单上只剩下潟湖。地理保留村子的相对布局，并接纳新任务的锚点。
10 月 5 日的山谷：天空、地面与日常生活
银河天空、低地薄雾与海湾地平线；按坡度和高度混合的八层地面；片状树林、空地和远处树冠；庭院、田地、房屋、各行村民和有作息的动物。镜头避让墙、地面、房屋和石块，经过村民或装饰物时不会突然跳动。
9 条规则
落到实处，体现在日常
- 数据分层：data/mapas/bom_jesus_dos_pobres_fonte.kml（原始绘图，逐字节保留）、bom_jesus_dos_pobres.json（由 importar_kml.py 归一化的几何数据；不要手改）、bom_jesus_dos_pobres_cenario.json（推断出的海岸、村子和树林；可审阅修改）以及 regioes.json（含 active_region 和 scale_m_per_unit 的区域目录）。
- 更新绘图时：从 Google Earth 重新导出，核对 Placemark 的 ID、名称和数量，替换受版本管理的源文件，运行 importar_kml.py；如果遮罩有变化，再运行 importar_mascaras_html.py；把俯视图和绘图对照一遍，再到游戏里走一遍广场、海岸、桥和观景台。
- ID：导入器以每个 Placemark 的 id 属性作为要素的键；没有 id 的要素会被分配 'provisional_…'，它不应变成永久键。ExtendedData 中的 kind 字段可声明为 poi、road、river 或 area。
- 陆地双面都有碰撞，材质也是双面的（否则物理系统看不到广场的地面，角色会掉下去）；街道有自己的碰撞体，跨过水面的路段也能照常行走；水面没有碰撞，但海底有碰撞，用于游泳。
- 建筑以地理点为参照，但最终位置要在陆地上寻找：留足整栋建筑的空间，避开街道和树木，门朝向最近的街道（地块划分）；会与房屋重叠的树木则被挪开。
- 植被可见距离（geo_region_renderer.gd）：林下植被 85 u；海岸沙地灌丛（restinga）200；河岸树木 230；椰子树 250；林冠 280，另有 20 u 的防闪烁余量；在正交地图（相机位于 3,000 u）和小地图（100 u）中停用。
- 菜单的飞越镜头是离线规划的（data/sobrevoo_menu.json，每 0.1 秒一个采样点，共 720 个），离地 14.6–17.4 米飞行，与真实几何体保持 5 米间距，并由 tests/sobrevoo_livre*.gd 门禁检查；种了一棵树、挪了一栋房子，门禁就会不通过：那就重新规划。
- 可编辑的地形预览（scenes/prototipo_3d/terreno_editavel.tscn）由 tools/mapas/gerar_terreno_editavel.gd 生成，每次运行都会被替换：在导入底座与作者调整真正分离之前，不要在里面保存手工的顶点编辑。
- 村民的岗位和台词在 data/npcs_3d.json 中（每个时段一个岗位：早晨、下午、黄昏、夜晚、凌晨，每个岗位由一个锚点加一个偏移量构成）；日出日落时间在 dia.gd 中；天空颜色在 world_builder.gd::_aplicar_hora 中；灯光在 _build_luzes_epoca 中。
体现在哪里
- KML 中的 12 个点
Rio（两处）、Pedras、Pier、Cemitério、Ponte、Mirante、Igreja、Bar、Praça、Restaurante 和 Casa da estrada 是地理来源中的地标。山谷也能解析战役新增的地点锚点；地图页面区分现有地点和计划中的地点。 - 三角形的广场与面朝街道的房屋
广场按实地广场的形状扩大，中央不再设菜园（菜畦挪到了边上），街道两旁新增了八栋房屋；玩家继承的房子就在田地旁边。 - 海图里的大海
海底依据 DHN 1108 号海图塑造（潮间带、浅水台地、斜坡和 Paraguaçu 水道）；海水透明，颜色随深度变化——岸边是泛绿的沙色，浅水处如玉，水道里是深青绿，与 Bom Jesus 的航拍照片一致。在浅滩平地上，可以向海里走出约 600 米。 - 弯曲的街道与路口
KML 的线条经过 Chaikin 算法平滑（切角三次，最多约 100 米）；在路口，较宽的街道压在上面，每个接缝处都补上一块边缘不规则的夯土；通到海滩的街道被沙子盖过。 - 游戏内的地图
山谷的俯视地图与场景使用相同的地理布局，支持缩放、拖动和可点击的标记。游戏中按 M 打开；从菜单点“地图”按钮，则会加载山谷并打开地图，加载界面上显示的是画好的地图。 - Saubara 当地的树林
河口是由 mangue-vermelho 组成的红树林，河岸有 ingá，树林中有 piaçava 棕榈和 jenipapo，restinga 海岸植被带有 clúsia 和 piaçava，每户院子里都有 pitanga，林下生长着蝎尾蕉和凤梨科植物。按 E 可查看树木资料卡，资料卡保存在图鉴中。