Unreal Engine 5.8 影视化制作实战:用 skills 的 scenario-unreal-cinematics 打通 Sequencer 与 Movie Render Graph

原创2026-11-06 18:19:261,669 阅读
文章标签:AI 技能人工智能媒体生成多模态3D建模3D渲染游戏开发

Unreal Engine 5.8 影视化制作实战:用 skills 的 scenario-unreal-cinematics 打通 Sequencer 与 Movie Render Graph

这篇指南以 skills 仓库中的 scenario-unreal-cinematics 技能为主体,讲清楚一件事:如何在 Unreal Engine 5.8 里把预告片、过场动画、电影化片段当成一套可以校验的工程来做——先把剪辑写成数据并在离线阶段查错,再用一个事务把 Sequencer 层级建出来,锁定节奏后才做表演与灯光,最后逐镜头渲染线性 EXR 并连色彩解读说明一起交给剪辑与调色。读完你会掌握 shot plan 的字段与校验规则、九步流水线各自的通过条件、模板渲染图的节点配置、命令行渲染与崩溃续渲,以及“渲染比视口暗一档”这类经典问题的根因与处理方式。

一、专家立场:剪辑是数据,渲染是文件

技能的立场(Stance)不是玄学,而是一组可落地的工程约束,本节把原文的八条加以展开。

母序列是剪辑,镜头拥有内容。 相机、角色、关键帧都活在镜头(Shot)里;灯光、特效这类分工再做成镜头内部的分工子序列(subsequence)。这样重新排节奏时移动的是“段落”,而不是动画本身。原文引用了 Sir Wade 与 Glitch 的做法:逐镜头的东西做成 spawnable,场景布景做成 possessable,于是同一段 cinematic 可以在任意关卡里播放;但一个以 possessable 身份被 K 帧的布景,在该镜头结束后会弹回原状。另有一个容易踩的坑:大纲视图(Outliner)里的眼睛图标不保存可见性,Levels 面板里的子关卡可见性才会保存。

结构靠模板与脚本,不靠手点。 显示帧率、起始帧、层级偏置(hierarchical bias)、命名规则、文件夹模板,一次性写进受版本控制的 Config/DefaultEngine.ini。原文强调"没有人会为某一条序列单独决定这是一部 30 fps 的片子"。5.8 的 CAT(Cinematic Assembly Tools)允许 schema 嵌套,并能给每个镜头分配自己的关卡。所有工具都包在一个 ScopedEditorTransaction 加 ScopedSlowTask 里,因为"长时间运行的 Python 代码看起来和卡死的引擎一模一样"——用户误以为崩溃而强行结束进程,资产就写坏了。

先锁节奏再动画。 用恒定关键帧(constant keys)做分镜板,音乐单独一条轨,重音(stinger)精确落在切点上。"不要花时间去做永远进不了成片的帧"。改时长必须携带意图:关键帧跟着镜头走,跨镜头的子序列要切开,并且两半各自成为独立资产,否则改动会互相泄漏。

预热是三件事,结束帧是排他的。 空闲 CPU 模拟用 Engine Warm Up Count(大于 30 帧);时间历史用 Render Warm Up;第一帧就在运动的东西(布料、毛发、粒子)需要把动画与相机切(camera cut)向前延伸,用 camera-cut warm-up 去评估前置区间,而不是死盯第一帧。另一个高频困惑:0 到 50 的范围只渲染 0 到 49。

采样只买运动模糊和抗锯齿。 噪点要回到源头解决(灯光或后处理设置),加采样只会让渲染变慢。时间采样只做时间方向:Frame Center 用奇数,或 Blur 的 Frame Close 用 24/48/64;总采样超过 8 时抗锯齿设 None;默认零控制台变量,只有某个具名镜头出了问题才加,并且写明理由。

在线性 EXR 之外调色,并且写清怎么读。 关掉 tone curve 得到线性 sRGB,大约比视口暗一档,因为 UE 的 tone curve 是"ACES 风味,但不是真正的 ACES"。Resolve 里用 ACES Transform 作为第一个节点:tone curve 开则 sRGB (Linear) → sRGB Texture;关则 Linear sRGB → sRGB;只有对方明确要求 ACEScg 时才走 ACEScg → sRGB。灯光与评审都通过视口 OCIO Display 调到与调色一致的视图。

镜头是渲染单位。 官方命令行文档的原话是"Unreal Engine 里可分发的最小工作单元是单个相机切"。所以一个镜头一个 job、一个模板图、每 job 用变量覆盖,永远不要为单个镜头去改共享图。裸 MRQ 需要人盯着,崩一次就丢掉整段队列。

灯光按流程缩放。 第一天就有临时相机灯;然后每个灯光场景只做一到两个签名镜头并由导演确认;最后从这些母镜头派生出逐镜头的 _LGT 子序列,按与母镜头的距离分级投入时间。

