scenario-godot-rendering-lighting

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Godot rendering and lighting (lighter / graphics technical artist)

Godot 渲染与光照（灯光师 / 图形技术美术）

Target: Godot 4.7.2.stable, macOS Apple Silicon (Metal by default).

Expert level here means that lighting comes from a measured loop: a calibration scene, one variable at a time, a rendered image looked at after every change, numbers on that image, and a GPU cost for every effect. The renderer and the GI method are chosen first, because they decide what the other settings can do. The art direction (value pattern, warm and cool, focal contrast) is judged on pixels the agent actually opened, never on the inspector. If a sibling skill named here is missing from your available skills, ask the user to install it (

npx skills add scenario-labs/skills --skill <name>

); unattended, proceed from tool schemas and flag the gap.

REQUIRED BACKGROUND: scenario-godot-expert (channels,

gd_run

, the review loop, 4.7 traps).

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

这里的专家级工作方式，是指光照来自一个经过测量的循环：搭建校准场景，每次只改变一个变量，每次修改后都查看实际渲染的图像，读取图像中的数值，并评估每项效果带来的 GPU 成本。首先选择渲染器和 GI 方法，因为它们决定了其他设置能够实现什么。艺术方向（明暗关系、冷暖关系、焦点对比）必须根据 Agent 实际打开查看的像素来判断，而不能只看 Inspector。如果这里提到的某个同级 skill 未包含在可用 skills 中，请要求用户安装（

npx skills add scenario-labs/skills --skill <name>

）；在无人值守执行时，则依据 tool schemas 继续操作，并明确标记缺失项。

必需背景： scenario-godot-expert（channels、

gd_run

、审查循环、4.7 陷阱）。

Stance (the expert delta)

立场（专家能力的增量）

Use lightmaps for static scenes. SeasonalAsh measured on an RTX 4060 that SDFGI roughly halves fps, VoxelGI runs at 60 to 80 fps, and lightmaps are fastest: lightmaps "9 times out of 10" unless the world is destructible (SeasonalAsh 13:07, 17:48). In 4.7.2 an agent can bake them: the editor job presses "Bake Lightmaps" itself (P7). Dynamic geometry or a moving sun means SDFGI or VoxelGI; static means LightmapGI plus ReflectionProbes.
Calibrate on a lookdev scene before lighting the level. Brackeys uses guide spheres (dark, white, mirror) and Display > Lighting (Brackeys 7:19, 28:53). Picster keeps the primitive blockout for later retests (Picster 2:05, 1:15:35).
```
lookdev.gd
```
builds an exterior and a sealed room.
Pick the tonemapper by look, then retune exposure. Brackeys and Wild Ox use AgX; SeasonalAsh and LegionGames use ACES. Measured: AgX gives the lowest p95, no clipping, and keeps an orange emitter orange where Filmic and ACES push it to yellow (P5). AgX is also the costliest tonemapper, which matters on phones (docs). A new Environment is Linear (P1): always set it.
Make emission readable on two levels. Glow makes an emitter look bright; a real light (or baked GI) makes it light the scene (Brackeys 13:56, Gamefromscratch 7:09). Glow defaults changed in 4.6 (Screen, intensity 0.3, levels 2 to 4 at 0.8/0.4/0.1, P15): retune scenes made before 4.6.
Never use SDFGI and VoxelGI together, and never trust SDFGI on frame one. SDFGI converges in about 30 frames (P1) and is darker right after enabling (P8). GDQuest retunes the tonemap after turning it on.
Volumetric fog quality lives in Project Settings, and that is where its cost is. Four Games calls volume size 64 too low and 256 a good compromise; god rays need anisotropy about 0.7 and a shorter length (Four Games 0:32 to 3:52). Raise one hero light's Volumetric Fog Energy, drop a flashlight's to 0.1 (Brackeys 19:52, LegionGames 2:08). Measured: 512 costs +3.9 ms at 1080p (P9).
The base look must hold on every renderer; tiers only add. Mobile ignores SDFGI, VoxelGI, SSR, SSAO, SSIL and volumetric fog; Compatibility the same minus SSAO; each prints one WARNING line at load (P4). Fog, glow, tonemap, lightmaps and probes carry the look everywhere [added]. Renderer fallback to Compatibility is silent since 4.4 and
```
fallback_to_opengl3
```
defaults to true (docs, P15): set it false on PC so a bad driver fails loudly; on Android keeping it true is a choice, so test the Compatibility look.
CompositorEffect is GLSL compute, not
.gdshader
(Acerola 9:39). The docs list Forward+ and Mobile, but the docs pattern (color as a storage image) logs 172 errors on Mobile in 4.7.2 because Mobile's color buffer lacks the storage bit, and Compatibility ignores the effect silently (P12). Ship it on Forward+ and guard Mobile. Callbacks run on the render thread: mutex any state shared with the main thread, pad push constants to multiples of 16 bytes, and remember upscaling runs after post (docs). For post with UI on top, a CanvasLayer ColorRect works everywhere (Lukky).

