FAnimNode_KawaiiPhysics

KawaiiPhysicsのメインAnimGraphノードのAPIリファレンスです。

ソースを見る

クラス定義

USTRUCT(BlueprintType)
struct KAWAIIPHYSICS_API FAnimNode_KawaiiPhysics : public FAnimNode_SkeletalControlBase

Bones（ボーン設定）

プロパティ	型	デフォルト	説明
RootBone	FBoneReference	-	制御対象のルートボーン（子孫ボーンも対象）
ExcludeBones	TArray<FBoneReference>	-	制御から除外するボーン（指定ボーンとその子孫）
AdditionalRootBones	TArray<FKawaiiPhysicsRootBoneSetting>	-	追加のルートボーン設定
DummyBoneLength	float	0.0	末端ボーンの回転を改善するための末端ダミーボーン長（0で無効、ClampMin=0）
BoneForwardAxis	EBoneForwardAxis	X_Positive	ボーンの前方向軸（ダミーボーン配置に影響）
ModifyBones	TArray<FKawaiiPhysicsModifyBone>	-	（ランタイム / Transient）物理制御対象ボーンのキャッシュ

Bones | Bone Subdivision（ボーン分割）

プロパティ	型	デフォルト	説明
BoneSubdivisionCount	int32	0	ボーン間ダミー分割数（ClampMin=0, ClampMax=10、0で無効）
bBoneSubdivisionCollisionOnly	bool	true	ボーン間ダミーを速度積分から除外しコリジョン/制約専用にする
bBoneSubdivisionDensifyByRadius	bool	false	BoneSubdivisionCount を最小として、ボーン間が半径に対して離れた区間ほどダミーを多く追加配置（1区間最大50本）。有効中に Radius / RadiusCurve を変更した場合はダミー数の再計算に再初期化（ABP再コンパイル等）が必要なことがある
BoneConstraintSubdivisionCount	int32	0	横方向BoneConstraintに沿ったコリジョンプロキシダミー数（ClampMin=0, ClampMax=10、0で無効）
BoneConstraintSubdivisionFeedbackScale	float	1.0	bridgeダミーのコリジョン変位を端点ボーンへ伝える強度（ClampMin=0.0, ClampMax=2.0）

Physics Settings（物理設定）

プロパティ	型	デフォルト	説明
PhysicsSettings	FKawaiiPhysicsSettings	-	物理制御の基本設定（Damping / Stiffness / Radius など）
SimulationSpace	EKawaiiPhysicsSimulationSpace	ComponentSpace	シミュレーション空間
SimulationBaseBone	FBoneReference	-	BaseBoneSpace 選択時の基準ボーン
TargetFramerate	int32	60	物理ステップのターゲットフレームレート（ClampMin=1）
TeleportDistanceThreshold	float	300.0	この距離以上の移動でテレポート扱いにする
TeleportRotationThreshold	float	10.0	この角度以上の回転でテレポート扱いにする
PlanarConstraint	EPlanarConstraint	None	各ボーンを平面上に拘束する
SkelCompMoveScale	FVector	(1, 1, 1)	コンポーネント移動を物理へ反映する際のスケール
WarmUpFrames	int32	0	ウォームアップフレーム数（bNeedWarmUp有効時）
bNeedWarmUp	bool	false	ウォームアップの有効化
bUseWarmUpWhenResetDynamics	bool	true	ResetDynamics時にウォームアップを行う
bUpdatePhysicsSettingsInGame	bool	true	毎フレーム各ボーンの物理パラメータを更新（AdvancedDisplay、無効化で軽量化）
ResetBoneTransformWhenBoneNotFound	bool	false	制御対象ボーンが見つからない場合にTransformをリセット（AdvancedDisplay）

Physics Settings | Curves（カーブ）

