aberration

Imported from Dainokami/aberration (AGENTS.md). Install upstream with npx skills add Dainokami/aberration. Copyright stays with the author.

畸变项目开发指南

2026-10-19 最终整合状态（优先于下方历史说明）

• 本地最终入口统一为 main；朝向修复、怪物刷新和游泳/区块碰撞修复纳入同一次整合提交。不要把旧分支名称误当作三份独立实现。
• 当前 Dock 为地形、物件、导入、预制、视角、细节、怪物、流程。刷怪配置与分层探索/静止/禁刷标记保存在 LevelData，运行时支持普通怪、精英、Boss 门和浓雾；鸟妖完整 Boss 战仍不在本轮范围。
• 世界生成锁定固定视角美术的朝向；怪物美术目录为 assets/derived_art/monsters_20261018，10 类已提供，4 类缺美术默认禁用。
• 世界生成算法v9：先定位必选特殊地图并为生态延伸、出生净空与通路留出空间，再以特殊地图为起点做带噪声的多源生态生长，不得在已生成世界上覆盖矩形生态基底。完整占地及外侧一圈是生长的内部约束，外边界应延伸并弯曲。空间不足自动扩图至最多600×600；可选地形继续完整候选搜索，失败不得换生态。配方宽高保留起始值，地图与预览记录实际尺寸。保留刷新点、旋转、高度对齐与配方手工点修改。新导入须选地形，旧配方缺字段显示“不限制地形”。
• 普通怪改为 LevelData.monster_spawn_points 固定相邻格组，每点独立30秒周期，默认存活上限2。普通物种地形严格读取设计表，不沿用旧怪池自定义生态。静止区允许固定点，禁刷阻止生成；无点无普通怪。精英/Boss仍按探索时间。地图怪物页以点操作为主，高级配置折叠；世界生成预览复用同一编辑控件。验收与使用见 docs/小怪刷新点_验收.md 和 docs/怪物刷新_策划使用说明.md。
• 点的 activation_radius 同时控制刷新与追踪；0自动按实际相机可视地面边界+4m，正数固定米数。只在玩家进入点中心圆形范围内累计30秒，离开暂停并取消攻击、怪物回出生格。画面外已激活有怪点用紫色方向提示引导玩家；精英不套用此范围。
• LevelData.level_transition 保存地图级倒计时传送配置；旧地图缺配置时运行时采用60秒默认流程，终点地图可显式关闭。倒计时后在玩家附近合法可达地面生成唯一传送门，按E切换目标地图并保留角色能力、生命、氧气和轻量背包；与怪物、Boss门独立。策划在“流程”页配置。
• 2026-10-19 已原路径替换内置 grass / rock / sand / water 四种地貌图片，地块 ID 与旧地图数据不变；painted_grass / painted_meadow 明确保留旧素材。来源与哈希见 assets/source_art/terrain_handoff_v02/replacement_manifest_20261019.json。
• 地形碰撞按8×8区块及高度层共享物理体，命中形状保留格与层级；SurfaceZone只是逻辑标签节点。鱼尾水面/水下5m/s，完整移动回归通过。64×64/96×64混合世界碰撞对象472/571；600×600满图战斗性能未验收。
• 用户明确要求交付最终提交，不能把已完成代码长期留在未提交状态，也不要每修一个问题就新建一个空分支。后续开发沿用当前经确认的工作分支，完成后按授权收口；禁止擅自提交用户正在编辑的地图/场景。
• 使用说明见 docs/怪物刷新_策划使用说明.md、docs/世界生成_策划使用说明.md。本轮提交前必须从暂存区构建独立副本并验证，不能依赖工作区未提交地图或资源。

当前分层地形规则（v9，优先于下方历史版本说明）