静态场景使用 lightmaps。 SeasonalAsh 在 RTX 4060 上测得，SDFGI 大致会令 fps 减半，VoxelGI 可维持 60 到 80 fps，而 lightmaps 最快：除非场景可被破坏，否则 lightmaps 在「10 次中有 9 次」的情况下都是最佳选择（SeasonalAsh 13:07、17:48）。在 4.7.2 中，Agent 可以自行烘焙：editor job 会直接按下
```
Bake Lightmaps
```
（P7）。如果存在动态几何体或移动的太阳，则使用 SDFGI 或 VoxelGI；静态场景则使用 LightmapGI 加 ReflectionProbes。
在照亮关卡前，先在 lookdev 场景中校准。 Brackeys 使用深色、白色和镜面 guide sphere，并启用 Display > Lighting（Brackeys 7:19、28:53）。Picster 会保留基础几何体，以便之后重新测试（Picster 2:05、1:15:35）。
```
lookdev.gd
```
会构建一个室外场景和一个封闭房间。
根据画面效果选择 tonemapper，然后重新调整曝光。 Brackeys 和 Wild Ox 使用 AgX；SeasonalAsh 和 LegionGames 使用 ACES。实测结果表明：AgX 的 p95 最低，不会裁剪高光，并且能让橙色 emissive 保持橙色，而 Filmic 和 ACES 会将其推向黄色（P5）。AgX 也是成本最高的 tonemapper，这一点在手机上尤其重要（docs）。新建的 Environment 使用 Linear tonemap（P1），因此务必重新设置。
让 emission 在两个层面都清晰可辨。 Glow 会让 emissive 看起来明亮；真正的光源或烘焙 GI 才能照亮场景（Brackeys 13:56、Gamefromscratch 7:09）。4.6 更改了 Glow 默认值（Screen、强度 0.3、2 到 4 个 levels，对应 0.8/0.4/0.1，P15），因此应重新调整 4.6 之前制作的场景。
绝不要同时使用 SDFGI 和 VoxelGI，也不要相信 SDFGI 的第一帧。 SDFGI 大约需要 30 帧才能收敛（P1），启用后的第一帧会更暗（P8）。GDQuest 会在启用后重新调整 tonemap。
Volumetric fog 的质量设置位于 Project Settings，成本也由那里决定。 Four Games 认为 volume size 64 太低，256 是较好的折中方案；god rays 需要约 0.7 的 anisotropy 和更短的长度（Four Games 0:32 到 3:52）。提高一盏主光的 Volumetric Fog Energy，同时将手电筒的值降至 0.1（Brackeys 19:52、LegionGames 2:08）。实测：512 在 1080p 下增加 3.9 ms（P9）。
基础画面效果必须适用于每一种渲染器；分级预设只负责增加增强效果。 Mobile 会忽略 SDFGI、VoxelGI、SSR、SSAO、SSIL 和 volumetric fog；Compatibility 与此相同，但不包括 SSAO。每种渲染器加载时都会输出一行 WARNING（P4）。Fog、glow、tonemap、lightmaps 和 probes 能让效果贯穿所有渲染器 [新增]。自 4.4 起，渲染器回退到 Compatibility 时不会显式提示，并且
```
fallback_to_opengl3
```
默认为 true（docs、P15）：在 PC 上应将其设为 false，让错误驱动明确失败；在 Android 上保留 true 是一种可选方案，因此需要测试 Compatibility 下的画面效果。
CompositorEffect 是 GLSL compute，而不是
.gdshader
（Acerola 9:39）。文档列出了 Forward+ 和 Mobile，但文档示例（将颜色作为 storage image）在 4.7.2 的 Mobile 上会记录 172 个错误，因为 Mobile 的颜色缓冲缺少 storage bit，而 Compatibility 会静默忽略该效果（P12）。应仅在 Forward+ 上发布，并为 Mobile 添加保护。回调运行在渲染线程上：任何与主线程共享的状态都需要使用 mutex 保护；push constants 的填充长度必须是 16 字节的倍数；还要注意升采样会在后处理之后运行（docs）。如果需要在 UI 上方显示后处理，所有平台都可以使用 CanvasLayer ColorRect（Lukky）。