プロパティ	型	エディタ表示名	説明
DampingCurveData	FRuntimeFloatCurve	Damping Rate by Bone Length Rate	減衰カーブ
StiffnessCurveData	FRuntimeFloatCurve	Stiffness Rate by Bone Length Rate	剛性カーブ
WorldDampingLocationCurveData	FRuntimeFloatCurve	World Damping Location Rate by Bone Length Rate	ワールド位置減衰カーブ
WorldDampingRotationCurveData	FRuntimeFloatCurve	World Damping Rotation Rate by Bone Length Rate	ワールド回転減衰カーブ
RadiusCurveData	FRuntimeFloatCurve	Radius Rate by Bone Length Rate	半径カーブ
LimitAngleCurveData	FRuntimeFloatCurve	LimitAngle Rate by Bone Length Rate	角度制限カーブ

すべて RootBone からのボーン長比（0.0〜1.0）に応じて各パラメータへ乗算されます（AdvancedDisplay）。

Limits（コリジョン）

プロパティ	型	説明
SphericalLimits	TArray<FSphericalLimit>	球体コリジョン
CapsuleLimits	TArray<FCapsuleLimit>	カプセルコリジョン
BoxLimits	TArray<FBoxLimit>	ボックスコリジョン
PlanarLimits	TArray<FPlanarLimit>	平面コリジョン
LimitsDataAsset	UKawaiiPhysicsLimitsDataAsset*	コリジョンData Asset（共有可能）
PhysicsAssetForLimits	UPhysicsAsset*	コリジョンソースとして使うPhysics Asset

注記

SphericalLimitsData / CapsuleLimitsData / BoxLimitsData / PlanarLimitsData は、LimitsDataAsset や PhysicsAssetForLimits から取り込んだコリジョンをプレビュー表示する 読み取り専用（Transient / VisibleAnywhere） の配列です。直接編集はできません。

Limits | Shared Collision（共有コリジョン）

プロパティ	型	デフォルト	説明
bSharedCollisionSource	bool	false	コリジョンを公開する（Source）
bUseSharedCollision	bool	false	共有コリジョンを使用する（Target）
SharedCollisionGroupTag	FGameplayTag	-	共有グループの識別タグ

Limits | Bone Constraint（ボーン制約）

プロパティ	型	デフォルト	説明
BoneConstraintGlobalComplianceType	EXPBDComplianceType	Leather	剛性タイプ
BoneConstraintIterationCountBeforeCollision	int32	1	コリジョン前処理回数
BoneConstraintIterationCountAfterCollision	int32	1	コリジョン後処理回数
bAutoAddChildDummyBoneConstraint	bool	true	ダミーボーン自動追加
BoneConstraints	TArray<FModifyBoneConstraint>	-	ボーン制約リスト
BoneConstraintsDataAsset	UKawaiiPhysicsBoneConstraintsDataAsset*	-	制約Data Asset

Limits | World Collision（ワールドコリジョン）

プロパティ	型	デフォルト	説明
bAllowWorldCollision	bool	false	ワールドコリジョン有効化（有効にすると物理負荷が大幅に上がる）
bOverrideCollisionParams	bool	false	独自のコリジョン設定を使用する（CollisionChannelSettings のインライントグル）
CollisionChannelSettings	FBodyInstance	-	独自コリジョン設定（表示名: Override SkelComp Collision Params、bOverrideCollisionParams 有効時のみ）
bIgnoreSelfComponent	bool	true	自己コリジョン（PhysicsAsset）を無視（編集条件: bAllowWorldCollision）
IgnoreBones	TArray<FBoneReference>	-	無視ボーンリスト（編集条件: !bIgnoreSelfComponent）
IgnoreBoneNamePrefix	TArray<FName>	-	無視ボーン名プリフィックス（編集条件: !bIgnoreSelfComponent）

Force（外部力）

プロパティ	型	デフォルト	説明
Gravity	FVector	ZeroVector	重力ベクトル
bUseLegacyGravity	bool	false	レガシー重力方式
bUseDefaultGravityZProjectSetting	bool	false	プロジェクト設定の重力使用
bUseWorldSpaceGravity	bool	true	ワールド空間重力
bEnableWind	bool	false	風の有効化（WindDirectionalSource の影響を受ける）
WindScale	float	1.0	風のスケール（編集条件: bEnableWind）
WindDirectionNoiseAngle	float	0.0	風方向ノイズ（度、編集条件: bEnableWind）

Force | External Force（外力プリセット）

