玩法架构与阅读路线

CubeLand 把关卡数据、规则状态、Unity 画面和正式游戏业务接入分开。理解一个现象时，先确认它属于哪一层，再查对应入口，可以避免把美术动画当成规则，或把编辑器统计当成通关结论。

想了解什么，从哪里读

你的问题	推荐文档
炮台为什么攻击这块、那块为什么打不到	攻击、子弹与可达范围
转动模型有什么影响、为什么扫描一圈才失败	旋转、停滞与工具
怎样编辑体素、队列、机关并试跑	关卡编辑器
怎样改模型大小、位置、射速和弹道	运行时模型调参
方块材质、原版模型、入槽动画和特效怎样接入	画面与美术实现
文件放哪里、Addressables 怎样管理	资产目录与资源规范
开发快捷键、改关卡与测试条件	玩法快捷键与 GM

一、关卡数据层：这一关是什么

LevelData 是关卡的结构化内容，包括：

• 固定炮位数量 Slots。
• 模型位置、旋转、缩放、旋转中心等 View 信息。
• 体素层 Layers，每层记录颜色、逻辑 Depth 和三维坐标。
• 可上阵炮手队列 Queues。
• 被其他对象引用的炮手池 Shooters。
• 大方块、覆盖物、围栏等机关 Obstacles。

炮手数据包括颜色、弹量、类型、双色弹夹、隐藏、冰冻、Pilot 和关联关系。关卡数据描述初始状态，运行中的剩余弹量、HP 和飞行进度由状态对象持有。

LevelRepository 从 CubeLand/Levels/ 的 Addressables 地址读取索引和 JSON。第一轮按索引关序加载，超出关序后仅循环标记了 canLoop 的条目；加载后会核对索引 ID 与文件内容是否一致。

项目内的关卡来源为 Assets/SGame/CubeLand/Data/Levels。编辑器使用 index.json、index.iap.json 和 index.all.json 等已有索引；不要假定本玩法存在 Excel 导表流程。

二、棋盘规则层：当前还剩什么、从哪里能打到

BoardState 从关卡数据建立目标状态，包括：

• 方块或机关的局部空间范围。
• HP、已预占伤害和剩余计数权重。
• 是否仍存活、能否被直接攻击、是否阻挡射线。
• 机关父子关系和当前占用格。

它负责寻敌、直线遮挡、目标预占、伤害和部分机关状态变化。这里使用数学坐标、Bounds 和网格索引，不读取相机画面，也不靠美术模型 Collider 决定射击结果。

Depth 是数据中的逻辑分类，普通攻击不以它决定可打层级。 编辑器按 depth 剥层有助于观察关卡，但不是正式炮台的攻击规则。

三、会话规则层：这一局如何推进

LevelSession 持有一个棋盘，以及队列、已上阵炮台、普通/Pilot 槽位、工具、在途子弹和胜负状态。

它的主要职责包括：

• 校验上阵资格，预留炮位，处理连体炮和队首关系。
• 推进冷却、寻找目标、预占伤害、扣弹与发射。
• 推进子弹生命周期，抵达结算或取消。
• 判断棋盘清空、炮弹耗尽及停滞扫描。
• 通过事件通知画面和外部接入层。

它不拥有场景、资源加载、UI、广告或经济系统。代码仍使用 Unity 的向量等数学类型，所以这里的“规则独立”指不依赖场景表现和外围业务，并不意味着完全不引用 Unity 类型。

ShotSolution 保存目标、局部炮口、局部表面命中点和发射时范围；ShotState 再增加颜色、飞行时长、进度与结算结果。规则层和表现层共享这份飞行状态，避免画面抵达与伤害时刻各算一套。

四、表现层：怎样把规则画出来

CubeLandGame 负责创建和更新 Unity 玩法画面，包括模型变换、相机、炮位和队列布局、入槽运动、炮口瞄准、子弹动画及命中特效。

它有两个重要方向的连接：

