UKawaiiPhysicsLibrary — Transient Effects and Wind

Not Officially Released

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

Control temporary settings multipliers, gusts, wind parameters, and the Shared Publisher from Blueprint and C++. See Settings Multiplier and Procedural Wind for effect setup.

Blueprint Start and Stop

Target	Start	Stop
Node reference	`StartPhysicsSettingsMultiplier`	`StopPhysicsSettingsMultiplier`
Component	`StartPhysicsSettingsMultiplierOnComponent`	`StopPhysicsSettingsMultiplierOnComponent`

Save Start's OutHandle and Stop the same target/handle. Component forms collect main, linked, and post-process AnimInstances. Empty Filter Tags matches all; bFilterExactMatch=false permits parent tags. Their return values count nodes where requests were queued.

Duration includes both fades. Positive means a trapezoid, zero is a no-op, and negative holds until Stop. If Blend In + Out exceeds Duration, the fades scale proportionally. Negative Duration ignores Start's Blend Out and uses Stop's value for release.

Stop fades linearly from the current applied ratio to 0. Blend Out 0 releases immediately. Stopping the same still-pending handle replaces its release fade time.

C++ Updates and Threading

GenerateTransientHandle, PushPhysicsSettingsMultiplier, and PushPhysicsSettingsMultiplierOnComponent are C++ only, not Blueprint-exposed. Update using one pre-generated handle and Stop when finished. Pushing an unset handle is a no-op; the node-reference form reports NotValid.

Push updates the same entry and returns a stopped/fading entry to external drive. The ordinary overload does not expire by time. The component overload with a lease fades after the specified number of evaluations without refresh. Repeated pushes to the same handle during URO/LOD pauses retain only the latest pending value.

AnimGraph BlueprintThreadSafe collection must target the caller's own component. Collect other objects on the GameThread while they are not being evaluated. Blueprint can hold using negative Start Duration, but arbitrary-Alpha Push updates are not exposed.

Animation Notifies · Kawaii Physics Settings Multiplier · UKawaiiPhysicsLibrary

The effective scale is calculated as Lerp(1, Scale, EnvelopeAlpha).

APIs and Application Scope

Gust and Transient Force APIs

Use the handle-based APIs in UKawaiiPhysicsLibrary to add a short burst for a gameplay event. These are runtime-only transient forces; they do not append to the authored External Forces array.

API	Purpose
`StartProceduralWindGust`	Start a gust on one node and obtain `OutHandle`
`StartProceduralWindGustOnComponent`	Start gusts on filtered component nodes, including linked / post-process instances
`AddTransientExternalForce` / `AddTransientExternalForceOnComponent`	Add a generic force struct with `LifetimeSeconds`
`StopTransientExternalForce` / `StopTransientExternalForceOnComponent`	Stop forces early using the stored handle

Strength is the gust's peak strength. Duration includes rise, hold, and decay; hold is calculated as max(0, Duration - RiseTime - DecayTime). A nonzero GustDirection specifies a world-space direction. A zero vector inherits direction, space, bone filters, and related settings from an authored Procedural Wind. On the node API, ExternalForceIndex = -1 uses the first enabled Procedural Wind as the inheritance source.

When RiseTime + DecayTime exceeds Duration, both are scaled down proportionally. Specify a positive Duration. At zero or below, gust strength is zero, but the API may still accept the request and return a handle. Request acceptance does not establish a visible effect.

bRealTimeEnvelope defaults to true and sets the transient gust's TimeScale to 1. With false, the inherited wind's Time Scale affects progress. Both depend on animation evaluation: URO / LOD suspension can extend the elapsed real duration.

Stopping with BlendOutTime fades Procedural Wind linearly from its current value in wind time. A value of 0 removes it immediately. Generic transient forces do not use this fade; their lifetime is shortened instead.

