为 Unreal Engine 5.8 影视流程建立可核查的资料溯源:解读 scenario-unreal-cinematics 的 sources.md
为 Unreal Engine 5.8 影视流程建立可核查的资料溯源:解读 scenario-unreal-cinematics 的 sources.md
在 Unreal Engine 中做影视化内容时,最昂贵的错误通常来自"记住了一个看似正确的参数"。scenario-unreal-cinematics 这个技能把每一处技术判断都绑定到具体的演讲、文档章节和 URI 上,而 references/sources.md 正是这份证据索引。读完本文,你能看懂这套"来源标注体系"的分层规则(verified、[verify]、[added])、每个两字母或三字母代号在源码中对应的出处,以及如何按同一套方法核验并扩写一份 Unreal 影视管线的技术档案。
一、这份来源清单在技能中的位置:它与正文的关系
SKILL.md 在状态声明中就把来源清单作为可信度的依据:
Status (2026-09-24):
scripts/ue_cine.py和scripts/cine_render_callbacks.py尚未在 Unreal 中运行;离线测试通过(计数见references/sources.md)。在引擎中请先运行tests/code/unreal-cinematics/job_00_probe_cine.py。
也就是说,sources.md 承担三项职责:
- 事实库:演讲、官方文档、版本说明的权威出处与最佳时间戳;
- 可信度台账:哪些专家的身份经过核实(verified),哪些是自述(self-described);
- 修订记录:每一版技能改了什么、离线测试计数是多少、哪些结论仍未被引擎验证。
references/sources.md 开头的定位段落明确了三个层级:蒸馏笔记(distilled notes)在 notes/sequencer/、notes/cinematography/、notes/virtual-production/,摘要(digest)分别是 notes/sequencer/_digest_cinematics_sequencer.md;渲染侧在 notes/rendering/,摘要是 _digest_rendering_mrg_pathtracer_post.md;版本事实在 sources/unreal-version-deltas.md。
这里有一个必须说清的边界:上述 notes/ 与 sources/ 目录属于技能编写阶段的研究工作区,并未随本仓库发布。当前仓库中实际可读的是 SKILL.md、references/ 下五个参考文件(critique.md、expert-notes.md、gui-paths.md、procedures.md、sources.md)以及 scripts/ 下的两个脚本。因此阅读 sources.md 时,应把它当作"结论的引文目录",而不是可直接打开全文的本地资料库;原文位置(YouTube 视频、Epic 开发者社区页面)在文档中以 URL 列给出,本仓库只保留代号、讲者、用途与时间戳。
二、演讲与视频来源:12 条记录与代号语义
下表完整继承自 sources.md 的 Talks and videos 章节,去掉了 URL 列(URL 在源文件中原样保留),保留代号、内容、讲者与凭证、最佳用途和最佳时间戳:
| 代号 | 来源与版本语境 | 讲者与凭证 | 最适合查阅 | 最佳时间戳 |
|---|---|---|---|---|
| SI | "Shoot Your Shot: Cinematic Pipeline Dating Advice",Unreal Fest Orlando 2025(UE 5.6,预览 5.7) | Thomas Kilkenny(Epic 高级技术产品经理,镜头与影视管线)、Jeff Douglas(工具程序员,编写了 CAT),已核实 | 生产默认值、命名词元、文件夹模板、CAT schema 与 assembly、共享子序列陷阱 | 00:15:22, 00:17:30, 00:21:52, 00:24:31, 00:27:13, 00:33:13, 00:35:42, 00:41:34 |
| SPI | "Automate and Expand Sequencer's Functionality with Python",Unreal Fest Orlando 2025 | Daniel Orozco Garcia,Sony Pictures Imageworks 实时管线 TD(KPop Demon Hunters 的 layout 工具),已核实 | 带意图的重定时、切分与拆分、撤销与进度、可移植绑定 ID、通道写入 | 00:05:52, 00:14:04, 00:16:16, 00:19:36, 00:24:19, 00:28:28, 00:33:37 |
| BLUR | "Crafting an Episode for Secret Level with Unreal Engine",Unreal Fest Seattle 2024(UE 5.0–5.3) | Blur Studio 制作团队(创意、UE 技术、绑定、动画、CG 主管),已核实 | 时间采样基线(24/48/64,Frame Close)、插件结构、pass 系统经验、角色开销 | 00:06:35, 00:12:01, 00:31:09, 00:34:25, 00:34:58, 00:39:32, 00:40:05 |
| GLITCH | "Learnings from The Amazing Digital Circus and Murder Drones",Unreal Fest Gold Coast 2024 | Glitch Productions:Mark Humphrey(首席绑定师、TA)、Armen Hawk(灯光与渲染主管),已核实 | 临时光、master/final 灯光分层、镜头 master 结构、QA 轮次、农场、关节预算 | 00:05:33, 00:14:20, 00:27:18, 00:28:51, 00:31:32, 00:32:37, 00:35:24, 00:36:59, 00:40:14 |
| SW-L | "Level Management: Sub-Levels, Spawnables, Possessables in UE5"(UE 5.6,A-COM 示例) | Sir Wade Neistadt(动画师与讲师),Epic 官方频道,已核实 | spawnable 与 possessable 的取舍、空关卡测试、子关卡可见性 | 00:02:23, 00:07:53, 00:10:34, 00:13:50 |
| SW-P | "Unreal Engine 5: Animation Cinematic Production Overview"(UE 5.6) | Sir Wade Neistadt 与 Epic,已核实 | master 即一次剪辑、animatic 序列、重剪前先复制 | 00:02:34, 00:07:32, 00:08:05, 00:10:09 |
| SW-C | "Advanced UE5 Cinematic Workflow: Camera Rigs and Custom Viewports"(UE 5.6) | Sir Wade Neistadt 与 Epic,已核实 | 相机 Control Rig、偏移与抖动图层、双视口 | 00:03:58, 00:05:03, 00:05:17, 00:06:21, 00:08:48 |
| JT | "Why Every Shot in Obsession was Storyboarded (in Unreal 5)" | Josh Toonen,Unreal for VFX 创始人(自述十年好莱坞 VFX 经验,未核实) | 分镜顺序、常量关键帧、用音频锁定时长、真实 filmback 与机位高度 | 00:04:55, 00:09:44, 00:10:29, 00:11:35, 00:13:38, 00:15:04, 00:15:36 |
| WF-C | "The 2026 Unreal Engine to DaVinci Resolve Guide: ACES and sRGB" | William Faucher,VFX 艺术家与 UE 讲师(自述 Epic ambassador,未核实) | 关闭 tone curve、仅在必要时使用 OCIO、Resolve 的 ACES Transform 设置、约一档差异、码率 | 00:01:53, 00:02:27, 00:04:31, 00:08:30, 00:09:05, 00:09:39, 00:10:28, 00:22:54 |
| WF-R | "The 2025 Guide to Rendering in Unreal Engine 5"(旧版 MRQ UI) | William Faucher(注明参考 Comly 的文章) | 不要迷信 cvar、时序与空间的区别、奇数采样、AA None、重影修复 | 00:03:00, 00:04:58, 00:06:01, 00:07:59, 00:09:15, 00:10:58 |
| SC | "How to render layers using the new Unreal Engine Movie Render Graph"(UE 5.4) | Shaun Comly,Epic 员工,已核实 | MRG 模型:Render Layer 节点、last-one-wins、holdout、集合中的 spawnable、暴露变量、子图 | 00:04:00, 00:07:33, 00:10:48, 00:16:01, 00:21:56, 00:26:58, 00:28:03, 00:30:14 |
| VP | "State of Virtual Production",Unreal Fest Chicago 2026(UE 5.8) | Ryan Mayeda(VP 首席技术产品经理)与 Thomas Kilkenny,Epic,已核实 | 5.8 现状:MRG 生产可用、Basic config、Accumulation DOF、Light Modifier、CAT 5.8、Sandboxes、Take Recorder 中的 spawnable | 00:19:07, 00:20:44, 00:22:47, 00:27:25, 00:33:35, 00:34:41, 00:36:19, 00:36:56, 00:38:35, 00:40:44 |
这张表的关键设计不是罗列,而是把"代号 + 时间戳"变成可检索的坐标。技能里所有正文引用都写成 GLITCH [00:28:51]、SI [00:41:34] 这种形式,读者可以一次定位到"400 镜头一集只要 10 到 13 个 master 灯光"或"复制 master 会共享子序列,某人一改灯光就影响七个镜头"的原始表述,无需在数小时视频中盲找。
三、官方文档来源:13 条页面与它们支撑的规则
第二部分是 Articles and official docs 章节,标注为 Epic 开发者社区、页面版本 5.8、检索时间 2026-09-24:
| 代号 | 页面 | 最适合查阅 |
|---|---|---|
| dmrq | "Demystifying Movie Render Queue",Shaun Comly 与 Matt Hoffman(MRQ 开发者),Epic 官方教程,覆盖 4.27 至 5.5 | 采样与噪点的区别、warm-up 内部机制、camera-cut warm-up、不可见的 Game Overrides |
| seq-py | Python Scripting in Sequencer 及 5.8 API 摘要 | 对象模型、子系统调用、可移植绑定 ID、弃用项 |
| shots | Sequences, Shots, and Takes | Shots 轨道规则、层级 bias、takes、time warp |
| bind | Spawnables、轨道重绑定、自定义绑定 | 绑定类型、Replaceable、Resolve to Player Pawn |
| tips | Cinematic Workflow Tips、Event Tracks | 结束帧独占、按原因选择 warm-up、默认轨道、超宽画幅 |
| mrq-cli | Command Line Rendering、MRQ 到 MRG 的迁移、用 MRG 编写渲染、MRG 回调脚本 | 以镜头为渲染单位、命令行模式、变量覆盖、回调 |
| mrg | Movie Render Pipeline、MRG 节点、影视渲染画质设置 | 节点名称、每作业与每层的区别、8 采样以上的 AA 规则、LODZero 植被上限、令牌 |
| cam | Cinematic Cameras、Camera Rig Rail 与 Crane | Cine Camera 设置、spawnable 相机按钮、轨道与摇臂 |
| cons | Animation Constraint Tools | 约束、补偿、烘焙 |
| take | Take Recorder | 录制源、场记板、5.8 的 spawnable 支持 |
| pt | Path Tracer | 路径追踪序列:1 个空间采样,时序采样配合 Reference Motion Blur |
| expo | Exposure、后处理与色彩 | EV100 数学、物理相机曝光(光圈直接驱动曝光) |
| rn54 至 rn58 | UE 5.4 至 5.8 发行说明(摘录位于 sources/docs/versions__ue-5.x-release-notes.md) |
"UE 5.8 notes" 中引用的状态与新增特性 |
注意文档表格的粒度差异:演讲表记录到时间戳,文档表记录到章节主题。这是因为文字页面可被全文检索,而视频只能靠时间锚点。技能正文中的引用形态也不同,例如 SKILL.md 的 "Warm-up is three fixes" 一条 直接写 tips doc; Comly/Hoffman, demystifying MRQ,不附带时间戳。
四、凭证分级:verified 与 self-described 的处理方式
sources.md 用一句话定义了凭证规则:
Credentials marked "verified" were checked against official session descriptions or Epic staff pages by the research agents; others are self-described.
落到实践上,这张表里 12 条有 9 条明确写 verified(SI、SPI、BLUR、GLITCH、SW-L、SW-P、SW-C、SC、VP),JT 与 WF-C 标为 unverified(Josh Toonen 自述十年好莱坞经验,William Faucher 自述 Epic ambassador),WF-R 通过"他引用了 Comly 的文章"间接建立可靠性。
这套分级在正文里有可观察的后果:来自未核实讲者的结论不会被用来定义硬性失败(fail),而更多以 warn 或选项形式存在。例如 references/expert-notes.md 的"分歧与判定条件"表,把 Faucher(奇数采样、Frame Center)与 Blur(24/48/64、Frame Close)放在同一行对立,判定依据写成"Camera Settings 节点里的快门时序",而不是"谁更权威"。同样,Toonen 的分镜方法(常量关键帧、用音频锁长度)被采纳为流程建议,但在代码中体现为 check_music_sync 的 warn 级别与 ready_to_animate 的显式锁标记,而不是自动 fail。
这一设计值得借鉴:把来源可信度映射到检查严重级别,是让"引用"具备工程意义的关键一步。
五、代码如何消费这些代号
sources 并不是装饰性的注释字段。ue_cine.py 中每条 finding 都有统一的五键结构:
def _f(status, check, message, shot=None, source=""):
return {"check": check, "status": status, "message": message,
"shot": shot, "source": source}
见 scripts/ue_cine.py。全文件共出现 31 处 source= 赋值,值就是 sources.md 里的代号加时间戳。举几处可直接对照的例子:
| 代码位置 | finding | source 字符串 | 对应来源 |
|---|---|---|---|
| ue_cine.py#L780 | 制作记录缺失 | SI [00:15:22] [00:21:52] |
生产默认值只设一次并纳入版本控制 |
| ue_cine.py#L783 | 序列帧率与项目记录不符 | SI [00:21:52] |
"没人会因为某个原因单独把一个序列定成 30 fps" |
| ue_cine.py#L873-L877 | 时序未锁定就进入动画 | JT [00:15:04] [00:15:36] |
常量关键帧分镜、先锁时长再做动画 |
| ue_cine.py#L915-L919 | 每个镜头各成一个灯光场景 | GLITCH [00:28:51] |
"70 个不同灯光场景,明显超范围" |
| ue_cine.py#L1021-L1029 | 采样失败:时序与空间混用、奇偶性不符 | dmrq、WF [00:06:01]、BLUR [00:39:32] |
MRQ 揭秘文与两个渲染讲座 |
| ue_cine.py#L1049-L1059 | 交付格式、tone curve、位深 | WF 2Q3CybANHKE [00:01:21] [00:04:31] |
只从 EXR 调色、关闭 tone curve |
| ue_cine.py#L1062 | 开了 camera-cut warm-up 但没有 pre-roll | dmrq WARMUPS |
warm-up 内部机制 |
| ue_cine.py#L1066 | 时序采样大于 1 但区间未延长 | mrg doc (Anti-Aliasing) |
时序采样会评估起始前一帧 |
| ue_cine.py#L1070 | 植被镜头启用 LODZero | mrg doc (Game Overrides) |
三角面上限触发后完全不渲染植被 |
| ue_cine.py#L1193 | 无人值守的本地多镜头队列 | GLITCH [00:40:14]; mrq-cli |
普通 MRQ 需要盯守、崩溃丢队列 |
这种写法的直接收益是:当有人质疑某条检查时,可以顺着 source 字段回到 sources.md 的具体行,再回到讲座的某一分钟,整条证据链闭合。反过来,如果某个 source 里的代号在 sources.md 中不存在,就说明引用断裂——这正是可以自动化的审查点。
六、[added] 段落:把"没有来源的约定"显式标出来
Added knowledge 章节 是整个文件最诚实的一部分。开场即写明:No source; marked [added] in the skill。内容分三类。
1. 摄影与成像的通用实践
- 每种景别对应的镜头与光圈区间、按画幅高度划分的景别类别;
- 弥散圆 = 传感器对角线 / 1500;
- 薄透镜景深公式、30 度规则;
- 180 度的记账法(中性镜头与镜头内越轴会重置左右侧);
- CMX 3600 EDL 的字段布局;
- 用于预览的类 ACES 曲线(Narkowicz 拟合)。
这些在代码里都有一比一的落点,见 ue_cine.py 的常量区:
SHOT_SIZES = {
"EWS": {"focal": (14, 24), "fstop": (5.6, 11), "label": "establishing / extreme wide"},
"WS": {"focal": (18, 35), "fstop": (4, 8), "label": "wide"},
"FS": {"focal": (24, 35), "fstop": (4, 5.6), "label": "full body"},
"MFS": {"focal": (35, 50), "fstop": (2.8, 4), "label": "cowboy / medium full"},
"MS": {"focal": (35, 50), "fstop": (2.8, 4), "label": "medium"},
"MCU": {"focal": (50, 85), "fstop": (2, 2.8), "label": "medium close-up"},
"CU": {"focal": (85, 135), "fstop": (1.4, 2.8), "label": "close-up"},
"ECU": {"focal": (85, 135), "fstop": (1.4, 2.8), "label": "extreme close-up"},
"INSERT": {"focal": (90, 110), "fstop": (2.8, 5.6), "label": "insert (prop, hand)"},
}
注释明确写道,除了 24 mm 建立镜头与"长焦更紧"两点有 Toonen 的演讲依据外,其余区间属于 [added] 通用摄影实践,因此这些检查只产生 warn,永不 fail——镜头是创作选择。
弥散圆的实现也只有一行,见 ue_cine.py#L369-L371:
def coc_for(filmback):
"""Circle of confusion (mm) = sensor diagonal / 1500 [added convention]."""
return math.hypot(filmback["sensor_width"], filmback["sensor_height"]) / 1500.0
配套的 DEFAULT_FILMBACK 同样标了 [added, verify],说明"16:9 Digital Film 及其毫米数"并未被官方文档逐字确认,需要在实际引擎中核对。
2. 工具包自身的约定
这一组条目解释了为什么脚本里会出现一些"看似随意"的硬编码:_LGT 命名后缀、模板变量名、{sequence_name}/{sequence_name}.####.exr 的输出布局、spawnable 相机上以关键帧驱动的镜头轨道、用相机变换打关键帧的临时光而非 attach 轨道、动画偏移换算到 tick 精度、master 灯光留在关卡里(因为按镜头渲染不评估 master 级轨道)。
最后一条尤其重要,它是流程正确性问题而非风格问题:既然渲染单位是单个镜头序列,把灯光放在 master 序列里就会在正式渲染中失效。对应代码见 procedures.md 的 P3 段落。
3. 离线测试发现的实现细节
由离线测试发现(2026-09-24):ffmpeg 8.0.1 把 half 型 EXR 解码为
gbrpf16le;转成gbrpf32le会把数值夹到 0..1,从而掩盖 NaN 与 Inf,所以exr_pixels读取原生平面。
这条记录直接对应 ue_cine.py#L1300-L1301 的像素格式表:
_NATIVE_FMT = {"gbrpf16le": ("<f2", 3), "gbrapf16le": ("<f2", 4),
"gbrpf32le": ("<f4", 3), "gbrapf32le": ("<f4", 4)}
它解释了为什么"检查 EXR 是否含 NaN/Inf"的结论可信:如果走浮点提升路径,越界值会被静默削平,检查永远通过。这类"测试发现"被写进来源文档,是整份文件里工程价值最高的一段。
七、v0.2 增补的七条:从盲评缺口到具体字段
同一章节的末尾 记录了 v0.2 新增的、仍无外部来源的条目,每条都能在代码里找到承载它的字段或函数:
| 增补内容 | 代码落点 |
|---|---|
| 85 mm 作为"长焦"阈值,用于 Use Field of View for LOD 提醒(恰是 CU 镜头区间下界) | LONG_LENS_MM = 85,ue_cine.py#L106 |
| 未标记 master 时,取最长镜头作为灯光 master 候选 | lighting_masters(plan),ue_cine.py#L885 |
lighting.scope 规则:每个镜头各自成一个灯光场景时给出 warn |
check_lighting,ue_cine.py#L908 |
| 动画轨道未绑定的多个网格不会跟随,除非设置 Leader Pose | check_characters 要求 "leader_pose": true |
-notexturestreaming 的理由(所有文档示例都带该参数,但未说明原因) |
mrq_command_line(..., notexturestreaming),ue_cine.py#L1152-L1172 |
cine_render_callbacks.py 的 manifest 文件布局 |
scripts/cine_render_callbacks.py#L36-L43 |
| Level Visibility 轨道用于逐镜头可见性 | procedures.md P3 |
注意 -notexturestreaming 这一条的处理方式:官方每个命令行示例都带这个 flag,但没有任何示例解释原因,于是 sources.md 明确写出"原因是我们补的(reason added)",代码注释同样如此标注,而不是假装它是官方结论。这种"区分文档事实与推断动机"的写法,正是防幻觉的具体手段。
八、修订历史:把测试计数当作发布证据
Revision history 只有两条,但信息密度很高:
- 2026-09-24 v0.1:首版。SKILL.md 2,349 词;离线 165 项检查 + fake-unreal 81 项 + 过程块 32 项。快照位于
skills/_versions/unreal-cinematics v1 2026-09-24/,测试位于_tests_code_unreal-cinematics/。 - 2026-09-24 v0.2:按盲评
tests/grading/U6_grade.md的"两侧都缺失"清单重构。新增内容包括:按渲染模式的 Resolve 解释与视口 OCIO 显示(color_handoff、delivery_note、P11);生产记录只设一次并版本化、CAT 5.8 嵌套 schema 与每镜头一个关卡(check_production、P2);农场管理器、全局执行器、崩溃后恢复(render_orchestration、shots_to_render、P9);possessable 覆盖在镜头结束后回弹、保存与未保存的可见性差异(audit_sequence的bind.override、P3);带审批闸门的 master 打光法(lighting_masters、check_lighting、ready_for_final_lighting、P7b);每个事务配ScopedSlowTask(editor_tool、retime);pre-roll 单独分镜(board_generator(preroll=True));Set Leader Pose 与关节预算(check_characters);常量关键帧分镜、剪切点上的 stingers 与时长锁定(check_music_sync、ready_to_animate、P4/P5);长焦镜头的 Use Field of View for LOD(lens.lod);Execute Script 写文件回调在 Editor Only 模式与 Flush Disk Writes Per Shot(scripts/cine_render_callbacks.py、latest_manifests、check_manifest、P8/P10);慢镜头的stat与 Insights 检查(P7b)。 - 同一条记录还说明了两处表述层面的修正:转述不再伪装成引号;评测用的码率被明确标注为"视频码率";Faucher 的 15 至 31 采样区间与奇数采样并列引用。
- 结果:SKILL.md 2,296 词(四条错误行与三条数值行迁移到
critique.md与procedures.mdP1);离线 208 项纯逻辑检查、98 项 fake-unreal 检查、41 项过程块检查全部通过;一切仍未在 Unreal 中实际运行。
这组数字是理解这个技能成熟度的关键。208 + 98 + 41 说明"Python 逻辑与调用顺序"被充分覆盖;而"仍未在 Unreal 中运行"说明 API 名称、属性是否存在等事实尚未被引擎确认。两者结合,才能准确判断哪些结论可以直接照用、哪些必须先在引擎里探测。
九、[verify] 标记:把未知显式留白
sources.md 本身没有集中列出 <a href="https://link.gitcode.com/i/3616b205c000b822435f3570b7cbf952" target="_blank">verify] 项,但它在整棵技能树里共出现 21 次(ue_cine.py、procedures.md、critique.md、SKILL.md 合计),且 [docs/expert-tools.md 把这条写成了仓库级约定:
代码若尚未在应用中运行,就带上该家族的标记(
[verify],或 "not yet run in")。
具体留白项包括:5.8 中 CAT 菜单标签、SequencerTools toolset 的名称与覆盖面、DefaultEngine.ini 里 CAT 写入的键名、EditorAssetLibrary.make_directory 的返回值、动画起始偏移对应的属性名、WarmUpSettings 节点上是否存在 UseCameraCutWarmUp、Level Visibility 轨道的类名、MRG 的 H.264 节点是否仅限 Windows、OpenColorIO 2.5.1 搭配 ACES 2.0 时的视图名,以及 Deadline for Unreal 对 5.8 的支持。
与之配套的是"先探测再构建"的第一步。见 procedures.md 的 P0:
import json
import unreal
import ue_cine as C
rep = C.probe()
missing = [n for n, ok in rep["classes"].items() if not ok]
missing += ["subsystem." + n for n, ok in rep["subsystem"].items() if not ok]
print(json.dumps({"missing": missing, "graph_classes": rep["graph_classes"][:20],
"accumulation_dof": rep["accumulation_dof"], "cat": rep["cat"]}, indent=1))
思路很清楚:既然 API 名称未确认,就先让引擎自己报告哪些类与子系统不存在,再据此修正,而不是在 try/except 里静默失败。P0 的理由段写得很直白:"错误的名称要么在 try 里静默失败,要么在构建中途大声失败。"
十、把来源代号接进审阅链:三份参考文件的分工
sources.md 不是孤立的附录,它被另外三份文件从不同方向引用:
- expert-notes.md:按专家分组,每条判断附时间戳;末尾的"分歧与判定条件"表把互相冲突的建议并列,并给出裁决依据(快门时序、是否有后续调色、是否是植被镜头等)。这是"证据 → 判断"层。
- critique.md:把判断转成 8 个阶段的自评量规,每条都标注了由哪个代码检查测量,以及"数字回答不了的视觉问题"。这是"判断 → 检查"层。
- procedures.md:P0 至 P11 的可执行代码块,每块标注
# test: <id>与运行状态(python3 / 仅编译 / 尚未在 Unreal 中运行)。这是"检查 → 执行"层。
例如"渲染设置审计"一节在 critique.md 列出了 9 条规则及其 checking id(samples.mixed、samples.parity、aa.method、output.format、output.depth、color.tone_curve、warmup.cut、warmup.section、overrides.lod0、cvars.reason、pt.samples、pt.refmb),每条的 source 都能回溯到 sources.md 中的 mrg doc、dmrq、WF、path tracer doc。这就是完整的可追溯闭环。
十一、复用这套方法:一份来源清单的最小实践
若要把这种写法迁移到自己的 Unreal 影视项目文档,可以按下面的顺序落地(不需要修改本仓库任何文件,只需在你自己的项目里新建文档):
- 建立代号表:给每个一手来源分配 2 至 4 个字母的短码(
SI、GLITCH、dmrq),在正文中只写代号 + 时间戳或章节名。 - 区分三种断言:有明确出处的写代号;有出处但版本未核实的加
[verify];完全来自通用实践或团队约定的标[added]并写明"无来源"。 - 把可信度映射到严重级别:已核实的团队实践可设为 fail,自述经验与通用摄影规则设为 warn,并强制 warn 必须在计划里被"回答",而不是被忽略。
- 让检查携带
source字段:仿照{"check", "status", "shot", "message", "source"}五键结构,使任何一条报错都能反查到出处。 - 记录测试计数与运行状态:像 sources.md 那样写清"离线 208 项通过、未在引擎中运行",并把每次修订说明写具体到函数名与阶段编号。
- 先探测后构建:首次在真实引擎中运行时,先跑一个 probe 脚本列出缺失的类、子系统与图节点,再执行构建流程。
十二、使用这份文档时容易踩的三个坑
- 把
notes/、sources/当作仓库内路径:它们属于编写工作区,不在本仓库中。仓库内可读的是references/sources.md本身以及expert-notes.md、critique.md、procedures.md、gui-paths.md。 - 把"离线通过"当成"引擎可用":208 + 98 + 41 项检查证明的是逻辑与调用顺序,fake
unreal模块无法证明 API 名称。文档在 SKILL.md、procedures.md开头、两个脚本的 docstring 中反复强调这一点。 - 把
[added]的数值当成官方默认值:例如 16:9 Digital Film 的 23.76 × 13.365 mm、景别与光圈区间、24 至 48 帧 pre-roll,都属于工具包约定或通用实践,需要按你的项目与镜头实拍校准。
当一份技术文档能让你随时回答"这条结论从哪来、有多可靠、在哪一层被检查、是否已在引擎中验证"这四个问题时,它才真正具备被 Agent 与人类协作者共同信任的基础。sources.md 提供的正是这样一个可复制的模板:短码索引、时间戳锚点、凭证分级、[added] 留白与修订计数,五者合一,构成 Unreal 影视管线文档的证据底座。