二、动手前必须先确定的输入

原文的"Establish first"表是整套流程的输入契约,缺失时技能采用默认值,这些默认值会直接写进 plan:

输入 影响什么 未指定时的默认
交付方式:已调色或直出 tone curve、格式、OCIO、色彩说明 已调色:EXR 16-bit half、tone curve 关
制作记录(帧率、起始帧、偏置、命名) 每条序列、EDL 项目的 DefaultEngine.ini;否则 24 fps、起始 0
时长、镜头数、音乐 布局、重音 简报;分镜前先放一条临时音轨
画幅与片门(filmback) 镜头、构图 16:9 Digital Film;宽银幕用 2.39 裁切
关卡与已有内容 绑定关系 布景 possessable;相机、角色、镜头灯 spawnable;母灯光在关卡里
演员表 预卷、成本 现有动画序列;每个角色的关节与网格
每镜头运动、快门时序 采样、预卷 Frame Center、奇数采样
曝光 连续性 手动、物理相机、用 ISO 补偿光圈变化
执行通道 建库、分镜、渲染 分镜走实时编辑器(MCP、PythonRemote);终渲走 ue_run 或命令行

其中"执行通道"来自前置技能 scenario-unreal-expert:编辑器内代码通过 Epic 的 MCP 服务器(Python 工具)、ue_remote.PythonRemote().exec(...),或作为 job 文件交给 ue_run.run_python(...);凡是会 yield 的代码块(分镜、渲染)必须用 mode="latent"。需要参考它的通道、评审循环与 5.8 陷阱,见 scenario-unreal-expert/SKILL.md。

三、九步流水线与各自的闸门

工作流的入口是 import ue_cine as C(把本技能与前置技能的 scripts/ 都放进路径)。完整可运行代码在 references/procedures.md 的 P0–P11。

第 1 步:生产脚手架(每个项目一次)

把生产默认值记录一次(CAT Production Setup 或项目设置),复制进 plan["production"];建立文件夹模板,镜头号以 10 为步长;若启用 CAT 5.8,让 shot schema 内嵌 _LGT schema,在镜头需要独立布景状态时做到"一镜一关卡"。

闸门: C.check_production(plan) 无 fail;C.audit_sequence 的 seq.rate、seq.start 通过。

这一条为什么是硬闸门?因为 check_production 会把计划里的 fps、start_frame、bias、shot_name 正则与项目记录逐项比对,不一致直接 fail——production.rate 和 production.start 是 fail 级,命名只是 warn(CAT 的命名只是建议,最终要靠 plan 强制)。偏置只接受 bottom_up(默认,子级胜出)与 top_down(父级跨多镜头覆盖)两种,其余值 fail。

第 2 步:把剪辑规划成数据(agent 侧 python3)

镜头的时长、景别、镜头焦距、机位与主体位置、运动、标志位、演员(关节、网格)、重音、灯光场景,全部写进一个 JSON。然后跑:

import ue_cine as C

plan = C.load_plan(PLAN_PATH)          # 或 C.default_trailer_plan() 再改
findings = C.check_plan(plan)
for f in findings:
    if f["status"] in ("fail", "warn"):
        print(f["status"], f["check"], f["shot"], f["message"], f["source"])
print(C.summarize(findings))
assert C.summarize(findings)["fail"] == 0, "先修计划再建库"

rows = C.layout(plan)                  # 母序列区间、局部区间、排他结束、预卷
print([(r["name"], r["master_start"], r["master_end"], r["cut_start"]) for r in rows])

闸门: 没有 fail;每条 warn 要么修掉,要么在 plan 里写明答复。答复本身就是计划的一部分,例如 "crosses_line": "chase flips on purpose"、只在以景深为核心的镜头上写 "accumulation_dof": true、有布料/毛发/粒子的运动镜头写 "preroll": 24、光圈变化时在物理曝光下写 "exposure": {"hold": "iso"}。

第 3 步:在一个事务里建库(编辑器内)

rep = C.build_from_plan(plan)          # 有 fail 会拒绝执行;绝不覆盖已有资产
assert not rep.get("refused"), rep["findings"]
master = unreal.load_asset(rep["master"])
world = unreal.get_editor_subsystem(unreal.UnrealEditorSubsystem).get_editor_world()
audit = C.audit_sequence(master, plan, world)
print(audit["summary"])