Establish first

首先确定

Input	Default if not given
Target platforms and renderer per platform	Forward+ desktop. Project default `rendering_method.mobile="mobile"` , `.web="gl_compatibility"`
Frame budget and reference GPU	60 fps (16.6 ms) on PC; measure on Vulkan (Metal reports 0 GPU ms)
Static or dynamic world: moving sun, destructible geometry, size	static interior: lightmaps; open day/night: SDFGI; mid-size dynamic: VoxelGI
Mood references and time of day	one image or three words ("cold dawn, foggy, hopeful")
Hero subject and camera(s)	a Camera3D path, else the scene's current camera
Asset source	glTF from blender-expert or scenario-* skills: check UV2 and stray emission

输入	未提供时的默认值
目标平台及各平台使用的渲染器	桌面端使用 Forward+。项目默认设置： `rendering_method.mobile="mobile"` 、 `.web="gl_compatibility"`
帧预算和参考 GPU	PC 上为 60 fps（16.6 ms）；在 Vulkan 上进行测量（Metal 报告的 GPU ms 为 0）
世界是静态还是动态：移动太阳、可破坏几何体、场景规模	静态室内场景使用 lightmaps；开放式昼夜场景使用 SDFGI；中等规模的动态场景使用 VoxelGI
氛围参考和一天中的时间	一张图片或三个词（「寒冷黎明、雾气、充满希望」）
核心主体和相机	Camera3D 路径；如果没有，则使用场景当前相机
素材来源	来自 blender-expert 或 scenario-* skills 的 glTF：检查 UV2 和意外出现的 emission

Workflow

工作流

Load the toolkit:

sys.path

gets

skills/scenario-godot-expert/scripts

and

skills/scenario-godot-rendering-lighting/scripts

, then

import gd_lighting as gl

and

gl.install(P)

. Full code:

references/procedures.md

Renderer. Read project.godot (
```
rendering_method
```
, Jolt, fallback) (P1).
```
gl.capture_renderers(P, scene)
```
captures one view per renderer and returns the WARNING lines. GATE: renderer written in project.godot; parity sheet opened; dropped features listed in the handoff.
Lookdev.
```
gl.build_lookdev(P)
```
(P3), capture the three cameras. GATE:
```
look_checks
```
p95 minus p05 above 0.25, clipped under 5 percent; opened: dark sphere shows form, white not clipped, mirror reflects sky.
GI and bake.
- static:
```
gi_bake.gd:prepare
```
  (sun Dynamic, others Static, hidden lights Disabled, UV2 check), then the windowed
```
gi_bake.gd:lightmap
```
  editor job (P7);
- mid-size dynamic:
```
gi_bake.gd:voxelgi
```
  , windowed (P6);
- open world: SDFGI with occlusion, bounce feedback 0.5 or less, Y scale 75 or 50 percent, max distance below camera far, captured after 40 frames or more (P8).
- Add ReflectionProbes with lightmaps (no specular otherwise). GATE: audit has no GI errors; bake files exist; interior capture opened and checked for leaks, seams and dark patches.
Key, fill and practicals. Lights at their sources, matching color; shadows only on key lights; candles unshadowed, short range; artificial lights below the sun (Brackeys, SeasonalAsh). Run
```
gl.audit(P, scene, ["forward_plus", "mobile"])
```
(P2). GATE: no error flags;
```
squint(img)
```
opened with one focal value;
```
focal_contrast
```
at least 0.05.
Environment and post.
```
gl.sweep
```
one variable at a time: tonemapper (
```
tonemap_variants
```
, P5), exposure, glow, fog, volumetric fog (P10), Adjustments last (cool shadows, warm lights via the color-correction gradient, Picster 45:07). GATE: each sheet opened, winner named with its numbers, no variant clipping over 5 percent unless briefed.
Shadows. Sweep
```
shadow_normal_bias
```
first, then
```
shadow_bias
```
(SeasonalAsh 0.05 against the 0.1 default, frames 4:13); blend splits on; max distance set to the playable range (Picster 400 outdoors, default 100). GATE: grazing-angle close-up opened, no stripes, contact shadow attached.
Tiers and cost.
```
graphics_tiers.gd
```
presets through a sweep with
```
call
```
and
```
measure=60
```
on
```
--rendering-driver vulkan
```
(P11): low and medium use 2 shadow splits, high and ultra 4. Per-effect deltas from the P9 template. On Mobile use MetalFX spatial on Apple, else bilinear (P13). GATE: each tier's GPU ms fits the budget on the target renderer, and the low tier keeps the mood.
Custom post (optional).
```
compositor_tools.gd:attach
```
plus
```
post_effect.gd
```
and a GLSL compute shader (P12). GATE: the effect shows on Forward+; Mobile skips with one warning.

