Communitygithub.com

ue-sequencer-cinematics

你是一位精通虚幻引擎Sequencer与影视级过场系统的专家。

ue-sequencer-cinematics 是什么?

该技能将AI代理定位为虚幻引擎Sequencer和影视级过场系统的专家,提供了一套全面的C++ API参考,用于创建、绑定、播放和控制过场动画序列。它涵盖了从构建配置模块(LevelSequence、MovieScene、CinematicCamera)和不同播放方式(世界放置的ALevelSequenceActor与运行时生成的ULevelSequencePlayer)到详细的播放控制(Play、Pause、Stop、PlayTo、SetPlaybackPosition)以及Actor绑定(占据物与生成物、基于标签和GUID的绑定)的所有内容。该技能还深入讲解了相机系统(CineCameraActor、CineCameraComponent、焦距、光圈、对焦、注视跟踪)、过场事件(通过事件轨道和ULevelSequenceDirector触发C++函数)以及MovieScene轨道类型(变换、骨骼动画、音频、摄像机剪切等)。它强调了与项目上下文文件(.agents/ue-project-context.md)协同工作的重要性,以确保代码与目标UE版本(例如5.4+中SequencePlayer属性已弃用)和特定项目需求(多人游戏、Movie Render Queue)兼容。该技能适用于Claude Code、Cursor、Codex或任何其他AI编码助手,有助于生成专业、版本感知的虚幻引擎过场过场动画C++代码。

兼容平台~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/ComeOnOliver/skillshub/tree/HEAD/skills/quodsoler/unreal-engine-skills/ue-sequencer-cinematics

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

技能:ue-sequencer-cinematics

你是一位精通虚幻引擎Sequencer与影视级过场系统的专家。

上下文检查

在编写任何过场动画代码之前,请阅读 .agents/ue-project-context.md 以了解:

  • 目标UE版本(API可用性因版本而异 — SequencePlayer 属性在 5.4+ 中已弃用)
  • 过场动画需求(过场动画、游戏内摄像机、离线渲染)
  • 多人游戏上下文(序列复制行为不同)
  • Build.cs 中已声明的模块

信息收集

请询问:

  1. 过场动画类型:全屏过场动画、游戏内摄像机或背景环境序列
  2. Actor是在运行时绑定还是预先放置在关卡中
  3. 播放后是否必须将摄像机控制权返还给玩家
  4. 单次播放还是循环序列
  5. 实时游戏输出还是离线 Movie Render Queue 输出

Build.cs 模块

PublicDependencyModuleNames.AddRange(new string[]
{
    "LevelSequence", "MovieScene", "CinematicCamera",
});
// 仅离线渲染时添加:
PrivateDependencyModuleNames.Add("MovieRenderPipelineCore");

播放关卡序列

ALevelSequenceActor — 世界放置方式

ALevelSequenceActor 拥有播放器。使用 GetSequencePlayer() — 直接的 SequencePlayer 属性自 UE 5.4 起已弃用。

// LevelSequenceActor.h: ULevelSequencePlayer* GetSequencePlayer() const;
ULevelSequencePlayer* Player = SeqActor->GetSequencePlayer();
if (Player) { Player->Play(); }

ULevelSequencePlayer::CreateLevelSequencePlayer — 运行时生成方式

// LevelSequencePlayer.h:
// static ULevelSequencePlayer* CreateLevelSequencePlayer(
//     UObject* WorldContextObject, ULevelSequence*, FMovieSceneSequencePlaybackSettings,
//     ALevelSequenceActor*& OutActor);

FMovieSceneSequencePlaybackSettings Settings;
Settings.bAutoPlay              = false;
Settings.PlayRate               = 1.0f;
Settings.LoopCount.Value        = 0;       // 0=一次,-1=无限
Settings.bDisableMovementInput  = true;
Settings.bDisableLookAtInput    = true;
Settings.bHidePlayer            = false;
Settings.bHideHud               = false;
Settings.bDisableCameraCuts     = false;
Settings.bPauseAtEnd            = false;
Settings.FinishCompletionStateOverride =
    EMovieSceneCompletionModeOverride::ForceRestoreState; // 对于可跳过的过场动画安全

ALevelSequenceActor* OutActor = nullptr;
ULevelSequencePlayer* Player  = ULevelSequencePlayer::CreateLevelSequencePlayer(
    this, Sequence, Settings, OutActor);

// 将 OutActor 存储在 UPROPERTY 中以防止被 GC
ActiveSequenceActor = OutActor;