• 地形源数据为 LevelData.columns；layers 中 {} 表示空气，实体与海水独立占槽，实体层保存 overlay。每层固定厚 2m，第 L 层顶面为 (L + 1) × 2m。海水没有固体阻挡，水面与水中分区，旧液体附件迁移为海底上方独立海水；水体不遮掉海底物件。海洋及 1016 资产规则见 docs/ocean_scene_assets.md。
• 高层独立摆放，不补支撑；允许挖掉任意层，其他高度不变。新工具用分层 API，不用兼容 set_cell() 表达普通绘制。
• “选地块”合并绘制和擦除：左键贴面摆放，可沿起始平面拖笔并按三维坐标去重；右键每次点击只删除一个目标，不受 3×3 画笔影响，不允许长按或拖动连续删除。无 Shift 悬空摆放、无手动摆放层选择器；通过逐块搭建再拆除支撑形成悬空结构。
• 文件按钮行右侧提供“默认右键删除”开关，默认开启，存于编辑器项目设置。开启时右键删除、Alt＋右键转向；关闭时 Alt＋右键删除、右键转向。删除地块和物件共用该规则，每次点击一个目标；3D 左上角红绿标识随此映射切换。
• 地图两个水平方向支持最大 600×600 格，接近上限时缩减可选扩图留白；逻辑坐标和世界原点保持稳定。
• 紧邻上层有实体块时，顶面物件、细节、水面、贴花不生成，记录保留；移走遮挡块后恢复。有空气间隔的低层仍显示。新增地块不移动已有物件、细节或出生点。
• 顶面、侧壁、底面与拾取保留层级信息；只按真实占用生成碰撞。切片只是显示/碰撞过滤，不得改写数据或在空气层制造盖面。连续实体段共用轮廓，有重叠高度的相邻块接边齐平。
• 物件保存 anchor_cell / anchor_layer，出生点保存 spawn_layer，阶梯连接相差一层的外露顶面。预制保存并旋转空气槽、各层实体及附件。
• v5 地图在内存中迁移为原有连续实体并上移 2m；v6/v7 只迁移附件结构，不再次抬高。不得仅因打开资源而回写磁盘。
• 地形按 8×8 区块更新，空区块不生成；物件按记录变更复用节点，物件撤销只保存物件数组，扩图撤销保存边界与地块差异。内容校验仍保留真实支撑和碰撞检查，图片格式/图集校验在导入和试玩完整校验中执行。性能限制见 STACKED_TERRAIN.md。
• 分层回归为 tests/test_free_blocks.gd、tests/test_stacked_terrain.gd 和编辑器套件内的 tests/editor_stacked_checks.gd；图形检查为 tests/render_stacked_terrain.gd。

当前维护规则（优先于历史版本说明）

• 地形视觉的当前规范见 TERRAIN_VISUAL_RULES.md：固定斜俯视透视、同高度 Mask 过渡、不同高度保留崖壁、固有色与后期调色分离。
• 插件提供顶部工具栏“关卡编辑器”入口，必须自动打开/复用标准工作场景并选择 TerrainBuilder；不得要求用户日常手动打开场景和节点。
• Dock 顺序为地形、物件、导入、预制。以 USAGE_GUIDE.md 的修复说明为当前行为依据。
• 地块记录的 tile_id 决定顶面材质，rotation 是 0～3 的四向旋转；旧数据缺省为 0。
• 地块保存样式、高度、朝向；新增地块不改变已有内容的锚点。擦除某层连同依附该层的内容一起撤销/重做，其他层保持原位。
• 试玩请求写入与读取统一为 playtest/level_path。内嵌子资源必须先另存独立 .tres；取消或保存失败不得启动旧地图。
• 地块画笔预览复用 TerrainBuilder、实际贴图与旋转，不用假图形代替；禁止预览碰撞。
• tests/editor_art_regression.gd 检查实际生成节点/材质、真实撤销与地图读取一致性；不得为“通过测试”删除失败断言。图形窗口失败必须单独记录。

当前执行范围（v0.2，优先于下方早期构想）