1. 把真实条件交给规则层。 例如每帧读取实际 FirePoint，传入模型局部坐标；提供入槽完成和瞄准完成的门控；给新子弹提供飞行时长。
2. 把规则变化显示出来。 例如读取 ShotState.Elapsed 绘制子弹，监听命中事件后产生碎片，显示当前弹量和目标状态。

CubeLandComposition 与共用 Composition.asset 管理构图、模型缩放、炮位布局、瞄准速度和弹道参数。运行时模型调参使用当前实例副本，显式保存后才写回共用配置。

CubeLandBoardView、CubeLandPixelArt 和 CubeLandImpactEffects 分别承担棋盘画面、炮台/环境资源和弹体/命中特效等表现职责。它们显示规则结果，不自行决定目标是否该被消除。

五、正式游戏接入层：一局如何连接整个游戏

CubeLandGameController 把玩法接入现有的 UI、道具、暂停、音效、振动、胜负和复活流程。

初始化时，它创建 CubeLandGame 并订阅会话的发射、胜利和失败事件；点击炮手时转为上阵请求；吸尘器选择时调用可见颜色清除事务；胜负通过 GamePlayManager 进入外围结算。

会话的逐帧推进由表现层负责。 接入控制器维护外围道具时间和交互状态，不再重复推进一次 LevelSession。

GamePlayManager 管理正式游戏的关卡目录、当前关卡、玩法入口和结果接入等外围职责。修改玩家进度、体力、广告或结算时，应从接入层继续追踪，不能只改棋盘状态便认为完整业务流程已完成。

六、编辑器为什么能试跑正式玩法

关卡编辑器的游戏视图会建立隔离的关卡副本，复用正式 CubeLandGame、LevelSession 和构图配置。这样可以用同一套规则观察草稿，但试跑过程不会回写正在编辑的数据，修改草稿后需要重置试跑。

颜色弹量统计、自由视角和编辑筛选是编辑工具。它们能辅助发现问题，但不自动证明关卡可解。自动生成候选必须经过正式规则回放通关，才能作为已验证候选应用。

修改需求与入口对应

以下路径均相对 Assets/SGame/CubeLand/：

要修改的内容	先检查的源码
关卡字段、索引和读取	Runtime/Levels/LevelData.cs、LevelJson.cs、LevelRepository.cs
目标选择、遮挡、HP 和机关实体	Runtime/Gameplay/BoardState.cs、TargetState.cs
队列上阵、发射冷却、在途结算、停滞	Runtime/Gameplay/LevelSession.cs、ShooterState.cs、ShotState.cs
模型、炮口瞄准、弹道和画面时序	Runtime/Presentation/CubeLandGame.cs
相机、布局和共用射击参数	Runtime/Presentation/CubeLandComposition.cs、Art/Gameplay/Composition.asset
方块、炮台资源和命中特效	Runtime/Presentation/CubeLandBoardView.cs、CubeLandPixelArt.cs、CubeLandImpactEffects.cs
正式道具、暂停和胜负接入	Runtime/Integration/CubeLand/CubeLandGameController.cs 及其分部文件
外围关卡与结算	Runtime/Integration/GamePlayManager/
关卡编辑与隔离试跑	Editor/LevelPreview/

怎样理解文档中的验证结论

• 源码核对说明可以从当前实现确认的行为，不等于已经在 Unity 中跑过。
• 契约测试说明测试覆盖的规则；只有实际执行记录才能证明相应版本已通过。
• 运行实测需要说明正确的项目、场景、条件和实际操作路径。
• 美术参数拟合描述参考录屏的视觉匹配，不自动等同于原版物理或算法已经恢复。
• 未恢复机关会在当前规则中保留明确的限制，不能把外壳已经显示当成机关行为已完整实现。

开发文档应随相关实现同步更新，保留这些证据边界，让读者能够知道“当前代码是什么”以及“实际验证到了哪里”。