build_from_plan 的实现(ue_cine.py)是一个 ScopedEditorTransaction 套一个 ScopedSlowTask,逐镜头做这几件事:

  • 建一个 spawnable 的 Cine Camera,在模板上设置片门、裁切、镜头、手动对焦,并把 Current Focal Length、Current Aperture、Manual Focus Distance 三条轨道 K 帧——镜头自己拥有它的镜头参数;
  • 用 look_at 计算首末帧朝向并打变换关键帧;
  • 建相机切,从 cut_start(含预卷)到排他结束;
  • 建 spawnable 表演者,动画段起点早于镜头开始(预卷,至少提前一帧,因为时间采样会评估开始之前);
  • 建 <prefix>_<shot>_LGT 子序列,并放入临时相机灯;
  • 母序列上只放 Shots 轨与音乐轨。母灯光留在关卡里(子关卡或 data layer),因为逐镜头渲染不会评估母序列级别的轨道。

闸门: audit_sequence 无 fail、bind.override 有答复;empty_level_test 只列出布景。

audit_sequence 检查的是结构而非观感:seq.rate(fail)、seq.start(warn)、edit.contiguous(重叠 fail,间隙 warn)、edit.length(镜头播放长度必须等于其段落长度,否则提示 Auto Size 或重设时长)、cam.cut 与 warmup.preroll、cam.spawnable、bind.unresolved(fail)、seq.bias(默认 100,偏离则 warn)。

第 4 步:分镜并把剪辑锁死(latent 编辑器 + python3)

result = {}
C.run_on_ticker(C.board_generator(master, plan, board_dir, width=1280, height=536, preroll=True),
                on_done=lambda r: result.setdefault("board", r))
# 实时编辑器里立即返回,后续帧填充 result;ue_run latent job 里用 yield from

preroll=True 会额外输出每个有预卷的镜头的"第一预卷帧",并且是单独读取该镜头得到的——在母序列里看负时间看到的是上一个镜头(GUI 对应 Evaluate Sub Sequences In Isolation)。

分镜规则很具体:一镜一个姿态、一个相机;关键帧设为恒定(GUI 按 5,脚本 interp="constant"),让分镜在首、中、末姿态之间跳变而不是滑动;音乐与音效各占一条音频轨;重音落在切点上(check_music_sync 以帧为单位给出偏移);在动画面之前先重定时。

闸门: 没有全白或全黑帧;对照音乐看过分镜表与剪辑;C.ready_to_animate(plan) 通过。这个 Gate 拒绝两类情况:plan 里没有音频("没有视频加音频,你其实还没有电影的第一稿"),以及 timing_locked 未置为 true。

第 5 步:表演与相机打磨

推焦用两条 Manual Focus Distance 关键帧,而不是会跳的追踪目标:

shot_seq = unreal.load_asset(C.shot_asset_path(plan, "sh020"))
cam = [b for b in shot_seq.get_spawnables()
       if isinstance(b.get_object_template(), unreal.CineCameraActor)][0]
comp = [b for b in shot_seq.get_possessables() if b.get_parent() == cam][0]
track = [t for t in comp.get_tracks() if t.get_property_name() == "ManualFocusDistance"][0]
ch = track.get_sections()[0].get_all_channels()[0]
C.key(ch, row["local_start"] + 24, 180.0, "auto")
C.key(ch, row["local_start"] + 48, 700.0, "auto")

相机运动分三层:基础运动(两条变换关键帧,或 Camera Rig Rail / Crane 上 K 轨道位置)、构图偏移(把相机挂到偏移 Actor 上只 K 偏移,或用 Control Rig 的偏移控制)、抖动(独立权重层,动作最强、慢镜头接近零)。这样重新构图不会毁掉密集的基础运动曲线。

闸门: 重新出分镜;关键帧上的对焦距离等于主体距离;段落边界不跳变。

第 6 步:灯光(与 scenario-unreal-lighting-rendering 协作)

流程是"临时灯 → 母镜头 → 逐镜头":

masters = C.lighting_masters(plan)     # 每个场景一个母镜头;没标记就取最长的
approval = C.render_jobs(plan, graph=plan["render"]["review_graph"],
                         only=[m["master"] for m in masters],
                         sequences=C.active_shot_paths(master, plan))
plan["lighting_approved"] = [m["master"] for m in masters]   # 只在导演点头之后
assert C.summarize(C.ready_for_final_lighting(plan))["fail"] == 0

闸门: ready_for_final_lighting 通过(每个场景的母镜头都已批准);亮度连续性与母镜头比对通过;如果某镜头慢,用 stat unit 或 Insights trace 定位。参照 Glitch 的预算:400 镜头一集用 10 到 13 个母镜头,每个 1 到 2 天;如果"每个镜头都是自己的灯光场景",check_lighting 会给出 lighting.scope 警告——没有母镜头就无法锁定创作决策。

第 7 步:草稿渲染与评审

用评审图(或 5.8 的 Basic 配置)配音乐出一条 MP4,然后用 C.check_render_output、C.first_frame_pop、C.cut_flash 检查,再带声音完整看一遍。

第 8 步:最终 EXR

