Godot 碰撞层契约治理：能撞到谁，不能靠节点名字猜

为什么要单独治理

版本后期，项目里有 Player、Enemy、Projectile、Interactable、Loot、QuestArea、CameraBlocker 十几类节点。某次改动后，治疗弹会被装饰物挡住，拾取物又能触发敌人警戒区。排查发现多个脚本直接改 collision_layer 和 collision_mask，命名也不统一。碰撞层如果没有契约，后期每个物理 bug 都像随机事件。

这篇不是物理查询预算治理，而是关注碰撞层语义、玩法规则和项目协作契约，避免物理交互被散落脚本改乱。 真正要解决的是状态边界。Godot 项目到了中后期，问题很少只停留在一个脚本里：输入会牵动 UI，网络会牵动资源，资源又会牵动画面和存档。把这类问题拆成系统，不是为了显得架构复杂，而是为了让每一次状态变化都能被解释、被复现、被回滚。

我更建议把它当成客户端可靠性工程来做。第一版不需要覆盖所有平台和所有边界，但必须有统一入口、可观察状态、明确的失败原因和 QA 能复现的样本。如果这些东西缺失，后面新增几个 if 分支只会把问题藏得更深。

先划清边界

建议从这些模块开始：CollisionLayerCatalog, PhysicsContractValidator, RuntimeMaskGuard, InteractionRuleMatrix, CollisionDebugOverlay, PrefabImportChecker。模块名不重要，重要的是职责不能混在一起。采样模块只采样，策略模块只给决策，执行模块只做状态切换，表现层只展示归一化后的结果。页面脚本不应该直接读取平台状态、修改资源、发起请求、调整渲染和写入存档。

这类系统最容易犯的错误是“临时处理一下”。比如某个按钮发现状态不对，就自己重试；某个资源加载失败，就自己换 fallback；某个输入事件迟到，就自己吞掉。短期看问题消失了，长期看排查路径被切碎了。更稳的做法是让所有特殊情况都回到同一个服务，至少在日志和调试面板里能看到它们来自哪里。

核心规则可以先写成几条：

• 每次外部状态变化都要生成 generation，旧回调不能覆盖新状态。
• 每个失败都要有 reason，不使用单纯的 failed 或 ok。
• 每个自动恢复动作都要能取消，不能在玩家离开场景后继续写状态。
• 每个高风险动作都要有 QA 场景，而不是只靠开发机手动点一次。

架构图

flowchart TD
    A["定义碰撞层目录"] --> B["建立交互规则矩阵"]
    B --> C["导入和场景检查"]
    C --> D["运行时修改经过 Guard"]
    D --> E["调试层显示命中原因"]
    E --> F["PR 阶段输出差异"]
    C --> G["Debug Trace"]
    F --> H["QA Scenario"]

这张图的价值不是画得完整，而是给程序、策划、QA 和运营一个共同语言。线上问题发生时，大家可以沿着图问：卡在采样、策略、执行、表现，还是恢复？如果图外还有隐式通路，比如页面直接改状态、回调直接写 UI，就要把它收回来。

数据模型

关键字段建议至少包含：node_path, layer_name, mask_names, contract_id, owner_system, runtime_override, violation_reason, query_profile。字段不是为了堆结构，而是为了让问题能被解释。很多线上事故不是因为客户端完全没处理，而是处理过之后没人知道为什么会走到这个分支。

命名要尽量具体。enabled、valid、ready 这些字段只能说明当前分支想通过，不能说明由谁决定、什么时候决定、还能不能恢复。更好的字段会带 owner、source、reason、generation、revision、scope 和 timestamp。它们让日志能回答“谁在什么时候因为哪个原因把状态改成了什么”。

在 Godot 里，稳定配置适合放进 Resource，跨场景状态适合放在 autoload service，临时 UI 状态则留在页面节点。不要反过来：用页面节点保存跨场景状态，或者用全局单例保存每个控件的临时视觉状态。生命周期一乱，重连、切场景、热更新和前后台恢复都会变得不可预测。