if (Player)
{
    Player->OnFinished.AddDynamic(this, &AMyClass::OnCutsceneFinished);
    Player->Play();
}

播放控制(基类 UMovieSceneSequencePlayer)

// MovieSceneSequencePlayer.h
Player->Play();
Player->PlayReverse();
Player->PlayLooping(-1);       // -1 = 无限循环
Player->Pause();
Player->Stop();                // 将光标移动到末尾,触发 OnStop
Player->StopAtCurrentTime();
Player->GoToEndAndStop();
Player->SetPlayRate(0.5f);     // 负值 = 倒放

// 跳转到指定帧(跳过当前帧与目标帧之间的事件)
// 在蓝图中暴露为 GoToFrame。在 C++ 中,使用 SetPlaybackPosition 并配合 Jump 方法。
Player->SetPlaybackPosition(
    FMovieSceneSequencePlaybackParams(FFrameTime(120), EUpdatePositionMethod::Jump));

// 播放到指定帧(沿途触发所有事件)
Player->PlayTo(
    FMovieSceneSequencePlaybackParams(FFrameTime(240), EUpdatePositionMethod::Play),
    FMovieSceneSequencePlayToParams());

// 限制播放范围
Player->SetFrameRange(0, 60);           // 帧 0–60
Player->SetTimeRange(0.0f, 2.5f);       // 秒

// 状态查询
bool bPlaying = Player->IsPlaying();
FQualifiedFrameTime Now = Player->GetCurrentTime();
FQualifiedFrameTime Dur = Player->GetDuration();

// 委托(在调用 Play 之前绑定)
Player->OnFinished.AddDynamic(this, &UMyClass::OnSeqFinished);
Player->OnPlay.AddDynamic(this, &UMyClass::OnSeqPlay);
Player->OnStop.AddDynamic(this, &UMyClass::OnSeqStop);
Player->OnNativeFinished.BindUObject(this, &UMyClass::OnNativeFinished); // 非动态

// 摄像机剪切事件(LevelSequencePlayer.h)
// DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(FOnLevelSequencePlayerCameraCutEvent, UCameraComponent*, CameraComponent)
LsPlayer->OnCameraCut.AddDynamic(this, &UMyClass::OnCameraCut);

// 提前停止时恢复状态(可跳过的过场动画)
Player->SetCompletionModeOverride(EMovieSceneCompletionModeOverride::ForceRestoreState);
Player->Stop();

// 子序列快照
FLevelSequencePlayerSnapshot Snap;
Player->TakeFrameSnapshot(Snap);
// Snap.CurrentShotName, Snap.RootTime, Snap.CameraComponent, Snap.ActiveShot

Actor 绑定

在Sequencer中标记绑定(右键单击对象绑定 -> 标签...)然后在运行时覆盖。 始终在调用 Play() 之前进行绑定。

占据物(Possessables)与生成物(Spawnables)

占据物绑定到预先存在的世界Actor(放置在关卡中或由游戏玩法生成)。生成物是序列自身创建和销毁的Actor。

// 生成物:序列拥有Actor的生命周期
// 在Sequencer编辑器中设置:右键单击Actor轨道 → "更改为生成物"
// 运行时,当序列到达其范围时生成Actor,离开范围时销毁

// 动态占据物:将游戏玩法生成的Actor绑定到序列轨道
// 在编辑器中创建绑定ID,然后在运行时覆盖:
FMovieSceneObjectBindingID BindingID = /* 来自序列编辑器 */;
ALevelSequenceActor* SeqActor = /* 你的序列Actor */;
SeqActor->SetBinding(BindingID, {SpawnedActor});

为何重要:对持久的世界Actor(门、电梯)使用占据物,对瞬态的仅过场动画Actor(仅过场动画的角色、道具)使用生成物。占据物在序列结束后仍然存在;生成物会自动清理。

// LevelSequenceActor.h — 所有绑定API都在这里

// 替换绑定的Actor(推荐:基于标签,对GUID更改有弹性)
SeqActor->SetBindingByTag(FName("Hero"), TArray<AActor*>{ HeroActor },
    /*bAllowBindingsFromAsset=*/ false);

// 基于GUID(通过 UPROPERTY 暴露 FMovieSceneObjectBindingID 以在编辑器中赋值)
// UPROPERTY(EditAnywhere) FMovieSceneObjectBindingID HeroBindingID;
SeqActor->SetBinding(HeroBindingID, TArray<AActor*>{ HeroActor }, false);

// 追加而不移除现有绑定
SeqActor->AddBindingByTag(FName("NPC"), NpcActor, /*bAllowBindingsFromAsset=*/ true);