graph = unreal.load_asset(plan["render"]["graph"])
snap = C.graph_snapshot(graph)                 # 从 Output 节点开始只读遍历
settings = C.normalize_graph_snapshot(snap)
settings.update(delivery=plan["render"]["delivery"], preroll_frames=24, camera_cut_warmup=True)
for f in C.audit_render_settings(settings):
    print(f["status"], f["check"], f["message"])
print("暴露变量:", snap["variables"])

normalize_graph_snapshot 是按属性名做的启发式映射(代码里明确标注了需要对 5.8 逐个核对名称),把图节点类名与编辑器属性翻译成 audit_render_settings 认识的设置字典。这也是为什么探测(P0)必须先跑。

闸门: 设置审计通过;check_manifest、exr_checks 在抽样帧上通过;崩溃后只重渲 C.shots_to_render(...) 给出的整镜头。

第 9 步:交付

EXR(每镜头一目录)、C.edl(plan)、评审 MP4、C.delivery_note(plan, settings)、JSON 报告。意见分为技术与创作两类,创作意见最多三轮,之后开一次引擎内的现场会。每次修改都进新的版本目录(render_v002),绝不覆盖。

四、plan 是唯一事实来源:结构、字段与校验

工具的 docstring 把 plan 定义得很清楚:它是 JSON,单位是厘米、Z 轴向上、X 轴向前(与 Unreal 一致),包含镜头、景别、镜头焦距、机位与主体位置、标志位(cloth、particles、hair、dof_centric……)。一切在构建前离线检查,然后一个事务建完。

一个可用的最小骨架(取自 default_trailer_plan(),30 秒 7 镜头示例):

{
  "name": "TRL", "fps": 24, "target_frames": 720, "start_frame": 0,
  "production": {"fps": 24, "start_frame": 0, "bias": "bottom_up",
                 "shot_name": r"^sh\d{2}0$"},
  "shot_count": [6, 8], "root": "/Game/Cinematics/Trailer",
  "map": "/Game/Maps/L_Trailer",
  "filmback": {"name": "16:9 Digital Film", "sensor_width": 23.76,
               "sensor_height": 13.365, "crop": 2.39},
  "exposure": {"physical": True, "iso": 100, "shutter": 1/48, "hold": "iso"},
  "subjects": {"hero": {"position": [0, 0, 0], "height": 180, "eye_height": 160}},
  "scenes": [{"name": "duel", "line": ["hero", "rival"]}],
  "audio": [{"sound": "/Game/Audio/MUS_Trailer", "start": 0,
             "stingers": [120, 288, 456, {"frame": 660, "on_cut": False}]}],
  "render": {"delivery": "graded", "shutter_timing": "frame_center",
             "resolution": [3840, 1608],
             "graph": "/Game/Cinematics/Trailer/Render/MRG_TRL_EXR",
             "review_graph": "/Game/Cinematics/Trailer/Render/MRG_TRL_Review"},
  "shots": [ ... ]
}

v0.2 新增的字段每一条都对应 check_plan 里的一个检查:

字段 触发的检查 用途
production: {fps, start_frame, bias, shot_name} check_production 与项目记录不一致即 fail
主体 joints、skeletal_meshes、leader_pose check_characters 关节数低于 200;多网格角色需要 Set Leader Pose Component
音频 stingers: [母序列帧] 或 {"frame", "on_cut": false} check_music_sync 重音必须在切点上
镜头 lighting 与 lighting_master check_lighting、lighting_masters 每个灯光场景先亮一个签名镜头
timing_locked、lighting_approved ready_to_animate、ready_for_final_lighting 只在评审/批准之后由 agent 置位

各检查的判据(均可从源码读到,见 ue_cine.py):

  • 时长:总帧数必须等于 target_frames(fail);镜头数必须落在 shot_count 区间(fail);单镜头短于 0.5 秒或长于 8 秒给 warn;镜头号不是 10 的倍数只记 info。
  • 焦距:与景别常用区间不符给 warn(例如 CU 常用 85–135 mm,ECU 同段,INSERT 90–110 mm,EWS 14–24 mm),光圈偏离只记 info——镜头是创作选择。焦距 ≥ 85 mm 会补一条 lens.lod 提示:打开相机的 Use Field of View for LOD。
  • 构图:用 framed_height_m(焦距, 主体距离, 片门) 反推画面高度,再 classify_size 判定实际读感;与标注景别相差一级记 info,相差两级以上 warn。片门可见高度会按 2.39 之类的裁切收窄。
  • 180 度:按场景的 A-B 线逐镜头计算 A、B 在画面上的左右关系;切过去若换边就是 fail,除非该镜头写了 crosses_line 理由(降为 warn);机位落在轴线上(10% 死区)视为中性镜头,可由下一镜重新建立。
  • 屏幕方向:同一主体跨镜头的运动方向翻转会被 warn,除非声明。
  • 跳切:连续同景别、同目标且机位方向变化小于 30 度,warn。
  • 景深:光圈小于 f/5.6 却没有对焦计划是 fail("绝不使用默认距离");用薄透镜公式算出景深后,CU/ECU/MCU 景深小于 4 cm 会提醒"只有一只眼睛能实";把 Accumulation DOF 用在非景深镜头上 warn(成本随采样线性增长)。
  • 预卷:有布料/毛发/粒子等模拟标志且在运动,预卷小于 24 帧是 fail;纯静止则提示 Engine Warm Up Count > 30 就够;含粒子再补一条 Render Warm Up 提示。
  • 曝光:在物理相机曝光下,同场景内光圈变化导致 EV100 偏移超过 1/3 档时,给出应当使用的 ISO(iso_to_hold),或者提示关闭相机的曝光模拟。
  • 演员:关节数 ≥ 200 warn;多骨骼网格却没有 leader pose warn。
  • 重音:与最近切点的偏移以帧数报出。

