Untoon Engine

Maintainer-Rules

本页目录

维护者规则

目标

这里写的是维护 untoon 分支时的源码、文档和上游合并规则，是根目录 AGENTS.md 的展开版，从维护者视角讲同一套约束。

适用对象：

  • 引擎维护者
  • 图形程序员
  • AI coding agent
  • 负责 release -> untoon 合并的人

仓库定位

  • 仓库：UntoonEngine
  • 功能分支：untoon
  • 上游基线：release
  • 引擎基础版本：Unreal Engine 5.8.2

untoon 是源码引擎定制分支，不是普通 gameplay 项目，也不是插件式扩展。维护时应优先保证：

  • 与 release 的差异可审计
  • Untoon 渲染路径稳定
  • 上游合并冲突可定位
  • 材质、Shader、Renderer 和文档语义一致

Untoon Marker 规则

除 Untoon 自有目录外，所有 engine、renderer、shader、runtime 源码改动必须包含在明确 marker 中：

// Untoon Engine Start
// ... Untoon changes here ...
// Untoon Engine End

这个规则用于保护上游代码，方便后续合并 release 时快速识别 Untoon 定制。

Marker 例外目录

以下目录是 Untoon 自有实现目录，目录内文件不需要 Untoon Engine Start/End 包裹：

  • Engine/Shaders/Private/Untoon
  • Engine/Source/Runtime/Renderer/Private/Untoon

这些目录已经通过路径表达 Untoon 所有权。除非文件内已有必须延续的局部约定，否则不要在这些目录里额外添加 marker 噪声。

Marker 不嵌套规则

marker 只保留一层。

  • 如果改动位置已经在 Untoon Engine Start/End 块中，直接在现有块内修改。
  • 不要在现有 marker 内再添加新的 marker。
  • 如果需要新增 Untoon 改动，在上游文件中使用最小合理 marker 包住该改动。
  • 如果无法用一个清晰 marker 隔离改动，先暂停并确认设计。

推荐：

// Untoon Engine Start
ApplyUntoonLighting(View, SceneTextures);
// Untoon Engine End

避免：

// Untoon Engine Start
// Untoon Engine Start
ApplyUntoonLighting(View, SceneTextures);
// Untoon Engine End
// Untoon Engine End

文件所有权判断

修改前先判断文件属于哪类：

类型 示例 规则
Untoon 自有目录 Engine/Shaders/Private/Untoon/* 不需要 marker，按本地风格维护
Untoon 自有目录 Engine/Source/Runtime/Renderer/Private/Untoon/* 不需要 marker，按本地风格维护
上游引擎文件 Engine/Shaders/Private/BasePassPixelShader.usf Untoon 改动必须在 marker 内
上游引擎文件 Engine/Source/Runtime/Renderer/Private/DeferredShadingRenderer.cpp Untoon 改动必须在 marker 内
上游引擎文件 Engine/Source/Runtime/Engine/Private/Materials/* Untoon 改动必须在 marker 内

如果一个文件不是 Untoon 自有目录下的文件，就默认按上游引擎文件处理。

高风险区域

以下区域变更需要特别谨慎：

  • Engine/Source/Runtime/Engine/Private/Materials
  • Engine/Source/Runtime/Engine/Private/ShaderCompiler
  • Engine/Source/Runtime/Engine/Private/SceneTexturesConfig.cpp
  • Engine/Source/Runtime/Renderer/Private
  • Engine/Source/Runtime/Renderer/Internal
  • Engine/Source/Runtime/RenderCore
  • Engine/Shaders/Private
  • Engine/Shaders/Private/Untoon
  • Engine/Source/Runtime/Renderer/Private/Untoon

在这些区域不要做推测性清理、批量格式化或无明确目标的重构。

Untoon 架构维护原则

Untoon 当前包含多条互相关联的渲染链路：

  • 原生 MSM_Untoon Shading Model
  • GBufferToon
  • UntoonShadow R/G/B/A 通道语义
  • RenderToonShadowMask
  • Untoon Shadow Blur
  • RenderToonLightPass
  • RenderToonOutlinePass
  • Nanite ToonShadowMask / ToonLight post-light export
  • Toon Light、ToonShadowMask、ToonPassSwitch
  • Light|Toon 参数
  • Scene / Post Process Untoon Diffuse 参数

不要把材质、Shader 或 Renderer 某一处改动当成孤立改动。修改前至少确认它的 engine-side、shader-side 和 renderer-side 消费者。

文档同步规则

如果改动影响 Untoon 行为、架构或维护方式，检查是否需要更新：

  • README.md
  • README.zh-CN.md
  • AGENTS.md
  • Wiki/Home.md
  • Wiki/_Sidebar.md
  • Wiki/Maintainer-Rules.md
  • Wiki/Toon-Rendering-Pipeline.md
  • Wiki/Renderer-Architecture.md
  • Wiki/Material-Authoring-Guide.md
  • Wiki/Lighting-and-Post-Process-Guide.md
  • Wiki/Upstream-Merge-Checklist.md

如果不更新文档，需要在提交或交付说明中解释原因。

验证要求

非平凡源码改动要尽量验证到：

  • 编辑器可启动
  • Shader 编译通过
  • Untoon 材质可编译
  • UntoonShadow.R/G/B/A 语义符合预期
  • Untoon Light Pass 可合成回 SceneColor
  • Untoon Outline 无明显回归
  • Nanite ToonShadowMask / ToonLight export 在相关改动后仍可工作
  • Lumen / Ray Tracing 相关路径无明显编译或运行回归

无法验证的项目必须明确写出。

何时暂停确认

遇到以下情况应先暂停：

  • 改动会影响 GBuffer / GBufferToon 编码且没有明确迁移意图
  • 改动会同时影响普通 mesh 与 Nanite 路径，但目标行为不清晰
  • 改动无法放进一个清晰的 Untoon marker 块
  • 高风险文件中存在未解释的本地冲突
  • 需要重命名 Wiki 页面或材质概念

相关页面