scenario-unity-shaders

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Unity shaders (technical artist, shading)

Unity Shader（技术美术、着色）

Expert shading in Unity 6.3 is a shader you can prove: it compiles for the target graphics API, every pass agrees, its variants are counted after stripping, its first use is shown warm, its cost is measured in GPU milliseconds, and its look is checked in a capture with numbers. An agent without a mouse gets there through text: hand-written URP HLSL is the primary route, Shader Graph is used through existing graphs driven by exposed properties plus agent-owned

.hlsl

behind Custom Function nodes, and new graph wiring is a GUI step (

references/gui-paths.md

). Target: 6000.3.21f1, URP 17.3, Shader Graph 17.3, Metal on Apple Silicon. 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-unity-expert (channels, review loop, 6.3 traps). Its toolkit (

ut_env

ut_run

ut_review

, AgentKit) is imported, never copied.

Status (2026-09-24, after the blind-grade refactor): every procedure ran in Unity 6000.3.21f1 here:

tests/code/unity-shaders/run_all.sh --live

(73 live checks including a development-player PSO proof, 32 offline checks, all passing; evidence in

archive/tests/unity-shaders/

Unity 6.3 中的专家级着色是一项可以证明的 Shader：它能针对目标图形 API 编译，所有 Pass 达成一致，其 Variant 在 Stripping 后完成计数，首次使用时会显示为已预热状态，其成本以 GPU 毫秒衡量，其外观则在带数值指标的截图中接受检查。没有鼠标的 Agent 通过文本抵达这一状态：手写 URP HLSL 是主要路径，Shader Graph 则通过现有 Graph 与暴露的属性驱动，并在 Custom Function 节点后使用由 Agent 负责的

.hlsl

；新增 Graph 连线属于 GUI 步骤（

references/gui-paths.md

）。目标：6000.3.21f1、URP 17.3、Shader Graph 17.3、Apple Silicon 上的 Metal。如果这里提到的某个同级 skill 不在可用 skills 中，请要求用户安装（

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

）；无人值守时，依据 tool schema 继续执行，并标记这一差距。

必需背景： scenario-unity-expert（通道、审查循环、6.3 陷阱）。其 toolkit（

ut_env

、

ut_run

、

ut_review

、AgentKit）为导入项，绝不复制。

状态（2026-09-24，blind-grade 重构后）： 此处的每项流程都已在 Unity 6000.3.21f1 中运行：

tests/code/unity-shaders/run_all.sh --live

（包含开发版 Player 的 PSO 证明在内的 73 项实时检查、32 项离线检查，全部通过；证据位于

archive/tests/unity-shaders/

）。

Stance (the expert delta)

原则（专家级提升）

Text first, graphs by template. Shader Graph has no loops and almost no lighting nodes, so lights and loops live in HLSL (Daniel Ilett, F8bAI6dIrto [00:07:13]); its one advantage is generated depth and shadow passes (bH--RU6qyTw [00:38:24]), which
```
AgentPasses.hlsl
```
gives hand-written shaders too. With graphs, duplicate one, set its exposed references, put changing logic in a File-mode
```
.hlsl
```
. Graph Settings bind every pass: Alpha Clipping without Allow Material Override writes
```
#define _ALPHATEST_ON 1
```
into all 8 generated passes, and no Boolean keyword removes it (installed
```
UniversalTarget.cs
```
, observed).
Every pass must agree. Displacement and
```
clip()
```
run in ShadowCaster, DepthOnly and DepthNormals too (6.3 Manual; Ilett [00:37:52]). A missing DepthOnly pass makes an opaque shader invisible with Depth Priming (observed). DepthNormals writes the raw world normal: the Manual's
```
normal * 0.5 + 0.5
```
example reads back wrong in SSAO and outlines (observed).
Read the installed pipeline, not the tutorial. Copy keywords from the installed
```
Lit.shader
```
(Ilett [00:14:51];
```
ut_shaders.urp_lit_keywords()
```
): 6.3 has
```
_CLUSTER_LIGHT_LOOP
```
and four soft shadow variants.
```
LIGHT_LOOP_BEGIN
```
skips directional lights, so a custom loop needs a directional pre-loop under Forward+; Unity's own Custom Lighting sample lacks it (observed).
Variants are a budget counted after stripping.
```
shader_feature
```
for material toggles,
```
multi_compile
```
only for runtime C# toggles,
```
dynamic_branch
```
tested with
```
if
```
, never
```
#if
```
(6.3 Manual). Strict Shader Variant Matching before stripping, then the funnel in the build log (Carotenuto, Unity blog 2024). A
```
shader_feature
```
(or
```
_local
```
) variant ships only if a material in the build enables it (observed 0 vs 6): never toggle one from runtime C#. Unity 6 Shader Build Settings exclude or retype keywords with zero code, but a
```
dynamic_branch
```
override is silently ignored for
```
#if
```
-tested keywords, URP's soft shadow and SSAO sets included (observed).
First use is proven warm. Trace one
```
GraphicsStateCollection
```
per graphics API and platform in a development player, warm it behind the loading screen, and show gameplay frames with zero
```
Shader.CreateGPUProgram
```
samples and zero logged uploads (6.3 Manual; observed 14 to 0 on Metal).
Cost is GPU time, not instruction count. Loops count at max trip, float4 costs about 4x float, transcendentals cost many cycles (Ben Cloward, E82XxlXMJs4 [00:15:44]). Measured here: 64
```
sin
```
on a float4 about 3x a float, 10x or more a multiply-add loop. Half pays only where a device profiler shows ALU-bound (Freya Holmér, kfM-yu0iQBk [01:20:26]): desktop PlatformDefault compiles
```
half
```
as
```
float
```
.
Render Graph shape.
```
RecordRenderGraph
```
declares, never records; blit once into a new texture then
```
resourceData.cameraColor = destination
```
; gate in
```
AddRenderPasses
```
; refuse the back buffer (6.3 docs; Unity dither sample, U8PygjYAF7A [00:09:06] [00:10:10]).
One scalar field, one threshold, two colors; look and measure. Toon, water, dissolve, outline and dither threshold a 0..1 value (visual digest); the water's depth mask also calms its shore normals (gRq-IdShxpU [00:06:12]). Offset an emissive edge from the clip test (Brackeys, taMp1g1pBeE [00:05:31]). Output intermediates as colors (Freya [01:57:25]), then assert pixels at projected probes.

文本优先，Graph 使用模板。 Shader Graph 没有循环，且几乎没有光照节点，因此光照和循环应放在 HLSL 中（Daniel Ilett，F8bAI6dIrto [00:07:13]）；它唯一的优势是可自动生成深度与阴影 Pass（bH--RU6qyTw [00:38:24]），而
```
AgentPasses.hlsl
```
也为手写 Shader 提供了这些能力。对于 Graph，应复制一个现有 Graph，设置其暴露的引用，并将变化的逻辑放入 File 模式下的
```
.hlsl
```
。Graph Settings 会绑定每个 Pass：未启用 Allow Material Override 时，Alpha Clipping 会将
```
#define _ALPHATEST_ON 1
```
写入全部 8 个生成的 Pass，任何 Boolean Keyword 都无法移除它（检查已安装的
```
UniversalTarget.cs
```
后观察到）。
每个 Pass 都必须一致。 位移和
```
clip()
```
也会在 ShadowCaster、DepthOnly 和 DepthNormals 中执行（6.3 手册；Ilett [00:37:52]）。缺少 DepthOnly Pass 时，启用 Depth Priming 会导致不透明 Shader 不可见（已观察）。DepthNormals 写入原始世界法线：手册中
```
normal * 0.5 + 0.5
```
的示例在 SSAO 和描边中回读错误（已观察）。
读取已安装的 Pipeline，而不是照着教程做。 从已安装的
```
Lit.shader
```
复制 Keyword（Ilett [00:14:51]；
```
ut_shaders.urp_lit_keywords()
```
）：6.3 包含
```
_CLUSTER_LIGHT_LOOP
```
和四种软阴影 Variant。
```
LIGHT_LOOP_BEGIN
```
会跳过方向光，因此在 Forward+ 下，自定义循环需要在方向光预循环中先处理方向光；Unity 自己的 Custom Lighting 示例缺少这一点（已观察）。
Variant 是 Stripping 后才计数的预算。 材质开关使用
```
shader_feature
```
，只有运行时 C# 开关才使用
```
multi_compile
```
；
```
dynamic_branch
```
应使用
```
if
```
进行测试，绝不要使用
```
#if
```
（6.3 手册）。先启用严格 Shader Variant Matching，再查看构建日志中的漏斗（Carotenuto，Unity 博客 2024）。
```
shader_feature
```
（或
```
_local
```
）Variant 只有在构建中某个材质启用它时才会交付（观察值为 0 对 6）：绝不要在运行时 C# 中切换它。Unity 6 Shader Build Settings 可以排除代码引用数为零的 Keyword 或将其重新归类，但对于通过
```
#if
```
测试的 Keyword，
```
dynamic_branch
```
覆盖会被静默忽略，其中包括 URP 的软阴影和 SSAO 集合（已观察）。
首次使用必须证明已预热。 在开发版 Player 中，针对每个图形 API 和平台追踪一个
```
GraphicsStateCollection
```
，在加载界面后进行预热，并展示
```
Shader.CreateGPUProgram
```
采样数和日志上传数均为零的游戏帧（6.3 手册；在 Metal 上从 14 降至 0）。
成本是 GPU 时间，而不是指令数。 循环按最大迭代次数计数，float4 的成本约为 float 的 4 倍，超越函数会消耗许多周期（Ben Cloward，E82XxlXMJs4 [00:15:44]）。此处测得：对 float4 执行 64 次
```
sin
```
的成本约为 float 的 3 倍，是乘加循环的 10 倍或更多。只有当设备 Profiler 显示 ALU-bound 时，
```
half
```
才划算（Freya Holmér，kfM-yu0iQBk [01:20:26]）：桌面端 PlatformDefault 会将
```
half
```
编译为
```
float
```
。
Render Graph 的形态。
```
RecordRenderGraph
```
用于声明，绝不用于录制；先 Blit 一次到一张新纹理，然后设置
```
resourceData.cameraColor = destination
```
；在
```
AddRenderPasses
```
中设门控；拒绝 Back Buffer（6.3 文档；Unity dither 示例，U8PygjYAF7A [00:09:06] [00:10:10]）。
一个标量场、一个阈值、两种颜色；既观察又测量。 卡通、水体、溶解、描边和 Dither 都会对 0..1 的值进行阈值处理（视觉摘要）；水体的深度遮罩还会平缓岸边法线（gRq-IdShxpU [00:06:12]）。将自发光边缘偏移到 Clip Test 之外（Brackeys，taMp1g1pBeE [00:05:31]）。将中间结果输出为颜色（Freya [01:57:25]），随后在投影探针处断言像素值。

Establish first

首先确定

Platforms and graphics APIs: Metal, Vulkan, DX12, GLES 3.x, WebGL 2 or WebGPU. Compute runs on Metal, Vulkan, DX11/12 and GLES 3.1+ (4 buffers guaranteed on GLES 3.1), not on GLES 3.0 or WebGL 2; the Web gets it through WebGPU (experimental in 6.3). The GPU Resident Drawer and STP exclude GLES entirely.
Rendering path per renderer (Forward, Forward+, Deferred+): decides the light-loop code; Shader Graph custom lighting works in Forward and Forward+ only.
URP assets per quality level: Depth and Opaque Texture, soft shadows, SSAO. The template's
```
Mobile_RPAsset
```
has Depth Texture off: depth-faded water needs it on or a baked shore mask.
Style and authors: toon or PBR; artists editing graphs (keep a graph, agent owns the
```
.hlsl
```
) or code only.
Per-object values: material instance,
```
MeshRenderer
```
/
```
SkinnedMeshRenderer.SetShaderUserValue
```
(6.3, SRP Batcher friendly), or
```
MaterialPropertyBlock
```
(breaks the SRP Batcher).
Budgets: GPU ms for the effect, variants per shader, overdraw, first-use hitches. Defaults when silent: URP 17.3 Forward+, PC and mobile tiers from the template, HLSL, shaders under
```
Assets/AgentShaders/
```
.

平台与图形 API：Metal、Vulkan、DX12、GLES 3.x、WebGL 2 或 WebGPU。Compute 可在 Metal、Vulkan、DX11/12 和 GLES 3.1+ 上运行（GLES 3.1 保证提供 4 个 Buffer），在 GLES 3.0 或 WebGL 2 上不可用；Web 通过 WebGPU 使用该能力（6.3 中为实验性）。GPU Resident Drawer 和 STP 完全不支持 GLES。
每个 Renderer 的渲染路径（Forward、Forward+、Deferred+）：决定光照循环代码；Shader Graph Custom Lighting 仅支持 Forward 和 Forward+。
每个质量级别的 URP Asset：Depth 和 Opaque Texture、软阴影、SSAO。模板的
```
Mobile_RPAsset
```
关闭了 Depth Texture：需要深度渐隐的水体必须将其开启，或使用烘焙的岸边遮罩。
风格与作者：卡通还是 PBR；是由美术编辑 Graph（保留 Graph，由 Agent 负责
```
.hlsl
```
），还是仅使用代码。
逐对象数值：材质实例、
```
MeshRenderer
```
/
```
SkinnedMeshRenderer.SetShaderUserValue
```
（6.3，兼容 SRP Batcher），或
```
MaterialPropertyBlock
```
（会破坏 SRP Batcher）。
预算：效果占用的 GPU ms、每个 Shader 的 Variant 数量、Overdraw、首次使用时的卡顿。未明确说明时的默认值：来自模板的 URP 17.3 Forward+、PC 与移动端档位、HLSL、位于
```
Assets/AgentShaders/
```
下的 Shader。

Workflow

工作流

Install and inventory.
```
ut_shaders.install(P)
```
;
```
RendererFeatureJobs.ListFeatures
```
(every quality level, asset, renderer, feature);
```
lint_shader_file
```
,
```
shadergraph_summary
```
(targets, properties, Graph Settings findings),
```
lint_project_keywords
```
. GATE: pipeline facts in the plan; lint errors listed.

Author. Start from

scripts/Shaders/

AgentLit

AgentToon

AgentWater

AgentDissolve

AgentEdgeOutline

AgentGrayscale

AgentCompute

, shared

AgentPasses.hlsl

(

AGENT_CLIP

AGENT_DISPLACE

) and

AgentNoise.hlsl

. Graph route:

ShaderGraphJobs.ImportPackageSample

DuplicateGraph

shadergraph_set_target_settings

GeneratedCode

AgentCustomLighting.hlsl

. GATE: lint zero errors.

Compile for the target.
```
ShaderJobs.ValidateShaders
```
(
```
ShaderUtil.GetShaderMessages
```
plus
```
CompileVariant
```
per pass for Metal). GATE: zero errors, the four opaque passes present.
Bench and look.
```
SetupMaterials
```
,
```
ShaderLab.BuildScene
```
,
```
ShaderLab.Shots
```
(many shots per boot: material, renderer, feature and URP changes; probes projected to pixels). GATE:
```
ut_review
```
flags clean, contact sheet opened, probe numbers (shadow darker than open ground, dissolve shadow gone at 1, extra lights change the lit side).
Full-screen effects.
```
RendererFeatureJobs.AddFeature
```
with
```
AgentFullscreenFeature
```
or the zero-code
```
FullScreenPassRendererFeature
```
. GATE: on/off captures differ as intended; no back-buffer error.
Variants.
```
VariantJobs.StrippingSettings
```
(strict matching on),
```
BuildShaderBundle
```
for the shipping materials,
```
parse_variant_funnel
```
,
```
variant_budget_check
```
, strip rules or
```
KeywordOverrides
```
(Shader Build Settings),
```
PostProcessingAudit
```
(every VolumeProfile under Assets/ keeps its post variants). GATE: shipped count per shader under budget; logger total equals Unity's "After scriptable stripping"; overrides cleared or committed on purpose.

First-use stutter.

PsoJobs.BuildPsoScene

ut_run.build(development=True)

ut_shaders.run_pso_player

trace, cold, warm;

PsoJobs.InspectCollection

; ship

StreamingAssets/PSO/<platform>_<api>.graphicsstate

read by

AgentPsoProbe

. GATE:

pso_gate

clean (cold shows uploads, warm shows none by marker and by log).

Cost.
```
GpuCostJobs.MeasureFullscreenCost
```
A/B, interleaved, async compilation off (
```
precision_model
```
for half tests). GATE: faster in ms beyond noise; device numbers from a development player (scenario-unity-performance).
Deliver. Shaders, materials, feature assets,
```
.graphicsstate
```
per API, and the evidence packet (Handoffs).

安装并盘点。
```
ut_shaders.install(P)
```
；
```
RendererFeatureJobs.ListFeatures
```
（每个质量级别、Asset、Renderer 和 Feature）；
```
lint_shader_file
```
、
```
shadergraph_summary
```
（Target、Property、Graph Settings 检查结果）、
```
lint_project_keywords
```
。GATE：计划中包含 Pipeline 事实；列出 Lint 错误。

创作。 从

scripts/Shaders/

开始：

AgentLit

、

AgentToon

、

AgentWater

、

AgentDissolve

、

AgentEdgeOutline

、

AgentGrayscale

、

AgentCompute

、共享的

AgentPasses.hlsl

（

AGENT_CLIP

AGENT_DISPLACE

）和

AgentNoise.hlsl

。Graph 路径：

ShaderGraphJobs.ImportPackageSample

、

DuplicateGraph

、

shadergraph_set_target_settings

、

GeneratedCode

、

AgentCustomLighting.hlsl

。GATE：Lint 零错误。

针对目标编译。
```
ShaderJobs.ValidateShaders
```
（
```
ShaderUtil.GetShaderMessages
```
，并针对 Metal 按 Pass 执行
```
CompileVariant
```
）。GATE：零错误，存在四个不透明 Pass。
基准测试与外观检查。
```
SetupMaterials
```
、
```
ShaderLab.BuildScene
```
、
```
ShaderLab.Shots
```
（每次启动生成多张截图：材质、Renderer、Feature 和 URP 变更；探针投影到像素）。GATE：
```
ut_review
```
标记为 clean，已打开 Contact Sheet，探针数值满足条件（阴影比开阔地面更暗；溶解值为 1 时阴影消失；额外光照会改变受光面）。
全屏效果。 使用
```
RendererFeatureJobs.AddFeature
```
搭配
```
AgentFullscreenFeature
```
或零代码的
```
FullScreenPassRendererFeature
```
。GATE：开启与关闭的截图按预期存在差异；无 Back Buffer 错误。
Variant。
```
VariantJobs.StrippingSettings
```
（启用严格匹配）、针对正式构建材质的
```
BuildShaderBundle
```
、
```
parse_variant_funnel
```
、
```
variant_budget_check
```
、Strip 规则或 Keyword Overrides（Shader Build Settings）、
```
PostProcessingAudit
```
（Assets/ 下的每个 VolumeProfile 都保留其 Post Variant）。GATE：每个 Shader 的交付数量低于预算；Logger 总数与 Unity 的“After scriptable stripping”一致；覆盖项已清除或有意识地提交。
首次使用卡顿。
```
PsoJobs.BuildPsoScene
```
、
```
ut_run.build(development=True)
```
、
```
ut_shaders.run_pso_player
```
追踪、冷启动与预热后运行、
```
PsoJobs.InspectCollection
```
；交付
```
StreamingAssets/PSO/<platform>_<api>.graphicsstate
```
，由
```
AgentPsoProbe
```
读取。GATE：
```
pso_gate
```
clean（冷启动显示上传，预热后通过 marker 和日志均显示无上传）。
成本。
```
GpuCostJobs.MeasureFullscreenCost
```
A/B、交错执行、关闭异步编译（half 测试使用
```
precision_model
```
）。GATE：排除噪声后，ms 耗时确有改善；设备数值来自开发版 Player（scenario-unity-performance）。
交付。 Shader、材质、Feature Asset、每个 API 对应的
```
.graphicsstate
```
，以及证据包（Handoffs）。

Numbers

数值

Value	Relative to	Source
7,688 full; 4,046 per stage; 62 after settings; 13 shipped	`AgentKit/Lit` in a macOS AssetBundle build with the template's URP assets	observed
13 to 11	AgentLit shipped variants after excluding the soft shadow set in Shader Build Settings	observed
433 to 577	UberPost variants when one unused Bloom HQ + dirt profile sits under Assets/	observed
14 to 0; 1.8 to 2.4 ms	first-use GPU program uploads in gameplay, cold vs warm; warm-up of 26 to 27 PSOs in one frame, macOS player	observed
0.007 to 0.033 / 0.29 to 0.42 / 0.89 to 1.66 ms	one 1080p full-screen draw: 64 multiply-adds / 64 `sin` / 64 float4 `sin` , M5 Max; compare within one run	observed
0.92 to 1.00 / 0.77 to 0.89	half4 over float4 `sin` time, PlatformDefault / Unified precision model, M5 Max (noise about 10 %)	observed
more than 128 keywords, 4 reserved	per shader: compile slows	6.3 Manual
2000 / 2450 / 3000	Geometry / AlphaTest / Transparent queues	Cyanilux
64x1x1, 8x8x1	compute thread groups; ceil-divided dispatch plus bounds check	6.3 Manual, [added]
(1.2, 0.35, 0.03) vs (4, 1.1, 0.15)	HDR dissolve edge that stays orange vs washes to cream under Neutral tonemapping	observed
0.2126, 0.7152, 0.0722	Rec. 709 luminance on linear color	6.3 Manual

数值	相对于	来源
7,688 个完整 Variant；每个阶段 4,046 个；设置后 62 个；交付 13 个	使用模板 URP Asset 构建 macOS AssetBundle 中的 `AgentKit/Lit`	已观察
从 13 个降至 11 个	从 Shader Build Settings 中排除软阴影集合后的 AgentLit 交付 Variant	已观察
从 433 个增至 577 个	Assets/ 下存在一个未使用的 Bloom HQ + dirt Profile 时的 UberPost Variant	已观察
从 14 次降至 0 次；从 1.8 降至 2.4 ms	游戏内首次使用时的 GPU Program 上传，冷启动与预热后对比；macOS Player 在一帧内预热 26 至 27 个 PSO	已观察
0.007 至 0.033 / 0.29 至 0.42 / 0.89 至 1.66 ms	1080p 下一次全屏 Draw：64 次乘加 / 64 次 `sin` / 64 次 float4 `sin` ，M5 Max；在同一次运行内比较	已观察
0.92 至 1.00 / 0.77 至 0.89	half4 相对 float4 `sin` 的耗时，PlatformDefault / Unified 精度模型，M5 Max（噪声约 10%）	已观察
每个 Shader 超过 128 个 Keyword，另有 4 个保留 Keyword	编译速度变慢	6.3 手册
2000 / 2450 / 3000	Geometry / AlphaTest / Transparent 队列	Cyanilux
64x1x1、8x8x1	Compute 线程组；向上取整分派并进行边界检查	6.3 手册，[新增]
(1.2, 0.35, 0.03) 与 (4, 1.1, 0.15)	HDR 溶解边缘在 Neutral Tonemapping 下保持橙色与泛白成奶油色的对比	已观察
0.2126、0.7152、0.0722	线性颜色上的 Rec. 709 亮度	6.3 手册

Quality gates

质量门控

Measurable: lint and
```
lint_project_keywords
```
zero errors;
```
ValidateShaders
```
zero errors for the target API; SRP Batcher compatible (read after a render); probes (shadow luma under 0.75x open ground; dissolve shadow restored at 1; extra lights change the lit side in Forward and Forward+; water normals calmer at the shore than deep); feature on/off difference; shipped variants under budget and stable; no stray VolumeProfile;
```
pso_gate
```
clean per API; GPU ms A/B; compute GPU equals CPU (max error below 1e-5).
Visual: contact sheet opened; toon bands sharp; water hue shift, calm shore, foam, motion; dissolve edge keeps its hue; outline on silhouettes only; no magenta.

可测量： Lint 和
```
lint_project_keywords
```
零错误；
```
ValidateShaders
```
针对目标 API 零错误；兼容 SRP Batcher（渲染后读取）；探针（阴影亮度低于开阔地面的 0.75 倍；溶解值为 1 时阴影恢复；Forward 和 Forward+ 中额外光照会改变受光面；岸边水面法线比深处更平缓）；Feature 开启与关闭存在差异；交付的 Variant 数量低于预算且保持稳定；无游离的 VolumeProfile；每个 API 的
```
pso_gate
```
clean；GPU ms A/B；Compute GPU 结果等于 CPU 结果（最大误差低于 1e-5）。
视觉： 已打开 Contact Sheet；卡通色带锐利；水体有色调偏移、岸边平缓、泡沫和运动；溶解边缘保持色相；描边仅出现在轮廓上；无洋红错误。

Common mistakes

常见错误

Mistake	What it looks like	Fix
no DepthOnly pass	object vanishes with Depth Priming Forced	`AgentDepthOnlyVertex/Fragment`
clip only in the forward pass	dissolved object still casts a full shadow	`AGENT_CLIP` shared by all passes
DepthNormals returns `n * 0.5 + 0.5`	wrong SSAO and outlines	return the raw normal
`LIGHT_LOOP_BEGIN` without a directional pre-loop	a second directional light lights nothing under Forward+	loop `URP_FP_DIRECTIONAL_LIGHTS_COUNT` first
`_FORWARD_PLUS` , `SHADOWS_SCREEN` , `ComputeScreenPos` (deprecated since URP 11)	compile warning, dead shadow branch	`_CLUSTER_LIGHT_LOOP` , `GetMainLight(shadowCoord)` , `GetNormalizedScreenSpaceUV(positionCS)`
`shader_feature_local` toggled from runtime C# (dissolve "on hit")	variant missing in the player: pink or closest match	material swap, or `multi_compile_local` ; `lint_project_keywords`
a Boolean keyword to skip Shader Graph Alpha Clipping	whole object alpha-tested in every pass, all the time	Allow Material Override ( `_ALPHATEST_ON` keyword) or a second opaque material
`dynamic_branch` Type Override on an `#if` -tested keyword	variant count unchanged	test with `if()` , declare without a stage suffix
`if (KW)` on a `_fragment` -suffixed keyword	"a known keyword but not declared in this pass"	declare it for all stages
stray VolumeProfile assets (samples, tests)	post variants for effects no scene uses	move them out of Assets/; `PostProcessingAudit`
one PSO collection for every API, or none proven	first-use hitches on device	per-API trace, cold vs warm runs
Depth Texture off on the URP asset	water turns to solid foam; hidden while SSAO still requests depth	enable on every URP asset that renders it; test with SSAO off
feature missing from one renderer	"the effect does nothing" on one quality level	`ListFeatures` across quality levels
After Rendering injection	nothing drawn, back-buffer error	After Rendering Post Processing
HDR edge color 4 and up	emissive edge washes to cream	1 to 1.5, Bloom carries the glow
judging cost by instruction count, or half on desktop	"optimized" shader no faster	`MeasureFullscreenCost` ; half on the device
properties outside `UnityPerMaterial`	SRP Batcher off, values bleed	one CBUFFER in `HLSLINCLUDE`

错误	表现	修复方式
缺少 DepthOnly Pass	启用 Depth Priming Forced 时对象消失	`AgentDepthOnlyVertex/Fragment`
仅在 Forward Pass 中执行 Clip	已溶解的对象仍投下完整阴影	由所有 Pass 共享 `AGENT_CLIP`
DepthNormals 返回 `n * 0.5 + 0.5`	SSAO 和描边结果错误	返回原始法线
`LIGHT_LOOP_BEGIN` 前没有方向光预循环	Forward+ 下第二盏方向光不产生照明	先循环处理 `URP_FP_DIRECTIONAL_LIGHTS_COUNT`
`_FORWARD_PLUS` 、 `SHADOWS_SCREEN` 、 `ComputeScreenPos` （从 URP 11 起弃用）	编译警告、无效阴影分支	`_CLUSTER_LIGHT_LOOP` 、 `GetMainLight(shadowCoord)` 、 `GetNormalizedScreenSpaceUV(positionCS)`
运行时 C# 切换 `shader_feature_local` （“命中时溶解”）	Player 中缺少该 Variant：变粉或退化为最接近的匹配	切换材质，或使用 `multi_compile_local` ； `lint_project_keywords`
使用 Boolean Keyword 跳过 Shader Graph Alpha Clipping	整个对象始终在每个 Pass 中执行 Alpha Test	Allow Material Override（ `_ALPHATEST_ON` Keyword），或使用第二种不透明材质
对通过 `#if` 测试的 Keyword 使用 `dynamic_branch` Type Override	Variant 数量不变	使用 `if()` 测试，不声明 Stage 后缀
`if (KW)` 用于带 `_fragment` 后缀的 Keyword	“已知 Keyword，但此 Pass 中未声明”	为所有 Stage 声明
游离的 VolumeProfile Asset（Sample、Test）	为场景未使用的效果生成 Post Variant	将其移出 Assets/； `PostProcessingAudit`
所有 API 共用一个 PSO Collection，或未证明任何 Collection	设备首次使用时卡顿	按 API 追踪，对比冷启动与预热后运行
URP Asset 关闭 Depth Texture	水体变成实心泡沫；SSAO 请求深度时对象隐藏	在每个渲染它的 URP Asset 上启用；关闭 SSAO 进行测试
某个 Renderer 缺少 Feature	某个质量级别上“效果毫无作用”	跨质量级别执行 `ListFeatures`
After Rendering 注入	未绘制任何内容，出现 Back Buffer 错误	After Rendering Post Processing
HDR 边缘颜色达到 4 或以上	自发光边缘泛白成奶油色	使用 1 到 1.5，由 Bloom 承担辉光
按指令数判断成本，或在桌面端使用 half	“已优化”的 Shader 反而没有变快	`MeasureFullscreenCost` ；在设备上使用 half
属性位于 `UnityPerMaterial` 之外	SRP Batcher 关闭，数值串扰	在 `HLSLINCLUDE` 中使用一个 CBUFFER

Handoffs

Receives from scenario-unity-rendering-lighting: URP assets per quality level, rendering path, Depth/Opaque Texture, post stack, tonemapping, the Default Volume Profile. From scenario-unity-vfx: particle shader needs (blend mode, soft particles, flipbooks); scenario-unity-vfx owns VFX Graph, the Particle System and effect budgets. From scenario-unity-world-building: water and terrain surfaces. From scenario-unity-architecture: gameplay code that drives materials.
Delivers to scenario-unity-vfx and scenario-unity-world-building: shaders, materials with documented references, feature assets. To scenario-unity-performance: GPU ms tables, variant funnels,
```
.graphicsstate
```
files with the cold/warm proof for device captures. To scenario-unity-pipeline-automation: the variant budget and PSO gates for CI. To scenario-unity-mobile and scenario-unity-web: API limits (compute from GLES 3.1, none on GLES 3.0 or WebGL 2), half precision to profile on device, mobile Depth Texture cost, alpha-test cost on tile GPUs.
Packet: paths,
```
ValidateShaders
```
JSON, contact sheet, probes, funnel, PSO runs, cost table, Verified and Assumed.

接收来自 scenario-unity-rendering-lighting 的：每个质量级别的 URP Asset、渲染路径、Depth/Opaque Texture、后处理栈、Tonemapping、Default Volume Profile。来自 scenario-unity-vfx：粒子 Shader 需求（混合模式、软粒子、Flipbook）；scenario-unity-vfx 负责 VFX Graph、Particle System 和效果预算。来自 scenario-unity-world-building：水面和地形表面。来自 scenario-unity-architecture：驱动材质的游戏逻辑代码。
交付给 scenario-unity-vfx 和 scenario-unity-world-building：Shader、带有已记录引用的材质、Feature Asset。交付给 scenario-unity-performance：GPU ms 表格、Variant 漏斗、
```
.graphicsstate
```
文件及用于设备截图的冷启动与预热证明。交付给 scenario-unity-pipeline-automation：用于 CI 的 Variant 预算和 PSO Gate。交付给 scenario-unity-mobile 和 scenario-unity-web：API 限制（Compute 从 GLES 3.1 起支持，GLES 3.0 或 WebGL 2 不支持）、用于在设备上分析的 half 精度、移动端 Depth Texture 成本、Tile GPU 上的 Alpha Test 成本。
证据包： 路径、
```
ValidateShaders
```
JSON、Contact Sheet、探针、漏斗、PSO 运行记录、成本表、Verified 和 Assumed。

Unity 6.3 notes

Unity 6.3 注意事项

Render Graph only: Compatibility Mode removed (
```
URP_COMPATIBILITY_MODE
```
only to port, gone in 6.4);
```
AddBlitPass
```
returns a builder (
```
returnBuilder: true
```
); After Rendering always follows the final blit (6.2+).

_CLUSTER_LIGHT_LOOP

replaced

_FORWARD_PLUS

(6.1); soft shadows have

_LOW/_MEDIUM/_HIGH

variants; fog is declared

dynamic_branch

in URP's

Fog.hlsl

Shader Build Settings:
```
EditorGraphicsSettings.Get/SetShaderBuildSettings
```
(the active set; a build profile can override).
```
GraphicsStateCollection
```
is experimental; tracing needs a development player; on Metal
```
CreateGraphicsGraphicsPipelineImpl
```
does not exist. Log Shader Compilation prints
```
Uploaded shader variant to the GPU driver: ...
```
.
URP re-adds every override to the Default Volume Profile before a build, so most post-processing variant families always ship.

SetShaderUserValue(uint)

exists on

MeshRenderer

and

SkinnedMeshRenderer

, not

Renderer

; the shader reads

unity_RendererUserValue

Shader Graph 17.3: templates, custom lighting via Unlit plus Keep Lighting Variants; reflected HLSL nodes need 17.5, Preprocessor Directives arrive in 6.6. WebGPU is supported from 6.6; Built-in RP is deprecated from 6.5.

仅支持 Render Graph： Compatibility Mode 已移除（
```
URP_COMPATIBILITY_MODE
```
仅用于移植，6.4 中将彻底消失）；
```
AddBlitPass
```
返回 Builder（
```
returnBuilder: true
```
）；After Rendering 始终在最终 Blit 之后执行（6.2+）。

_CLUSTER_LIGHT_LOOP

在 6.1 中替代

_FORWARD_PLUS

；软阴影有

_LOW/_MEDIUM/_HIGH

Variant；Fog 在 URP 的

Fog.hlsl

中声明为

dynamic_branch

。

Shader Build Settings：
```
EditorGraphicsSettings.Get/SetShaderBuildSettings
```
（当前集合；Build Profile 可以覆盖它）。
```
GraphicsStateCollection
```
处于实验阶段；追踪需要开发版 Player；在 Metal 上不存在
```
CreateGraphicsGraphicsPipelineImpl
```
。Shader Compilation 日志会打印
```
Uploaded shader variant to the GPU driver: ...
```
。
构建前，URP 会将每个覆盖项重新添加到 Default Volume Profile，因此大多数后处理 Variant 家族始终会交付。

SetShaderUserValue(uint)

存在于

MeshRenderer

和

SkinnedMeshRenderer

，不存在于

Renderer

；Shader 读取

unity_RendererUserValue

。

Shader Graph 17.3：模板、通过 Unlit + Keep Lighting Variants 实现 Custom Lighting；反射 HLSL 节点需要 17.5；Preprocessor Directives 将于 6.6 提供。WebGPU 从 6.6 起受支持；Built-in RP 从 6.5 起弃用。

References

参考资料

```
references/procedures.md
```
: P1 to P19, copyable code with live test and result.
```
references/expert-notes.md
```
: principles by expert, observed findings, disagreements.
```
references/critique.md
```
: the rubric before calling work done.
```
references/gui-paths.md
```
: the same procedures in the GUI.
```
references/sources.md
```
: sources, credentials, timestamps, revision history.
```
scripts/ut_shaders.py
```
: install, lints, variant and PSO helpers, Shader Graph reader and editor, pixel probes.

scripts/AgentKit/Shaders/

ShaderJobs

ShaderLab

RendererFeatureJobs

VariantJobs

PsoJobs

ComputeJobs

GpuCostJobs

ShaderGraphJobs

scripts/Runtime/

AgentFullscreenFeature.cs

AgentPsoProbe.cs

(runtime assembly);

scripts/Shaders/

(templates).

```
references/procedures.md
```
：P1 到 P19，以及带有实时测试和结果的可复制代码。
```
references/expert-notes.md
```
：按专家划分的原则、观察结果和分歧。
```
references/critique.md
```
：宣布工作完成前的评估标准。
```
references/gui-paths.md
```
：在 GUI 中执行相同流程。
```
references/sources.md
```
：来源、凭据、时间戳和修订历史。
```
scripts/ut_shaders.py
```
：安装、Lint、Variant 和 PSO 辅助工具、Shader Graph 读取器与编辑器、像素探针。

scripts/AgentKit/Shaders/

：

ShaderJobs

、

ShaderLab

、

RendererFeatureJobs

、

VariantJobs

、

PsoJobs

、

ComputeJobs

、

GpuCostJobs

、

ShaderGraphJobs

。

scripts/Runtime/

：

AgentFullscreenFeature.cs

、

AgentPsoProbe.cs

（Runtime Assembly）；

scripts/Shaders/

（模板）。