• 用户已验收第一版地形编辑，并选择第二版方案 A：自动导入图片 + 物件编辑 + 营地预制；刷怪、遭遇、倒计时/BOSS 后移。
• 入口仍为 addons/terrain_editor；Dock 为地形、导入、物件、预制四页。操作与验收见 SECOND_VERSION.md。
• scripts/assets/ 保存相机规范、物件定义、载体生成与前景淡出；scripts/level/object_rules.gd 统一物件校验，level_prefab.gd 处理选区和原子投放。
• LevelData.objects 保存稳定 ID、定义路径、世界位置、水平旋转、统一缩放。旧地图默认空物件数组，须继续兼容。
• 图片导入不推断真实深度，不自动拆层。固定相机卡片、贴地平面、盒体/坡体投影 UV 都使用显式参数。只有独立前景图支持分层淡出。
• 通用导入不得要求资产属于程序内置的树木/岩石等模板。选图后自动读取透明边界、保持比例并估算落点；世界尺寸来自 px/m 约定，纵深与碰撞只能给可调整初值。配置预设由用户保存，不含图片路径、资源 ID 或名称。
• 相机配置在 data/art_profile.tres，不要随意改变。画面尺寸和真实碰撞尺寸是不同参数。
• 生成目录为 assets/generated/<id>/，保留源图路径和参数；禁止覆盖既有 ID 或原图。外部源图原样复制进项目再导入。
• 预制为带尺寸的 LevelData 片段，矩形最小格为锚点；包含地形、阶梯、物件，不带玩家出生点。四向旋转、候选数据全量校验后一次提交，失败不得部分写入。
• 所有地图编辑使用 EditorUndoRedoManager，并绑定原 LevelData，不能因切换地图把旧撤销写到新地图。
• 地形页、物件页删除按“默认右键删除”开关映射；物件操作复用地形，仅刷新有变化的物件节点。全地图读取、内容校验和切片封口仍有全量步骤。
• 第一版样例、营地场景、源资料和用户未提交修改保留；未经要求不得 Git 提交。
• 已做数据、物理、编辑器逻辑测试与 OpenGL 离屏画面检查；Computer Use 报 cgWindowNotFound，真实窗口鼠标操作/淡出观感未完成验收。不要把无窗口通过等同全部 GUI 验收。
• 自动化入口：tests/test_v2.gd、tests/editor_v2_checks.gd（通过 --editor -- --test-v2-editor），第一版回归仍须执行。

项目目标

本仓库用于开发 Godot 游戏“畸变”。当前阶段的首要目标不是完成正式关卡编辑器，而是用最小验证确认以下技术路线可行：

1. 策划能按 2 米地块格刷地表类型。
2. 策划能按整数层设置高度差。
3. 策划能吸附到格子放置场景物件和刷怪点。
4. 编辑结果能在游戏运行时正确加载。
5. 2.5D 手绘素材能在带透视感的固定视角下正确遮挡和排序。
6. 能以预制场景为单位投放营地，并预览倒计时事件生成的 Boss 场地。

首版只验证完整工作流，不追求正式美术品质、海量地形类型、自动地形生成或最终性能。

设计资料

资料暂存于仓库上级目录。阅读顺序如下：

1. ../畸变.mm
   • 当前游戏核心设计的主要依据。
   • 与关卡有关的重点包括阶梯式生态、岩石群态、草原群态、海洋群态、沙漠群态，以及肢体能力和地形交互。
2. ../畸变-游戏框架.docx
   • 游戏框架参考。
   • 当前文件的主要内容是框架截图，涉及角色拼接、肢体分类和移动优先级。不要仅依赖正文文本提取来理解此文件。
3. ../2m单元格_4K场景素材绘制规格.xlsx
   • 当前场景资产规格的主要依据。
   • 关键约束是 1 Godot 世界单位按 1 米理解，最小关卡设计单元为 2 米，基础高差为 2 米。
4. ../畸变_关卡场景物件尺寸定标.docx
   • 过期资料，只用于参考末尾的场景资产拆分思路。
   • 如果它与 Excel 或当前需求冲突，以 Excel 和当前需求为准。
5. 主策分享的 2.5D 原理参考视频：
   • https://www.bilibili.com/video/BV17XB9YDEEU/
   • 已确认的项目意图不是单纯把图片立成始终面向相机的纸片，而是由美术提供目标摄像机视角下的一张平面成图，程序工具生成或调整包裹该画面的 3D 几何，并完成与该视角匹配的 UV 投射或展开。
   • 视频只作为原理参考。实现决策以主策描述和项目内实际测试结果为准。