// 移除 / 重置
SeqActor->RemoveBindingByTag(FName("NPC"), NpcActor);
SeqActor->ResetBinding(HeroBindingID);  // 回退到资源绑定
SeqActor->ResetBindings();              // 回退所有覆盖

// 通过标签查找
FMovieSceneObjectBindingID ID = SeqActor->FindNamedBinding(FName("Hero"));
const TArray<FMovieSceneObjectBindingID>& All = SeqActor->FindNamedBindings(FName("NPC"));

// 检查当前绑定的内容
TArray<UObject*> Bound = Player->GetBoundObjects(HeroBindingID);

// FMovieSceneObjectBindingID (MovieSceneObjectBindingID.h):
//   通过公共访问器访问 — 内部字段是私有的:
//     GetGuid()              — 标识绑定轨道的 FGuid
//     GetRelativeSequenceID() — 标识哪个子序列持有它(0 = 本地)

摄像机系统

ACineCameraActor / UCineCameraComponent

// CineCameraActor.h: UCineCameraComponent* GetCineCameraComponent() const;
// CineCameraComponent.h / CineCameraSettings.h:
//   FCameraFilmbackSettings Filmback  (SensorWidth, SensorHeight 以毫米为单位,只读 SensorAspectRatio)
//   FCameraLensSettings LensSettings  (MinFocalLength, MaxFocalLength, MinFStop, MaxFStop 毫米)
//   FCameraFocusSettings FocusSettings (FocusMethod, ManualFocusDistance 厘米, bSmoothFocusChanges)
//   float CurrentFocalLength  — 可插值,可在Sequencer中动画化
//   float CurrentAperture     — f-stop,插值可动画化

ACineCameraActor* Cam = GetWorld()->SpawnActor<ACineCameraActor>(SpawnTransform);
UCineCameraComponent* CC = Cam->GetCineCameraComponent();

FCameraFilmbackSettings FB;
FB.SensorWidth = 36.0f; FB.SensorHeight = 24.0f;  // 全画幅 35mm
CC->SetFilmback(FB);

CC->SetCurrentFocalLength(50.0f);   // 毫米
CC->SetCurrentAperture(2.0f);       // f-stop

FCameraFocusSettings FS;
FS.FocusMethod         = ECameraFocusMethod::Manual;  // Manual | Tracking | Disable | DoNotOverride
FS.ManualFocusDistance = 500.0f;    // 厘米
FS.bSmoothFocusChanges = true;
CC->SetFocusSettings(FS);

// 注视追踪 (CineCameraActor.h: FCameraLookatTrackingSettings LookatTrackingSettings)
Cam->LookatTrackingSettings.bEnableLookAtTracking     = true;
Cam->LookatTrackingSettings.ActorToTrack              = TargetActor;
Cam->LookatTrackingSettings.LookAtTrackingInterpSpeed = 5.0f;
Cam->LookatTrackingSettings.RelativeOffset            = FVector(0, 0, 90.f);

// 阻止序列覆盖游戏摄像机(在调用 Play 之前设置)
SeqActor->PlaybackSettings.bDisableCameraCuts = true;

// 过场动画后恢复玩家摄像机(从 OnFinished 委托中调用)
APlayerController* PC = GetWorld()->GetFirstPlayerController();
PC->SetViewTargetWithBlend(PC->GetPawn(), 0.5f, VTBlend_Cubic);
PC->SetIgnoreMoveInput(false);
PC->SetIgnoreLookInput(false);

APlayerCameraManager

APlayerCameraManager(通过 PlayerController->PlayerCameraManager 访问)管理本地玩家的摄像机混合和视图目标选择。过场动画结束后,显式恢复游戏摄像机 — Sequencer 不会自动执行此操作:

APlayerController* PC = GetWorld()->GetFirstPlayerController();
// PlayerCameraManager 处理混合状态;SetViewTargetWithBlend 触发它。
PC->SetViewTargetWithBlend(PC->GetPawn(), 0.5f, VTBlend_Cubic);
// 混合在 APlayerCameraManager::UpdateCamera 的每个tick中被处理。

Sequencer 事件

事件轨道对事件上下文中的对象调用 UFUNCTION。 默认事件上下文:UWorld + ALevelScriptActor。

// 函数必须是上下文对象上的 UFUNCTION(BlueprintCallable)
UFUNCTION(BlueprintCallable, Category = "Cinematics")
void TriggerExplosion()
{
    ExplosionSystem->SpawnExplosion(ExplosionLocation);
}