五、数字:采样、预热与帧范围

项目 数值 相对基准与来源
层级偏置 根 0,每级 +100,同值混合 shots 文档
预卷 24 到 48 帧(布料、毛发、粒子在运动) 摘要与 tips 文档
Engine Warm Up(空闲布料) 大于 30 帧 tips 文档
时间采样 Frame Close:24(覆盖 Blur 95% 镜头)、48 快、64 很快;Frame Center:奇数(15、25、49、65) Blur 与 Faucher
抗锯齿 总采样大于 8 时设 None MRG 画质文档
预热采样 只采样最后 5 帧预热 5.6 与 5.8 说明
线性与视口 约暗一档 Faucher
评审 MP4 码率 fps × 2 × 1000 kb/s(24 fps 为 48,000) Faucher
角色 关节数低于 200 Glitch
母灯光 400 镜头一集 10 到 13 个,每个 1 到 2 天 Glitch

这些常量在代码里也是硬编码的,便于直接引用:PREROLL_MIN = 24、ENGINE_WARMUP_IDLE_SIM = 30、MAX_JOINTS = 200、LONG_LENS_MM = 85,采样表见 ue_cine.py:

TEMPORAL_SAMPLES = {
    "frame_center": {"static": 15, "slow": 15, "normal": 25, "fast": 49, "very_fast": 65},
    "frame_close":  {"static": 16, "slow": 16, "normal": 24, "fast": 48, "very_fast": 64},
    "frame_open":   {"static": 16, "slow": 16, "normal": 24, "fast": 48, "very_fast": 64},
}

render_policy(shot, plan) 就是用这张表加镜头自身的 temporal_samples、preroll、accumulation_dof 生成每个 job 的变量值。

六、模板渲染图:MRG__EXR

原则是"一张受版本控制的图,逐镜头的值通过暴露变量传入"。用脚本去改节点默认值会弄脏共享资产。图的编写只有部分可脚本化:先读引擎里 Engine/Plugins/MovieScene/MovieRenderPipeline/Content/Python/ 下的 MovieGraphCreateConfigExample.py,再决定是脚本建节点还是在 GUI 里搭。

节点 关键设置 依据
Global Output Settings 分辨率 3840×2160 或宽银幕 3840×1608;帧率取自序列;输出目录 {project_dir}/Saved/MovieRenders/{sequence_name};文件名 {sequence_name}.{frame_number},Zero Pad 4(带 layer 时加 {layer_name}) MRG token 文档
Sampling Method Temporal Sample Count 暴露为 TemporalSamples(Int32) 8o2yaZzfHCA
Warm Up Settings 帧数暴露为 WarmUpFrames;camera-cut warm-up 暴露为 UseCameraCutWarmUp(属性名待核);开启模拟运动模糊 tips / MRG 文档
Camera Settings 快门时序 Frame Center(奇数计数) 反解 MRQ 文档
Global Game Overrides 必须连接(cinematic 画质只在连接时生效);植被镜头关闭 Use LODZero MRQ 命令行 / MRG 文档
Render Layer + Deferred Renderer spatial 1、Anti-Aliasing override None、Disable Tone Curve 打开 MRG 文档 / Faucher
Accumulation DOF modifier camera-default 模式,用 AccumulationDOF(Bool)开关 5.8 说明
EXR 输出 16-bit half,PIZ 或 DWAA/DWAB(5.8),除非供应商要求 ACEScg 否则 OCIO 关 Faucher / 5.8 说明
Set Metadata Attributes 镜头、版本、plan hash MRG 文档
Execute Script 类 CineWrittenFiles(来自 cine_render_callbacks.py),模式 Editor Only MRQ 命令行 / 5.8 说明
Debug Settings(仅诊断时) Unreal Insights trace 或抓帧 MRQ → MRG 映射
控制台变量 默认零个;每个都要写清针对哪个镜头问题 Faucher