Godot 接入点

Godot 的优势是场景和信号组织灵活，风险也是太灵活。建议把统一服务做成 autoload，例如 ClientReliabilityService 的一个子服务，再让具体场景通过信号订阅结果。平台层、网络层或资源层的原始事件先进入服务，服务归一化之后再通知 UI 和玩法节点。

下面的代码只展示关键习惯：先确认 generation，再做策略判断，最后由表现层订阅结果。

func set_collision_profile(node: CollisionObject2D, profile_id: String) -> void:
    var profile := catalog.get_profile(profile_id)
    if not profile.allowed_for(node):
        push_error("collision profile rejected: %s" % profile_id)
        return
    node.collision_layer = profile.layer_bits
    node.collision_mask = profile.mask_bits
    debug_overlay.note_profile(node, profile_id)

真实项目里还要补错误码、trace_id、调试开关和单元测试夹具。trace_id 用来把一次玩家操作串起来；错误码让 UI、日志和客服口径一致；调试开关让开发包看得清，正式包不泄露内部细节。单元测试则至少覆盖状态机分支，避免后续改动把恢复流程打断。

和其他系统的协作

这个主题通常会同时影响三个相邻系统。第一是 UI：它要知道当前是恢复中、暂停、失败还是可继续，而不是只显示一个通用转圈。第二是资源或网络：它们要能暂停和恢复，不能在状态不稳定时抢跑。第三是 QA 和可观测性：它们要能制造边界场景，而不是等玩家在线上遇到。

协作时要避免互相调用成网状。更推荐事件和状态订阅：服务发布状态，UI 订阅；服务请求资源层执行动作，资源层返回结构化结果；QA 面板从服务读取当前快照。这样每条链路都能画出来，也能在日志里串起来。

另一个细节是玩家可感知行为。系统内部自动恢复不代表 UI 可以沉默。超过 500ms 的恢复最好有轻量状态，超过 3 秒的恢复要有明确文案，超过可接受阈值的失败要给玩家下一步选择。很多客户端问题不是不能恢复，而是恢复期间玩家不知道发生了什么。

QA 场景

这类功能必须做真机场景，而不是只在编辑器里点按钮。建议至少覆盖：

• 投射物穿过友方但命中敌人和墙体
• 拾取物只响应玩家不响应敌人和弹体
• 任务区域不挡路但能触发进入事件
• 剧情期间临时关闭碰撞后恢复原 profile
• 导入新 prefab 时未声明碰撞契约

每个场景都检查四件事。第一，状态是否进入预期分支。第二，旧 generation 的回调是否被丢弃。第三，UI 文案是否解释了真实原因。第四，恢复后是否会把临时状态写成永久状态。最后一条尤其重要，很多 bug 当场看不出来，几分钟后自动保存或下一次切场景才暴露。

QA 面板可以显示当前 generation、状态机节点、最后一次 reason、最近十条状态变化和当前 owner。这个面板不需要做得漂亮，但要能截图。只要 QA 能把截图和 trace_id 发给程序，定位效率就会明显提高。

线上指标

建议记录这些指标：collision_contract_violation, runtime_mask_override_count, unknown_layer_usage, physics_bug_repro_time, debug_overlay_hit_reason_used。指标不要只服务漂亮报表，要能回答具体问题：恢复是否成功，失败是否集中在某类设备，重试有没有浪费玩家时间，fallback 是否真的被用上，玩家是否因为状态不确定而退出。

采样要克制。不要上传隐私内容，不要上传完整本地路径，也不要把每一帧状态都打上来。通常记录状态变化、错误码、设备类别、资源版本、场景 id 和耗时就够了。如果需要更细日志，只在灰度包或玩家授权的诊断模式里打开。

落地步骤

第一阶段只做观测。把现有散落的判断集中到调试面板里，不急着改变行为。你会很快发现哪些状态没有 owner，哪些失败没有 reason，哪些模块在绕过统一入口。

