UKawaiiPhysicsLibrary — ノード属性とプリセット
この機能はまだ正式リリースされていません。KawaiiPhysics v1.22でリリース予定です。開発中のため仕様が変更される場合があります。
概要
ゲームイベントで髪の重力方向を変え、イベント終了時に戻すなど、実行中のノード設定をBlueprintから読み書きできます。ノードタグで部位を選び、型に合うSet／Get関数で値を扱います。アセットに保存する設定の編集はUKawaiiPhysicsEditorLibraryを使います。
Gravityの変更例
CollectKawaiiPhysicsNodesFromComponentへ対象メッシュとFilterTagsを渡し、ノード参照を取得します。- 各参照の
GetNodeVectorPropertyへPropertyName = Gravityを渡し、元の値を保持します。 SetNodeVectorPropertyへ新しいFVectorを渡し、ExecResultで成否を扱います。- イベント終了時に、保持した値を同じSetterへ渡します。
通常の属性変更は自動で復元されません。期間終了で解除する効果にはSettings Multiplierなどの一時効果APIを使えます。
v1.21との違い
Alphaの変更・取得、外力の追加・削除、外力属性の型別／Wildcardアクセス、C++のノード収集はv1.21にもあります。今回の追加はノード本体の属性アクセスや新機能へのAPIです。ボーン分割や固定サブステップ自体も既存機能です。
| 旧名（非推奨・引き続き動作） | 開発版で推奨する名前 |
|---|---|
SetAlphaToComponent | SetAlphaOnComponent |
GetAlphaFromComponent | GetAlphaOnComponent |
AddExternalForcesToComponent | AddExternalForcesOnComponent |
RemoveExternalForcesFromComponent | RemoveExternalForcesOnComponent |
単一ノードへのAddExternalForceも非推奨です。AddExternalForceWithExecResultではEKawaiiPhysicsAccessExternalForceResultのValid／NotValid分岐で成否を扱えます。名前変更だけを新しい物理挙動と解釈しないでください。
対象ノードの取得
ConvertToKawaiiPhysicsはFAnimNodeReferenceをFKawaiiPhysicsReferenceへ変換します。Blueprintに公開されたCollectKawaiiPhysicsNodesFromAnimInstance／CollectKawaiiPhysicsNodesFromComponentは、参照配列Nodesと収集成否を返します。Component側は本体のAnimInstanceに加え、Linked AnimInstanceとPostProcessを対象にします。
FilterTagsは各ノードのKawaiiPhysicsTagで絞る条件です。空なら全件、bFilterExactMatchの既定はfalseです。複数対象へのSet Alphaは一致ノード全件、Get Alphaは最初の一致ノード1件を扱います。
型別・Wildcardの属性アクセス
BlueprintのKawaii Physicsカテゴリに、次のSet／Getペアがあります。PropertyNameには表示名ではなくソースのFNameを渡し、ExecResultを必ず確認します。
| 値の型 | API名の共通部分 |
|---|---|
| bool / int32 / float | NodeBoolProperty / NodeIntProperty / NodeFloatProperty |
| FVector / FRotator / FTransform | NodeVectorProperty / NodeRotatorProperty / NodeTransformProperty |
| FName / FGameplayTag | NodeNameProperty / NodeGameplayTagProperty |
| ピンに接続した型 | NodeWildcardProperty |
名前指定で任意の内部値を変更できるわけではありません。対象はFAnimNode_KawaiiPhysics自身が持つ、プリセットの属性分類で許可された項目です。Transient／EditorOnlyや拒否対象を除外し、型別APIは期待型、Wildcardはプロパティとピンの同一型を要求します。変更する属性に応じてボーン・共有コリジョン・Simple World Collisionの再初期化が要求されます。
WildcardはBlueprint用のCustomThunkです。ヘッダー上のint32仮引数を「どの型にも使えるC++関数」として直接呼び出さないでください。C++向けの文字列／低レベルヘルパーはUFUNCTIONを持たず、Blueprint公開APIとは区別します。
プリセットと機能別制御
ApplyPresetDataAsset(ExecResult, KawaiiPhysics, Preset, Options)はUKawaiiPhysicsPresetDataAssetをランタイムノードへ適用します。安全のためExternalForcesとCustomExternalForcesは除外します。外力まで一括置換するEditor操作とは同じ範囲ではありません。
| 用途 | 代表API／参照先 |
|---|---|
| Simple World Collisionの切替 | SetUseSimpleWorldCollision、SetSimpleWorldCollisionSource、SetSimpleWorldCollisionSharedTag、SetSimpleWorldCollisionGatherInterval → Simple World Collision |
| コリジョンの左右生成 | SetMirrorDataTableForLimits（設定 Mirror Data Table for Collision に対応）、SetSkipMirroredBoneWithExistingCollision |
| Procedural Wind | SetProceduralWindParameters／OnComponent、ApplyProceduralWindPreset／OnComponent → Procedural Wind |
| 一時効果 | StartPhysicsSettingsMultiplier／OnComponent、AddTransientExternalForce／OnComponent、対応するStop API |
| Shared Publisher | SetSharedPublisherEnabled、SetSimpleWorldCollisionSettingsOnSharedPublisher、風のOnSharedPublisher API |
GenerateTransientHandleとPushPhysicsSettingsMultiplier系はC++用で、Blueprintノードとしては公開されていません。一時効果の寿命・ブレンド・ハンドル管理は機能別説明に従ってください。
呼び出しタイミング
BlueprintThreadSafeは別スレッドとの同期を自動で作る印ではありません。ノード属性アクセスは参照先へ即時実行します。AnimGraphの適切なThreadSafe文脈、または対象が評価中でないGameThreadから呼んでください。収集をAnimGraphから行う場合は呼び出し元自身のAnimInstance／Componentに限定し、他のオブジェクトは評価されていないGameThreadで扱います。
個々のAPIには別の制約があります。診断はGameThread専用、風のパラメータ更新はPendingRequest経由です。属性APIで共有時計・外力の内部状態を書き換える代わりに、対応する専用APIを使ってください。
ランタイム適用
Blueprint公開の UKawaiiPhysicsLibrary::ApplyPresetDataAsset はノード参照、プリセット、適用オプションを受け取り、ExecResultでアクセス結果を返します。ExternalForcesとCustomExternalForcesは安全性のためコピーしません。
適用後はModifyBonesとShared Collisionの再初期化を要求します。期間終了で元へ戻る効果ではなく、ノード設定の適用です。一時効果はSettings Multiplier、スレッド・評価文脈の条件はUKawaiiPhysicsLibraryを確認してください。
関連するUE公式ドキュメント
- Animation Blueprintのノード — AnimGraphのノード追加・接続・Details編集を確認できます。 (UE 5.7) UE5.8版（英語）も参照できます。日本語ページの表示版は5.7です。