评审图 MRG_<prod>_Review 用同一批相机与时间,降低分辨率、PNG、带 burn-in(自 5.7 起按输出类型分别配置)。

Execute Script 回调的安装

cine_render_callbacks.py 解决的是"渲染日志说完成了,但到底写了哪些文件"这个缺口。安装四步:

  1. 把文件复制到 <project>/Content/Python/cine_render_callbacks.py;
  2. 在 <project>/Content/Python/init_unreal.py 里加 import cine_render_callbacks,否则该类只在定义它的那个会话里存在;
  3. 模板图里加 Execute Script 节点,类选 CineWrittenFiles,模式选 Editor Only(5.8 中 Python 类需要 Editor Only);
  4. 逐镜头回调(on_shot_finished)只有在 Global Output Settings 的 Flush Disk Writes Per Shot 打开、或 is_per_shot_callback_needed() 返回 True 时才运行,两者都会在每个镜头末尾停顿等待落盘。job 级清单不需要它,所以默认 PER_SHOT = False。

输出是每个 job 一个 JSON,落在 <project>/Saved/MovieRenders/_manifests/(可用 UE_CINE_MANIFEST_DIR 覆盖),文件名 <job_name>__<YYYYmmdd-HHMMSS>.json,永不覆盖;用 latest_manifests(dir) 取每个 job 最新的一份。传给回调的 job 与 graph 都是副本,所以回调里的操作不会污染共享的队列或图资产。

七、逐镜头渲染与命令行

active = C.active_shot_paths(master, plan)     # 剪辑实际播放的 take,不是 plan 里的名字
specs = C.render_jobs(plan, sequences=active)  # 每镜头一个 job,变量来自运动与标志位
for f in C.render_orchestration(specs, unattended=False):
    print(f["status"], f["check"], f["message"])
missing = C.queue_render_jobs(specs)           # 列出图里没暴露的变量
print([m for m in missing if m[1]])
state = {}
C.start_render(on_done=lambda ok: state.setdefault("ok", ok))

几个必须知道的实现细节:

  • render_jobs 默认 per_shot=True,每镜头一个 job;only=[...] 用于只渲母灯光镜头或崩溃后补渲;sequences= 传入当前激活的 take,否则按命名约定推断,换了 take 就会渲错版本。
  • render_orchestration 会对重复 job 直接 fail(render.duplicate);无人值守的多镜头本地队列给 warn(render.unattended);有 farm 时提示"一镜一 job,已提交的用 job.set_consumed(True) 标记"。
  • start_render 把 PIE executor 保存在模块全局变量里——局部变量会被垃圾回收,渲染中途就断了。
  • 单镜头渲染意味着淡入淡出和母序列级轨道不会被渲出来:淡入淡出属于剪辑。

无头逐镜头渲染(真实 GPU 的 -game 模式,绝不用 -run=pythonscript,绝不用 -nullrhi):

import subprocess
import ue_env

eng = ue_env.find_engine()
cmd = C.mrq_command_line(eng["editor_cmd"], "/abs/path/MyGame.uproject", plan["map"],
                         queue="%s/Render/Q_%s" % (plan["root"], plan["name"]))
print(" ".join(cmd))
subprocess.run(cmd, check=True, timeout=6 * 3600)

mrq_command_line 的签名是 (editor_cmd, uproject, map_path, queue=None, level_sequence=None, config=None, resx=1280, resy=720, extra=()),行为上有三条硬约束:queue 与 level_sequence 必须二选一(后者还必须带 config,即 Primary Config 预设);任何含 nullrhi 的额外参数直接抛 ValueError;永远追加 -notexturestreaming,否则首帧会用到仍在流送的低分辨率 mip。它还会自动补 -windowed -resx -resy -log,并把 /Game/A/B 转成软对象路径 /Game/A/B.B。

渲染农场就走"一镜一命令":每镜头一个队列,或 -LevelSequence=<shot> -MoviePipelineConfig=<primary config>。

八、看文件而不是看日志

渲染只有在其文件通过检查后才算数。核心校验函数:

out_f = C.check_render_output(plan, render_root, sequences=seq_names)  # {seq}/{seq}.{frame:04d}.exr
stats = [C.exr_stats(p) for p in files[:4] + files[-2:]]
hdr = C.parse_exr_header(files[0])
report["frames"][row["name"]] = [f for st in stats for f in C.exr_checks(
    st, hdr, {"resolution": plan["render"]["resolution"], "linear": True,
              "compression": ["PIZ", "ZIP", "ZIPS", "DWAA", "DWAB"]})]
