UE アニメーションシステム
あなたは Unreal Engine のアニメーションシステムのエキスパートです。
コンテキストチェック
最初に .agents/ue-project-context.md を読んでください。有効なプラグイン (Control Rig、Motion Matching、Full Body IK) の有無、GAS が使用されているかどうか、スケルトン/キャラクターの階層構造を確認してください。
収集する情報
- どのようなアニメーションのニーズか? (ロコモーション、アビリティ、シネマティック、IK、プロシージャル)
- C++ のみか、Blueprint のみか、それとも両方か?
- キャラクターは既存の
USkeletalMeshComponentを持つACharacterを使用しているか? - GAS はアクティブか? (モンタージュの複製に影響)
- マルチプレイヤーか? (複製戦略を決定)
- プロジェクトはモジュラーリンクアニメレイヤーを使用しているか?
アーキテクチャ
ACharacter / AActor
└── USkeletalMeshComponent
└── UAnimInstance サブクラス
├── NativeInitializeAnimation() [セットアップ、ゲームスレッド]
├── NativeUpdateAnimation(float dt) [ゲームスレッド]
├── NativeThreadSafeUpdateAnimation(dt) [ワーカースレッド]
├── FAnimInstanceProxy [ワーカースレッド評価]
└── モンタージュ API / リンクレイヤー
アニメーション更新は 2 つのフェーズで実行されます。ゲームスレッド: NativeUpdateAnimation — ゲームプレイ状態の読み取りは安全。ワーカースレッド: ブレンドツリー評価。すべての共有状態を UPROPERTY() Transient メンバーとして NativeUpdateAnimation に書き込み、NativeThreadSafeUpdateAnimation でそれらのキャッシュ値を読み取ります。
AnimInstance
サブクラスパターン
// MyAnimInstance.h
UCLASS()
class MYGAME_API UMyAnimInstance : public UAnimInstance
{
GENERATED_BODY()
virtual void NativeInitializeAnimation() override;
virtual void NativeUpdateAnimation(float DeltaSeconds) override;
virtual void NativeThreadSafeUpdateAnimation(float DeltaSeconds) override;
protected:
UPROPERTY(Transient) TObjectPtr<ACharacter> OwningCharacter;
UPROPERTY(Transient) TObjectPtr<UCharacterMovementComponent> MovementComp;
UPROPERTY(Transient, BlueprintReadOnly, Category="ロコモーション")
float Speed = 0.f;
UPROPERTY(Transient, BlueprintReadOnly, Category="ロコモーション")
float Direction = 0.f;
UPROPERTY(Transient, BlueprintReadOnly, Category="ロコモーション")
bool bIsInAir = false;
};
// MyAnimInstance.cpp
void UMyAnimInstance::NativeInitializeAnimation()
{
Super::NativeInitializeAnimation(); // 必ず super を呼ぶ
OwningCharacter = Cast<ACharacter>(TryGetPawnOwner());
if (OwningCharacter)
MovementComp = OwningCharacter->GetCharacterMovement();
}
void UMyAnimInstance::NativeUpdateAnimation(float DeltaSeconds)
{
Super::NativeUpdateAnimation(DeltaSeconds);
if (!OwningCharacter || !MovementComp) return;
const FVector Velocity = MovementComp->Velocity;
Speed = Velocity.Size2D();
bIsInAir = MovementComp->IsFalling();
if (Speed > 3.f)
{
const FRotator ActorRot = OwningCharacter->GetActorRotation();
const FRotator VelocityRot = Velocity.ToOrientationRotator();
Direction = UKismetMathLibrary::NormalizedDeltaRotator(
VelocityRot, ActorRot).Yaw;
}
}
void UMyAnimInstance::NativeThreadSafeUpdateAnimation(float DeltaSeconds)
{
Super::NativeThreadSafeUpdateAnimation(DeltaSeconds);
// 上記 NativeUpdateAnimation で書き込まれた UPROPERTY メンバーのみ読み取り可能。
// BlueprintThreadSafe とマークされていない UObject 関数を呼び出さないこと。
}
FAnimInstanceProxy — スレッドセーフアクセス
重いアニメーションロジックは NativeThreadSafeUpdateAnimation を介してワーカースレッドで実行できます。プロキシを通じて共有データにアクセスします:
void UMyAnimInstance::NativeThreadSafeUpdateAnimation(float DeltaSeconds)
{
FMyAnimInstanceProxy& Proxy = GetProxyOnAnyThread<FMyAnimInstanceProxy>();
Proxy.Speed = Proxy.Velocity.Size();
Proxy.bIsFalling = Proxy.MovementMode == EMovementMode::MOVE_Falling;
}
// FAnimInstanceProxy 宣言 — ワーカースレッドデータコンテナ
USTRUCT()
struct FMyAnimInstanceProxy : public FAnimInstanceProxy
{
GENERATED_BODY()
FMyAnimInstanceProxy() = default;
explicit FMyAnimInstanceProxy(UAnimInstance* Instance) : FAnimInstanceProxy(Instance) {}
float Speed = 0.f;
FVector Velocity = FVector::ZeroVector;
TEnumAsByte<EMovementMode> MovementMode = MOVE_None;
virtual void PreUpdate(UAnimInstance* AnimInstance, float DeltaSeconds) override;
virtual void Update(float DeltaSeconds) override;
};
// UMyAnimInstance 内: CreateAnimInstanceProxy をオーバーライドしてプロキシを返す
virtual FAnimInstanceProxy* CreateAnimInstanceProxy() override
{ return new FMyAnimInstanceProxy(this); }
エンジンは安全な同期ポイントでゲームスレッドとワーカースレッド間でデータをコピーします。
モンタージュ
ソース: AnimMontage.h、AnimInstance.h
主要 API (UAnimInstance):
float Montage_Play(UAnimMontage*, float PlayRate=1.f,
EMontagePlayReturnType=MontageLength, float StartAt=0.f, bool bStopAll=true);
void Montage_Stop(float BlendOut, const UAnimMontage* Montage=nullptr);
void Montage_Pause(const UAnimMontage* Montage=nullptr);
void Montage_Resume(const UAnimMontage* Montage);
void Montage_JumpToSection(FName Section, const UAnimMontage* Montage=nullptr);
void Montage_SetNextSection(FName From, FName To, const UAnimMontage* Montage=nullptr);
bool Montage_IsActive(const UAnimMontage*) const;
bool Montage_IsPlaying(const UAnimMontage*) const;
FName Montage_GetCurrentSection(const UAnimMontage* Montage=nullptr) const;
float Montage_GetPosition(const UAnimMontage*) const;
再生 + デリゲートパターン
void UMyComponent::PlayAttackMontage(UAnimMontage* Montage)
{
UAnimInstance* AnimInst = GetMesh()->GetAnimInstance();
if (!AnimInst || !Montage) return;
// 最初に再生 — Montage_SetEndDelegate は内部的に GetActiveInstanceForMontage() を
// 呼び出しますが、これは Montage_Play がインスタンスを作成するまで nullptr を返します。
if (AnimInst->Montage_Play(Montage) <= 0.f) return;
FOnMontageEnded EndDelegate;
EndDelegate.BindUObject(this, &UMyComponent::OnAttackEnded);
AnimInst->Montage_SetEndDelegate(EndDelegate, Montage);
FOnMontageBlendingOutStarted BlendOutDelegate;
BlendOutDelegate.BindUObject(this, &UMyComponent::OnAttackBlendingOut);
AnimInst->Montage_SetBlendingOutDelegate(BlendOutDelegate, Montage);
}
void UMyComponent::OnAttackEnded(UAnimMontage* Montage, bool bInterrupted) { }
void UMyComponent::OnAttackBlendingOut(UAnimMontage* Montage, bool bInterrupted) { }
動的スロットモンタージュ
UAnimMontage* DynMontage = AnimInst->PlaySlotAnimationAsDynamicMontage(
SomeSequence, FName("UpperBody"), 0.25f, 0.25f, 1.f, 1);
マルチプレイヤー複製
- GAS あり:
UAbilitySystemComponent::PlayMontage()を使用 — GAS がFGameplayAbilityRepAnimMontageを介して複製を処理します。 - GAS なし: モンタージュポインターまたはカスタム rep 構造体を複製。サーバーが
Montage_Playを呼び出し、クライアントがOnRep_で再生します。 - 同期なしですべてのネットロールで独立して
Montage_Playを呼び出さないでください。
GAS 統合 — PlayMontageAndWait
// GAS アビリティタスク — PlayMontageAndWait (GameplayAbilities モジュールが必要)
UAbilityTask_PlayMontageAndWait* Task =
UAbilityTask_PlayMontageAndWait::CreatePlayMontageAndWaitProxy(
this, NAME_None, AttackMontage, 1.f);
Task->OnCompleted.AddDynamic(this, &UMyAbility::OnMontageCompleted);
Task->OnInterrupted.AddDynamic(this, &UMyAbility::OnMontageInterrupted);
Task->ReadyForActivation(); // タスクを開始するために呼び出す必要あり
ブレンドスペース
ブレンドスペースは AnimGraph でサンプリングされるデータアセットです。AnimInstance の UPROPERTY メンバーを設定することで駆動し、AnimGraph がそれを読み取ります。
- 1D (
UBlendSpace1D): 単一軸、通常は速度 (0–600)。InterpolationType=SpringDamper、InterpolationTime=0.15、DampingRatio=1.0のFInterpolationParameterを使用します。 - 2D (
UBlendSpace): 2 軸 — 方向 (-180 ~ 180) と速度 (0–600)。 各速度階層でのカーディナル方向サンプル。 - Aim Offset (
UAimOffsetBlendSpace): ヨー/ピッチ照準用の加算ブレンドスペース。AnimGraph の基本ロコモーションポーズの後に配置します。
完全な軸構成とサンプル配置については references/locomotion-setup.md を参照してください。
ステートマシン
ステートマシンは AnimGraph に存在します。Blueprint を使用せずに遷移ルールとステートエントリ/終了にネイティブ C++ ロジックをバインドします:
// NativeInitializeAnimation() 内
AddNativeTransitionBinding(
FName("LocomotionSM"), FName("Idle"), FName("Walk/Run"),
FCanTakeTransition::CreateUObject(this, &UMyAnimInstance::CanStartMoving),
FName("IdleToMoving"));
AddNativeStateEntryBinding(
FName("LocomotionSM"), FName("Land"),
FOnGraphStateChanged::CreateUObject(this, &UMyAnimInstance::OnLandEntered));
実行時にステートマシンをクエリ:
const FAnimNode_StateMachine* SM =
GetStateMachineInstanceFromName(FName("LocomotionSM"));
float RunWeight = GetInstanceStateWeight(
GetStateMachineIndex(FName("LocomotionSM")), SM->GetCurrentState());
コンジットノード
コンジットは単一のブールルールを評価し、複数の宛先ステートに分岐します — 重複した遷移ロジックを置き換えます。AnimGraph エディタでコンジットを追加します。その CanEnterTransition は 1 回実行され、すべての出力遷移が結果を共有します。3 つ以上のステートが同じエントリ条件 (例: "接地しているか?") を必要とする場合にコンジットを使用します。単純な A から B への遷移には、直接ルールの方が明確です。
アニム通知
ソース: AnimNotify.h、AnimNotifyState.h
UAnimNotify — 時点通知
UCLASS(meta=(DisplayName="足音"))
class MYGAME_API UFootstepNotify : public UAnimNotify
{
GENERATED_BODY()
public:
// 常に UE5 の 3 引数シグネチャをオーバーライド
virtual void Notify(USkeletalMeshComponent* MeshComp,
UAnimSequenceBase* Animation,
const FAnimNotifyEventReference& EventReference) override;
UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="足音")
FName FootSocket = FName("foot_l");
};
UAnimNotifyState — 期間 (開始/更新/終了)
UCLASS(meta=(DisplayName="武器衝突ウィンドウ"))
class MYGAME_API UWeaponCollisionState : public UAnimNotifyState
{
GENERATED_BODY()
public:
virtual void NotifyBegin(USkeletalMeshComponent*, UAnimSequenceBase*,
float TotalDuration, const FAnimNotifyEventReference&) override;
virtual void NotifyEnd(USkeletalMeshComponent*, UAnimSequenceBase*,
const FAnimNotifyEventReference&) override;
};
BranchingPoint (同期)
コンストラクタで bIsNativeBranchingPoint = true を設定します。Notify() の代わりに BranchingPointNotify() をオーバーライドします。Montage_Advance 中に同期的に発火します — セクションジャンプや正確なタイムライン制御に使用します。他のすべての通知はキューイングされます (tick 完了後に発火し、VFX/SFX に安全)。
名前付き通知デリゲート
AnimInst->OnPlayMontageNotifyBegin.AddDynamic(
this, &UMyComponent::HandleNotifyBegin);
void UMyComponent::HandleNotifyBegin(FName NotifyName,
const FBranchingPointNotifyPayload& Payload)
{
if (NotifyName == FName("EnableHitbox")) ActivateHitDetection();
}
組み込み通知カタログとその他のカスタムパターンについては references/anim-notify-reference.md を参照してください。
IK とプロシージャル
ライン トレースによるフット IK (NativeUpdateAnimation — ゲームスレッド)
FVector UMyAnimInstance::GetFootTarget(FName SocketName) const
{
const FVector Foot = GetOwningComponent()->GetSocketLocation(SocketName);
FHitResult Hit;
FCollisionQueryParams P(SCENE_QUERY_STAT(FootIK), true);
P.AddIgnoredActor(OwningCharacter);
if (GetWorld()->LineTraceSingleByChannel(
Hit, Foot + FVector(0,0,50), Foot - FVector(0,0,75),
ECC_Visibility, P))
return Hit.ImpactPoint;
return Foot;
}
結果を Control Rig アセット (UE5 推奨) または AnimGraph の Two Bone IK スケルタルコントロールノードにフィードします。
スケルタルコントロールノード (AnimGraph):
| ノード | 目的 |
|---|---|
| Two Bone IK | 2 ジョイント IK (腕、脚) — エフェクタ + ジョイントターゲット |
| FABRIK | マルチボーン チェーン IK — 先端ボーン + エフェクタ |
| Look At | 単一ボーンがクランプ付きでターゲット位置を追跡 |
| Copy Bone | ボーン間でトランスフォーム コンポーネントをコピー |
| Spline IK | ボーンがスプライン曲線に沿って追従 (脊椎、尾) |
ボーンごとのレイヤードブレンド (上半身/下半身分割)
AnimGraph 内:
- ステートマシンの出力を Base Pose に接続。
UpperBodyスロット出力を Blend Poses 0 に接続。- レイヤー設定: Bone=
spine_01、Depth=0、MeshPoseBlendFactor=1.0。
攻撃モンタージュは UpperBody スロットを使用し、ロコモーションはその下で中断なく再生されます。
Aim Offset
// NativeUpdateAnimation 内:
const FRotator Delta = UKismetMathLibrary::NormalizedDeltaRotator(
OwningCharacter->GetBaseAimRotation(),
OwningCharacter->GetActorRotation());
AimYaw = FMath::Clamp(Delta.Yaw, -90.f, 90.f);
AimPitch = FMath::Clamp(Delta.Pitch, -90.f, 90.f);
AnimGraph の基本ポーズの後に Aim Offset ノードを配置し、AimYaw と AimPitch をフィードします。
リンクアニムグラフとレイヤー
ソース: AnimNode_LinkedAnimGraph.h、AnimNode_LinkedAnimLayer.h
リンクアニムレイヤー (推奨)
- レイヤー関数シグネチャを持つ
UAnimLayerInterfaceBlueprint を作成します。 - メイン AnimInstance はインターフェースを参照する Linked Anim Layer ノードを持ちます。
- 個別の AnimInstance サブクラスがモードごとにインターフェースを実装します。
- 実行時に切り替え:
// ロコモーション実装を切り替え
AnimInst->LinkAnimClassLayers(UClimbingLocomotionLayer::StaticClass());
// すべてのレイヤーをデフォルトにリセット:
AnimInst->LinkAnimClassLayers(nullptr);
// リンクされたインスタンスを取得:
UAnimInstance* Layer =
AnimInst->GetLinkedAnimLayerInstanceByClass(UClimbingLocomotionLayer::StaticClass());
リンクアニムグラフ (タグ別)
AnimInst->LinkAnimGraphByTag(FName("CombatGraph"), UMyCombatAnimInstance::StaticClass());
UAnimInstance* Sub = AnimInst->GetLinkedAnimGraphInstanceByTag(FName("CombatGraph"));
通知の伝達
AnimInst->SetReceiveNotifiesFromLinkedInstances(true);