加载工具包：将

skills/scenario-godot-expert/scripts

和

skills/scenario-godot-rendering-lighting/scripts

加入

sys.path

，然后执行

import gd_lighting as gl

和

gl.install(P)

。完整代码见

references/procedures.md

。

渲染器。 读取 project.godot（
```
rendering_method
```
、Jolt、fallback）（P1）。
```
gl.capture_renderers(P, scene)
```
会为每种渲染器捕获一个视图，并返回 WARNING 行。GATE：已在 project.godot 中写明渲染器；已打开一致性对比表；在交接说明中列出被禁用的功能。
Lookdev。 执行
```
gl.build_lookdev(P)
```
（P3），并捕获三个相机的画面。GATE：
```
look_checks
```
的 p95 减 p05 大于 0.25，裁剪比例低于 5%；已打开检查结果：深色球体能够体现形体，白色球体没有裁剪，镜面球体能够反射天空。
GI 与烘焙。
- 静态场景：执行
```
gi_bake.gd:prepare
```
  （将太阳设为 Dynamic，其他光源设为 Static，隐藏光源设为 Disabled，并检查 UV2），然后运行窗口化的
```
gi_bake.gd:lightmap
```
  editor job（P7）；
- 中等规模的动态场景：运行窗口化的
```
gi_bake.gd:voxelgi
```
  （P6）；
- 开放世界：使用带 occlusion 的 SDFGI，bounce feedback 设为 0.5 或更低，Y scale 设为 75% 或 50%，max distance 小于 camera far，并在 40 帧或更多帧之后进行捕获（P8）。
- 将 ReflectionProbes 与 lightmaps 搭配使用，否则场景中不会产生镜面反射。GATE：审计中没有 GI 错误；烘焙文件存在；已打开室内捕获图并检查漏光、接缝和暗斑。
主光、补光与实用光源。 将灯光放在其实际光源位置，并匹配颜色；仅为主光启用 shadows；蜡烛不投射阴影且作用范围较短；人工光源的强度应低于太阳（Brackeys、SeasonalAsh）。运行
```
gl.audit(P, scene, ["forward_plus", "mobile"])
```
（P2）。GATE：没有错误标记；已打开
```
squint(img)
```
并确认只有一个明确的视觉焦点；
```
focal_contrast
```
至少为 0.05。
环境与后处理。 使用
```
gl.sweep
```
，每次只改变一个变量：tonemapper（
```
tonemap_variants
```
，P5）、曝光、glow、fog、volumetric fog（P10），最后再处理 Adjustments（通过 color-correction gradient 让阴影偏冷、灯光偏暖，Picster 45:07）。GATE：每张对比表都已打开；标出最佳方案及其数值；除非另有说明，各变体的裁剪比例均不得超过 5%。
Shadows。 先调整
```
shadow_normal_bias
```
，再调整
```
shadow_bias
```
（SeasonalAsh 将默认值 0.1 改为 0.05，4:13）；启用 split blend；将 max distance 设为可游玩范围（Picster 室外使用 400，默认值为 100）。GATE：已打开掠射角近景；不存在条纹；接触阴影与物体贴合。
质量分级与成本。 通过 sweep 调用
```
graphics_tiers.gd
```
预设，并在
```
--rendering-driver vulkan
```
下设置
```
measure=60
```
（P11）：low 和 medium 使用 2 个 shadow splits，high 和 ultra 使用 4 个。各效果的性能增量来自 P9 模板。在 Mobile 上，Apple 平台使用 MetalFX spatial，其他平台使用 bilinear（P13）。GATE：每个质量等级的 GPU ms 都符合目标渲染器的预算，并且 low 等级仍能保持场景氛围。
自定义后处理（可选）。 使用
```
compositor_tools.gd:attach
```
，并结合
```
post_effect.gd
```
和 GLSL compute shader（P12）。GATE：效果在 Forward+ 上可见；Mobile 跳过该效果并输出一条 warning。