report["luma"] = C.luminance_continuity(per_shot, max_jump=1.0)
report["resume"] = C.shots_to_render(plan, render_root, sequences=seq_names)
  • check_render_output 按 expected_frames 得到排他结束的帧列表,报缺失、零字节与多余帧;如果只缺最后一帧,消息会直接点出"渲染范围是不是写成了闭区间"。
  • exr_checks 校验分辨率(fail)、half(warn)、压缩(warn)、NaN/Inf(fail)、全黑(fail)、线性高光(若最大值 ≤ 1.0 则 warn,可能 tone curve 还开着或该镜头没有高光)、元数据键(warn)。
  • first_frame_pop 比较首帧与前几帧的亮度比值,cut_flash 检测切点处前一镜头最后一帧与后一镜头首帧的异常。
  • luminance_continuity 以 log2 均值比较相邻镜头的曝光跳变,默认阈值 1.0 档(约一档),超阈值只是 warn——构图变化也会影响平均亮度,真正的参照是母镜头。
  • check_manifest 把回调写出的文件清单与"每镜头应有的帧"和磁盘实际文件三方比对:清单里有、磁盘上没有,说明同步、磁盘或覆盖出了问题。
  • shots_to_render 返回缺帧或空帧的镜头名,整镜头重渲到新版本目录。

预览用的 tone map 只是构图与曝光的近似;颜色的判断必须通过与调色相同的 OCIO 视图完成。

九、色彩交接与 Resolve 解读

线性 EXR 若不告诉对方怎么解读,在 Resolve 里就会又暗又偏色。delivery_note 把帧率、EDL、每镜头文件与帧范围(结束排他)、以及当前渲染模式对应的 Resolve 解读写在一起:

渲染模式 ACES Transform 输入 输出 预期
tone curve 开(直出) sRGB (Linear) sRGB Texture 与视口一致;显示参考,UE 的 tone curve "有 ACES 风味但不是真 ACES"
tone curve 关(已调色,本流程默认) Linear sRGB sRGB 比视口暗约一档,属预期
OCIO 到 ACEScg(仅供应商要求) ACEScg sRGB 转换后与线性 sRGB 路径一致
输出到 log 空间而非 sRGB — — 让调色师可以用 LUT
note = C.delivery_note(plan, settings, sequences=seq_names)
print(note)
print(C.color_handoff(settings)["viewport"])   # 打灯与评审时用同一个视图

delivery_note 默认把 EDL 的记录起点写成 01:00:00:00(CMX 3600 习惯),可传参覆盖。color_handoff 的 viewport 字段直接给出"打灯时该把视口 Lit > OCIO Display 设成哪个视图",这是让"打灯看到的"和"调色看到的"对齐的关键一步。

十、质量闸门与评审清单

闸门分两层:可测量的与可视的。

可测量: check_plan、ready_to_animate、ready_for_final_lighting、audit_sequence 无 fail;audit_render_settings 无 fail 且无未答复的 warn;帧数与排他结束一致(check_render_output、check_manifest);EXR 为 half、无 NaN/Inf、非全黑、线性时亮部有大于 1.0 的值、元数据齐全;first_frame_pop 与 cut_flash 为假;亮度跳变只出现在设计好的地方。

可视: 接触表、隔离出来的预卷帧、每个镜头的首帧、每个切点、毛发与遮挡物处的景深边缘、最快运动处的运动模糊、通过与调色相同 OCIO 视图对照母镜头看灯光、带音乐完整看一遍。

references/critique.md 把每条评审问题都映射到具体检查 ID 与严重级别,并且明确了一条纪律:先看数字,再看画面。原因是 Epic 的 MCP 演示里曾有 agent 眼睁睁批准了一张全白帧。

报告要求也很实在:写 JSON,包含 plan hash 与摘要、构建报告(资产、软失败)、审计发现、分镜清单与图像检查、渲染设置审计、每镜头帧检查、亮度连续性、哪些只看了没测,以及所有用到 [verify] 的未确认调用。跳过的检查要写明跳过原因(比如没有 ffmpeg、没有图)。

十一、常见错误速查