第二阶段接入最容易出事故的一个场景，先跑通状态机、UI 文案和 QA 用例。不要一开始全项目替换，否则问题面太大，团队很难判断是新架构的问题还是旧逻辑没有迁干净。

第三阶段加入恢复和回滚。恢复动作必须可取消，回滚路径必须保留旧状态。玩家离开场景、切账号、切语言、切网络、切前后台时，旧恢复任务都要重新确认 generation。

第四阶段再做自动化和灰度。把 QA 场景沉淀成调试命令或测试夹具，在线上灰度中观察指标。指标稳定后，再把更多页面和玩法接入。

常见误区

一个误区是把所有问题都归成“平台差异”。平台差异当然存在，但客户端仍然需要统一模型。没有模型时，每个平台都会长出自己的特殊分支，最后谁也说不清哪个分支是当前真相。

第二个误区是把恢复做得太积极。自动重试、自动重载、自动切换 fallback 都有成本。它们可能掩盖真正的错误，也可能在错误条件仍然存在时反复执行。恢复策略要有次数、间隔和退出条件。

第三个误区是只关注成功路径。越是边界系统，越要把失败路径写清楚。失败时能保留玩家状态、给出可理解文案、留下诊断证据，往往比成功时快几十毫秒更重要。

碰撞契约复盘演练

碰撞层治理最好从一次矩阵评审开始。把玩家、敌人、友方弹体、敌方弹体、拾取物、任务区域、镜头遮挡、装饰物、触发器列成表，逐格确认应该碰撞、只查询、只触发还是完全忽略。这个矩阵要进入仓库，而不是只存在策划文档里。

运行时也要防止脚本私自改 mask。剧情、技能、无敌、潜行、穿墙这些状态确实会临时改碰撞，但都应该申请 profile override，并在结束时恢复。调试面板需要显示当前节点的 base_profile 和 override_reason。否则一个临时无敌效果漏恢复，就可能让玩家之后一直无法被命中。

交付标准与 review 关注点

PR review 要拒绝魔法数字。任何 collision_layer 和 collision_mask 的修改都应该通过 profile id，运行时 override 要有 owner 和恢复点。交付标准是：新 prefab 没有碰撞契约不能通过检查，调试层能显示命中原因，剧情和技能临时改碰撞后能回到原 profile。

团队分工和长期维护

这个系统上线后，维护责任要写清楚。客户端负责状态机、UI 反馈、日志和本地恢复；服务端或平台层负责给出稳定错误码、版本信息和最终状态；QA 负责保留可复现样本；制作团队负责确认体验降级是否可接受。不要把所有问题都丢给客户端临时兜底，也不要让客户端在没有服务端语义的情况下猜测最终结果。

每次版本迭代都应该检查三类变更。第一，是否新增了状态来源，比如新平台 SDK、新资源包、新输入设备或新玩法入口。第二，是否新增了自动恢复动作，比如重试、重载、fallback 或重建会话。第三，是否新增了玩家可见文案。只要其中一项变化，就要同步更新调试字段、QA 用例和线上指标。

长期维护还要避免“隐性成功”。系统自动恢复后，不能什么都不记录。恢复成功同样需要 trace，因为线上偶发问题往往来自连续成功后的某一次失败。只记录失败会让团队看不到恢复频率，也就无法判断系统是否正在频繁擦屁股。稳定的客户端不是永远不遇到边界，而是遇到边界后能用一致方式处理，并留下足够证据。

小结

Godot 碰撞层契约治理：能撞到谁，不能靠节点名字猜 这个问题看起来很具体，但它代表了 Godot 客户端中后期最常见的工程挑战：系统之间互相牵动，而玩家只关心结果是否可信。把它拆成可观察、可恢复、可验证的系统，才能避免后期靠临时分支续命。

建议从一个真实事故场景开始落地。先让状态能被看见，再让恢复能被控制，最后再追求自动化。只要边界清楚，后续扩平台、扩玩法、扩资源包时，团队就不用每次重新解释同一个问题。