不要擅自修改这些源资料。代码、测试场景和项目文档应放在本仓库内。

已确认的美术与尺寸约束

• 目标风格参考《咩咩启示录》：美术按固定摄像机视角绘制手绘平面成图，程序把成图映射到具有真实空间体积的简化 3D 包裹模型上。
• 美术的主要输入应保持为“目标摄像机看到的平面图”，不要求美术手工建模或手工展 UV。3D 包裹、投射 UV、预览和导出由程序工具承担。
• 不要把每个 2 米格做成一张完整独立贴图。2 米格是逻辑编辑模数，不是强制的纹理切片方式。
• 地面采用连续基础纹理，后续再叠加大尺度色差和细节贴花。
• 地形顶部和悬崖侧壁应分开表现。
• 边缘、内外角和端头是独立的视觉模块，但首版可以用程序生成的占位几何体验拼接规则。
• 正式资产密度参考：
  • 基础地面：128 px/m。
  • 环境模块：256 px/m。
  • 玩法焦点物件：512 px/m。
• 关键物件包括岩石块、风化岩石、攀岩点和宝箱。最小验证阶段统一用有明显颜色和轮廓差异的占位素材。

技术路线

空间方案

使用 Godot 3D，而不是纯 2D TileMap：

• 水平面使用 XZ。
• Y 轴表示真实高度。
• 一个逻辑格为 2m × 2m。
• 一个高度层级为 2m。
• 摄像机使用正交投影，固定俯视角。首版先尝试约 35 至 45 度俯角和轻微水平旋转，具体参数由视觉验证决定。
• 地面和悬崖使用简单 3D 几何承载手绘材质。
• 场景主体物件优先使用“单视角平面成图 + 简化包裹 Mesh + 摄像机投射 UV”的方式；很薄的草叶、特效或远景装饰仍可使用 Sprite3D 或纸片。
• 玩法碰撞与视觉包裹模型分离。视觉 Mesh 可以为了匹配画面而变形，碰撞体应保持简单、稳定且符合玩法尺寸。

选择真实 3D 的原因是高度差、坡面、遮挡、投影和可交互物碰撞都属于核心需求。不要用手工修改 2D z_index 来模拟整个世界的楼层关系。

单视角包裹工作流

主策补充的信息改变了首版视觉验证的重点。不能只验证 Billboard 纸片，还必须验证以下工作流：

1. 锁定 Godot 中的目标正交相机、视口比例和关卡观察角度。
2. 工具从该相机导出带尺寸标尺、地面格和物件占地框的绘制模板。
3. 美术在模板上绘制一张该相机视角下的完整平面成图，保留透明背景。
4. 程序在 Godot 内提供一个简化包裹 Mesh。首版允许手工调整少量控制点，后续再评估轮廓或深度辅助的自动生成。
5. 工具从目标相机对 Mesh 做投射映射，使正面观察时尽可能还原原画。
6. 从目标相机检查轮廓、接地、遮挡、层间穿插和纹理拉伸。
7. 轻微偏移相机做容错检查，但不以支持自由旋转相机为首版目标。
8. 保存生成结果时保留源图、包裹参数、相机参数和生成版本，避免只保存不可追溯的最终 Mesh。

这里所谓“展 UV”在首版中优先理解为与目标摄像机一致的投射 UV。是否还需要自动切缝、UV 岛重排和烘焙，应由验证结果决定，不要提前制作完整通用 UV 工具。

该方案有一个硬约束：相机就是资产规范的一部分。相机俯角、水平角、正交尺寸或画幅发生变化，都可能暴露模型侧面空白、产生纹理拉伸或破坏原画轮廓。因此相机参数必须资源化并受版本控制，不能由关卡策划随意修改。

数据与表现分离

关卡源数据不得只存在于编辑器节点树中。采用以下分层：

1. LevelData
   • Godot Resource，保存关卡尺寸、格子数据、物件实例、刷怪点和时间事件。
2. LevelGrid
   • 每格至少保存：
     • terrain_id
     • elevation_level
     • 可选的 flags
