Godot 阴影更新预算：好看的光照不能每帧都重新算一遍

先把问题放到真实场景里

动态阴影很贵，预算应该花在玩家看得见、会影响判断的地方。这句话听起来像经验，但在项目里它通常会变成一次次具体事故：某个设备表现不一致，某条异步链路旧回调回来，某个资源被错误保留，或者某次优化只解决了开发机上的现象。Godot 项目做客户端开发，最怕把这些问题当作孤立脚本处理，因为脚本越补越多，状态反而越来越难解释。

夜晚城镇版本上线后，画面气氛很好，但中低端设备掉帧明显。Profiler 显示渲染压力上升，进一步看是多个动态灯和角色阴影频繁更新。很多阴影来自远处路灯和看不清的装饰物，玩家感知很弱，成本却是真实的。

所以这篇文章把Godot 阴影更新预算当作一个小型系统来设计。系统化并不是把事情做重，而是让数据来源、状态归属、失败恢复和调试出口都能对齐。只要团队能在开发包里看到当前状态，QA 能用固定样本复现，发布后能通过指标确认风险，这个功能就不再只是靠作者记忆维护。

边界和模块拆分

建议先拆出这些模块：ShadowCasterRegistry, LightImportanceScorer, ShadowUpdateScheduler, CascadeQualityPolicy, BlobShadowFallback, ShadowDebugOverlay。模块名可以按项目习惯调整，但职责必须清楚。采样模块只拿事实，策略模块只做判断，表现模块只负责反馈，调试模块只记录证据。不要让页面脚本同时读取平台状态、修改资源、发请求、改 UI 和写缓存。

这种边界能减少很多后期争论。比如一个按钮为什么不可用，页面不应该自己猜；一个资源为什么没有释放，释放工具应该能说出 owner；一个输入为什么被忽略，输入链路应该能指出是噪声、焦点冲突还是模式锁定。边界越清楚，事故复盘越快。

设计时先把下面几条规则写清楚：

• 光源和投影物都要评分，不是开了动态阴影就永久高质量。
• 远处和小屏幕占比对象降低更新频率或使用假阴影。
• 战斗相关角色和可交互物体优先保留可信阴影。
• 低端设备用稳定降级，不在镜头移动时频繁切档。

流程架构

下面的 Mermaid 图把核心链路画出来。复杂系统不一定要一开始就做得很大，但链路必须能画清楚。图上的每个节点都应该有日志、调试字段和失败原因。

flowchart TD
    N0["Caster Registry"] --> N1["Importance Scorer"]
    N1["Importance Scorer"] --> N2["Update Scheduler"]
    N2["Update Scheduler"] --> N3["Quality Policy"]
    N3["Quality Policy"] --> N4["Fallback Shadow"]
    N4["Fallback Shadow"] --> N5["Debug Overlay"]

如果实现里出现图上没有的隐式路径，比如某个子页面直接修改全局状态，或者某个回调绕过策略层直接操作表现，就要特别小心。隐式路径短期省事，长期会让 QA 截图、日志和玩家反馈对不上。

数据模型不是附属品

核心数据至少要覆盖这些字段：light_id, caster_id, screen_coverage, distance_to_camera, importance_score, update_interval, shadow_resolution, fallback_mode。这些字段不一定全部进入正式埋点，但开发包和测试报告里要能看到。字段的作用不是装饰，而是在异常发生时回答“当前结果由谁决定、基于什么输入、处在哪个版本”。

字段命名要避免只有 enabled、valid、done、state 这种宽泛词。它们在第一版很好写，到了第三版就会变成谜语。更稳的做法是拆成 source、reason、owner、revision、scope 和 expires_at。source 说明来自平台、配置、玩家还是服务器；reason 说明为什么进入这个状态；owner 说明谁有控制权；revision 用来丢弃旧回调；scope 决定影响范围；expires_at 处理过期和回滚。

Godot 里可以用 Resource 保存稳定配置，用 autoload 保存跨场景运行时状态，用普通节点负责表现。这样切场景时状态不会跟着 UI 一起销毁，UI 重建也不会重新发起危险操作。

关键实现片段

下面这段 GDScript 不是完整框架，只展示推荐的实现习惯：统一入口、记录原因、不要让业务绕过策略层。

func schedule_shadow_updates() -> void:
    var ranked := scorer.rank_visible_lights(camera)
    for item in ranked:
        if scheduler.has_budget_for(item):
            item.light.update_shadow()
        else:
            fallback.apply(item)

实际工程里还要补 request_id、trace_id、错误码和调试开关。request_id 解决旧请求覆盖新状态，trace_id 让一次操作能跨模块串起来，错误码让 UI 文案、日志和客服查询共用同一套解释。调试开关则保证开发包能看清问题，正式包不会暴露内部细节。

具体落地步骤

可以按这个顺序推进：

• 注册所有投影物，按距离、屏幕占比、玩法重要度计算 importance_score。
• ShadowUpdateScheduler 按预算分配每帧更新的阴影。
• CascadeQualityPolicy 根据设备档位和场景复杂度调整级联数量和分辨率。
• BlobShadowFallback 为远处 NPC、掉落物和装饰物提供低成本替代。

第一阶段只做一个高频场景，不要一开始铺满全项目。比如先选主城、战斗、下载、房间或设置页里最容易复现的一条链路，把状态、日志和 QA 样本跑通。第二阶段再接入相邻场景，确认状态模型没有被特殊页面破坏。第三阶段才做编辑器检查、导出报告或自动化测试。

