SuperAPI AI 工具集

ue-sequencer-python

编程与开发

查看项目

更新于 11-16 16:28

技能介绍

用途 本技能针对在 Unreal Engine 5.9 编辑器中用 Python 构建或编辑 Level Sequence(Sequencer、MovieScene、过场动画),以及运行时绑定覆盖和序列检视(scrubbing)的场景。资料说明:Sequencer 的 Python API 是一组扩展库(MovieSceneSequenceExtensions、MovieSceneSectionExtensions、MovieSceneBindingExtensions 等),其静态函数以 snake_case 方法挂到对象上(ScriptMethod),另有仅在编辑器中可用的 LevelSequenceEditorSubsystem。这些名称与 C++ 或 Sequencer 界面中的命名并不一致,资料称在一次 48 小时的 UE 5.9 游戏创作项目中有 133 个编辑器脚本操作了 MovieScene,约 28 个调用因猜错名称而失败,本技能提供了修正后的名称清单。C++ 运行时播放属于另一项技能(ue-sequencer-and-cinematics),通用 Python 规则属于 ue-editor-scripting-and-python。

适用时机 资料列出以下触发场景:从 Python 构建或编辑 Level Sequence(绑定、轨道、区段、关键帧、剪切);重定时(区段范围、动画播放速率、循环偏移、缓动、标记帧);为游戏玩法在运行时提供的 Actor 执行绑定覆盖(可替换绑定、标签);在编辑器或 PIE 中检视序列以捕获或检查某一帧;以及针对 MovieScene 类型出现 unreal.AttributeError、"Cannot nativize" 或 "Failed to find property" 时。

核心模型 方法挂在序列资产上,而不是 UMovieScene 上,例如 seq.get_display_rate()、seq.get_bindings()。UMovieScene::GetDisplayRate 是普通 C++(非 UFUNCTION),所以 seq.get_movie_scene().get_display_rate() 会报 AttributeError。 绑定有两种句柄:MovieSceneBindingProxy(guid + sequence)用于添加轨道;MovieSceneObjectBindingID 是不透明存储引用(guid + sequence ID + parent index),用于相机切镜区段和运行时覆盖,其 Guid 不是蓝图可见的,因此 .guid 会失败。 时间有四种单位:显示帧率帧(UI 显示)、tick 分辨率帧(存储,如 24000/s)、秒、FrameTime(帧 + 子帧),每次调用只接受其中一种。 缺少 getter/setter 时改用属性:资料称 5.9 Python 中 lsa.get_sequence_player() 和 cine.set_current_focal_length() 会抛 AttributeError,应使用 get_editor_property / set_editor_property。 编辑器子系统需要已打开的序列:LevelSequenceEditorSubsystem 上可生成对象、相机和绑定对象的调用作用于 Sequencer 中打开的序列。

错误与对策 资料以表格形式列出常见错误及正确写法,包括:MovieSceneObjectBindingID 无 guid 属性(用 seq.get_binding_id(proxy) 或 root.get_portable_binding_id 生成,用 bid.get_editor_property("guid") 读 guid);绑定代理找不到(find_binding_by_name 匹配内部名而非显示名,转换绑定会返回新代理,结构变化后需重新读取 seq.get_bindings());play_rate 是 MovieSceneTimeWarpVariant;缓动结构成员不是脚本可见的(用 set_ease_in_duration/set_ease_out_duration,单位为 tick 帧);标记帧 FrameNumber 只读且 Comment 不可见;LevelSequenceActor 无 get_sequence_player(读 sequence_player 属性);CineCameraComponent 无 set_current_focal_length(设 current_focal_length 属性);区段可能无起始帧(先 has_start_frame()/has_end_frame());MovieScene 无 get_display_rate(在 seq 上调用);SoundWave 无 get_duration(读 duration 属性);以及音频区段超出播放结束的警告。