3. PlacedObjectData
   • 保存资源 ID、格坐标、层级、局部偏移、旋转和可选属性。
4. SpawnData
   • 保存敌人类型、位置、朝向、组 ID 和触发方式。
5. TimelineEventData
   • 保存触发秒数、事件类型和要投放的预制场景。
6. LevelRenderer
   • 根据 LevelData 生成或更新地面、侧壁、物件和调试标记。

编辑器负责修改数据，渲染器负责显示数据，运行时加载器负责实例化同一份数据。不要让编辑器和运行时各维护一套不兼容的关卡格式。

首版可以用清晰、可调试的 Resource 子资源或数组保存数据。不要为了最小验证提前制作二进制格式、复杂分块流送或数据库。

编辑器形态

使用 Godot EditorPlugin 制作仓库内工具，不制作独立外部应用。

首版界面包括：

• 左侧或右侧 Dock：
  • 工具模式：地形、高度、物件、刷怪、预制、事件。
  • 画笔尺寸，首版支持 1 格和 3×3 格即可。
  • 当前地形类型。
  • 当前高度层。
  • 当前物件或敌人类型。
• 3D 视口覆盖：
  • 鼠标指向格高亮。
  • 左键绘制或放置。
  • 右键擦除。
  • 拖动连续绘制。
• 撤销与重做：
  • 所有编辑操作必须接入 EditorUndoRedoManager。
• 保存：
  • 保存为项目内的 LevelData 资源。

首版不实现复杂选区、复制粘贴、笔刷规则图、多人编辑和运行时内置编辑器。

最小验证范围

建议做一个 16 × 16 格，即 32m × 32m 的验证地图。只使用下列内容：

地形

• 两种地表：草地、岩地。
• 三个高度层：0、1、2，分别对应 0m、2m、4m。
• 自动生成外露的悬崖侧壁。
• 暂不做自动坡面、复杂内外角美术和导航网格烘焙。

场景物件

• 岩石块：占 1 格，可跳上或作为阻挡。
• 风化岩石：占 1 格，用不同颜色标识“可破坏”。
• 宝箱：占 1 格，用于验证交互物放置。
• 地块编辑功能可以先使用占位颜色和简单几何。
• 至少选择一个岩石块制作“平面成图 → 包裹 Mesh → 投射 UV → Godot 场景”的完整样例。该样例是首版视觉技术验证的必做项，不能全部用纯色方块代替。

2.5D 包裹工具

• 输入：透明 PNG、目标相机配置、世界尺寸、占地尺寸和简化 Mesh。
• 首版编辑能力：显示原画叠加预览、移动少量顶点或控制点、重新投射 UV、切换原画对比、保存生成资源。
• 输出：Godot 可直接实例化的 Mesh/场景、材质和描述生成参数的资源。
• 首版只支持一个固定相机和静态物件，不支持自由旋转展示、骨骼动画或多视角贴图。
• 工具生成的资源放在独立目录，源图不得被覆盖。

刷怪

• 放置一种普通怪刷怪点。
• 显示位置、朝向和刷怪组。
• 运行验证时生成占位敌人或调试模型，不要求完成战斗 AI。

预制投放

• 制作一个约 3 × 3 格的“山丘营地”测试预制。
• 预制中包含升高地形、一个怪物点和一个场景物件。
• 首版预制可以作为带元数据的 PackedScene 或独立 LevelData 片段。
• 投放时必须整体吸附到 2 米格，并能在放置前显示占地预览。
• 首版不处理预制旋转后的复杂地形融合；只支持 0 度，或最多支持 90 度整数旋转。

倒计时事件

• 每层关卡有独立倒计时配置。
• 首版只做一种事件：到达指定时间后投放 Boss 场地预制并生成 Boss。
• 编辑器必须可视化事件的时间、投放区域和预制占地。
• 运行时用一个独立 LevelEventController 管理，不把倒计时逻辑塞进地形编辑器。
• 编辑器只编辑 TimelineEventData，运行时控制器消费这些数据。这样后续可以加入环境变化、封路、奖励或其他事件。

首版验收场景

