scenario-godot-rendering-lighting

Godot 渲染与光照（lighter / graphics technical artist）

目标：Godot 4.7.2.stable，macOS Apple Silicon（默认使用 Metal）。

这里的专家水平意味着通过实测循环来调整光照：一个校准场景，每次只改变一个变量，每次更改后查看渲染图像，在图像上标注数值，并计算每种效果的 GPU 开销。首先选择渲染器和 GI 方法，因为它们决定了其他设置的效果。艺术方向（明度分布、冷暖关系、焦点对比）要根据 Agent 实际打开的像素来判断，绝不能只看检查器。如果这里提到的某个关联技能不在你可用的技能中，请让用户安装它 （npx skills add scenario-labs/skills --skill <name>）；若无法等待，请根据工具架构继续操作，并指出这一缺口。

必备背景知识： scenario-godot-expert（渲染通道、gd_run、审查循环、4.7 陷阱）。

立场（专家差异）

1. 静态场景使用光照贴图。 SeasonalAsh 在 RTX 4060 上测得，SDFGI 会让帧率大约减半，VoxelGI 的帧率为 60 到 80 fps，而光照贴图速度最快：除非世界可破坏，否则“十次有九次”都该用光照贴图（SeasonalAsh 13:07、17:48）。在 4.7.2 中，Agent 可以烘焙光照贴图：编辑器任务会自行按下“Bake Lightmaps”（P7）。动态几何体或移动的太阳意味着使用 SDFGI 或 VoxelGI；静态场景则使用 LightmapGI 加 ReflectionProbes。
2. 先在外观开发场景中校准，再为关卡布光。 Brackeys 使用参考球体（暗色、白色、镜面）和 Display > Lighting（Brackeys 7:19、28:53）。Picster 会保留原始几何体搭建场景，以便日后重新测试（Picster 2:05、1:15:35）。 lookdev.gd 会构建一个室外场景和一个密闭房间。
3. 根据画面效果选择色调映射器，然后重新调整曝光。 Brackeys 和 Wild Ox 使用 AgX；SeasonalAsh 和 LegionGames 使用 ACES。实测结果：AgX 的 p95 最低，不会发生剪切，并且能让橙色发光体保持橙色，而 Filmic 和 ACES 会使其偏黄（P5）。AgX 也是成本最高的色调映射器，在手机上尤为重要（文档）。新建的 Environment 默认使用 Linear（P1）：务必设置。
4. 让发光效果在两个层面上都清晰可见。 Glow 会让发光体看起来很亮；真实光源（或烘焙 GI）才能让它照亮场景（Brackeys 13:56、Gamefromscratch 7:09）。4.6 更改了 Glow 的默认值（Screen、强度 0.3、级别 2 到 4 分别为 0.8/0.4/0.1，P15）：请重新调整 4.6 之前制作的场景。
5. 绝不要同时使用 SDFGI 和 VoxelGI，也不要相信 SDFGI 的首帧效果。 SDFGI 大约需要 30 帧才能收敛（P1），启用后会立即显得更暗（P8）。GDQuest 会在启用后重新调整色调映射。
6. 体积雾的质量在 Project Settings 中设置，其开销也在此体现。 Four Games 认为体积尺寸 64 太低，256 是不错的折中值；体积光束需要约 0.7 的各向异性和较短的长度（Four Games 0:32 到 3:52）。提高一个主打光源的 Volumetric Fog Energy，将手电筒的值降至 0.1（Brackeys 19:52、LegionGames 2:08）。实测结果：在 1080p 下，512 会增加 +3.9 ms 的开销（P9）。
7. 基础画面必须在每种渲染器上都能成立；分级设置只能锦上添花。 Mobile 不支持 SDFGI、VoxelGI、SSR、SSAO、SSIL 和体积雾；Compatibility 的限制相同，但不包括 SSAO；加载时每种情况都会输出一行 WARNING（P4）。雾、Glow、色调映射、光照贴图和探针能让各种渲染器都呈现所需效果［新增］。自 4.4 起，渲染器回退到 Compatibility 不再输出提示，且 fallback_to_opengl3 默认为 true（文档，P15）：在 PC 上将其设为 false，让有问题的驱动程序明确报错；在 Android 上保留 true 则是一个选择，但要测试 Compatibility 下的画面效果。
8. CompositorEffect 使用 GLSL compute，而非 .gdshader（Acerola 9:39）。文档列出了 Forward+ 和 Mobile，但文档中的实现方式（将颜色作为存储图像）在 4.7.2 的 Mobile 上会报 172 个错误，因为 Mobile 的颜色缓冲区没有 storage 位；Compatibility 则会静默忽略该效果（P12）。请在 Forward+ 上使用，并为 Mobile 添加保护。回调会在渲染线程上运行：与主线程共享的状态都要使用互斥锁，为推送常量补齐字节，使其大小为 16 字节的倍数，并记住升频发生在后期处理之后（文档）。若要在 UI 上方进行后期处理，可使用 CanvasLayer ColorRect，它在所有平台上都适用（Lukky）。