落地时还要约定配置权限。程序负责字段语义和保护线，策划或内容同学可以改阈值和映射，美术可以改表现资源，但任何人都不应该临时新增未登记字段。否则数据会越来越像自由文本，工具和校验就失去意义。

事故复盘方式

复盘不要只写“已修复”。建议固定写三段：玩家看到什么、系统真实状态是什么、代码为什么没有表达这个状态。第一段帮助团队理解体验损失，第二段定位数据和状态，第三段决定模型是否需要调整。很多重复事故不是因为修得不认真，而是第三段没有写清楚。

还要避免局部成功误导。一个请求成功不代表页面成功，一个资源存在不代表依赖完整，一个输入被收到不代表玩家意图被执行，一个性能指标变好也不代表体验稳定。客户端工程看的是链路闭环，单点成功只能说明某个函数没报错。

如果事故涉及移动端、网络或资源，复盘里还要补设备型号、系统版本、构建渠道、资源版本和前后台状态。没有这些上下文，后续只能靠猜。

性能和资源预算

预算要在第一版就写出来。预算不一定复杂，可以只是每帧最多处理多少次、缓存最多多大、日志采样率是多少、重试间隔怎么退避、一次状态切换允许耗时多少毫秒。没有预算，功能成功后很容易被内容量拖垮。

低端设备上要优先保留玩家理解状态所需的信息，再削减装饰、动画密度、刷新频率和后台任务。不要为了省一点性能隐藏错误原因，也不要为了表现顺滑让主线程等待磁盘、网络或资源。Godot 项目里常见的隐形成本包括同步 ResourceLoader、Control 树批量重建、AnimationTree 全量采样、材质 duplicate、信号重复连接和每帧轮询。

上线后建议至少观察这些指标：shadow_update_ms, active_shadow_caster_count, shadow_resolution_switch, fallback_shadow_count, gpu_shadow_pass_ms。指标不只是给报表看的，它们会告诉团队是某类设备有问题、某个内容版本引入问题，还是某个策略阈值太激进。

QA 清单

这批用例建议进入回归：

• 夜晚城镇、室内多灯、Boss 战大体型、低端机和动态天气都要测。
• 检查阴影降级不会让攻击范围、地面高度和可交互提示变得误导。
• 镜头快速旋转时不应出现明显阴影闪烁。

QA 用例要写前置状态、操作步骤、预期结果和预期原因。只写“功能正常”没有价值。比如“网络切换后能够继续加载，并提示正在恢复”比“弱网正常”更可执行。好的测试描述会反过来要求代码输出清楚的 reason。

每次修复内测或线上问题，都把最小复现路径固化成样本。后续改同一模块时先跑样本，再谈新功能。样本库越稳定，团队越不依赖某个老同事记得当年踩过什么坑。

调试工具和报告

开发包里至少要有一个可截图面板，显示当前状态、关键字段、owner、最近状态变化、错误码和耗时。面板不用花哨，但必须准确。QA 截图后，程序应该能知道卡在采样、策略、请求、资源、表现还是恢复阶段。

如果系统涉及资源或导出，最好生成离线报告；涉及性能，保留输入脚本和帧时间样本；涉及输入，保留最近输入事件和意图转换；涉及网络，保留请求 epoch 和最后确认状态。调试工具不是额外负担，它是让系统从“作者能懂”变成“团队能维护”的关键。

正式包里不要暴露内部面板。可以保留低频匿名指标、错误码和必要的客服查询字段，但不要把内部资源路径、设备唯一标识或策略细节直接展示给玩家。

上线和回滚

上线前要写清楚哪些配置能远程关闭，哪些资源能回退，哪些状态需要玩家重进，哪些数据一旦写入就不能撤。灰度发布不是把风险变慢，而是给团队留出发现和回滚的窗口。没有回滚策略的灰度，本质上只是晚一点全量。

回滚时也要考虑玩家感知。不要让玩家因为一次技术回退丢草稿、丢进度、重复领奖、重复下载或离开队伍。客户端无法解决所有服务端和平台问题，但至少要避免展示错误承诺。比如还在校验时不要显示完成，还没确认进房时不要显示已加入。

上线后一周内要重点看异常分布，而不是只看总量。总失败率低，不代表某个低端设备、某个语言、某个渠道没有严重问题。把指标按设备、渠道、内容版本和场景拆开看，才能发现真正的风险。

可操作的最小验收标准

我会用六条标准验收：状态能解释表现；失败原因能展示和记录；旧请求、切场景、切后台不会破坏状态；低端设备有预算；QA 有可复现样本；发布后有指标。六条都满足，再继续扩内容和美化体验。

做到这里之后，后续迭代会变得更具体：哪个字段不够，哪个阈值太紧，哪个页面没有订阅，哪个资源没有 owner，哪个样本缺少设备信息。具体问题才方便被具体解决。

交接给团队

最后要把规则交接给团队，而不是只把代码合进去。文档里至少要有状态图、字段表、错误码、配置入口、调试面板位置、QA 样本和回滚方式。新同学接手时，能通过这些材料理解系统，而不是从十几个脚本里反推作者意图。

这类系统越早被写清楚，后续批量内容越轻松。反过来，如果每个内容都绕开规则做特例，短期上线很快，长期维护会越来越慢。客户端开发的质量差距，很多时候就体现在这些不起眼的状态和工具上。

补充排查细节

阴影预算的调试视图要能按光源和投影物两种维度排序。有时不是某盏灯太贵，而是某个角色携带了过多可投影子网格；有时不是角色多，而是级联范围太大。把两个维度拆开看，优化才不会误伤画面。

阴影优化不要只在静态镜头下截图验收。角色奔跑、镜头快速转向、灯光开关和天气变化时的稳定性更重要。