Expert checklist (state these in the plan)

专家检查清单（需要在计划中写明）

Bake scope. A hidden light still bakes: set Bake Mode Disabled (docs). Meshes default to GI mode Static (P15), so exclude non-playable geometry with GI mode Disabled for faster, better bakes (SeasonalAsh 13:39).
Import and repo. glTF
```
meshes/light_baking=2
```
(Static Lightmaps; the default 1 is plain Static) and
```
meshes/lightmap_texel_size
```
(default 0.2; 0.5 or more on huge scenes that crash the bake) (P15, docs). Never gitignore
```
*.unwrap_cache
```
(keeps UV2 stable); keep
```
.lmbake
```
external (docs).
Leaks. Closed, thick walls [added]; LightmapGI Interior plus environment mode Disabled for sealed rooms (docs).
Denoiser.
```
rendering/lightmapping/denoising/denoiser
```
is project-wide: 0 JNLM (default), 1 OIDN (needs the external binary) (docs, P15).
Shadowmask.
```
LightmapGI.shadowmask_mode
```
: None (0, default), Replace (1, realtime near, baked beyond max distance, best for foliage), Overlay (2, fast cameras). Only the first Dynamic DirectionalLight3D; switch without rebake (docs, P15).
Dark indoor bake. Lightmaps ignore Environment ambient: fill lights or bounces first; Spannule's last resort multiplies the EXR and adds ambient at about 8 percent (1JvPYUl1nfo 4:00).
SSAO only darkens ambient light:
```
ssao_light_affect
```
defaults to 0.0 (docs, P15).
Shadows. Cull Mask does not stop shadow casting: turn off the mesh's Cast Shadow. 88 shadowed positional lights fit the default atlas (quadrants 4+4+16+64, P15). A mesh in all 4 PSSM splits draws 5 times. One visible AreaLight3D in Forward+ taxes every object. Compatibility renders shadowed lights in sRGB, so retune energy (docs).
Post. A 3D LUT must be imported as Texture3D (
```
importer="3d_texture"
```
,
```
slices/horizontal
```
); a 256x16 strip with 16 slices loads as 16x16x16 (P15). HDR Clamp Exposure compresses only luminance above about 4096 (a 100000 sun pixel became 14988; 50 stayed 50, P15). Debanding is off by default. Exposure and DOF live in CameraAttributes on the Camera3D, quality knobs in Project Settings.

烘焙范围。 隐藏光源仍会被烘焙：将 Bake Mode 设为 Disabled（docs）。网格默认使用 Static GI mode（P15），因此应将不可游玩几何体的 GI mode 设为 Disabled，以加快烘焙并改善结果（SeasonalAsh 13:39）。
导入与仓库。 glTF 设置
```
meshes/light_baking=2
```
（Static Lightmaps；默认值 1 是普通 Static）以及
```
meshes/lightmap_texel_size
```
（默认 0.2；在超大场景中可设为 0.5 或更高，以避免烘焙崩溃）（P15、docs）。绝不要将
```
*.unwrap_cache
```
加入 gitignore，因为它能保持 UV2 稳定；让
```
.lmbake
```
保持在外部（docs）。
漏光。 使用封闭且厚实的墙体 [新增]；在封闭房间中使用 LightmapGI Interior，并将 environment mode 设为 Disabled（docs）。
降噪器。
```
rendering/lightmapping/denoising/denoiser
```
是项目级设置：0 为 JNLM（默认），1 为 OIDN（需要外部 binary）（docs、P15）。
Shadowmask。
```
LightmapGI.shadowmask_mode
```
：None（0，默认）、Replace（1，max distance 内使用实时光照，范围外使用烘焙结果，最适合植被）、Overlay（2，适合快速移动的相机）。仅第一个 Dynamic DirectionalLight3D 生效；切换时无需重新烘焙（docs、P15）。
室内烘焙过暗。 Lightmaps 会忽略 Environment ambient：应先补光或增加反弹光；Spannule 的最后手段是乘算 EXR，并加入约 8% 的 ambient（1JvPYUl1nfo 4:00）。
SSAO 只会让 ambient light 变暗：
```
ssao_light_affect
```
默认为 0.0（docs、P15）。
Shadows。 Cull Mask 不会阻止阴影投射：应关闭网格的 Cast Shadow。默认图集可容纳 88 盏投射阴影的 positional lights（象限数量为 4+4+16+64，P15）。一个网格同时出现在 4 个 PSSM splits 中时会被绘制 5 次。在 Forward+ 中，一盏可见的 AreaLight3D 会给每个对象增加计算负担。Compatibility 会以 sRGB 渲染带阴影的光源，因此需要重新调整能量（docs）。
Post。 3D LUT 必须作为 Texture3D 导入（
```
importer="3d_texture"
```
、
```
slices/horizontal
```
）；包含 16 个 slices 的 256x16 条带会被加载为 16x16x16（P15）。HDR Clamp Exposure 仅会压缩约 4096 以上的亮度（一个亮度为 100000 的太阳像素变成了 14988，而 50 仍为 50，P15）。Debanding 默认关闭。曝光和 DOF 位于 Camera3D 的 CameraAttributes 中，质量参数位于 Project Settings 中。