// 通过播放到特定帧来触发 C++ 代码(触发范围内的所有事件)
Player->PlayTo(
    FMovieSceneSequencePlaybackParams(FFrameTime(60), EUpdatePositionMethod::Play),
    FMovieSceneSequencePlayToParams());

FMovieSceneEvent

FMovieSceneEvent 持有事件端点数据 — 事件触发时要调用的绑定函数。事件轨道的结构如下:

  • UMovieSceneEventTrack — 添加到绑定或作为主轨道的主轨道
  • UMovieSceneEventTriggerSection — 包含一个或多个触发器条目的节段
  • FMovieSceneEvent — 触发器节段内的每个条目,指向端点函数

端点函数在运行时针对事件上下文对象(默认情况下是 UWorld 和 ALevelScriptActor)解析。基于导演的事件针对 ULevelSequenceDirector 子类实例解析。

ULevelSequenceDirector — 自定义事件上下文

ULevelSequenceDirector 提供一个每个序列的脚本上下文,该上下文接收事件轨道调用。对其子类化(蓝图或C++)并赋值给 LevelSequence 资源的 Director Class 属性。Director 实例在序列开始播放时创建,并在停止时销毁 — 其生命周期与序列播放器匹配。

// MySequenceDirector.h
#include "LevelSequenceDirector.h"
#include "MySequenceDirector.generated.h"

UCLASS(Blueprintable)
class UMySequenceDirector : public ULevelSequenceDirector
{
    GENERATED_BODY()
public:
    // 从Sequencer事件轨道调用 — 在Sequencer编辑器中绑定到事件键
    UFUNCTION(BlueprintCallable, Category = "Cinematics")
    void OnDialogueStart(FName SpeakerTag);

    UFUNCTION(BlueprintCallable, Category = "Cinematics")
    void OnCutsceneChoice(int32 ChoiceIndex);
};

// MySequenceDirector.cpp
void UMySequenceDirector::OnDialogueStart(FName SpeakerTag)
{
    // 在Director内部访问序列播放器和绑定的Actor。
    // ULevelSequenceDirector.h: UPROPERTY ULevelSequencePlayer* Player(直接字段,无getter)
    TArray<UObject*> Bound = Player->GetBoundObjects(SpeakerBindingID);
    // 触发游戏逻辑:UI、对话系统、摄像机对焦等。
}

为何Director优于关卡脚本:Director随序列资源而不是关卡移动。可在多个地图中复用。支持每个序列的状态(成员变量)。关卡脚本事件仅当序列放置在特定关卡中时才有效。


MovieScene 轨道

// MovieScene.h — 从 LevelSequence 资源获取
UMovieScene* MS = SeqActor->GetSequence()->GetMovieScene();

// 占据物(世界Actor)— 按索引迭代
for (int32 i = 0; i < MS->GetPossessableCount(); ++i)
{
    const FMovieScenePossessable& P = MS->GetPossessable(i);
}
// 生成物(序列拥有的Actor)— 按索引迭代
for (int32 i = 0; i < MS->GetSpawnableCount(); ++i)
{
    const FMovieSceneSpawnable& S = MS->GetSpawnable(i);
}

// 主轨道(未绑定到任何Actor)
const TArray<UMovieSceneTrack*>& Masters = MS->GetTracks();

// 特定绑定上的轨道
const FMovieSceneBinding* B = MS->FindBinding(SomeGuid);
if (B) { for (UMovieSceneTrack* T : B->GetTracks()) { /* 转换为子类型 */ } }
轨道类用途
UMovieScene3DTransformTrack变换动画
UMovieSceneSkeletalAnimationTrack骨骼网格体动画
UMovieSceneEventTrack事件触发器
UMovieSceneAudioTrack音频
UMovieSceneFadeTrack屏幕淡入淡出
UMovieSceneCameraCutTrack摄像机剪切
UMovieSceneSubTrack子序列
UMovieScenePropertyTrack任意 UPROPERTY 动画(基类)

所有轨道类型都需要在 Build.cs 中包含 MovieSceneTracks。

自定义轨道:子类化 UMovieSceneTrack + UMovieSceneSection 以实现领域特定的动画数据。通过 ISequencerModule::RegisterTrackEditor 注册。这是一个高级模式 — 大多数需求都可以通过 UMovieScenePropertyTrack 的子类化来满足。

…

[为翻译截断]

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

ComeOnOliver/skillshub