首先明确

输入	未提供时的默认值
各平台的目标平台及渲染器	桌面端 Forward+。项目默认值为 rendering_method.mobile="mobile"、.web="gl_compatibility"
帧预算及参考 GPU	PC 上为 60 fps（16.6 ms）；使用 Vulkan 测量（Metal 报告的 GPU 时间为 0 ms）
静态或动态世界：移动的太阳、可破坏几何体、尺寸	静态室内场景：光照贴图；昼夜开放场景：SDFGI；中等规模动态场景：VoxelGI
氛围参考及时间段	一张图片或三个词（“寒冷的黎明，雾蒙蒙，充满希望”）
主体及摄像机	一条 Camera3D 路径，否则使用场景的当前摄像机
资源来源	来自 blender-expert 或 scenario-* 技能的 glTF：检查 UV2 和多余的自发光

工作流

加载工具包：将 skills/scenario-godot-expert/scripts 和 skills/scenario-godot-rendering-lighting/scripts 添加到 sys.path，然后执行 import gd_lighting as gl 和 gl.install(P)。完整代码：references/procedures.md。

1. 渲染器。 读取 project.godot（rendering_method、Jolt、回退）（P1）。 gl.capture_renderers(P, scene) 会为每个渲染器截取一个视图，并返回 WARNING 行。 GATE：在 project.godot 中写明渲染器；打开奇偶对照表；在交接内容中列出舍弃的功能。
2. 外观开发。 执行 gl.build_lookdev(P)（P3），截取三个摄像机的画面。GATE：look_checks 的 p95 减去 p05 大于 0.25，裁切比例低于 5％；打开并检查：暗色球体能呈现形体，白色未被裁切，镜面能反射天空。
3. 全局光照和烘焙。
   • 静态场景：执行 gi_bake.gd:prepare（太阳设为 Dynamic，其他灯光设为 Static，隐藏灯光设为 Disabled，检查 UV2）， 然后运行窗口模式的 gi_bake.gd:lightmap 编辑器任务（P7）；
   • 中型动态场景：运行窗口模式的 gi_bake.gd:voxelgi（P6）；
   • 开放世界：使用带遮蔽的 SDFGI，反弹反馈设为 0.5 或更低，Y 轴缩放设为 75％ 或 50％，最大距离小于摄像机远裁剪距离， 并在 40 帧或更多帧后截取画面（P8）。
   • 使用光照贴图时添加 ReflectionProbes（否则没有镜面反射）。GATE：审计无 GI 错误；烘焙文件存在；打开室内截图并检查漏光、 接缝和暗斑。
4. 主光、补光和实用灯光。 灯光应位于光源处，颜色相符；只有主光开启阴影；蜡烛不投射阴影、照射范围较短；人造灯光亮度低于太阳（Brackeys，SeasonalAsh）。 运行 gl.audit(P, scene, ["forward_plus", "mobile"])（P2）。GATE：没有错误标记；打开 squint(img) 并使用一个焦点值；focal_contrast 至少为 0.05。
5. 环境和后期处理。 通过 gl.sweep 一次调整一个变量：色调映射器（tonemap_variants，P5）、 曝光、泛光、雾、体积雾（P10），最后调整 Adjustments（通过色彩校正渐变实现冷色阴影、暖色灯光，Picster 45:07）。GATE：打开每张对照表，注明选中的方案及其数值；除非任务说明另有要求，否则任何方案的裁切比例均不得超过 5％。
6. 阴影。 先调整 shadow_normal_bias，再调整 shadow_bias（SeasonalAsh 使用 0.05，对比默认值 0.1，帧 4:13）；开启分割融合；最大距离设为可玩范围（Picster：室外 400，默认 100）。GATE：打开掠射角特写；没有条纹；接触阴影贴合物体。
7. 档位和成本。 通过 call 和 measure=60 对 graphics_tiers.gd 预设进行扫描，使用 --rendering-driver vulkan（P11）：低档和中档使用 2 个阴影分割，高档和超高档使用 4 个。根据 P9 模板计算每种效果的增量。在 Mobile 上，Apple 设备使用 MetalFX 空间放大，否则使用双线性放大（P13）。GATE：每个档位的 GPU 毫秒数均符合目标渲染器的预算，且低档保留整体氛围。
8. 自定义后期处理（可选）。 使用 compositor_tools.gd:attach、post_effect.gd 和 GLSL 计算着色器（P12）。GATE：效果在 Forward+ 上显示；Mobile 跳过并发出一条警告。