最小验证只有在以下流程全部可演示时才算完成：

1. 打开 Godot 项目和关卡测试场景。
2. 在编辑器 Dock 选择草地或岩地并刷一片区域。
3. 把部分格子抬高到第 1 层和第 2 层，视口中出现正确顶部和侧壁。
4. 放置岩石、风化岩石和宝箱，位置吸附正确。
5. 放置普通怪刷怪点并看见方向标记。
6. 整体投放山丘营地预制。
7. 配置一个短倒计时 Boss 事件，在编辑器中看见其投放区域。
8. 保存、关闭并重新打开场景后，编辑结果不丢失。
9. 点击运行后，运行时从同一份 LevelData 重建关卡。
10. 倒计时结束时，Boss 场地和占位 Boss 出现。
11. 至少验证一次撤销和重做。
12. 从目标相机观察测试岩石时，包裹模型基本还原美术平面图，并能与前后物件产生正确的深度遮挡。
13. 修改包裹模型后可以一键重新投射 UV；关闭并重新打开项目后，源图和生成参数仍可追溯。

建议目录

aberration/
├── AGENTS.md
├── project.godot
├── addons/
│   └── level_editor/
│       ├── plugin.cfg
│       ├── level_editor_plugin.gd
│       ├── level_editor_dock.tscn
│       └── level_editor_dock.gd
│   └── projection_mapper/
│       ├── plugin.cfg
│       ├── projection_mapper_plugin.gd
│       └── projection_profile.gd
├── assets/
│   ├── placeholders/
│   ├── source_art/
│   └── generated/
├── data/
│   ├── levels/
│   ├── palettes/
│   └── prefabs/
├── scenes/
│   ├── test/
│   ├── prefabs/
│   └── runtime/
├── scripts/
│   ├── level/
│   │   ├── level_data.gd
│   │   ├── level_grid.gd
│   │   ├── placed_object_data.gd
│   │   ├── spawn_data.gd
│   │   ├── timeline_event_data.gd
│   │   ├── level_renderer.gd
│   │   └── level_runtime_loader.gd
│   └── events/
│       └── level_event_controller.gd
└── tests/

目录可随 Godot 实际资源依赖小幅调整，但编辑器、数据、表现和运行时逻辑必须保持边界清楚。

实现顺序

按以下顺序推进，前一步未验证时不要跳到大规模内容制作：

1. 初始化 Godot 4.7.2 项目，建立固定正交相机和 2 米调试网格。
2. 完成 LevelData、格子坐标转换和最简单的地面渲染。
3. 完成地表画笔与高度画笔，并接入撤销重做。
4. 自动生成外露侧壁，验证三层高度的遮挡和透视效果。
5. 锁定测试相机，制作最小投射映射工具，用一个手绘岩石验证平面成图包裹流程。
6. 完成物件放置与刷怪点。
7. 完成保存、重载和运行时加载。
8. 完成山丘营地预制投放。
9. 完成倒计时事件数据、编辑器可视化和运行时触发。
10. 用少量接近目标风格的地面、侧壁和包裹物件做组合画面，评估《咩咩启示录》方向是否成立。

暂不进入首版的内容

• 完整生态系统和四种生态的正式素材。
• 自动地形边缘美术拼接的所有组合。
• 程序化大世界生成。
• 世界分块流送和远景 LOD。
• 正式敌人 AI、战斗、掉落和肢体系统。
• 完整导航、攀爬、推动、滚石和地形机制杀。
• 正式 Boss 战。
• 多事件轨道、复杂条件表达式或可视化脚本系统。
• 编辑器的美术抛光。
• 通用自动建模、复杂拓扑生成和面向任意相机的通用 UV 展开器。

编码规则