Create stunning, animation-rich HTML presentations from scratch or by converting PowerPoint files. Use when the user wants to build a presentation, convert a PPT/PPTX to web, or create slides for a talk/pitch. Helps non-designers discover their aesthetic through visual exploration rather than abstract choices.

ComeOnOliver/skillshub

Next.js 16+ 和 Turbopack — 增量打包、文件系统缓存、开发速度,以及何时使用 Turbopack 与 webpack。

ComeOnOliver/skillshub

SwiftUI architecture patterns, state management with @Observable, view composition, navigation, performance optimization, and modern iOS/macOS UI best practices.

ComeOnOliver/skillshub

See, Understand, Act on video and audio. See- ingest from local files, URLs, RTSP/live feeds, or live record desktop; return realtime context and playable stream links. Understand- extract frames, build visual/semantic/temporal indexes, and search moments with timestamps and auto-clips. Act- transcode and normalize (codec, fps, resolution, aspect ratio), perform timeline edits (subtitles, text/image overlays, branding, audio overlays, dubbing, translation), generate media assets (image, audio, video), and create real time alerts for events from live streams or desktop capture.

ComeOnOliver/skillshub

AI-assisted video editing workflows for cutting, structuring, and augmenting real footage. Covers the full pipeline from raw capture through FFmpeg, Remotion, ElevenLabs, fal.ai, and final polish in Descript or CapCut. Use when the user wants to edit video, cut footage, create vlogs, or build video content.

ComeOnOliver/skillshub

Next.js 15 애플리케이션을 위한 프론트엔드 개발 가이드라인. React 19, TypeScript, Shadcn/ui, Tailwind CSS를 사용한 모던 패턴. Server Components, Client Components, App Router, 파일 구조, Shadcn/ui 컴포넌트, 성능 최적화, TypeScript 모범 사례 포함. 컴포넌트, 페이지, 기능 생성, 데이터 페칭, 스타일링, 라우팅, 프론트엔드 코드 작업 시 사용.

ComeOnOliver/skillshub

Provides Tamagui patterns for config v4, compiler optimization, styled context, and cross-platform styling. Must use when working with Tamagui projects (tamagui.config.ts, @tamagui imports).

ComeOnOliver/skillshub

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.

ComeOnOliver/skillshub

Create high-converting, visually distinctive landing pages. Use when building marketing pages, product launches, SaaS homepages, or any single-page conversion-focused website. Guides section-by-section composition with anti-AI-slop principles.

ComeOnOliver/skillshub

Auto-loaded context for Portfolio Buddy 2 development. Use for ANY task involving: React 19 development, TypeScript, portfolio analysis features, metrics calculations, trading strategy comparison, or working with the Portfolio Buddy 2 codebase. Contains tech stack, known issues, and architectural constraints.

ComeOnOliver/skillshub

Next.js development tooling via MCP. Inspect routes, components, build info, and debug Next.js apps. Use when working on Next.js applications, debugging routing, or inspecting app structure. NOT for general React or non-Next.js projects.

ComeOnOliver/skillshub

Implement UI using Shadcn MCP (atoms/theme) and 21st.dev MCP (complex sections). Use when adding buttons, layouts, or generating landing pages.

ComeOnOliver/skillshub

A conceptual skill for building an API client in Next.js that handles JWT tokens

ComeOnOliver/skillshub

Best practices and patterns for Next.js App Router, Server Actions, and Routing in this project.

ComeOnOliver/skillshub

The Design System, Theme, and UX rules for the Physical AI Hub.

ComeOnOliver/skillshub

Comprehensive frontend development skill for building modern, performant web applications using ReactJS, NextJS, TypeScript, Tailwind CSS. Includes component scaffolding, performance optimization, bundle analysis, and UI best practices. Use when developing frontend features, optimizing performance, implementing UI/UX designs, managing state, or reviewing frontend code.

ComeOnOliver/skillshub

This document captures learnings from fixing keyboard navigation issues when floating components (Select, DropdownMenu, Popover) have CSS open/close animations.

ComeOnOliver/skillshub

Build Next.js 16 applications with correct patterns and distinctive design. Use when creating pages, layouts, dynamic routes, upgrading from Next.js 15, or implementing proxy.ts. Covers breaking changes (async params/searchParams, Turbopack, cacheComponents) and frontend aesthetics. NOT when building non-React or backend-only applications.

ComeOnOliver/skillshub

Comprehensive Framer Motion animation library for React. Covers motion components, variants, gestures, page transitions, and scroll animations. Use when adding animations to React/Next.js applications.

ComeOnOliver/skillshub

Build interfaces that resonate, not just render. This skill enforces bold, intentional

相关技能