プロパティ	型	デフォルト	説明
SimpleExternalForce	FVector	ZeroVector	単純な外力
bUseWorldSpaceSimpleExternalForce	bool	true	ワールド空間外力
ExternalForces	TArray<FInstancedStruct>	-	外力プリセット（Instanced Struct、C++で拡張可能）
CustomExternalForces	TArray<UKawaiiPhysics_CustomExternalForce*>	-	BP/C++オブジェクト型の外力プリセット（実験的）

Force | Sync Bone（同期ボーン）

プロパティ	型	説明
SyncBones	TArray<FKawaiiPhysicsSyncBone>	同期ボーンリスト。詳細は Sync Bone を参照

Tag（タグ）

プロパティ	型	説明
KawaiiPhysicsTag	FGameplayTag	フィルタリング用タグ

KawaiiPhysics（ランタイム）

プロパティ	型	説明
DeltaTime	float	フレームのデルタタイム（BlueprintReadOnly）

主要メソッド

Initialize_AnyThread

virtual void Initialize_AnyThread(const FAnimationInitializeContext& Context) override;

ノードの初期化処理。ボーンチェーンの構築やパラメータの初期化を行います。

CacheBones_AnyThread

virtual void CacheBones_AnyThread(const FAnimationCacheBonesContext& Context) override;

ボーン参照のキャッシュ処理。

UpdateInternal

virtual void UpdateInternal(const FAnimationUpdateContext& Context) override;

フレームごとの更新処理。

EvaluateSkeletalControl_AnyThread

virtual void EvaluateSkeletalControl_AnyThread(
    FComponentSpacePoseContext& Output,
    TArray<FBoneTransform>& OutBoneTransforms
) override;

物理シミュレーションの評価とボーン変換の出力。

ResetDynamics

virtual void ResetDynamics(ETeleportType InTeleportType) override;

物理状態のリセット。テレポート時などに使用します。

HasPreUpdate / PreUpdate

virtual bool HasPreUpdate() const override;
virtual void PreUpdate(const UAnimInstance* InAnimInstance) override;

GameThread 上で呼ばれる前処理です。ワーカースレッドから UObject へ安全にアクセスできない処理をここで行います。

• 共有コリジョンの初期化（InitializeSharedCollision）: Subsystem への登録は TMap の変更を伴うため、スレッドセーフな GameThread 側で実行されます
• 警告ログ用の識別名（AnimInstance クラス名・コンポーネント名・オーナー Actor 名）を初回 1 回だけ収集します（AnyThread からの UObject アクセスを回避）

注記

HasPreUpdate() が true を返すノードのみ PreUpdate() が呼ばれます。物理シミュレーション本体はワーカースレッド上の EvaluateSkeletalControl_AnyThread で実行され、PreUpdate は GameThread 限定の初期化・キャッシュ収集に徹しています。

IsValidToEvaluate

virtual bool IsValidToEvaluate(
    const USkeleton* Skeleton,
    const FBoneContainer& RequiredBones
) override;

ノードが評価可能かを判定します。

GatherDebugData

virtual void GatherDebugData(FNodeDebugData& DebugData) override;

デバッグ情報の収集。

NeedsDynamicReset

virtual bool NeedsDynamicReset() const override { return true; }

ResetDynamics（テレポート対応）が呼ばれるよう常に true を返します。

ランタイム再初期化

RequestModifyBonesReinit / RequestSharedCollisionReinit

void RequestModifyBonesReinit();      // 次回Evaluateでボーンチェーンを再構築
void RequestSharedCollisionReinit();  // 次回Evaluateで共有コリジョンを再初期化

ランタイムでトポロジやコリジョン構成に影響する設定を変更した際に、安全な再初期化を予約します（フラグを立て、次回の Evaluate で実行）。UKawaiiPhysicsLibrary の各 Setter から内部的に呼ばれます。

座標変換ヘルパー

GetBoneTransformInSimSpace

FTransform GetBoneTransformInSimSpace(
    FComponentSpacePoseContext& Output,
    const FCompactPoseBoneIndex& BoneIndex
) const;

ボーンのTransformをシミュレーション空間で取得します。