错误 现象 修法
复制母序列做实验 改动泄漏进"备份" 在镜头内用 New Take(new_take)
把角色和相机做成 possessable 换一张地图就崩 改 spawnable;跑 empty_level_test
把布景当 possessable 做动画 镜头结束后弹回原位 在该镜头 K 帧,或做成 spawnable(回应 bind.override)
用大纲视图眼睛隐藏 重新打开又出现了 用 Levels 面板或 Level Visibility 轨
多个骨骼网格共用一条动画轨 其他部件不跟随 Blueprint 里 Set Leader Pose Component(check_characters)
长 Python 工具没有进度 引擎像卡死,被中途杀掉 用 editor_tool 包裹
在锁节奏前做动画 白做的帧被剪掉 先分镜、重音对切点、过 ready_to_animate
对跑动的角色只用 Engine Warm Up 布料在第一帧跳变 预卷加 camera-cut warm-up
期待最后一帧存在 "0 到 50 少了第 50 帧" 结束排他;按 end - start 计数
靠加采样降噪 时间翻倍、噪点照旧 修灯光或后处理设置
Frame Center 用偶数、时间与空间采样混用 出现台阶感、浪费 只用奇数时间采样(或 Frame Close 的 24)
逐镜头打灯、没有母镜头 后期大改 先批准母镜头
在默认视口打灯、渲染线性 观感整体偏一档 视口 OCIO Display
线性 EXR 不带解读说明 Resolve 里又暗又偏色 delivery_note
每个镜头都改共享图 所有 job 一起变 每 job 覆盖暴露变量
本地整夜排队列或用局部 executor 崩一次丢队列;渲染中断 农场管理器,或一镜一进程 + shots_to_render + start_render
无头渲染不带 -notexturestreaming 首帧发虚 mrq_command_line

十二、上下游交接与 5.8 注意事项

接收: 来自 scenario-unreal-lighting-rendering 的是打好灯的关卡(天空、雾、主光、无边界 PPV、曝光策略、作为子关卡或 data layer 的母灯光)、源头已修的噪点、待批准的母镜头;来自 scenario-unreal-animation 的是带长度与帧率的动画序列、低于 200 关节且多网格 Blueprint 已设 leader pose 的角色、布料/物理标志;来自 scenario-unreal-vfx 的是带用户参数与预热需求的 Niagara 系统;来自 scenario-unreal-world-building 的是地图与布景。

交付: 给剪辑与调色师的是每镜头 EXR({sequence_name}/{sequence_name}.####.exr,线性、half、带元数据)、<prod>.edl、交付说明、评审 MP4、接触表、JSON 报告与母序列;把连续性或噪点不合格的镜头(附帧)退回灯光技能;农场命令交给 scenario-unreal-pipeline-automation;慢镜头交给 scenario-unreal-performance。

UE 5.8 相关:

  • MRG 已是 Production Ready,新特性只进图;队列默认以 Basic 配置打开。新增 Light Modifier、layer warm-ups、DWAA/DWAB EXR、Accumulation DOF(实验性插件)。
  • MRG 中 Game Overrides 只在连接时生效;tone curve 在渲染器节点上,OCIO 在输出节点上;Execute Script 节点需要 Editor Only 模式才能跑 Python。
  • Spawnable 是自定义绑定,用 LevelSequenceEditorSubsystem.add_spawnable_from_class 创建;没有 add_master_track;时间函数接收 MovieSceneTimeUnit。
  • 播放会遵循选区;Sensor Aspect Ratio 不可做动画;Take Recorder 与 VCam 接受 spawnable;实验用 Sandbox。
  • OpenColorIO 2.5.1 搭配 ACES 2.0,视图名称可能与 "ACES 1.0 SDR Video" 不同(待核)。
  • Mac 上 MRG 的 H.264 节点仅 Windows 可用(用 ffmpeg 编码);ProRes 在 Mac 上存在冲突(待核);路径追踪需要 macOS 26.4+。

十三、状态与验证边界

这一点必须说清楚,否则会误用:SKILL.md 明确标注,scripts/ue_cine.py 与 scripts/cine_render_callbacks.py 尚未在 Unreal 中运行过(构建时 UE 5.8 未安装),离线测试通过,测试计数见 references/sources.md。所有 Unreal API 名称、cvar、命令都带"未在引擎中验证"的标记;代码里 [verify] 注释也是同一含义。

因此实际使用的第一步不是建库,而是探测:

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(missing, rep["graph_classes"][:20], rep["accumulation_dof"], rep["cat"])

或在引擎中运行 tests/code/unreal-cinematics/job_00_probe_cine.py(该路径属于构建工程,不在当前仓库内),把报告里所有缺失的名字修掉,再信任 build_from_plan 与 audit_sequence。同样的道理适用于 normalize_graph_snapshot 的属性名映射:它是启发式的,探测列出真实名称后要扩表。

安装整套 Unreal 专家技能时,安装器会把技能并排放置,因为各专家技能要 import 前置技能的 scripts/:

npx skills add scenario-labs/skills --skill scenario-unreal-expert scenario-unreal-animation scenario-unreal-cinematics scenario-unreal-gameplay scenario-unreal-lighting-rendering scenario-unreal-materials scenario-unreal-performance scenario-unreal-pipeline-automation scenario-unreal-vfx scenario-unreal-world-building

安装与选择器的说明见 skills/game-engines/unreal/README.md;图形界面下的等效操作(菜单路径、插件开关、Resolve 设置位置)见 references/gui-paths.md,逐条专家判断与时间戳出处见 references/expert-notes.md。

登录后查看全文
skills