Skip to main content

UKawaiiPhysicsLibrary — Node Properties and Presets

Not officially released

This feature has not been officially released yet. It is planned for KawaiiPhysics v1.22. Specifications may change during development.

Overview​

Read and write running node settings from Blueprint, for example to change hair gravity during a gameplay event and restore it when the event ends. Select the part by node tags and use the matching typed Set/Get functions. For settings stored in assets, use UKawaiiPhysicsEditorLibrary.

Gravity Change Example​

  1. Pass the target mesh and FilterTags to CollectKawaiiPhysicsNodesFromComponent to obtain node references.
  2. For each reference, call GetNodeVectorProperty with PropertyName = Gravity and retain the original value.
  3. Pass the new FVector to SetNodeVectorProperty and handle its ExecResult.
  4. When the event ends, pass the retained value to the same Setter.

Ordinary property changes do not restore themselves. For effects released when their duration ends, use a transient API such as Settings Multiplier.

Changes since v1.21​

Alpha access, external-force add/remove operations, typed/wildcard external-force property access, and C++ node collection already exist in v1.21. The additions here include property access on the node itself and APIs for the new features. Bone subdivision and fixed substepping are also existing physics features.

Old name (deprecated, still works)Recommended development name
SetAlphaToComponentSetAlphaOnComponent
GetAlphaFromComponentGetAlphaOnComponent
AddExternalForcesToComponentAddExternalForcesOnComponent
RemoveExternalForcesFromComponentRemoveExternalForcesOnComponent

The single-node AddExternalForce is deprecated too. AddExternalForceWithExecResult exposes Valid/NotValid execution branches through EKawaiiPhysicsAccessExternalForceResult. Renamed functions do not introduce new physical behavior by themselves.

Querying Target Nodes​

ConvertToKawaiiPhysics converts an FAnimNodeReference to an FKawaiiPhysicsReference. The Blueprint-exposed CollectKawaiiPhysicsNodesFromAnimInstance and CollectKawaiiPhysicsNodesFromComponent fill the Nodes reference array and return collection success. The component form includes its main AnimInstance, linked instances, and post-process instance.

FilterTags matches each node's KawaiiPhysicsTag. Empty filters collect all nodes; bFilterExactMatch defaults to false. Component Set Alpha affects all matching nodes; Get Alpha reads the first matching node only.

Existing Warm Up Blueprint passes left and right node references through Convert to Kawaii Physics into Set Need Warm Up
Existing documentation's Warm Up example, reused to explain passing the intended node reference. It does not show the new named-property setter UI.

Typed and wildcard property access​

The Blueprint Kawaii Physics category includes these Set/Get pairs. Pass the source property's internal FName as PropertyName, rather than its display label, and check ExecResult.

Value typeShared part of the API name
bool / int32 / floatNodeBoolProperty / NodeIntProperty / NodeFloatProperty
FVector / FRotator / FTransformNodeVectorProperty / NodeRotatorProperty / NodeTransformProperty
FName / FGameplayTagNodeNameProperty / NodeGameplayTagProperty
Type connected to the pinNodeWildcardProperty

Named access does not allow arbitrary internal fields. A property must belong to FAnimNode_KawaiiPhysics itself and pass preset property classification. Transient, EditorOnly, and explicitly denied properties are excluded. Typed functions require the expected type; wildcard access requires the pin and property types to match. Relevant setters request bone, shared-collision, or Simple World Collision reinitialization when needed.

Wildcard functions use Blueprint CustomThunk. Do not call the header's placeholder int32 signature as a generic C++ function. String and low-level C++ helpers without UFUNCTION are separate from Blueprint-exposed APIs.

Presets and feature controls​

ApplyPresetDataAsset(ExecResult, KawaiiPhysics, Preset, Options) applies a UKawaiiPhysicsPresetDataAsset to a runtime node. It excludes ExternalForces and CustomExternalForces for safety; its scope differs from an editor operation that replaces forces as well.

PurposeRepresentative APIs / details
Simple World CollisionSetUseSimpleWorldCollision, SetSimpleWorldCollisionSource, SetSimpleWorldCollisionSharedTag, SetSimpleWorldCollisionGatherInterval → Simple World Collision
Mirrored collision generationSetMirrorDataTableForLimits (corresponds to Mirror Data Table for Collision), SetSkipMirroredBoneWithExistingCollision
Procedural WindSetProceduralWindParameters/OnComponent, ApplyProceduralWindPreset/OnComponent → Procedural Wind
Temporary effectsStartPhysicsSettingsMultiplier/OnComponent, AddTransientExternalForce/OnComponent, and their Stop APIs
Shared PublisherSetSharedPublisherEnabled, SetSimpleWorldCollisionSettingsOnSharedPublisher, wind OnSharedPublisher APIs

GenerateTransientHandle and the PushPhysicsSettingsMultiplier family are C++ APIs, not exposed Blueprint nodes. Follow the feature-specific lifetime, blend, and handle rules for temporary effects.

Calling timing​

BlueprintThreadSafe does not add synchronization with evaluation threads. Node property access executes immediately on the referenced node. Call it from a suitable ThreadSafe AnimGraph context, or on the GameThread while the target is not being evaluated. Collection from an AnimGraph must target the caller's own AnimInstance/component; use the GameThread, outside evaluation, for other objects.

Individual APIs have further restrictions: diagnostics require the GameThread, while wind parameter updates use a pending request. Use dedicated feature APIs instead of writing internal shared clocks or force state through named access.

Runtime Application​

Blueprint-exposed UKawaiiPhysicsLibrary::ApplyPresetDataAsset accepts a node reference, preset, and options; ExecResult reports access success. ExternalForces and CustomExternalForces are skipped for safety.

Application requests ModifyBones and Shared Collision re-initialization. It applies node settings rather than restoring prior values after a duration. Use Settings Multiplier for temporary effects and UKawaiiPhysicsLibrary for threading and evaluation-context conditions.

v1.22 Preview Overview · Official Release Physics Setup

Related UE documentation​