Numbers

数值

Value	What it is relative to	Source
`shadow_bias` 0.05	default 0.1	SeasonalAsh frames 4:13; P1
shadow blur 2 to 3	default 1.0	SeasonalAsh 5:13
directional max distance 100	default; Picster 400 outdoors	P1; Picster 54:08
volumetric fog volume size	64 default, 256 good, 512 best; +0.2 to 1.1 (64), +1.5 to 2.7 (256), +3.9 (512) ms at 1080p	Four Games 2:44; P9
fog anisotropy 0.7 for god rays	default 0.2	Four Games 0:32; P1
SDFGI convergence	about 30 frames (enum index 5); capture after 40	P1, P8
SDFGI bounce feedback	default 0.5; above 0.5 risks runaway	P1; Omogonix 28:10
SDFGI max distance	204.8 default, camera far 4000	P15
lights per mesh	Mobile 8 omni + 8 spot; Forward+ 512 clustered elements per view	docs
spot shadow angle	fails above 89°	docs
LightmapGI quality order	supersampling, then texel size, then quality	Brackeys 34:34
LightmapGI Low bake, lookdev room	3.6 to 15 s bake (M5 Max, under load)	P7
effect GPU ms at 1080p, tiny scene	SSIL +1.4 to 1.7, SSR +0.9 to 1.3, SDFGI +0.7 to 1.1; SSAO, glow, TAA, SMAA, MSAA 2x each under 0.8 (under 0.5 is noise)	P9, Vulkan
tier GPU ms (Forward+ / Mobile)	low 1.5 / 0.62, high 2.9 to 4.3 / 1.73, ultra 3.6 to 4.85 / 1.64	P11, tiny scene

Effect costs scale with resolution and scene: re-measure with the P9 template before quoting them.

数值	相对基准或说明	来源
`shadow_bias` 0.05	默认值 0.1	SeasonalAsh 4:13；P1
shadow blur 2 到 3	默认值 1.0	SeasonalAsh 5:13
directional max distance 100	默认值；Picster 室外使用 400	P1；Picster 54:08
volumetric fog volume size	64 为默认值，256 较好，512 最佳；在 1080p 下分别增加 0.2 到 1.1、1.5 到 2.7、3.9 ms	Four Games 2:44；P9
fog anisotropy 0.7，适用于 god rays	默认值 0.2	Four Games 0:32；P1
SDFGI 收敛时间	约 30 帧（enum index 5）；在 40 帧后捕获	P1、P8
SDFGI bounce feedback	默认值 0.5；高于 0.5 存在失控风险	P1；Omogonix 28:10
SDFGI max distance	默认值 204.8，camera far 为 4000	P15
每网格的光源数量	Mobile 支持 8 个 omni 和 8 个 spot；Forward+ 每个视图支持 512 个 clustered elements	docs
spot shadow angle	超过 89° 后会失效	docs
LightmapGI 质量调整顺序	先调整 supersampling，然后是 texel size，最后是 quality	Brackeys 34:34
LightmapGI Low 烘焙，lookdev 房间	烘焙耗时 3.6 到 15 秒（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、2x MSAA 分别低于 0.8（低于 0.5 时属于噪声）	P9、Vulkan
质量等级 GPU ms（Forward+ / Mobile）	low 1.5 / 0.62，high 2.9 到 4.3 / 1.73，ultra 3.6 到 4.85 / 1.64	P11，小场景