ConvertSimulationSpaceTransform

FTransform ConvertSimulationSpaceTransform(
    FComponentSpacePoseContext& Output,
    EKawaiiPhysicsSimulationSpace From,
    EKawaiiPhysicsSimulationSpace To,
    const FTransform& InTransform
) const;

シミュレーション空間間でTransformを変換します。型ごとに以下のバリエーションがあります。

FVector ConvertSimulationSpaceVector(...) const;     // 方向ベクトルの変換
FVector ConvertSimulationSpaceLocation(...) const;   // 位置の変換
FQuat   ConvertSimulationSpaceRotation(...) const;   // 回転の変換
void    ConvertSimulationSpace(FComponentSpacePoseContext& Output,
            EKawaiiPhysicsSimulationSpace From, EKawaiiPhysicsSimulationSpace To); // 全ボーンを一括変換

型リファレンス（Enum / Struct）

主要なプロパティが参照する列挙型・構造体の定義です。

FKawaiiPhysicsSettings

物理制御の中心となる設定構造体です（PhysicsSettings プロパティ）。Damping（揺れやすさ）と Stiffness（戻りやすさ）のバランスで全体の柔らかさが決まります。各メンバーはボーン長比に応じてカーブ（DampingCurveData 等）で補正できます。

メンバー	型	デフォルト	範囲	説明
Damping	float	0.1	0以上	減衰度。小さいほど加速度が強く反映され、よく揺れる
Stiffness	float	0.05	0以上	剛性度。大きいほど元のポーズ（アニメーション）を強く維持する
WorldDampingLocation	float	0.8	0以上	コンポーネント移動の反映抑制。0=フル反映（最大に揺れる）／1=追従（揺れなし）。反映率 = 1 - 値
WorldDampingRotation	float	0.8	0以上	コンポーネント回転の反映抑制（上と同様、反映率 = 1 - 値）
Radius	float	3.0	0以上	各ボーンのコリジョン半径（エディタ表示名: Collision Radius）
LimitAngle	float	0.0	0以上	物理挙動による1ステップあたりの回転角度の上限（度）。0で無制限、荒ぶり抑制に有効

注記

WorldDampingLocation / WorldDampingRotation は名前に反して 値が大きいほど揺れは小さく なります（1 でコンポーネントに完全追従＝揺れなし）。

各メンバーの詳しい解説と図解は 物理パラメータ を参照してください。

EKawaiiPhysicsSimulationSpace

値	説明
ComponentSpace	スケルタルメッシュコンポーネント基準（デフォルト）
WorldSpace	ワールド基準。ルートボーンの急激な移動による問題を回避
BaseBoneSpace	指定した基準ボーン（SimulationBaseBone）基準

EPlanarConstraint

値	説明
None	制約なし（デフォルト）
X	X軸平面に拘束
Y	Y軸平面に拘束
Z	Z軸平面に拘束

EBoneForwardAxis

X_Positive（デフォルト）/ X_Negative / Y_Positive / Y_Negative / Z_Positive / Z_Negative

EXPBDComplianceType

Bone Constraint の剛性マテリアルタイプ（BoneConstraintGlobalComplianceType）。

Concrete / Wood / Leather（デフォルト）/ Tendon / Rubber / Muscle / Fat

ヒント

コリジョン形状（FSphericalLimit 等）や Sync Bone（FKawaiiPhysicsSyncBone）、Bone Constraint（FModifyBoneConstraint）の各メンバー詳細は、機能別ページを参照してください。

使用例

Animation Blueprintでの基本的な使用方法:

1. AnimGraphにKawaiiPhysicsノードを追加
2. RootBoneを設定
3. PhysicsSettingsでDamping/Stiffnessを調整
4. 必要に応じてコリジョンを追加

// C++からのアクセス例
FAnimNode_KawaiiPhysics* Node = ...;
Node->PhysicsSettings.Damping = 0.2f;
Node->PhysicsSettings.Stiffness = 0.1f;
Node->Gravity = FVector(0, 0, -980.0f);

関連

• パラメータリファレンス
• UKawaiiPhysicsLibrary
• Physics パラメータ
• Collision パラメータ