• 使用 Godot 4.7.2 和类型化 GDScript。
• 文件名、目录名、类名和资源 ID 使用英文；面向玩家的显示名称可以使用中文。
• 格子与世界坐标转换必须集中到单一工具或数据类，不允许到处手写 * 2.0。
• 2 米格宽和 2 米层高应定义为明确常量，例如 CELL_SIZE 与 ELEVATION_STEP。
• 数据类不得依赖编辑器插件，运行时脚本不得引用 EditorPlugin 或 EditorInterface。
• 编辑器修改必须支持撤销重做。
• 占位素材必须放在 assets/placeholders，便于后续整体替换。
• 对暂时无法确定的美术参数使用导出属性或资源配置，不要硬编码在 Shader 和脚本深处。
• 目标相机参数、绘制模板参数和投射参数必须保存在资源中并提交 Git。
• assets/source_art 保存美术源图，assets/generated 保存工具输出。生成工具不得原地改写源图。
• 每完成一个垂直切片就运行 Godot 项目并检查控制台错误。
• 提交应小而明确。不要提交 .godot/、导出构建、缓存或本机编辑器设置。

架构注意事项

• 不要一开始依赖 GridMap 作为唯一数据源。可以使用它做表现或占位，但策划数据必须由我们自己的 LevelData 持有，否则物件属性、刷怪、预制和时间事件会很快受限。
• 不要把地形、装饰、玩法物件和刷怪点混在同一数组中。它们的编辑规则和运行时含义不同。
• 不要在每次移动鼠标时重建整张地图。最小验证也应只更新受画笔影响的格和邻格；完整重建只用于加载或调试。
• 自动侧壁依赖当前格与四邻格的高度差。首版只需处理整数层差，侧壁可以按差值堆叠。
• 包裹 Mesh 的视觉排序优先交给真实 3D 深度。透明边缘、半透明材质、阴影和描边仍需专门测试，不能假定默认透明排序一定正确。
• 单视角投射会在遮挡区和侧背面产生信息缺失。首版应限制相机活动范围，并允许工具为侧面指定纯色、延展纹理或独立补片；不要假装单张图能支持任意视角。
• 包裹模型工具首先服务于本项目固定相机，不以制作通用建模软件为目标。若手工调整少量控制点已经能验证效果，不要过早投入自动轮廓识别或深度估计。
• 预制投放必须有占地掩码和锚点，不能只记录一个 PackedScene 路径。
• 时间事件应引用稳定的预制资源 ID 或资源路径，并在加载时校验缺失资源。

每次变更前后的检查

变更前：

1. 阅读本文件和相关源资料。
2. 检查当前 Git 状态，避免覆盖用户未提交的修改。
3. 明确本次工作属于数据层、编辑器层、表现层还是运行时层。

变更后：

1. 使用仓库上级目录中的 godot-engine/Godot.app 运行项目。
2. 至少执行一次无窗口的项目加载或脚本解析检查。
3. 打开受影响的测试场景做人工验证。
4. 检查 Godot 控制台没有新增错误。
5. 说明修改的文件、验证方式和仍未覆盖的限制。

当前结论

首版应被视为“关卡数据、编辑工作流和单视角包裹资产管线验证”，而不是“可投入量产的关卡编辑器”。最关键的不确定性是：固定相机下，单张手绘成图经过简化 3D 模型包裹和投射 UV 后，能否同时保持原画效果、正确接地、真实遮挡并适配高度差。因此该样例不应拖到编辑器全部完成后再做，而应在地形高度验证后立刻进行。若验证失败，应先调整相机、绘制模板、资产拆层、包裹几何和投射方式，而不是继续扩展编辑功能。

地形编辑器 v0.1 已实现范围

• 插件位于 addons/terrain_editor，在 scenes/terrain_editor_test.tscn 中使用。
• LevelData 是唯一地图源数据，保存16×16地块、地表、高度、阶梯与出生点。
• 地形构建器同时服务编辑预览和运行试玩，不允许另写一套运行时生成规则。
• 首版支持草地、岩地，0m/2m/4m，空格，1×1/3×3画笔，四向标准阶梯与出生点。
• 标准阶梯占1×2格，低端到高端只能相差一层；视觉台阶和连续斜坡碰撞分离。
• 现有 forest_camp.tscn 是独立技术样例，不要转换、删除或设为编辑器数据源。
• 本版明确不支持叠层、桥下通行、水体、装饰、预制、刷怪和时间事件。
• 操作和测试命令见 TERRAIN_EDITOR.md。