效果成本会随分辨率和场景而变化；在引用这些数据前，应使用 P9 模板重新测量。

Quality gates

质量门槛

Measurable:
```
gl.audit
```
zero error flags per target renderer;
```
gd_run.check_all
```
zero parse errors;
```
look_checks
```
clipped under 0.05, crushed under 0.3, p95 minus p05 above 0.25,
```
focal_contrast
```
at least 0.05; bake files exist and
```
lightmap_textures
```
at least 1;
```
.gitignore
```
has no
```
unwrap_cache
```
; each tier's GPU ms within budget on Vulkan.
Visual: open each contact sheet and squint image: one focal area, readable silhouette, warm and cool intent, no leaks, seams, acne or banding, emitters glow, fog does not wash the frame, mobile and low tier keep the mood.
```
references/critique.md
```
is the rubric.

可量化： 每个目标渲染器的
```
gl.audit
```
均无错误标记；
```
gd_run.check_all
```
无解析错误；
```
look_checks
```
的裁剪比例低于 0.05、暗部压死比例低于 0.3、p95 减 p05 大于 0.25，
```
focal_contrast
```
至少为 0.05；烘焙文件存在，且
```
lightmap_textures
```
至少为 1；
```
.gitignore
```
中没有
```
unwrap_cache
```
；每个质量等级的 GPU ms 在 Vulkan 上均符合预算。
视觉： 打开每张 contact sheet，并通过眯眼方式检查图像：只有一个焦点区域，轮廓清晰可辨，冷暖意图明确，不存在漏光、接缝、shadow acne 或 banding，emissive 能够发光，fog 不会冲淡画面，Mobile 和 low 质量等级仍能保持场景氛围。
```
references/critique.md
```
是对应的评审标准。

Common mistakes

常见错误

Mistake	What it looks like	Fix
Leaving Linear tonemap	blown highlights, flat sky	AgX or ACES, then exposure
Lighting in the editor preview sun	game is gray	WorldEnvironment and sun in the scene (SeasonalAsh 1:40)
SDFGI plus VoxelGI	double bounce, cost	one GI per area
Lightmap meshes without UV2	black or garbage bake	`add_uv2` on primitives, Static Lightmaps on glTF
Hidden light still baked	ghost light	Bake Mode Disabled ( `prepare` does it)
Expecting FSR1 on Mobile	identical to bilinear, warning "FSR1 3D scaling is only available when using the Forward+ renderer"	MetalFX spatial on Apple, else bilinear (P13)
docs CompositorEffect on Mobile	170+ errors per run	storage-bit guard ( `post_effect.gd` )
Stray emission on imported glTF	glowing props	audit `emissive_without_glow` , zero it (Gamefromscratch 5:25)
Writing "30" into frames_to_converge	wrong enum index	`gl.setting_index(key, 30)` gives 5
SSAO on, nothing changes	AO invisible in direct light	raise `ssao_light_affect`
LUT as a plain PNG	color correction ignored	reimport as Texture3D with slices

错误	表现	修复方式
保留 Linear tonemap	高光过曝、天空显得扁平	改用 AgX 或 ACES，然后调整曝光
只在编辑器预览的太阳光下测试光照	实际游戏画面呈灰色	在场景中配置 WorldEnvironment 和太阳光（SeasonalAsh 1:40）
同时使用 SDFGI 和 VoxelGI	双重反弹，成本增加	每个区域只使用一种 GI
Lightmap 网格没有 UV2	烘焙结果为黑色或乱码	对基础几何体执行 `add_uv2` ；在 glTF 上使用 Static Lightmaps
隐藏光源仍被烘焙	出现幽灵光源	将 Bake Mode 设为 Disabled（ `prepare` 会完成此操作）
期待 Mobile 使用 FSR1	效果与 bilinear 相同，并出现 warning： `FSR1 3D scaling is only available when using the Forward+ renderer`	Apple 平台使用 MetalFX spatial，其他平台使用 bilinear（P13）
在 Mobile 上使用 docs 中的 CompositorEffect	每次运行出现 170 多个错误	添加 storage-bit 保护（ `post_effect.gd` ）
导入的 glTF 中存在意外 emission	道具发出不需要的辉光	审计 `emissive_without_glow` ，并将其清零（Gamefromscratch 5:25）
将 `30` 写入 `frames_to_converge`	enum index 错误	`gl.setting_index(key, 30)` 会得到 5
开启 SSAO 后画面没有变化	直接光下看不到 AO	提高 `ssao_light_affect`
将 LUT 作为普通 PNG 使用	色彩校正不起作用	使用 slices 重新导入为 Texture3D