核心工作流 资料给出示例:用 AssetTools 创建序列,先 set_display_rate 设置显示帧率,再设置 playback_start/end(显示帧,结束为排他)、view/work range(秒),在调用任何可生成/相机/绑定对象调用前用 lse.open_level_sequence_async(seq) 打开。资料强调:先设显示帧率再计算帧,因为 set_range 和 add_key 在调用时把显示帧转换为 tick;只读取 tick 分辨率,不要修改;用 EditorAssetLibrary.save_loaded_asset(seq, False) 保存。

时间单位对照 显示帧率帧(int):set_playback_start/end、section.set_range、set/get_start_frame、set/get_end_frame。显式 MovieSceneTimeUnit:channel.add_key、标记帧调用,始终显式传 DISPLAY_RATE。tick 分辨率帧:params 的 start_frame_offset、first_loop_start_frame_offset、end_frame_offset、缓动时长。秒(float):set_view_range_、set_work_range_、set_range_seconds 等。秒转 tick:t = seq.get_tick_resolution(); int(round(sec * t.numerator / t.denominator))。

绑定、轨道与相机 Possessable 是关卡中的 Actor,Spawnable 是序列拥有的模板;修改可生成对象的实时 Actor 后需调用 lse.save_default_spawnable_state(proxy)。资料提醒 Sequencer 会自动添加按类默认值打键的轨道(相机组件的镜头轨道、MetaHuman 的 Control Rig 轨道),需改写或移除;可生成对象的 Spawn 轨道区段必须覆盖播放范围;相机由变换键而非生成姿态定位。运行时由游戏玩法提供的 Actor 可用 convert_to_custom_binding 转为 MovieSceneReplaceableActorBinding 并 tag_binding,玩法在 play() 前调用 lsa.set_binding_by_tag。相机切镜轨道的区段存储 MovieSceneObjectBindingID,跨子序列时用 get_portable_binding_id;create_camera 会添加不覆盖目标范围的默认切镜区段,需重建。资料列出可用的 CineCamera 属性和属性轨道路径(CurrentFocalLength、CurrentAperture、FocusSettings.ManualFocusDistance),并强调属性轨道必须 set_property_name_and_path,否则键不驱动任何东西;结构体和数组需写回。

动画与音频区段 动画区段:params.play_rate 为 MovieSceneTimeWarpVariant,用 set_fixed_play_rate 设置;5.9 另有 MovieSceneTimeWarpExtensions.set_section_play_rate/get_section_play_rate(类函数)。循环片段中途开始用 first_loop_start_frame_offset(tick 帧)。缓动用 set_ease_in_duration/set_ease_out_duration(tick,非显示帧)。 标记帧在 5.9 变为 [Start, End) 范围,FrameNumber 已弃用且只读;用 add_marked_frame_range_to_sequence、set_marked_frame_range;注释和颜色按索引设置,索引会因重排变化,用 find_marked_frame_by_label 重新查找。 音频区段:区段结束超出播放结束会记录警告,短于声音会戛然而止;保存前应列出开放式或超出播放结束的音频区段并修正,如裁剪区段并在最后 0.5–1 秒把音量通道线性降到 0。资料建议按实测素材长度(duration)而非按语速估算来定时。

运行时播放与检视 资料给出用 LevelSequencePlayer.create_level_sequence_player 创建播放器与 LevelSequenceActor,在 play() 前 set_binding_by_tag,用 MovieSceneSequencePlaybackParams 设置帧/时间/标记帧与 SCRUB/JUMP/PLAY 更新方式;从略早几帧步入以使切镜和姿态正向求值,并等待约 1 秒让帧稳定后再捕获。当前时间(秒)可由 get_current_time() 与 get_frame_rate() 换算。资料强调"未在播放"不等于"已结束",应在序列结束时间或播放器停止超过一秒后结束;根运动会让角色偏离 Actor 原点,需对相关骨骼网格组件设置 visibility_based_anim_tick_option = ALWAYS_TICK_POSE_AND_REFRESH_BONES。还提醒 find_binding_by_name 匹配内部名,应按 get_display_name() 匹配。

限制 资料仅针对 UE 5.9 编辑器 Python 与相关 Sequencer API,未说明其他版本兼容性、安装方式、收费或平台要求。