Transient forces are capped at 8 per node. Adding more evicts the oldest entry. Node re-initialization and BP recompile also remove them. IsTransientHandleSet only checks whether the ID is set; it does not prove the force still exists. Stopping a stale handle does nothing.

Generic transient forces do not receive Initialize(Context). Forces containing live UObject references, such as ExternalOwner or curve assets, are rejected. Procedural Wind creates its runtime state in PreApply; do not assume every existing force type supports the same transient workflow.

Component APIs return the number of nodes where a request was queued. Empty FilterTags matches all nodes. In an AnimGraph evaluation context, operate on the caller's own component; operations on other objects belong on the GameThread while the target is not evaluating. See UKawaiiPhysicsLibrary for the access contract and AnimNotify / NotifyState for animation-triggered gusts.

Wind Preset and Dynamic Parameter Details

A KawaiiPhysics Wind Preset Data Asset stores wind tuning values. Unlike the whole-node UKawaiiPhysicsPresetDataAsset, it applies specifically to Procedural Wind. Each entry in Presets contains a PresetName, PresetTag, and wind values. Tags are matched exactly.

ApplyProceduralWindPreset targets a node reference and external-force index; ApplyProceduralWindPresetOnComponent targets wind entries in filtered component nodes. Changes are requested for the next PreApply. Pre-load the DataAsset and avoid editing or reloading it while simulation is running.

ToDynamicParams() updates these 11 fields:

ConstantForce
SwayForce, SwayPeriod
RippleForce, RipplePeriod, RippleTipPhaseDelay
StrengthCycleRange, StrengthCyclePeriod
RandomForce, RandomForcePeriod
WindDirectionNoiseAngle

It preserves WindDirection, enabled state, phase offsets, TimeScale, and WindDirectionNoisePeriod. Applying this preset also does not create a new external-force entry.

When no DataAsset is supplied, or its Presets array is empty, the built-in tags KawaiiPhysics.WindPreset.Breeze / Strong / Storm are available. A supplied asset with entries is searched exclusively; a missing tag does not fall back to the built-in presets. An invalid tag fails as well.

Use FKawaiiProceduralWindDynamicParams with SetProceduralWindParameters / SetProceduralWindParametersOnComponent for individual changes. Only fields with their corresponding bOverride... flag set to true are changed. To change constant wind only, set bOverrideConstantForce and ConstantForce, leaving other overrides false.

GetProceduralWindParameters includes pending updates issued earlier in the same frame and returns all overrides as true. You can edit and submit that snapshot, or create a new struct with only the intended overrides enabled. Wind Scope helps compare waveforms and presets.

v1.22 Preview Overview · Official Release External Force Presets

Runtime Control

UKawaiiPhysicsLibrary provides SetSharedPublisherEnabled, SetSimpleWorldCollisionSettingsOnSharedPublisher, SetProceduralWindParametersOnSharedPublisher, shared gust start/stop operations, and GetSharedPublisherDebugInfo. Specify an Actor and group tag, and check the return value. Requests are processed on a subsequent publisher update rather than synchronously changing every consumer. Runtime overrides of Enabled and collision settings revert to node settings on reinitialization. Wind parameter updates modify the Shared Wind settings and remain after reinitialization.

See UKawaiiPhysicsLibrary for related operations and GetRuntimeNodeInfosOnComponent for inspection data.

v1.22 Preview Overview

The publisher also shares 13 wind parameters and active gust state. Use SetProceduralWindParametersOnSharedPublisher to update shared values, and StartProceduralWindGustOnSharedPublisher / StopProceduralWindGustOnSharedPublisher to start or stop a shared gust. These differ from handle-based APIs that add transient forces to individual nodes. See Kawaii Physics Shared Publisher for targets and persistence.

Blueprint Start and Stop​

C++ Updates and Threading​

APIs and Application Scope​

Gust and Transient Force APIs​

Wind Preset and Dynamic Parameter Details​

Runtime Control​

Related UE documentation​