专家清单（在计划中说明这些内容）

• 烘焙范围。 隐藏的灯光仍会参与烘焙：将 Bake Mode 设为 Disabled（文档）。网格默认 GI 模式为 Static（P15），因此将不可玩几何体的 GI 模式设为 Disabled，以加快烘焙并提升效果 （SeasonalAsh 13:39）。
• 导入和仓库。 glTF meshes/light_baking=2（静态光照贴图；默认值 1 为普通 Static），以及 meshes/lightmap_texel_size（默认值 0.2；在会导致烘焙崩溃的大型场景中设为 0.5 或更高）（P15、文档）。绝不要将 *.unwrap_cache 加入 gitignore（以保持 UV2 稳定）；将 .lmbake 放在仓库外（文档）。
• 漏光。 使用封闭的厚墙［新增］；对于密闭房间，使用 LightmapGI Interior，并将环境模式设为 Disabled（文档）。
• 降噪器。 rendering/lightmapping/denoising/denoiser 是项目范围的设置：0 为 JNLM（默认值），1 为 OIDN（需要外部二进制文件）（文档、P15）。
• Shadowmask。 LightmapGI.shadowmask_mode：None（0，默认值）、Replace（1，近处实时渲染，超出最大 距离后使用烘焙结果，最适合植被）、Overlay（2，适合快速移动的摄像机）。仅第一个 Dynamic DirectionalLight3D 生效；切换时无需重新烘焙（文档、P15）。
• 室内烘焙过暗。 光照贴图会忽略 Environment 环境光：先添加补光或反弹光； Spannule 的最后手段是对 EXR 进行乘法处理，并添加约 8% 的环境光（1JvPYUl1nfo 4:00）。
• SSAO 只会让环境光变暗：ssao_light_affect 的默认值为 0.0（文档、P15）。
• 阴影。 Cull Mask 不会阻止投射阴影：关闭网格的 Cast Shadow。默认图集可容纳 88 个投射阴影的 位置灯（象限为 4+4+16+64，P15）。网格若出现在全部 4 个 PSSM 分割中，就会绘制 5 次。在 Forward+ 中，一个可见的 AreaLight3D 就会增加每个物体的渲染负担。Compatibility 会以 sRGB 渲染带阴影的灯光，因此需重新调整能量值（文档）。
• 后期处理。 3D LUT 必须导入为 Texture3D（importer="3d_texture"、slices/horizontal）；包含 16 个切片的 256x16 条带会以 16x16x16 的形式加载（P15）。HDR Clamp Exposure 只会压缩亮度高于约 4096 的部分（一处 100000 的太阳像素变为 14988；50 仍为 50，P15）。默认情况下，Debanding 处于关闭状态。曝光和 DOF 位于 Camera3D 上的 CameraAttributes 中，质量选项位于 Project Settings 中。

数值

数值	相对基准	来源
shadow_bias 0.05	默认值为 0.1	SeasonalAsh frames 4:13；P1
阴影模糊度 2 到 3	默认值为 1.0	SeasonalAsh 5:13
定向光最大距离 100	默认值；Picster 在室外为 400	P1；Picster 54:08
体积雾体积大小	默认值为 64，256 效果良好，512 效果最佳；在 1080p 下，64 时增加 0.2 到 1.1 ms，256 时增加 1.5 到 2.7 ms，512 时增加 3.9 ms	Four Games 2:44；P9
用于光束的雾各向异性 0.7	默认值为 0.2	Four Games 0:32；P1
SDFGI 收敛	约 30 帧（枚举索引 5）；40 帧后捕获	P1、P8
SDFGI 反弹反馈	默认值为 0.5；高于 0.5 有失控风险	P1；Omogonix 28:10
SDFGI 最大距离	默认值为 204.8，相机远平面为 4000	P15
每个网格的光源数	Mobile：8 个全向光 + 8 个聚光灯；Forward+：每个视图 512 个聚类元素	文档
聚光灯阴影角度	大于 89° 时失效	文档
LightmapGI 质量顺序	先超采样，再纹素大小，最后质量	Brackeys 34:34
LightmapGI 低质量烘焙，外观开发房间	烘焙耗时 3.6 到 15 s（M5 Max，负载下）	P7
1080p 下效果的 GPU 耗时（ms），小型场景	SSIL +1.4 到 1.7，SSR +0.9 到 1.3，SDFGI +0.7 到 1.1；SSAO、glow、TAA、SMAA、MSAA 2x 各低于 0.8（低于 0.5 属于噪声）	P9、Vulkan
档位 GPU 耗时（Forward+ / Mobile）	低：1.5 / 0.62，高：2.9 到 4.3 / 1.73，超高：3.6 到 4.85 / 1.64	P11，小型场景