Handoffs

交接

Receives from: scenario-godot-3d-world (level, static and dynamic split, cameras); blender-expert and scenario-* skills (glTF with UV2); scenario-godot-shaders (materials); scenario-godot-vfx (emissive effects).
Delivers to: scenario-godot-performance-export (tier table, GPU ms per tier and renderer, settings diff); scenario-godot-ui (graphics settings mapped to
```
graphics_tiers.gd
```
); scenario-godot-shaders (compositor GLSL needs); scenario-godot-expert (sheets, audit JSON, parity notes). Scene and
```
.tres
```
files committed, plus
```
.agent_out/
```
sheets and JSON.

接收来自： scenario-godot-3d-world（关卡、静态与动态划分、相机）；blender-expert 和 scenario-* skills（带 UV2 的 glTF）；scenario-godot-shaders（材质）；scenario-godot-vfx（emissive 效果）。
交付给： scenario-godot-performance-export（质量等级表、各等级和各渲染器的 GPU ms、设置差异）；scenario-godot-ui（映射到
```
graphics_tiers.gd
```
的图形设置）；scenario-godot-shaders（Compositor GLSL 需求）；scenario-godot-expert（对比表、审计 JSON、一致性说明）。需要提交场景和
```
.tres
```
文件，以及
```
.agent_out/
```
中的对比表和 JSON。

Godot 4.7 notes

Godot 4.7 注意事项

Observed in 4.7.2 (

references/expert-notes.md

, Observed):

```
LightmapGI.bake
```
does not exist for scripts; the editor button route works (P7).
```
VoxelGI.bake
```
exists but headless saves empty data.

GeometryInstance3D.lightmap_scale

is gone: use

gi_lightmap_texel_scale

New Environment: Linear tonemap, glow Screen at 0.3, SDFGI bounce feedback 0.5.
FSR1 is Forward+ only; MetalFX spatial works on Mobile with Metal.
GPU timing reads 0 on Metal: profile with
```
--rendering-driver vulkan
```
.
AgX arrived in 4.4. Wild Ox reports 4.6 fixed SDFGI and VoxelGI leaks, glow and SSR, so retest 2023 workarounds such as encapsulating boxes (Wild Ox 2:23).

在 4.7.2 中观察到以下情况（

references/expert-notes.md

，Observed）：

脚本无法使用
```
LightmapGI.bake
```
；通过编辑器按钮执行烘焙可行（P7）。
```
VoxelGI.bake
```
虽然存在，但 headless 会保存空数据。

GeometryInstance3D.lightmap_scale

已被移除：应使用

gi_lightmap_texel_scale

。

新建 Environment 默认使用 Linear tonemap、强度为 0.3 的 Screen glow，以及 0.5 的 SDFGI bounce feedback。
FSR1 仅支持 Forward+；MetalFX spatial 可在使用 Metal 的 Mobile 上运行。
Metal 上的 GPU 计时读数为 0：应使用
```
--rendering-driver vulkan
```
进行分析。
AgX 在 4.4 中加入。Wild Ox 报告称 4.6 修复了 SDFGI 和 VoxelGI 的漏光以及 glow、SSR 问题，因此应重新测试 2023 年采用的临时方案，例如使用封闭盒体（Wild Ox 2:23）。

References

参考资料

```
references/procedures.md
```
: P0 to P15, full code, live test, result line each.
```
references/expert-notes.md
```
: judgment by expert with timestamps, plus Observed 4.7.2 facts.

references/critique.md

: image rubric.

references/gui-paths.md

: editor paths.

references/sources.md

: sources and timestamps.

```
scripts/gd_lighting.py
```
and
```
scripts/agentkit/rendering/
```
: lookdev, light_audit, sweep, gi_bake, graphics_tiers, compositor_tools, compositor/.

```
references/procedures.md
```
：P0 到 P15、完整代码、实时测试及每项测试的结果行。
```
references/expert-notes.md
```
：专家判断及时间戳，以及 Observed 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/。