效果开销会随分辨率和场景变化：引用这些数值前，请使用 P9 模板重新测量。

质量门槛

• 可测量：每个目标渲染器的 gl.audit 均无错误标记；gd_run.check_all 无解析 错误；look_checks 中 clipped 低于 0.05、crushed 低于 0.3、p95 减 p05 高于 0.25， focal_contrast 至少为 0.05；烘焙文件存在且 lightmap_textures 至少为 1；.gitignore 中没有 unwrap_cache；每个档位的 GPU 耗时均在 Vulkan 上的预算范围内。
• 视觉效果：打开每张联系表和眯眼图检查：有一个焦点区域、轮廓清晰可辨、冷暖意图明确， 没有漏光、接缝、斑点或色带，发光体有辉光，雾不会冲淡画面，移动端和低档位仍能保持氛围。 references/critique.md 是评判标准。

常见错误

错误	表现	修正
保留 Linear 色调映射	高光过曝，天空显得平淡	使用 AgX 或 ACES，再调整曝光
使用编辑器预览中的太阳进行照明	游戏画面发灰	在场景中使用 WorldEnvironment 和太阳（SeasonalAsh 1:40）
同时使用 SDFGI 和 VoxelGI	二次反弹，开销增加	每个区域只使用一种 GI
对没有 UV2 的网格烘焙光照	烘焙结果全黑或乱糟糟	对基本体使用 add_uv2，对 glTF 启用 Static Lightmaps
隐藏的灯光仍被烘焙	出现幽灵灯光	将 Bake Mode 设为 Disabled（prepare 会处理）
期待 Mobile 上支持 FSR1	效果与双线性过滤相同，并出现警告 "FSR1 3D scaling is only available when using the Forward+ renderer"	在 Apple 设备上使用 MetalFX spatial，否则使用双线性过滤（P13）
在 Mobile 上使用 docs CompositorEffect	每次运行出现 170 多个错误	添加存储位检查（post_effect.gd）
导入的 glTF 上存在多余的自发光	道具发光	检查 emissive_without_glow，并将其设为零（Gamefromscratch 5:25）
将 "30" 写入 frames_to_converge	枚举索引错误	gl.setting_index(key, 30) 会返回 5
开启 SSAO 后没有任何变化	在直射光下看不到 AO	调高 ssao_light_affect
将 LUT 用作普通 PNG	颜色校正被忽略	重新导入为带切片的 Texture3D

交接

• 接收自：scenario-godot-3d-world（关卡、静态与动态拆分、摄像机）； blender-expert 和 scenario-* 技能（带 UV2 的 glTF）；scenario-godot-shaders（材质）； scenario-godot-vfx（自发光效果）。
• 交付给：scenario-godot-performance-export（分级表、每个分级和渲染器对应的 GPU 毫秒数、 设置差异）；scenario-godot-ui（映射到 graphics_tiers.gd 的图形设置）； scenario-godot-shaders（合成器 GLSL 需求）；scenario-godot-expert（表格、审计 JSON、兼容性说明）。 提交场景和 .tres 文件，以及 .agent_out/ 中的表格和 JSON。

Godot 4.7 说明

在 4.7.2 中观察到（references/expert-notes.md，已观察）：

• 脚本中不存在 LightmapGI.bake；编辑器按钮的操作方式可用（P7）。VoxelGI.bake 存在，但无头模式下会保存空数据。
• GeometryInstance3D.lightmap_scale 已移除：请使用 gi_lightmap_texel_scale。
• 新建 Environment：线性色调映射，glow Screen 设为 0.3，SDFGI bounce feedback 设为 0.5。
• FSR1 仅支持 Forward+；使用 Metal 时，MetalFX 空间缩放可在 Mobile 上运行。
• Metal 上的 GPU 计时读数为 0：请使用 --rendering-driver vulkan 进行性能分析。
• AgX 于 4.4 引入。Wild Ox 称 4.6 修复了 SDFGI 和 VoxelGI 泄漏、glow 和 SSR，因此请重新测试 2023 年的变通方案，例如封装盒（Wild Ox 2:23）。

参考资料

• references/procedures.md：P0 至 P15，每项均包含完整代码、实时测试和结果行。
• references/expert-notes.md：附带时间戳的专家判断，以及已观察到的 4.7.2 事实。
• references/critique.md：图像评估标准。 references/gui-paths.md：编辑器路径。 references/sources.md：来源和时间戳。
• scripts/gd_lighting.py 和 scripts/agentkit/rendering/：lookdev、light_audit、sweep、 gi_bake、graphics_tiers、compositor_tools、compositor/。