Visuals and props

The module PulseVisual gives the Pulse plugins and your game two things:

  • FPulseVisualRef: one property type for anything a plugin shows: a static mesh, a skeletal mesh, a Niagara system, a sound or a Pulse prop, with the settings of its type (override materials, an animation, Niagara user parameters, volume and pitch) and a scale.
  • Pulse props (UPulseProp): objects made of parts that move, change state and play small events, without animation assets or Blueprints: a furnace with a turning wheel and bellows, a door that opens, a crystal that floats.

Visual references

/** What the machine shows. Only props and static meshes. */
UPROPERTY(EditAnywhere, meta = (PulseVisualTypes = "Prop, StaticMesh"))
FPulseVisualRef Visual;

The meta data PulseVisualTypes limits the types, like a material property: the picker of the details panel lists only assets of these types. Without the meta data every registered type is taken. PulseVisualRequired marks a visual that must be set. Elements of arrays, sets and maps take the meta data of their container.

The picker follows the meta data on its own; the check needs one call in the asset type that holds the property. Pulse::Visual::ValidateObject walks every visual of an object, also inside structs, arrays, sets, maps, instanced structs and instanced objects, and reports each problem at the path of its value (Visuals[2], Rules[0].Visual):

EDataValidationResult UMyMachine::IsDataValid(FDataValidationContext& Context) const
{
    EDataValidationResult result = Super::IsDataValid(Context);

    if (!Pulse::Visual::ValidateObject(*this, Context))
        result = EDataValidationResult::Invalid;

    return result;
}

It reports an asset of a type the property does not take, an asset no visual type takes, an asset whose class belongs to a plugin that is not loaded, settings that do not fit the type of the asset (at <path>.Settings) and an empty required visual as errors. A name in PulseVisualTypes that no registered type has (a typo, or a type of a plugin that is off) is a warning, and the picker names it in its tooltip.

Field What it is
Asset The asset (soft reference)
Settings Settings of the asset’s type (see below); empty uses the defaults of the type
Scale Scale on top of the transform the visual is spawned with

Settings of a type

What only one type knows lives in Settings, an instanced struct (TInstancedStruct<FPulseVisualTypeSettings>) of the struct the type names. When you pick an asset in the details panel, Settings gets the struct of its type on its own: a static mesh brings Static Mesh Settings, a sound Sound Settings. Values stay while the struct stays (another static mesh keeps the override materials); a prop has no settings and clears them. Settings that do not fit the asset (set from code or Blueprint, or pasted) get a button Fit Settings To Type below them in the details panel.

Type Struct Fields
StaticMesh FPulseVisualTypeSettings_StaticMesh OverrideMaterials: materials by slot; an empty entry keeps the material of its slot; MaterialParameters: material parameters (see below)
SkeletalMesh FPulseVisualTypeSettings_SkeletalMesh OverrideMaterials; MaterialParameters; Animation: the animation it plays; bAutoActivate: the animation starts at once; bLooping; PlayRate
Niagara FPulseVisualTypeSettings_Niagara bAutoActivate: the system starts at once; FloatParameters, VectorParameters, ColorParameters: user parameters by name (without User.)
Sound FPulseVisualTypeSettings_Sound bAutoActivate: the sound starts at once; Volume and Pitch: factors; StartTime, Attenuation, bOverrideAttenuation, AttenuationOverrides, Concurrency, SoundClass (see below)
Prop none -

In C++ the settings are read typed. GetSettings<T> returns the stored settings and null when the reference has no settings of T; Pulse::Visual::ResolveSettings<T> returns them or the defaults of the struct, as the builders do:

const FPulseVisualTypeSettings_Sound* stored = Visual.GetSettings<FPulseVisualTypeSettings_Sound>(); // may be null
float volume = Pulse::Visual::ResolveSettings<FPulseVisualTypeSettings_Sound>(Visual).Volume;     // or the default

Visual.FitSettingsToType();   // what the details panel does when the asset changes
Visual.HasFittingSettings();  // false for settings of another type

Soft references in settings that fit the asset (materials, the animation, textures of material parameters) load with the visual (GetLoadPaths, Load Pulse Visual); settings of another type load nothing.

Typed access in C++ (Unreal Header Tool cannot read custom templates, so the property itself stays untyped and the meta data filters):

if (Visual.IsA<UPulseProp>())             // without loading (asset registry)
    UPulseProp* prop = Visual.Load<UPulseProp>();

UStaticMesh* mesh = Visual.Get<UStaticMesh>(); // only if loaded
FName type = Visual.GetTypeName();             // "StaticMesh"

Material parameters

MaterialParameters (FPulseVisualMaterialParameters) of the static and skeletal mesh settings sets material parameters by name, the same way for every slot:

Field What it is
Scalars Scalar parameters (TMap<FName, float>)
Vectors Vector and color parameters (TMap<FName, FLinearColor>)
Textures Texture parameters (TMap<FName, TSoftObjectPtr<UTexture>>); the textures load with the visual

After the override materials, every slot whose material has at least one of the parameters gets a dynamic material instance (one per slot, and one the slot holds already is reused) with the values. Slots without them keep their material, and empty parameters make no dynamic material instance at all. Instances (AddInstance, far props) with other parameters land in an instanced static mesh component of their own, which gets the dynamic material instances the same way. The values are base values: states and animations of props override them while they act.

Code that sets the parameters on a mesh of its own calls the same function the builders use:

int32 made = Pulse::Visual::ApplyMaterialParameters(*MeshComponent, Settings.MaterialParameters); // dynamic instances made

Sound settings

Besides auto activation, volume and pitch, the sound settings carry what an audio component offers for one sound:

Field Type Applied as
StartTime float, seconds, at least 0 Where the sound starts, on every start (auto activation and SetPlaying)
Attenuation TSoftObjectPtr<USoundAttenuation> AttenuationSettings of the component; none keeps the attenuation of the sound
bOverrideAttenuation bool bOverrideAttenuation: AttenuationOverrides attenuates the sound instead
AttenuationOverrides FSoundAttenuationSettings (editable while bOverrideAttenuation is on) AttenuationOverrides
Concurrency TArray<TSoftObjectPtr<USoundConcurrency>> ConcurrencySet; empty keeps the concurrency of the sound
SoundClass TSoftObjectPtr<USoundClass> SoundClassOverride; none keeps the sound class of the sound

The attenuation, concurrency and sound class assets load with the visual. The sound type spawns a UPulseVisualAudioComponent, an audio component with a StartTime that it plays from when it activates and when Pulse::Visual::SetPlaying starts it; callers see an ordinary UAudioComponent.

Spawning

FPulseVisualSpawnParams params;
params.Transform = FTransform(FVector(0, 0, 50));
params.Socket = TEXT("Hand");
params.bCollision = false;

USceneComponent* component = Pulse::Visual::Spawn(Visual, GetRootComponent(), params);

FPulseVisualSpawnParams holds what every type shares (name, transform, socket, collision, collision profile) and an optional Settings for this spawn only: when it holds settings of the asset’s type, they win over the settings of the reference; empty, or settings of another type, use those of the reference. Start with a copy of the reference’s settings to change one value:

FPulseVisualSpawnParams params;
params.Settings = Visual.MakeFittingSettings(); // the reference's settings, or the defaults of its type

// Spawn without starting it; Pulse::Visual::SetPlaying starts it later
if (FPulseVisualTypeSettings* settings = params.Settings.GetMutablePtr())
    settings->SetAutoActivate(false);

USceneComponent* component = Pulse::Visual::Spawn(Visual, GetRootComponent(), params);

// Later: starts the Niagara system, the sound or the animation (at the PlayRate of the settings; the last argument is
// a factor on it)
Pulse::Visual::SetPlaying(Visual.GetTypeName(), component, true);

SetPlaying starts a skeletal mesh with the animation and looping of its settings, also after a one-shot of PlayAnimation, and an animation that does not loop and has ended starts from the beginning again.

Pulse::Visual::AddInstance(Visual, Actor, WorldTransform, Instances) adds instanced static meshes instead: one instanced static mesh component per mesh and materials on the actor, made when missing. A prop adds its static mesh parts at their rest pose. RemoveInstances takes them out again; the indices of later instances in the same component move down, so remove several instances in one call.

Spawn, AddInstance and HasSocket load the asset now when it is not loaded, which can hitch the game. To spawn at runtime without that, load the visual first and spawn when it is there: the Blueprint node Load Pulse Visual loads the asset, the soft references of its settings and what its type loads while it spawns (the parts of a prop), and spawns nothing itself. In C++, Pulse::Visual::GatherLoadPaths names the same paths for a Pulse::Loading::FLoadBundle; call it again after each load until it adds nothing new.

Runtime settings of the spawn params (other materials, another animation) are not part of the visual, so Load Pulse Visual does not load their assets, and Spawn would load them on the game thread. Load them yourself before the spawn: in C++ Pulse::Visual::GatherLoadPaths(Visual, Params, Paths) adds them to the paths, and Pulse::Visual::GatherSettingsLoadPaths(Settings, Paths) names the soft references of any settings.

Blueprint: Spawn Pulse Visual, Add Pulse Visual Instance, Load Pulse Visual, Is Set (Pulse Visual), Get Pulse Visual Type, Get Pulse Visual Types, Load Pulse Visual Asset, Get Pulse Visual Settings, Set Pulse Visual Settings, Fit Pulse Visual Settings To Type (category Pulse > Visual > Reference). Read settings with the engine node Get Instanced Struct Value (for example as Sound Settings) and make new ones with Make Instanced Struct; the Settings pin of the spawn params takes them the same way.

Visual types

A visual type maps an asset class to a builder that makes the component:

Type Asset class Component
StaticMesh UStaticMesh Static mesh component with the override materials, or instances
SkeletalMesh USkeletalMesh Skeletal mesh component with the override materials and the animation of its settings
Niagara UNiagaraSystem Niagara component with its user parameters
Sound USoundBase Audio component with volume and pitch
Prop UPulseProp Pulse Prop component (a prop inside a prop)

Plugins, bridges and projects add types (or replace one with the same name), with a settings struct of their own derived from FPulseVisualTypeSettings (or none):

USTRUCT(BlueprintType, meta = (DisplayName = "Decal Settings"))
struct FMyDecalSettings : public FPulseVisualTypeSettings
{
    GENERATED_BODY()

    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Settings")
    FVector Size = FVector(64.0);
};

FPulseVisualType type;
type.Name = TEXT("Decal");
type.DisplayName = INVTEXT("Decal");
type.AssetClass = FSoftClassPath(UMaterialInterface::StaticClass());
type.SettingsStruct = FMyDecalSettings::StaticStruct();
type.Builder = MakeShared<FMyDecalBuilder>(); // IPulseVisualBuilder: Spawn, AddInstance, SetPlaying, CanPlay, IsLooping, HasSocket, GatherLoadPaths
Pulse::Visual::RegisterType(type);

// ShutdownModule: removes only this registration; a type it replaced is used again
Pulse::Visual::UnregisterType(type.Name, type.Builder.Get());

The builder reads its settings with Pulse::Visual::ResolveSettings<FMyDecalSettings>(InRef, InParams): the runtime settings of the spawn params, else those of the reference, else the defaults of the struct. Settings structs of types that play something override SetAutoActivate, so callers such as props can turn auto activation off without knowing the struct.

The type with the closest asset class wins, so a type for a subclass is used before one for its base class. A replacement lasts while it is registered: when it is unregistered, the type it replaced comes back. The editor shows the DisplayName of a type in the picker and in validation messages.

A replacement of a built-in type registers the same settings struct, or one derived from it. Otherwise every existing reference of the type has settings that no longer fit: IsDataValid reports them, the builder ignores them, and the next asset change in the details panel replaces them (the override materials are gone). RegisterType logs a warning for such a replacement.

Niagara

Pulse Foundation does not depend on the Niagara plugin. The Niagara type reaches the Niagara classes by their paths (/Script/Niagara.NiagaraSystem, /Script/Niagara.NiagaraComponent) while the game runs, sets the system through the reflected function SetAsset (or the property Asset), the user parameters of its settings through SetVariableFloat, SetVariableVec3 and SetVariableLinearColor, and starts and stops it through the component’s activation. So every project can use Pulse Foundation without the Niagara plugin; with Niagara on (the engine default) Niagara systems work as visuals. Without Niagara the type stays unused, the picker lists no Niagara system, and Pulse::Visual::ValidateObject reports a Niagara asset as one whose plugin is not loaded.

Props

A prop is a data asset (Add > Pulse > Foundation > Prop, or the Pulse window, Create) with four parts: parts, motions, states and events. Place it with the Pulse Prop actor (replicates) or add the Pulse Prop component to an actor of your own and pick the prop. Double click a prop to open the prop editor; placed props update when the asset changes.

Parts

Field What it is
Name Unique in the prop; motions, states and steps refer to it
Visual What it shows: any visual type, also another prop, with the settings of its type (materials, the animation of a skeletal mesh, Niagara user parameters, volume)
Parent The part it hangs on; none for the root
Socket A socket or bone of the parent part’s mesh (static or skeletal); the transform is then relative to it
Transform Where the pivot sits, relative to the parent part’s pivot (or the socket): the rest pose
Pivot The hinge or axle in the visual’s own space; the part turns about it
bVisible Shown at the start; events show and hide parts
bCollision Collision Per Part: whether this part collides
Play When its Niagara system, sound or animation plays: Work (while the state’s rate is above 0), Always, Event (only by steps)

A part plays what its visual settings name: a skeletal mesh part the Animation of its settings (looping as bLooping says, at PlayRate, times the rate of the state for Work). Play decides when it plays; the bAutoActivate of the settings does not count for parts.

IsDataValid reports missing parents, loops, a socket the parent mesh does not have, a prop that holds itself and settings that do not fit the visual of a part.

A part whose visual is another prop (a nested prop) follows the prop it is in: its network role, its seed (made from the parent’s seed and the part name), every state the parent applies (it jumps when the parent jumps) and the collision of its part (no collision on a part without bCollision). Its Replicated events replicate through the outermost prop. SetState on a nested prop inside a replicated prop is refused with a warning, since clients would never get that state.

Motions

Type Moves Amount
Spin Turns about Axis Degrees per repeat
Swing Rocks about Axis along Shape Degrees
Slide Moves along Axis along Shape Centimeters
Scale Stretches along Axis in the part’s own space Added scale
Link A rod from LinkFromPoint on one part to LinkToPoint on another, such as a push rod -
Keyframes A clip of property tracks of the part (location, rotation, scale, visibility, opacity, material and Niagara parameters, volume, pitch), Duration long -

Shapes: Sine (back and forth), Wave (out and back), Pulse (open, hold, close).

Drives: Work runs with the rate of the state and stops where it is; Always keeps running, at IdleRate of its speed while the state’s rate is 0; Event runs once when a step of an event plays it (its Name). Repeats and Offset set how often and where a repeating motion runs per cycle (CycleTime seconds at rate 1). Several motions of one part add up in list order; links run last.

Keyframes

A Keyframes motion is a clip: Tracks holds one track (FPulsePropTrack) per property of its part, and Duration is the length of the clip. A clip works in two places: as a motion (Work and Always play it once per repeat, so the clip loops) and inside events (Play Motion plays it once). States have no tracks; they override properties (see States).

Field What it is
Property The property (FPulsePropProperty): PropertyId (Location, Opacity, MaterialScalar, …) and ParamName for properties that need a name (a material or Niagara user parameter); see Animatable properties
Keys The keys (FPulsePropTrackKey), sorted by time: Time (seconds from the start of the clip), Value (FPulsePropValue, of the kind of the property) and Interp

Interp says how the value runs from a key to the next:

  • Smooth: on a curve with clamped automatic tangents. It is flat at the ends and at turning points and never goes past the values of the two keys around it.
  • Linear: straight to the next key.
  • Step: holds the value until the next key.

Before the first key the first key holds, after the last key the last one. Each number runs on its own, so a rotation (Pitch, Yaw, Roll in degrees) can turn more than half a turn between two keys. Keys of a Bool property (Visible) always hold. Location, Rotation and Scale are offsets, turns and factors on the rest pose, so the gizmo keys a part without changing its transform; they add up with the other motions of the part.

States

Named states such as Idle, Working, Open, one at a time (StartState, else the first):

Field What it is
Rate Speed of Work motions and parts (0 = still, 1 = one cycle per CycleTime)
BlendTime Seconds of the smooth blend into the state
Overrides Values the state sets on parts instead of their base values, such as the door’s Open rotation or the Glow of a lamp

An override (FPulsePropOverride) names a Part (none for every part that has the property; not for Location, Rotation and Scale), a Property (PropertyId and ParamName, as in tracks) and a Value. A property a state does not override goes back to its base value (rest pose, settings, material default), so the overrides are all a state changes. Material values do not keep where they are when the next state does not set them.

SetState blends the rate and the overrides over the blend time: numbers and colors straight, the transform like a pose, and a property only one side sets from or to its base value. Visible switches on at the start of a blend and off at its end, so a part that fades out with Opacity stays shown until the fade is over. On a replicated component only the server changes the state; clients follow.

Animatable properties

What tracks and overrides can change on a part comes from a register: every visual type declares its animatable properties (FPulseVisualPropertyDesc) in FPulseVisualType::Properties, and four common properties belong to every part.

Property Of Kind What it changes
Location every part Vector Offset from the rest location (cm, in the space of the part’s parent)
Rotation every part Vector Turn on top of the rest rotation (Pitch, Yaw, Roll in degrees)
Scale every part Vector Factor on the rest scale
Visible every part Bool Shown or hidden, on top of bVisible and the Show and Hide steps
Opacity StaticMesh, SkeletalMesh Float 0 to 1 through the opacity parameter of the materials (see below)
MaterialScalar StaticMesh, SkeletalMesh Float, name A scalar parameter of the materials
MaterialVector StaticMesh, SkeletalMesh Color, name A vector parameter of the materials
UserFloat Niagara Float, name A float user parameter (name without User.)
UserVector Niagara Vector, name A vector user parameter
UserColor Niagara Color, name A color user parameter
Volume Sound Float Volume factor, replaces the Volume of the settings
Pitch Sound Float Pitch factor, replaces the Pitch of the settings

A nested prop part has only the common properties. Visual types of plugins bring their own. A track or override with an id the visual type of its part does not have (a type of a plugin that is off, a typo) is skipped with a warning in the log, once, and validation reports it.

A value of a part is decided in this order, the later one wins:

  1. The base: the settings of the visual, the default of a material parameter, the rest pose, bVisible and the Show and Hide steps of events.
  2. The override of the state (blended).
  3. The tracks of running clips, in list order (Work and Always clips, event clips while they play). An event clip that ended holds the values at its end (a Visible key off at the end keeps the part hidden), until it plays again; key the start values at the end to give them back. A client that joins after the end gets the end values at once.

Location, Rotation and Scale are the exception: they add up with the other motions of the part.

Opacity sets the scalar parameter Opacity Parameter of the project settings (default Opacity; a prop can name its own in OpacityParameter). Parts whose materials do not have the parameter only show and hide: they hide while the opacity is below Opacity Hide Below (0.01). Validation says so as an Info.

The Pulse Prop component builds a slot per property of a part that states and tracks set, once when it builds the parts, and writes a value only when it changed. Dynamic material instances are made only for the material slots whose material has a parameter a property needs (a dynamic instance made for the material parameters of the settings is reused). A prop that only moves pays nothing for this, and a dedicated server that does not pose the parts makes no slots. GetPropertyValue, GetPropertySlotCount and CountDynamicMaterials of the component tell tools and specs what it does.

Validation warns about a property the visual type of the part does not have, two tracks of one property in one clip, a key after the end of the clip, an override of the same property twice and a material parameter no material of the part has; an override of a part that does not exist is an error.

A visual type declares a property with an id, a kind and an Apply that sets the value on the component it spawned. ReadBase (optional) reads the value the component has before anything sets it, and ListNames (optional, for properties with a name) lists the names the “+ Track” menu of the prop editor offers:

FPulseVisualPropertyDesc fade;
fade.Id = TEXT("Fade");
fade.DisplayName = INVTEXT("Fade");
fade.ValueKind = EPulseVisualValueKind::Float;
fade.Default = FPulsePropValue::FromFloat(1.0);
fade.Range = FFloatInterval(0.f, 1.f);

fade.Apply = [](USceneComponent& InComponent, FName InParamName, const FPulsePropValue& InValue)
{
    UDecalComponent* decal = Cast<UDecalComponent>(&InComponent);

    if (!decal)
        return false; // the component lacks the property

    decal->SetFadeScreenSize(InValue.GetFloat());
    return true;
};

type.Properties.Add(fade); // the FPulseVisualType above, before Pulse::Visual::RegisterType(type)

Pulse::Visual::FindProperty(Type, Id) and GetProperties(Type) look properties up (the common ones, then those of the type). A replacement of a built-in type keeps the built-in properties with MakeBuiltInProperties(Type).

Old prop data

Props saved before property tracks keep their data. The old keys of Keyframes motions and the poses and material values of states load into deprecated properties, and UPulseProp::PostLoad converts them (custom version PulseProp 1):

  • Keys become tracks of Location, Rotation and Scale; Duration becomes the time of the last key, and rotations are unwound so they turn the same way as before.
  • Poses become Location, Rotation and Scale overrides.
  • Material values become MaterialScalar and MaterialVector overrides, or UserFloat and UserColor overrides on Niagara parts.

The log names each prop it converted. Re-save converted props: until they are saved, they convert again on every load. Two things look a little different: Smooth keys of old clips run on the new smooth curve (a slightly different shape), and material values a state does not set go back to their base value.

Events

An event is a small sequence of steps on a timeline:

Step Does
Show Part / Hide Part Shows or hides a part and its children
Play Motion Plays an Event motion once (also a keyframe clip)
Play Animation Plays an animation once on a skeletal mesh part (the step’s, else the one of the part’s settings)
Start Part / Stop Part Starts or stops the Niagara system, sound or animation of a part
Send Message Sends a Pulse message (payload FPulsePropMessage) on the bus of each machine that plays the event

Triggers start it, besides TriggerEvent from outside:

Trigger Starts the event
Random At random times: an interval range, a chance per try and optional Pulse conditions (context: the prop as source, its actor as target)
Message On a Pulse message of a channel; Source filters by the source, instigator or target: any, the prop’s actor, or actors with a tag
StateEntered / StateLeft When the prop enters or leaves a state

A trigger while the event plays is ignored unless bRestart is on.

Multiplayer

Each event chooses its Replication:

Mode Who triggers Traffic
Local Every machine, with its own random None; the machines differ
LocalSame Every machine; the random comes from the instance seed and the game clock None; the same times on every machine
Replicated The server; its triggers run only there A counter and a start time per event

LocalSame cuts the game clock into windows of (Min + Max) / 2 with one try per window at a place from the seed, so two tries are between Min and Max apart and every machine finds the same times. The seed comes from Seed, else from the path of the actor (without the PIE prefix, so each copy of a level instance has its own) and the name of the component, the same everywhere for placed actors; the server sends it once for spawned ones. Conditions of LocalSame triggers are checked on each machine.

Replicated events replicate as a counter with the game clock time of the last start (push model). A client plays the event once per change of the counter, from where it is now. A start the client was there for (it had the prop before, or the event started after the prop began play there: placed props get their first data with their first event) that arrives within a second plays even when the event lasts 0 seconds or less than the network delay, and its messages and one-shot animations run a little late. A player who joins later, or a prop that becomes relevant later, plays only what still runs and never replays old events. Steps passed before such a late start are caught up where they leave a state (show, hide, motions, start and stop); messages and one-shot animations are not replayed. The state is a replicated property (push model) with the server’s game clock time of the change. A change that is recent (within its blend time plus one second) blends from where the server is and runs its state triggers; an older one, such as the state a late joiner gets, jumps without state triggers. On State Changed is called in both cases.

The component replicates only on a replicated actor (the Pulse Prop actor is one). On an actor that does not replicate, every machine runs everything itself. Placed Pulse Prop actors start dormant (DORM_Initial); each change the server makes to a state, an event or the seed wakes the actor for that update.

Collision

Collision of the prop:

  • PerPart: each part with bCollision brings the collision of its mesh, with CollisionProfile. Moving parts move their collision where the parts move (on a dedicated server only with bMoveOnDedicatedServer).
  • Whole: one collision for the whole prop, simple CollisionShapes (box, sphere, capsule) and/or a CollisionMesh (a static mesh that is not shown); the parts have none. It does not move with the parts.

Distance levels

Like levels of detail, Levels of a prop make it cheaper far away. Each level starts at its Distance from the camera (the distances ascend; the first level is the nearest) and says per part what it shows:

Per part What the part shows on the level
Auto (no entry) Itself, unless the level’s SmallPartSize is above 0 and the part’s visual is smaller (largest side of its bounds)
Show Itself, also when it is small
Hide Nothing
Replace Replacement instead of its visual (a cheaper mesh); it does not collide

A level with bOff shows nothing of the prop and stops every visual-only motion (on the authority, motions that move collision keep running, see Collision on the authority below). Collision, states and events do not change with the level. Steps and Visible tracks still show and hide parts; a level hides on top.

A part a level hides really stops: its Niagara system deactivates, its sound stops, its skeletal mesh stops posing; a nested prop it hides plays nothing. When the part shows again it plays what its drive or Start Part and Stop Part say (at the rate of the state; never a sound in the level editor). A replacement behaves like the part: it does not start by itself, plays by the part’s drive and steps, stops when hidden, takes the values of states and tracks where its visual type has them, and hides a nested prop with all its parts. A replacement may not be the prop itself, directly or through another prop (validation error; at runtime the part shows instead).

Motions: Runs Up To Level (LastLevel, -1 for every level) of a motion says up to which level it runs. Beyond it the motion holds the pose it has when the prop gets there and does not tick (a prop whose loops all hold sleeps). When the prop comes back, a Work or Always motion is in phase with the game clock again (every machine shows the same pose) and catches up over LevelResumeBlendSeconds (0.25 s) instead of jumping; an Event motion is put where its start says (below). The cycle and the motions run on the game clock, awake or asleep alike: a game rate speeds them up, a pause stops them and a jump moves them on (a prop that slept stands where one that stayed awake does). While the game clock stands (paused or at rate 0) a prop with nothing else to do sleeps and wakes when the clock runs again. Motions added in the prop editor (on the timeline, by keys, or as a new entry of Motions in the details) start with the level before the first level with bNewMotionsStop.

Collision on the authority: on the server, a listen server host and in a standalone game, a motion whose part or a part below it collides (per-part collision) runs on every level and its Play Motion steps always play, so the collision other players walk against is where it should be. Visual-only motions follow the level, also on a listen server host.

Events: Fires Up To Level (LastLevel) of an event says up to which level it plays its cosmetic steps. Beyond it, and on an Off level, these steps do not play on this machine:

  • Play Motion (also when the event fires near but the motion holds there; the validation warns about that). On the authority a Play Motion of a motion that moves collision always plays. A skipped Play Motion catches up later (below).
  • Play Animation (a one-shot: it is over when the camera comes near, so it is not played later; it never plays on a mesh the level hides, and one that a hide cuts while it plays is over too: the animation of the part’s settings comes back, on any drive, and plays again where the drive or a Start Part wants it).
  • Start Part (Niagara systems, sounds, animations of the part’s settings) only waits: the part is marked as wanted to play, and it plays once it shows and the event’s level allows it (Stop Part always applies). Only an Event part waits for its event’s level; a Work or Always part plays by its drive. A one-shot effect or sound that a hide cuts, whether it had ended or still played, is over for the whole part: neither the part nor any replacement plays it again until the next Start Part. A loop goes on when the part shows again. Sounds and animations tell whether they loop; a type that cannot tell (Niagara) counts as a loop, so it resumes (IPulseVisualBuilder::IsLooping). A side that plays nothing (a static mesh, a skeletal mesh without an animation) never ends the one-shot or the loop of the other side; a builder of a custom type that plays overrides IPulseVisualBuilder::CanPlay. The one-shot of a Play Animation step is the step’s: a hide ends it, and the part’s own animation plays again when it shows.

The event still starts, counts and replicates, On Event Started fires, and Show Part, Hide Part, Stop Part and Send Message still run, so the prop looks right when the camera comes near and listeners still hear the message.

Event motions catch up: every Play Motion keeps its start, also when the level skipped it or the motion held there. When the prop comes nearer and the motion runs again, it is put where that start says: still running at that offset, past its end at its held end (a keyframe clip that holds its end) or at rest. So a door opened by a Replicated event while a client was far away is open when the client walks up, like on every client that stayed near (the same rule as a client that joins late).

Runtime: each machine picks the levels itself from the nearest camera of a local player, through the level manager (below); the level is never replicated, and a dedicated server keeps the nearest level. Get Level, Set Level Override (tools, cutscenes; -1 goes back to the level the manager picked) and Get View Distance are on the component; other systems read the level index and the view distance through them. Back to the distance without a manager or a camera (an editor preview), a prop takes its nearest level.

Level manager

One world subsystem, UPulsePropLevelSubsystem, picks the levels of all props of its world; there is no timer per component. A prop with levels registers when it begins play and leaves when it ends (a movable prop also tells the manager when it moves). The manager keeps the props in a search grid of cells (LevelCellSize, 50 m):

  • Every LevelCheckInterval (0.5 s) it starts a pass, but only when a camera moved more than LevelViewMoveThreshold (50 cm) or props came or moved; while nothing moves it does nothing.
  • A pass checks the props not on their farthest level, wherever they are, and per table of level distances (props with the same distances share one) the props in cells within that table’s reach of a camera (its farthest level border plus the hysteresis). Props far away on their farthest level are not looked at, and one prop with a distant level does not make the others be looked at farther away.
  • A frame may spend LevelFrameBudgetMs (0.5 ms) on the manager: collecting and checking props and applying the level changes to their components. A longer pass goes on in the next frames, changes left over are applied first in the next frame, and at least one change is applied each frame so the work keeps going. The cheat PulsePropsBudget <ms> changes the budget while playing.
  • The rule is the same as before, with LevelHysteresis (10 % of a level’s distance); a prop registered again (a new prop asset) keeps the level it is on. A component hears only of a change of its level. A flip is a change back to the level before within a second (a camera that keeps going is none).

The manager is overridable (Subsystems): a derived class replaces it, for example with GatherViews for other viewpoints (and GatherServerViews for the server views of the live band, see the server views under Many instances). A dedicated server picks no distance levels: its props stay on their nearest level, and the manager runs only the live band of prop instances around the pawns of the players (HasLevels is false there; where the net mode is known only when play begins, a PIE dedicated server, it drops what registered before at begin play). With bServerPawnViews off a dedicated server has no manager (not created there, or off at begin play: no snapshot, Get returns none, PulsePropsInfo says so). The grid is a plain class, Pulse::Visual::Levels::FLevelGrid (Prop/PulsePropLevelGrid.h); a spec runs 100,000 entries in it and checks how many entries and cells a pass visits (the times only go to the log). Its history and flip list for the debugger are compiled out of shipping builds.

What it costs: stat PulseProps (Level manager, Apply level, Props checked, Level changes, Props with levels), scopes in Unreal Insights, the cheat PulsePropsInfo, its snapshot (category Visual) and the Pulse Debugger page Props (below).

New and old props: a new prop starts with Near, Medium from 25 m (new motions stop) and Far from 60 m (parts under 50 cm hidden). Props saved before levels have none and look the same at every distance; add levels in their details to use them.

Validation: the distances must ascend and every Replace needs a replacement (errors); parts and levels that do not exist and events that fire farther than a motion they play runs give warnings.

Runtime and editor

The Pulse Prop component builds the parts from the asset as components below itself (never saved) and drives motions, states and events. Its tick sleeps while nothing moves and wakes for a state change, an event or the next random try, and follows the game clock: its rate, pauses and jumps (a jump plans the random tries anew). Props off screen only run their clocks (PoseOnlyWhenRenderedWithin); those that only run loops tick every 0.2 seconds then. Where nothing poses the parts (a dedicated server without bMoveOnDedicatedServer), loops do not keep the prop awake. In the level editor props move in realtime viewports only (bPreviewInEditor), never play sounds there, and are put back to rest before the level is saved.

In a game world a Pulse Prop component loads the assets of its prop asynchronously (bLoadAsync, on by default) and builds the parts once they are there, so nothing shows for a moment; assets in memory build at once, and so do editor worlds, previews and nested props. A dedicated server always builds at once, so its collision is there from the first frame. States set and events triggered while the assets load wait for the parts: once they are built the state blends from the state before and fires its triggers, and the events play late by the time they waited (their one-shot steps run late, not skipped). Replicated events that reach a client meanwhile play then as they would have on arrival. When another prop is set while the assets load, the events that waited for the prop before go (they neither play on the new prop nor block its events), whether the new prop builds at once (its assets in memory) or loads as well; the new prop starts as a newly set prop does, in the state set last where it has that state, without the waiting blend. Events and states set while the new prop loads wait for it as usual.

A prop dragged from the Content Browser into a level, or placed with Place Actors, becomes a Pulse Prop actor with that prop, previewed while dragging, its bottom on the surface (from the bounds of what the nearest level of its bake shows), like a static mesh.

Blueprint and C++ (category Pulse > Visual > Prop): Set Prop, Set State, Get State, Trigger Event, Get Rate, Is Event Playing, Get Event Play Count, Get Event Start Times, Get Part Component, Get Part Pivot, Get Collision Components, Reset Parts, Rebuild Parts; events On State Changed and On Event Started (native: OnStateChangedNative, OnEventStartedNative).

The rules are plain functions that specs test without a world: Pulse::Visual::Motion, Tracks, States, Pose (Gather: the poses of the parts in one frame), Timeline and Random (Prop/PulsePropLogic.h).

Debugging

Every prop component is a snapshot provider of the category Visual (Pulse Debugger, gameplay debugger, PulseDebugDump Visual): prop, state, rate, seed, network role, collision, sleep and the plays of each event. State changes and event starts go into the timeline. The level manager is a provider too (props per level, cells, cost per frame, changes per second, budget hits, flipping props). Cheats: PulseVisualInfo, PulseVisualState <State> [Actor], PulseVisualTrigger <Event> [Actor], PulsePropsInfo, PulsePropsBudget <ms>, PulsePropsSetting [Name] [Value] (a Pulse Visual setting for this session; bGpuMotions and RendererCellSize put every prop instance in again), PulsePropsDraw [Seconds] (the groups of prop instances by level), PulsePropsState <State> [Radius] and PulsePropsEvent <Event> [Radius] (states and events of prop instances near the view) (Console).

The Pulse Debugger page Props (module PulseVisualDebugger, in the editor and in Debug and Development builds of a game) shows the level manager of the world on top of the window:

  • Overview: props with levels and their cells, the cells and props the last pass checked, the props per level.
  • Cost: milliseconds per frame (last frame and the average of the last second) against the budget, level changes per second, and the last 60 seconds as a graph.
  • Prop assets by instances, most first, with Open in editor where there is an editor.
  • Prop instances: instances and sets, renderers and their mesh instances, hidden and loading instances with their placeholders, failed props, groups per level, instances moving on the GPU, live and waiting ones, and the calls of the handle functions with their refusals per reason (in total since the components were made). It shows without a level manager too.
  • Live props: live props of instances against the budget of the machine (MaxLive, MaxServerLive on a server with player pawns, see the server views under Many instances), warm props in the pool, the views of the last frame (cameras and player pawns, and how many live props may be near a camera and near a player pawn), and in the last frame the candidates, those without a place because the budget was full (a warning), those over the frame limit (MaxPromotionsPerFrame), those sent back over the budget, and the instances waiting for the assets of their live prop. On a dedicated server the page says that it picks no distance levels and runs only the live band.
  • Warnings: the budget ran out in the last 10 seconds (a pass took several frames), props changed level twice within a second (flipping at a border), or prop assets in the world have a stale bake for prop instances (save them); the page button counts them.

Many instances

Many props without an actor or a tick each: far away a prop is only instances of instanced static meshes, one renderer per mesh and material set, shared by every prop of the set. Near the camera an instance becomes a live prop from a pool, which starts where a prop live all along would be.

  • Pulse Prop Instances component (UPulsePropInstancesComponent, on the Pulse Prop Instances Actor): Instances are placed in its details and saved with it (prop, transform, start state, seed and id; Build Prop Instances and Pack into Prop Instances fill them from Pulse Prop actors, see Placing and packing); AddInstance, AddInstances and Add Prop Instance add instances at runtime (not saved, the prop must be loaded). The Seed of an instance (placed or in FPulsePropInstanceDesc) sets its random start and its Local Same tries; 0 takes one from its key, the same on every machine. Each instance has a handle (FPulsePropInstanceHandle) that stays valid while other instances come and go and goes stale when its instance is removed, or when the component registers again (a streamed level shown again, an edit): its instances are made anew and no handle of before comes back to life. Remove Prop Instance (RemoveInstances for many in one batch; with bInKeepStates the server keeps the states it sends of them for instances made again right after with the same ids, and ForgetStates drops those of ids that are not), Set Prop Instance Hidden, Get Prop Instance Face, Find Prop Instance (from a hit on a renderer); the component has Is Prop Instance Valid (Component), Get Prop Instance Transform (Component) and Get Prop Instance Prop (Component) beside the handle nodes of the same names. Never save or replicate a handle; the key (GetKey: the set from SetId, new for a copy of the component, and the id of the instance) is the same on every machine.
  • Renderers: the far entries of the prop’s bake go into instanced meshes attached to the component, one per mesh with its materials, rendering and collision (the prop’s collision profile), cull distance (FarCullDistance), and per prop where it needs custom data. Meshes with Nanite get an instanced static mesh, the others a hierarchical one. RendererCellSize splits the renderers of one component into cells. On a dedicated server only colliding entries are made (and no placeholders). Removing an instance moves the last mesh instance into its gap, so nothing else moves. A renderer is found by the hash of what its entries share and then compared in full (mesh, materials, material parameters, collision, prop with the hash of its bake, GPU entry, cell), so two entries never share a renderer by a hash collision. Many instances at once (the instances placed on the component, AddInstances, a prop that finished loading, a group that changes level) go in and out with one AddInstances and one RemoveInstances per renderer, with one navigation update each.
  • Distance levels: once play begins, the instances of one prop in one cell (InstanceCellSize, 20 m) form a group in the level manager and change level together; a group whose near and far edge lie on different levels gives each instance an entry of its own until it is on one level again. A level change moves only the entries that differ between the renderers: Show, Hide and Replace become instances of other meshes, Off leaves only collision. Without a level manager (editor worlds) and on a dedicated server instances stay on the nearest level. Get Prop Instance Level; SetInstanceLevel for tools and specs. The cheat PulsePropsDraw [Seconds] draws the group cells colored by level.
  • Loading: props load asynchronously through the asset cache of the world (UPulsePropAssetCache), once per prop asset: first the prop, then the meshes and materials of its far entries; a prop in memory is ready at once. Until a prop is there, PlaceholderMesh (empty: nothing) stands in, scaled to the bounds of the prop, which the asset registry knows before the prop loads (tag PulseInstanceBounds; read once per prop). Are Prop Instances Ready and On Ready say when every instance has its far assets. A prop or mesh that cannot be loaded is missing, with one warning. The near assets of live props (skeletal meshes, effects, sounds) load on request and stay NearAssetKeepSeconds after the last one; an instance the live band no longer looks at (its group out of reach after a teleport, hidden, removed) lets its request go in the next pass.
  • Live props: near a camera an instance becomes a live Pulse Prop component, so it plays its skeletal meshes, effects, sounds, events and CPU motions: within NearRadius of the prop (0: DefaultNearRadius, 30 m), back to instances beyond the radius times DemoteFactor (1.25) and after MinLiveSeconds. The assets of the live prop load ahead within the radius times PrefetchFactor; until they are there the instance waits (Promoting) outside the budget, so it takes no place, no promotion of the frame and no swap. At most MaxLive live props, MaxPromotionsPerFrame new and MaxDemotionsPerFrame gone per frame; the nearest come first (Priority of the prop counts; an instance outside the view cone of every camera, ViewConeDegrees from its view direction, counts BehindCameraFactor worse, one where a Replicated event runs or a state change still blends ActiveBonus better), and with a full budget a candidate takes the place of the worst live prop only with a score SwapMargin better. Static parts that never move stay as instances while the prop is live; the live prop builds the others. Live props come from a pool of the level manager: warm props of the same asset keep their parts (WarmPropsPerAsset, MaxWarmProps, gone after PoolTrimSeconds). A parked prop is hidden with every component below it and does not collide; it keeps nothing of its instance: events, motion clocks, triggers, play counts and its listeners are cleared, sounds, effects and skeletal animations stop at once. Get Prop Instance Live Component gives the live prop of an instance; GetInstanceHandle of a live prop gives its instance. The live prop belongs to the pool: never destroy it. One that game code destroyed anyway is dropped (never parked or taken again), and its instance is far again from the next pass on, or at once when an event is triggered or a state is set on it before that pass.
  • Server views: on a server (dedicated or listen) the live band also measures from the pawn of every connected remote player (its view target without a pawn, else the camera the client sent), so live props with their logic and collision are there where the players are, also on a dedicated server, which has no cameras: Replicated events, state blends, triggers and moving collision near a player run on the server as on the client. A server view is a position without a direction: it sees all around, so an instance whose nearest view is a player pawn never counts as behind a camera; the view cone counts only for the cameras of the machine (and an instance nearest to a camera is behind only outside the cone of every camera). The budget per machine (Pulse::Visual::Instances::Budget::GetLimits): a client keeps MaxLive; a dedicated server has MaxServerLive (128) live props, logic and collision without a picture (the distance levels stay off, live props pose and move their parts as props on a dedicated server do: only with bMoveOnDedicatedServer); a listen server with remote players splits its budget into two shares: MaxLive for the instances nearest to its own cameras and the rest, MaxServerLive minus MaxLive, for those nearest to the pawns of the remote players (MaxServerLive in all, never less than MaxLive; with MaxServerLive not above MaxLive the remote players get no live props there). Neither share can take the other’s places, however good its candidates, so the picture of the host keeps the budget of a client. A candidate whose share is full can only take the place of a live prop of the same share. When the limits shrink (a remote player goes, so the server share is gone) or an instance’s nearest view changes, the worst live props over a limit go back at once (within MaxDemotionsPerFrame, not waiting for MinLiveSeconds). Local players count only with their cameras; a client measures from its cameras alone. bServerPawnViews (on by default) switches the player pawns on and off (PulsePropsSetting bServerPawnViews False while playing: their live props go back); a dedicated server started without it has no level manager. SetExtraServerViews adds server views for tools and specs (with any of them the budget of a listen server applies, also in a game without network); GatherServerViews is the function to override. PulsePropsInfo and the debugger page show the cameras and server views of the last frame.
  • Catching up: far away nothing runs; a new live prop starts where a prop live all along would be. Work and Always motions start at the phase the far instance shows (from the game clock and the phase base of the instance, the same on every machine). The state jumps without state triggers, unless its change is younger than its blend time; then it blends on from the age of the change. Local events start afresh; Local Same tries that still run play from their offset (the tries follow from the seed and the game clock); Replicated events counted while the instance was far play from their offset while they still run, those that ran out are skipped. Each instance keeps the starts its live props saw, so nothing plays twice after it went back and became live again. The rate history far away is not kept: a state with another rate changes the phase bases so the far GPU phases go on without a jump, of Work motions and of Always motions alike (each runs on a clock of its own: Always motions at their idle speed below rate 1).
  • Handle functions (UPulsePropInstanceLibrary, C++ on the component): Set Prop Instance State (far it jumps: frozen parts take the pose of the state, the custom data its values; a live prop blends and fires its state triggers), Get Prop Instance State, Trigger Prop Instance Event (Local and Local Same only on a live instance; a Replicated event is counted also far away and plays once the instance is live while it runs; as on a live prop, a start while the last one still runs is refused with AlreadyPlaying unless the event restarts), Is Prop Instance Live, Get Prop Instance Live Component, Get Prop Instance Transform, Get Prop Instance Prop. The variants (Result) answer with an FPulseResult and a reason: Pulse.Visual.Result.StaleHandle, NotAuthority, UnknownState, UnknownEvent, NotLive, AlreadyPlaying. States and Replicated events change only on the authority (the server, or a game without network); with bLocalOnly on the component every machine decides for itself. SetState on a live prop goes to its instance, and its Replicated events are counted there. Delegates of the component: On Instance Promoted, On Instance Demoted, On Instance State Changed, On Instance Event Started (and ...Native). A state set while the prop still loads applies once it is there, and On Instance State Changed hears of it then, from the state the instance had before (its placed state, or the start state of the prop), and not at all when it ends where it was; a state the prop does not have falls back to its start state with a warning, as on a live prop. Get Prop Instance Id gives the id of an instance in its set (an int32 with the bits of the uint32 id, 0 for a stale handle), and Find Prop Instance By Id the handle of an id (one saved that way, or of an instance placed in the editor).
  • Replication: the sets are not replicated, every machine builds them from the same data (level, later the seed of a world); the server sends only what changes. An instance away from the state it was placed in, or with a Replicated event that may still play, has an entry (FPulsePropInstanceRep: set and id, state, server time of the change, name, count and last start of each Replicated event) in the Net Cells channel Pulse.NetCells.Channel.Props (layer Near: cells of 100 m, relevance 150 m plus half the cell diagonal in the plane, 5 updates per second, empty cells go after 10 s; loss behaviour Keep). The key is the set (A) and the id (B); the value is a compact codec (Pulse::Visual::PropNet::Encode / Decode: format byte, state name and number, change time, the events), smaller than the fast array item of before; ExpireTime stays on the server. Net Cells puts the entry into the cell of the instance, moves it when the instance moves to another cell (clients keep it meanwhile, no reset), covers the heights of the instances of a cell for Iris, keeps the cell awake and never saves it. Back in the state it was placed in, and once its events cannot play any more (a second after their length), the entry goes; so do the entries of a removed instance and of every instance of a set whose actor is destroyed (not of a level that streams out: its instances get their states back when it comes again). A client applies each entry to its instance by key: far it jumps (the frozen parts take the pose, the custom data the values; the phases go on from the time of the change), unless the change is younger than its blend time; a live prop takes it as a replicated Pulse Prop component does (a change this machine was there for blends from where the server is and fires its state triggers, an older one jumps), and plays a new Replicated start live when it is recent, else from its offset while it runs; a far instance keeps the starts for its next live prop. An entry whose instance is not there yet (a level not streamed in) waits in Net Cells (Waiting) and applies when the instance registers (ApplyKnown retries it). When a cell leaves the relevance of a client, its instances keep the last state they got (no reset to the start state); when the cell comes again, the new entries arrive, and instances the client knew a state of that have no entry any more are back in their start state, also when the server removed the whole cell meanwhile (Net Cells: a client near a cell without an actor for three seconds forgets its kept entries; near means within 80 % of the relevance radius in the plane and, as Iris measures in 3D, also to the middle of the heights of the cell, plus half of them). A late joiner gets the states and plays only events that still run. The live prop of an instance never replicates itself: its SetState, its Replicated events and its replicated state go to the instance and its entry. Without a network (standalone) or with bLocalOnly nothing is written, the states stay with the instances. States that are not kept are not saved: after a load every instance is in the state it was placed in.
  • Kept states: with bPersistInstanceStates on the prop, or Set Prop Instance State with Persist (SetInstanceState(Handle, State, true)), the server also keeps the state in a Pulse Sim record (kind FPulsePropInstanceSimState: set, id, state, change time; id PulseProp_<set hex>_<id>, relevancy None, no events, version 1). The record is there while the instance is away from the state it was placed in and goes when it is back (a state kept with Persist stays kept until then). Pulse Sim saves it with its regions; only the server knows it. A loaded record applies to its instance, also to one that registers later (a level streamed in after the load), and writes the entry of the instance, so a door stays open through a save, a reload and the unloading of its cell. The server clock starts again in every session: a loaded state counts as changed an hour ago (it jumps, without a blend or state triggers), and the record takes that time on. A load into the running world (Pulse Sim merges the records it reads) removes the records of kept states the save does not have: those instances were in their start state then and go back to it (OnRecordsLoadingNative and OnRecordsLoadedNative of Pulse Sim), also for a save without any Pulse Sim records. A record that changes, comes or goes while its instance is not there (its level streamed out on the server) takes the entry along: the entry gets the state of the record (a new entry in the cell of the record’s location; an entry there keeps its cell and height (FPulseNetCellPlace::KeepPlace); the start state when the record went), so clients see it now and the instance comes back in it. A record whose set is there but does not know its id (the instance was removed, for example a record of an older save) gets no new entry: no instance would ever put it back to the start state. Clients get kept states like all others in the entries: a kept state never depends on the relevancy of a Pulse Sim cell, and turning a state into a kept one changes nothing on clients.
  • GPU motions: far away, Spin, Swing, Slide, Scale and transform clips (Keyframes) move on the GPU through World Position Offset, up to Runs Up To Level; from the next level on the instance stands still (World Position Offset Disable Distance of its renderer). The material function MF_PulsePropMotion (Props/Functions in the Pulse Foundation content) computes the offset; add its output to the World Position Offset of the materials of moving parts, or use M_PulsePropMaster / MI_PulsePropMaster. Without it a part stands still far away, and the validation of the prop says so (a note). An entry with GPU motions has a renderer of its own whose material instance holds the pivots and axes of its motions and the scale of the entry; the phase base of its Work motions (from the key of the instance, the same on every machine), the rate of its state and the phase base of its Always motions are custom data 0, 1 and 2 (with MaxInstanceCustomData below 3 there is no room for them: the parts stand still far away, and the validation warns; far values follow from custom data 3 on); the time comes from the Pulse game clock through MPC_PulseProps, written once per frame: PulsePropTime within GpuTimeWrapSeconds, and PulsePropWrapCount, the whole periods before it. Each period adds its share of a repeat of each motion (PulsePropWrapCycles of the renderer times the speed and Repeats; for a Spin its share of a full turn, Repeats times Amount / 360), so every motion runs on without a seam at the wrap at every rate, Cycle Time, Repeats and Spin amount (up to the float drift of the material, under 0.01 cycles after about 100 hours), and a live prop takes over the pose the material shows: it runs on the clock not wrapped (CatchUp::GetPhase), which the material matches up to whole repeats (CustomData::GetCarried). The pose is the one of the live prop: the motions of one part add up (turns one after another, offsets added, scales multiplied) and go on once about its pivot as UE composes a live prop: the mesh scaled with the whole scale of the instance (entry, placement and component, read from the instance’s own local-to-world basis) and turned rigidly about the pivot, so a part with a non-uniform scale, or placed with one, keeps its shape while it turns; the arm from the pivot to the mesh and the offset are stretched by the placement scale in the space of the prop, so a part rotated against the part it hangs on still orbits that part’s pivot when the parent turns; then come the motions of the part it hangs on. Two limits: a mirrored (negative) placement scale counts as not mirrored, and the placement scale stretches offsets and arms in the space of the prop, where a live prop stretches them in the space of the part they hang on (the same while the parts they hang on are not rotated in the prop). Phases are clock * Repeats + Offset for every motion, transform clips included; clip offsets grow with the scale of the part they hang on; a motion without an axis stands still. When the rate of a far instance changes (a state with another rate), its phase bases keep only their share of a cycle, so a motion with Repeats that are not whole, or a Spin whose Amount times Repeats is not a multiple of 360 degrees, may jump there. One entry takes at most two GPU motions (MaxGpuMotionsPerEntry, clamped to 2); with more, the part stands still in the pose of its state. Transform clips are sampled into a curve texture made at runtime from the bake. bGpuMotions in the settings, GPU Motions of a prop (Default, On, Off) and Runs On GPU Far Away of a motion switch them; the content is built by Tools/build_prop_motion_content.py.
  • Culling of moving parts: the engine widens the culling bounds of instances only by Max World Position Offset Displacement of their material (and clamps offsets to it on each axis); a material instance can override it. M_PulsePropMaster sets 500 cm. When a renderer with GPU motions is made, Pulse Visual computes how far its parts move at most (GpuMotion::GetMaxDisplacement: turns sweep the corners of the mesh about each pivot, slides and clips move by their offsets); each time the renderer gets an instance with a larger placement scale (times the scale of the component, its largest axis), it checks that distance times the scale against its materials and logs one warning per material and prop where the material’s value is smaller, with the value to set: the need with room for larger placements (1.5 times); only a need beyond that value warns again, so slowly growing scales do not log a warning each. Without it, long blades or a bucket that swings from a far pivot flicker at screen edges and in shadows.
  • Surface: M_PulsePropMaster only combines MF_PulsePropSurface (Base Texture times Base Color, Roughness, Metallic) and MF_PulsePropMotion; use the functions in your own masters.
  • Custom data: the FarCustomData of the prop, with the values of the state the instance starts in (the default where the state sets none).
  • Instances in the details of a prop: NearRadius (where an instance becomes a live prop, 0 for the project setting), Priority (weight in the budget of live props), FarCullDistance, FarCustomData, bPersistInstanceStates (states kept through Pulse Sim) and GpuMotions (Default follows the project setting). Runs On GPU Far Away of a motion turns its GPU motion off; Far Stand In of a part shows a static mesh far away for a part that only lives near (a skeletal mesh, a Niagara system).
  • Bake: the instances read a runtime form of the prop (Baked): flat parts with their sockets resolved, the far instances of each distance level (Show, Hide and Replace become instances of other meshes, Off leaves only collision), the GPU motions with their sampled curves, the custom data layout, and bounds and costs per level. A hash of the source data (and of what the bake reads from the meshes) says when it is stale. The prop bakes when it is saved and cooked; in the editor a stale bake is made again after a change in the details and before instances read it; an instance whose prop was baked again in place puts the entries of the new bake in at its next change (state, level, live or far); renderers of entries with custom data or GPU motions belong to one bake, so those entries get the motions, curves and custom data of the new bake (the emptied renderers of the old one stay until the component registers again). The validation warns (“out of date”) only while the bake does not match the data (a mesh changed on disk, say); a prop the editor baked again is marked as changed and unsaved, which the Pulse Debugger lists (IsBakeStale) until the asset is saved (an autosave or the cook does not count). While playing in the editor a new bake stays in memory and does not mark the prop as changed. Saving a mesh, or importing it again, makes the props that use it bake again when the bake is next read. The cook declares the meshes and nested props the bake reads, and the project settings, as build dependencies of the prop (OnCookEvent), so an incremental cook bakes a prop again when one of them changed. A game never bakes: a prop without a bake of this version has invisible instances and logs one warning. Instances read the bake through UPulseProp::GetBake and the helpers Bake::GetLevelEntries, Bake::GetEntryTransform and Bake::UsesGpuMotions.
  • Plain parts: Pulse::Visual::Instances::Bake (Instances/PulsePropBake.h), the slot table and index map (Instances/PulsePropSlotTable.h) and the renderer keys (Instances/PulsePropFarRenderer.h) are plain functions and classes that specs test without a world.
  • Cost: stat PulseProps (Prop instances, Instance renderers, Instance updates, Live band, Live props, Warm pool props, Instance reps, Replication cells, Pending reps, Instance sim records), the tiles Prop instances, Live props and Instance replication (cells of the Props channel, entries sent, states received, states waiting for their instance, records kept in Pulse Sim, entries written and applied) of the Pulse Debugger page Props and PulsePropsInfo.
  • Validation: far values without a parameter or named twice, more custom data than MaxInstanceCustomData, GPU motions without room for their three floats, more than 64 levels, a stand-in on a static mesh part, states kept without states and states kept while Pulse Sim is off (bEnabled of the Simulation settings) give warnings; so does Whole collision without shapes and a collision mesh (see Collision).

Placing and packing

Level designers place props as actors and let the editor pack them into instances:

  • Drag and drop: a prop dragged from the Content Browser into a level (or placed with Place Actors) becomes a Pulse Prop Actor with that prop, previewed while dragging and standing on the surface with the bottom of what the nearest level of its bake shows, as a static mesh becomes a Static Mesh Actor.
  • Build Prop Instances (Build menu of the level editor, the right click menu of the level with or without a selection, or Pulse.Visual.BuildPropInstances): the Pulse Prop actors of the loaded levels stay the source in the editor and become Is Editor Only Actor: the cooked game does not have them, World Partition leaves them out of play in the editor, and in other levels they stay inert in play in the editor, whether the level is copied for play or a streaming level is loaded from disk only for play (no parts, no collision, hidden, not replicated), so only the instances play. The same holds for any Pulse Prop Actor marked Is Editor Only Actor. Their instances go into one Pulse Prop Instances Actor per cell of PackCellSize (64 m) and per level, data layers, runtime grid and Is Spatially Loaded of the actors. A built actor is labeled PropInstances_<x>_<y>, sits in the folder “Prop Instances”, carries the tag PulsePropBuild with the GUIDs of its sources (BuildSources) and is hidden in the editor, where its sources show. Each source keeps the set of its built actor (BuildSetId, advanced), so the build tells its own Is Editor Only Actors from those of the user. Who holds the instance of a source is one rule: the built actor that lists its GUID in BuildSources, nothing else. A pasted copy of a source (duplicated, or moved to another level, which the editor does by cut and paste) keeps BuildSetId and stays out of the game, but no built actor lists it yet: the next build takes it in by its new GUID, or lets it play as an actor where it stays one (Keep As Actor, a tag, a reference), so a moved source never plays beside its old instance and a copy never stays missing (the Check warns until that build, where a build can change it). The next build fills the same actors again: a cell whose actors did not change stays as it is, a changed cell is filled in place, a cell without prop actors loses its built actor; nothing is duplicated. The build is one undo step and reports what it did in a notification and the Output Log.
  • Stable ids: every instance takes its id from the GUID of its actor (the lower 32 bits of a hash, never 0); an id taken in its set goes to the next free one and the build reports it. A source keeps the id it had in its built actor, so only newcomers move, and a moved id is written into the source (InstanceId), so it stays when the source that held the id first goes. The set of a built actor comes from its level, cell, data layers and runtime grid, so a build keeps the key of every instance whose actor stays in its cell: handles found by id, saves and the Pulse Sim records of kept states stay valid. An actor moved to another cell gets the set of that cell (a new key). Start state and seed go with the instance; a seed of 0 means one from the path of the actor on the actor and one from the key on the instance, so the random start and the Local Same tries of an unset seed differ after packing (set a seed where they must stay).
  • World Partition: a built actor is spawned like any actor in the level of its sources (its own external package in a level with external actors), with exactly their data layers (not the current data layers of the editor, and each build sets them again) and their runtime grid and Is Spatially Loaded; the streaming generation then puts it into a cell by its bounds, as it does for its sources (a pack cell of 64 m lies inside one cell of the default 128 m grid; props that reach out of it can lift it one grid level). World Partition names the actor itself, so a build never looks for a built actor by name: one that is not loaded is found through its actor desc, which holds whether it was built, its set and the GUIDs of its sources (FPulsePropInstancesActorDesc, written when the actor is saved). An instances actor saved by an older version, whose actor desc does not hold these yet, tells nothing while it is not loaded: no build builds instances then (not on save either), and the build and the Check (a warning without a fix, also when nothing built is loaded) say to load it, build and save. Loading it and a build that leaves it unchanged do not rewrite its actor desc, so every build marks each such loaded actor to be saved (and says so), also while others are not loaded, so loading, building and saving region by region lifts the block; while one is loaded and not marked, the world counts as out of date (the Check offers the build, and the build on save runs; that save may not take the actor along, the next one does). Only loaded regions build: a cell whose built actor, or one of whose sources, is not loaded stays as it is (load the region and build again). A deleted built actor or source is gone, not unloaded, also before the deletion is saved (World Partition keeps its actor desc until then). A loaded source whose built actor is not loaded, or cannot be built now because other sources of it are not loaded, stays as it is too, also after it moved to another cell or became an actor that stays, so its old instance never plays beside it. A source moved into a cell that cannot be built now stays in the built actor that holds its instance, which takes it where it is now. A pasted copy of a source whose built actor (or another one of its set) still lists a prop actor that is gone and cannot be built now (after a cut and paste that is its own old instance) stays out of the game wherever it is, also in a cell that can be built, and the build and the Check say so, until the region is loaded and built. Any other source left out of the game that no built actor lists (its built actor was deleted, or it is a pasted copy) and whose cell cannot be built now plays as an actor until it can. Held sources and held copies do not make the level out of date: no build changes them while the region is not loaded, so the Check shows one note instead (see Check), and the build on save does not run for them. An unlisted copy that still waits to play as an actor does: the next build changes it, so the Check warns until then and leaves it out of the note. Locked levels are left out. The content of level instances is left to its own level asset (open it and build there): prop actors of a built level that were moved into a level instance or a packed level actor stay out of the game there and no build of the outer level reaches them, so the build and the Check name them (a warning without a fix) until their level asset is built.
  • Stay actors: props that the game finds as actors, or that do more than an instance can, are left as actors and the build says why: Keep As Actor (bKeepAsActor on the Pulse Prop Actor, off by default), Is Editor Only Actor set by the user (a placeholder: it stays out of the game and out of the instances), no prop, a class of its own (a Blueprint or another class: it may have logic), components added to the actor, attached actors, actor tags, replication settings that differ from the Pulse Prop Actor (Replicates, Always Relevant, Only Relevant To Owner, Net Dormancy, Net Update Frequency, Net Load On Client), Random Start off, hidden in game, and references from other objects of its level (another actor, a component, the level Blueprint; hard, weak and soft). A prop that stays an actor after it was built plays in the game again. References from assets outside the level are not seen.
  • Build on save: with bBuildPropInstancesOnSave on, saving a world that has built instances which are out of date builds them first (not for autosaves and the cook). Out of date means a build would change something: prop actors that only wait for a region to be loaded start no build. With World Partition the built actors are packages of their own: a build during the save of the map leaves them changed and unsaved; save again.
  • Check: Pulse Check (and Check All) warns about a level whose built instances are out of date (sources moved, changed, added or removed, or a prop still left out of the game that stays an actor or that no built instances hold) with the fix Build Prop Instances, and about prop actors inside a level instance that a build of another level left out of the game (no fix: build its level asset). While prop actors are only held back because their built instances actor, or other prop actors of it, are not loaded (World Partition), the Check adds one note with their number and the region to load, in whole cells of PackCellSize (“Load the region X … to …, Y … to … (cm) and build again”); a note is no warning and has no fix. Pulse.Visual.CheckPropInstances writes the same lines for the level in the editor to the Output Log (warnings as warnings, the note as a plain line). A level that was never built is never out of date; one whose built actors were deleted while their sources are still left out of the game is (and a save with bBuildPropInstancesOnSave builds it).
  • Pack into Prop Instances (right click on selected Pulse Prop actors, or Pulse.Visual.PackPropInstances): the actors become one Pulse Prop Instances Actor per level and data layers at the bottom center of the selection and go; one undo step. Its set is the one the actors had when they were unpacked (InstanceSetId, advanced) if they all had the same and no other instances actor uses it, so Unpack and Pack again keep the keys of the instances; else a new set. Actors that stay actors (see above) are left and reported, as are actors of locked levels and of level instances (Unpack leaves instances actors there too). Sources of a build that are packed leave the built actor that lists them in the same undo step (it goes when it has no sources left), so no prop plays twice; a source whose built actor is not loaded (World Partition) stays an actor, as does one a build left out of the game that no built actor lists yet (a pasted or moved copy: its old instance would stay; build first).
  • Unpack Prop Instances (right click on a Pulse Prop Instances Actor, or Pulse.Visual.UnpackPropInstances): every instance becomes a Pulse Prop Actor again with its transform, prop, start state and seed, in the level, folder and data layers of the instances actor (not those current in the editor), which goes; one undo step. The actor keeps the id of its instance (InstanceId, advanced), so packing it again gives the same id; a copy of the actor takes one from its own GUID. An instance whose prop does not load stays in the instances actor, which then keeps only such instances. Built actors are not unpacked: change their sources and build again.

PCG

The PCG node Spawn Pulse Props turns the points of a PCG graph into prop instances. It is the separate add-on Pulse Foundation PCG (module PulseVisualPCG, its own Git repository LuQ-Studios/PulseFoundationPCG), the only Pulse plugin that depends on PCG. A project without it never compiles or links PCG code. How the node places, picks and keeps props is in its documentation.

Prop editor

Double click a prop (or open it from the Pulse window) for the prop editor:

  • Parts (left), laid out like the Scene Outliner: a search box (it shows the parts with every word in their name and the parts they hang on), the columns eye, Part and Type (Static Mesh, Skeletal Mesh, Niagara System, Sound, Pulse Prop or Empty), the icon of the asset class before each name, and the count of the parts below (“2 of 5 parts (1 selected)”). The parts form a tree by parent. The eye hides a part in the editor only; parts hidden at the start of the game are dimmed. Rename in place (F2): motions, overrides and steps follow. Drag rows onto rows to hang parts elsewhere (they keep their place); drop meshes, Niagara systems, sounds or props from the Content Browser on a row (a new part below it) or on empty space (below the root part). The right click menu adds empty parts, duplicates (Ctrl+D), mirrors across X, Y or Z, makes four of a part (Mirror Four, for the legs of a table) and deletes parts with what hangs on them and what names them. A part on a socket is mirrored onto the socket of the parent at the mirrored place (Leg_L to Leg_R), or onto the parent’s pivot where there is none.
  • Viewport (middle): the assembled prop with a 1 m grid (a stronger line every 5 m; Show > Grid hides it) and a figure for comparison (FigureHeight). The motion paths of the selected part (or of all parts) show where it goes: the line of its pivot, the arc of its farthest corner and a ghost of its shapes at each end pose (both ends of a swing or a slide, the end of an event motion that stays away); keys of keyframe clips are dots. Collision shows the collision of the parts, or the shapes of a whole collision, which the gizmo moves, and the simple collision of its collision mesh. Click a part or its point to select it (Ctrl adds), drop assets on a part or on the ground, right click for the menu of the parts. Its toolbar is the viewport toolbar of the engine (on the left the camera speed, the transforms menu with World or Local space, snapping and the transform tools W, E, R; drags of the gizmo follow the grid, rotation and scale snapping, in Build, Animation and edit-state mode and for Pivot Only; on the right scalability, the preview profile, Show, Lit, Perspective and the options); the prop editor adds the green Play (Pause while it plays) on the left and Props (Snap to Sockets, Figure, Collision, Cost, All Paths and the distance level), Pivot Only and the state menu on the right. The mode shows as a badge in the top left corner (“Editing State: Open” in the purple of the mode; its tooltip has the hints of the mode). The state menu is the current state: what the editor shows, plays and edits; the timeline (every tab), the details and edit-state mode follow it. Its first entry, Base pose, is the rest pose with the base values (no state) and means Build mode: Build mode always shows the base pose. Picking a state in Build mode (in the menu or the state list) edits it in edit-state mode; picking Base pose in edit-state mode goes back to Build. Animation mode stays when a state or the base pose is picked and shows it (it keys the cycle in that state).
  • Details (right, full height), laid out like the details of a Blueprint’s components: at the top the green + Part (an Empty Part, or per visual type an asset picker of its assets; the new part hangs on the selected part, without one on the root part) and the search of the details. Below, the selected part, motion, track, key, state, override, event or step, or the prop when nothing is selected (more below). A part gets a header with the icon of its visual and a green + Motion: Work Motion, Always Motion or Event Motion, each with Keyframes, Spin, Swing, Slide or Scale (one undo step; a Work Keyframes clip is the clip of the cycle, an Event Keyframes clip the <Part>_Event clip a step plays, an Always clip <Part>_Always as long as the cycle), and Track of the Cycle with the properties of the part. In edit-state mode it is + Override: the properties to override in the current state.
  • The bottom tabs below the viewport are Timeline (in front), Check, Validation (comes to the front after Validate) and Notes. The default layout changed with this order; a layout saved by an earlier version is replaced once.
  • Timeline (bottom), three tabs, laid out closer to Sequencer: above the names of the rows the green + Track (the properties of the selected part, then a submenu per part; + Override on the States tab and in edit-state mode) and Search Tracks (it keeps the rows with every word in their name, their rows and the rows above them). Rewind, step back, play and pause, step and the speed (0.25 to 2) are in its bar with the transport icons of Sequencer; keys are drawn as the keys of Sequencer and the bars take the tints of its tracks (Work motions the 3D Transform teal, Always motions the Audio blue, Event motions the Event green, animations the Skeletal Animation purple). Click or drag on the tracks to go to a time; drag keys, clips and the phase marker (they snap to 1/30 s and to other items, Shift does not snap). The rows are a tree: a part row opens to its clips and their property tracks (the arrow; what is open stays open for the session).
    • Motions: two sections that open and close. Cycle holds the Work and Always motions, in seconds of the state the bar plays it in (a state with Rate 0.5 shows a cycle twice as long, so the playhead matches the pose). Below each part its motions: their repeats and a Phase marker to drag (it shifts the motion by its Offset). The tracks of a keyframe clip sit right below the part when the part has one cycle clip; with several, each clip gets a row of its own with its tracks below. Events holds a block per Event motion (“Open (Lid)”): its bar from its own 0 (drag the right end for its length), a row Own time with its seconds, and the tracks of a clip. The + of the section Cycle adds a motion for a part without one (as + Part), the + of Events an Event motion (a Keyframes clip <Part>_Event an event plays with Play Motion), each one undo step. The Focus list in the bar shows All (both sections), only the Cycle, or one Event motion: then only that motion shows, on its own length, and Play plays it once. The focus stays for the editor session. Fire Event fires an event, or plays an Event motion, at the play position on top of the running cycle, as the game does (focus All or Cycle); a paused preview starts playing, so it shows at once. Seeking runs it again from that time; Clear Fired, another tab or a focused motion forget it. What Play plays does not change: the cycle here, the event picked on the Events tab there.
    • States: on the left the list of the states (the start state is marked “start”), each row with its Rate and Blend time to type in. Click a row to make it the current state and to show its fields in the details (name, rate, blend time, overrides; a click on empty space of the list or another tab gives the selection before back); right click for New, Rename, Duplicate, Delete and Set as Start State (each one undo step; a state renamed here or in the details keeps its start state and the state triggers of the events). Delete on the keyboard deletes the selected state as the menu does. A click on the title STATES shows the settings of every state in the details (Start State, picked from the states). On the right a row per part the current state overrides, with a row per property below it and + Override on the part row; the status says what the state holds (“Open: 3 overrides”). Play transition from [state] plays the blend from the state picked into the current state, once: the track Blend shows the blend time of the current state (drag its end to change it) while and after it plays, and the preview stays in the current state at its end. Hide Blend, another current state or another tab end the transition preview.
    • Events: on the left the list of the events, as the state list of the States tab: each row with the name, a mark of its replication (LOCAL each machine, SAME the same on every machine, NET the server; the tooltip names the mode) and its length. + New adds an event (Event, made unique); right click for New, Rename (in place), Duplicate and Delete, and Delete on the keyboard deletes the selected event (each one undo step; a deleted event takes its triggers and steps, the motions it plays stay). A click on a row makes the event current (the timeline shows its steps from 0 and Play plays it) and shows it in the details (name, replication, restart, level, triggers and steps; a rename there keeps it current). A click on a step shows the step, a click on empty space of the tracks shows the event again. The bar keeps Add Step and Fires. A row per part (the parts with steps first) shows its steps as clips: the motions it plays, Plays from a Start Part to its Stop Part, Shown from a Show Part to its Hide Part, animations; messages are on their own row. The tracks of the event clips of a part sit below it, their keys at the time of the step plus the time of the key. Drag a clip to move its step (an edge moves only that step; the end of a motion clip sets the duration of the motion). Right click a row, or use Add Step, to add a step at the time: show, hide, start, stop, an animation, an Event motion of the part, a new keyframe motion (its Play Motion step goes to 0, so key times are event times) or a message.

Tracks and keys on the timeline:

  • + Track on a part row lists what the part can animate: the properties of its visual type and, for material parameters, the parameters of its materials with their defaults. Properties that have a track are checked. On the States tab the button is + Override (an override of the current state).
  • Right click on the timeline while a part is selected: Add track for Lid (on the States tab Add override for Lid) opens the same list.
  • + Part in the bar of the Motions and States tabs gives a part without a row one: on the Motions tab a motion for it (a click on the part adds a Keyframes clip to key in Animation mode; its submenu adds a Spin, Swing, Slide or Scale motion instead), on the States tab an override of the current state (pick the property).
  • Each track row has a key button (filled when a key sits at the play position; a click adds or removes it) and buttons for the previous and the next key. A part row has a button that keys all its tracks.
  • Parent rows (a part, a clip) show small summary diamonds for the keys of their tracks; dragging one moves every key of the clip at that time.
  • The shape of a key shows its interpolation: Smooth round, Linear a diamond, Step a square.
  • Click a key to select it, Ctrl and Shift add to the selection, drag on empty space for a box. Dragging moves every selected key.
  • The right click menu of a key or track: Set Key, Smooth, Linear, Step, Copy, Cut, Paste, Delete Key, Set Clip End Here, Remove Track, and Add track for (or Add override for) the part.
Key Does
S Set Key: keys the selected tracks at the play position, else every track of the selected part, else the channel the gizmo is on
, and . Previous and next key of the selected tracks or part
Ctrl+C, Ctrl+X, Ctrl+V Copy, cut and paste keys; pasted at the play position onto the selected tracks, else onto the same properties of the selected part. Keys are copied as text, so they paste into other props and later sessions
Delete Deletes the selected keys and steps of the timeline
1, 2, 3 Build mode, Animation mode, edit-state mode (for the current state)
Escape Leaves edit-state mode

The asset toolbar has Save, Browse, Validate, Simulate, Check and Review (the distance level, the cost, the docs and another prop to open); on its right the modes Build | Animation | State (keys 1, 2, 3).

Build mode (key 1, blue frame): the gizmo (W move, E turn, R scale) changes the rest place of the selected part; the preview shows the rest pose while you drag. Pivot Only (P, in the toolbar of the viewport) moves the hinge or axle of a part without moving its mesh or what hangs on it. With Snap on, a dragged part snaps to the sockets of other parts within SnapDistance and hangs on the socket when you let go. Scrubbing the timeline shows the pose at that time; on the base pose the start of the cycle shows the rest pose. Build mode always shows the base pose: key 1 in edit-state mode (or with a state shown in Animation mode) goes back to it, and picking a state edits that state.

Animation mode (key 2, red frame) leaves the rest pose alone: the gizmo puts the selected part where it should be at the play position and keys only the channel it changed (move a Location key, turn a Rotation key, scale a Scale key), making the track when it is missing. The chip in the view says what it keys:

  • Motions tab: the keyframe clip of the part (the selected one, or the only one) at that place of the cycle; the first key of a new track also adds rest keys at the start and the end of the clip, so the loop closes. An Event motion in focus is keyed in its own seconds.
  • Events tab: the keyframe clip of the part that a Play Motion step started before the play position, at the time since that step. A part the event does not move yet gets a new keyframe motion <Event>_<Part> with its Play Motion step at 0 and its first key.
  • States tab: an override of the current state (a transition preview goes to the end of its blend first).

The key takes what the other motions and the state add in the order the game adds them, so the part lands where you put it. A drag is one undo step.

Edit-state mode (key 3, State of the mode switch or a state picked in Build mode; purple frame) edits the current state; on the base pose key 3 edits the state edited last, else the start state. The viewport says “Editing State: Open”. The gizmo and the details write overrides of that state; a value set back to its base removes the override. Picking another state in the menu (or in the list of the States tab) edits that state; the base pose cannot be edited this way (picking it leaves edit-state mode for Build). The fields of the rest pose are read-only there, with a hint to switch to Build. Escape leaves the mode for the mode before it.

With nothing selected the details show the whole prop without Parts, Motions, States and Events (the parts tree, the timeline and the state list edit them): the level matrix and Levels, Cycle Time, Idle Rate and the advanced motion settings, Start State (picked from the states), Collision and Instances. A click on the header Cycle of the Motions tab shows the settings of every motion in the details (Cycle Time, Idle Rate, Opacity Parameter, GPU Motions), as a click on a motion shows the motion.

Fields that name something of the prop are picked from a list: the target of a step (a part for Show, Hide, Start and Stop Part and Play Animation, a motion for Play Motion), the state of a State Entered or State Left trigger, the part and the Link parts of a motion, the parent of a part (none: the root of the prop), the part of an override (none: every part) and the start state. A name that names nothing (a part that was deleted) stays with “(missing)” in the warning color.

The details follow the mode:

  • Animation mode: Animated values at 1.20 s lists the tracks of the selected part with their values at the play position and a key button each. Editing a value keys it (auto key).
  • Edit-state mode: State values in Open lists the overrides of the part with a reset arrow (back to the base); + Override in the header of the part adds more.
  • A selected state shows Overrides of Open (3), grouped by part, with a remove button on each and Remove All.

Values of keys and overrides show by their kind: one number, a checkbox, X Y Z (Pitch, Yaw, Roll for a rotation), or R G B A with a color swatch. Material Parameters of mesh settings have Add Parameter, which lists the parameters of the mesh’s materials.

Simulate (toolbar) runs the prop like in a game: its random and state triggers start events, the timeline shows the state changes and event starts, and its bar sets states and triggers events (also those started by messages). The gizmo is off while it runs; stopping goes back to the timeline where it was.

Check

Check (toolbar) finds parts that go into each other while they move. It poses the prop like the game, without a world, and tests the collision of the parts against each other:

  • the cycle in each state, by time as the prop plays it there (at CheckSamplesPerSecond, and at least 24 poses per repeat of the fastest motion);
  • in a state with a rate below 1, a grid of Work and Always phases (they drift apart there over time);
  • each blend from one state into another, at 5 poses;
  • each event from its start to its end, with the motions its steps play and the parts its steps show and hide.

Each part counts with the simple collision of its mesh (boxes, spheres, capsules; a convex hull as its box), or the bounds of its mesh when it has none. A nested prop counts by its parts, posed like the component plays it in each pose: in the state of the same name (else in its start state), blending with its own blend time when it has the state a blend goes to, with its Work and Always motions on its own rates and no events; a cycle is long enough for its motions too. Props nested in it count the same way, up to three levels deep. A prop that would show itself again (a loop) and deeper props count as the box of their bounds at rest. Parts of the same nested prop are not tested against each other: the Check of that prop does it. The Check tab says how many nested props it tested. Parts without a mesh and hidden parts are left out, and so are a part and its parent (they are joined by design), a Link rod and the parts it links, and two parts that never move. Two parts go into each other when they overlap more than at rest by more than CheckTolerance.

The Check tab lists the hits with the depth, where they happen and in how many poses. Click one: the state of the hit becomes current (a blend shows as a transition into it, an event in the start state, an overlap at rest on the base pose), the timeline goes to its tab and time, both parts are selected and their collision is drawn red where they go into each other most (for a nested prop the shapes of its parts in that pose). Parts that overlap at rest are listed below for information. Once it ran, the Check stays current while you edit. Validation runs it too (bCheckOnValidate): the Validate button, the Pulse Check and the validation of the Content Browser warn once per pair of parts (“Parts Lid and Frame go into each other by 3.2 cm in event Open at 1.20 s”). The hits are warnings, not errors: some props want parts to touch.

Levels and cost

The Level list (Review in the toolbar, Props in the viewport; it replaces Far View) shows the prop on one of its distance levels as the game shows it from there: parts shown, hidden or replaced, and motions that stop there hold their pose. Its first entry, Full prop, goes back to the normal preview (no level picked by hand: the nearest level); the console form is Pulse.Visual.PropEditor Level <index>, with something that is not a number for the full prop. The viewport says what the level costs (“Far from 60 m: 12 draws, 3.1k tris; 2 hidden, 1 replaced; 1 motion runs”).

What each part shows on each level is set in the details of the prop (no part selected), section Levels: a matrix with a row per part and a column per level, each cell Auto (it says “small: hidden” where the level hides it by size), Show, Hide or Replace with a static mesh from a picker (other visual types go in the list of levels below it). Up to which level a motion runs: right click its row on the timeline (Runs), or Runs Up To Level in its details; rows of motions that stop early say so (“Spin · to Medium”). Up to which level an event plays its cosmetic steps: Fires next to Add Step on the tab Events, or Fires Up To Level in its details.

Cost counts parts, draw calls (mesh sections, one per Niagara system) and triangles of the first level of detail, nested props by their parts, and names the dynamic material instances of the preview (“18 parts, 22 draws, 41.2k tris, 2 dynamic materials”). Props > Cost in the viewport shows “18 parts, 22 draws, 41.2k tris” as a badge; Review > Cost in the toolbar lists the totals with every part shown, as the prop starts and as far instances (from the bake of the prop, on its nearest level), one line per distance level (with what renders there as instances and how many of them move on the GPU, from the bake), and one sortable row per part.

Create from selection

Select actors in the level and pick Create Pulse Prop from Selection in their right click menu, or Prop from Selection on the Create step of Foundation in the Pulse window (the button is on while actors are selected). Their static meshes (each instance of an instanced static mesh too), skeletal meshes (with an animation played as a single node), Niagara systems, sounds and Pulse props become parts, with override materials that differ from the mesh and their collision; scene components between them stay as empty parts only when something hangs on them. Actors attached to other selected actors hang on them, the others on an empty root part. The pivot of the prop is the bottom center of the selection, turned like the first actor. Pick where to save the prop, then whether the actors are replaced by a Pulse Prop actor of it (one undo step); the prop opens in the prop editor. Unattended runs (-unattended, automation) ask nothing: the prop goes to /Game with a free name and the actors stay.

Settings

Project Settings > Pulse > Visual (UPulseVisualSettings, DefaultGame.ini):

Setting Default Description
bPreviewInEditor true Props move in realtime level editor viewports.
bMoveOnDedicatedServer false Props move their parts on a dedicated server too (moving per-part collision).
PoseOnlyWhenRenderedWithin 0.5 Props not rendered for this long only run their clocks; 0 poses them every frame.
OpacityParameter Opacity Scalar material parameter the Opacity property of props sets (a prop can name its own).
OpacityHideBelow 0.01 Parts whose materials lack the opacity parameter show only while their opacity is at least this.
LevelCheckInterval 0.5 s How often the level manager starts a pass over the props with distance levels (on each machine), when a camera moved or props came or moved.
LevelHysteresis 0.1 Share of a level’s distance a prop goes beyond a border before it changes level, and before it changes back.
LevelCellSize 5000 Edge length of a cell of the level manager’s search grid (cm).
LevelFrameBudgetMs 0.5 Milliseconds the level manager may spend per frame on collecting and checking props and applying their level changes; leftovers go on in the next frame, at least one change a frame (cheat PulsePropsBudget).
LevelViewMoveThreshold 50 A camera that moved less than this since the last pass starts no new one (cm).
LevelResumeBlendSeconds 0.25 s A Work or Always motion that held on a far level and runs again catches up with the cycle over this time.
MaxInstanceCustomData 8 Prop instances: floats of per-instance custom data at most (the three of GPU motions and the Far Custom Data of a prop); below 3, GPU motions stand still.
bGpuMotions true Prop instances: motions run on the GPU far away (props override it with GPU Motions).
MaxGpuMotionsPerEntry 2 Prop instances: GPU motions one far instance may have (its part’s and those of the parts it hangs on), 1 or 2 (what MF_PulsePropMotion takes; a larger value in an ini counts as 2).
CurveSamplesPerSecond 30 Prop instances: samples per second of transform tracks baked for the GPU.
RendererCellSize 0 Prop instances: cells that split the renderers of one component (cm); 0 for one renderer per mesh and material set.
PlaceholderMesh none Prop instances: the mesh that stands in while a prop loads, scaled to its bounds; none shows nothing.
NearAssetKeepSeconds 30 s Prop instances: seconds the assets of live props stay loaded after the last one went.
InstanceCellSize 2000 Prop instances: cells that group the instances of one prop for the level manager (cm).
MotionCollection none Prop instances: the parameter collection GPU motions read their time from; none takes MPC_PulseProps of Pulse Foundation.
GpuTimeWrapSeconds 3600 s Prop instances: the time of GPU motions runs in this period, so floats in the material stay exact; the whole periods go along (PulsePropWrapCount), so motions run on without a seam at the wrap (each period adds its share of a repeat of every motion). A change applies to renderers made after it.
DefaultNearRadius 3000 Prop instances: within this distance from a camera an instance becomes a live prop (props may set their own Near Radius).
DemoteFactor 1.25 Prop instances: a live prop goes back beyond its radius times this.
PrefetchFactor 1.5 Prop instances: the assets of a live prop load ahead within its radius times this.
MinLiveSeconds 1 s Prop instances: a live prop stays live at least this long.
MaxLive 64 Prop instances: live props at most on a client or in a game without network, and near the cameras of a listen server.
MaxServerLive 128 Prop instances: live props at most on a dedicated server (logic and collision near the pawns of the players), and in all on a listen server with remote players, of which MaxLive stay for its cameras and the rest is for the remote players (server views under Many instances).
bServerPawnViews true Prop instances: on a server the live band also measures from the pawns of the remote players; off: only the local cameras (a dedicated server started with it off has no level manager; switched off while playing, its live props go back).
MaxPromotionsPerFrame 4 Prop instances: instances that become live per frame at most.
MaxDemotionsPerFrame 8 Prop instances: live props that go back per frame at most.
BehindCameraFactor 2 Prop instances: the score of an instance behind the cameras counts this much worse.
ViewConeDegrees 70 Prop instances: degrees between the view direction of a camera and an instance beyond which it is outside the view cone; outside the cone of every local camera it counts as behind (BehindCameraFactor).
ActiveBonus 0.5 Prop instances: the score of an instance where something happens counts this much better.
SwapMargin 0.2 Prop instances: with a full budget a candidate takes the place of a live prop only with a score this much better.
WarmPropsPerAsset 4 Prop instances: warm live props kept per prop asset.
MaxWarmProps 64 Prop instances: warm live props kept at most (the oldest go first).
PoolTrimSeconds 30 s Prop instances: warm live props nobody took for this long are destroyed.
PackCellSize 6400 Prop instances: cells in which Build Prop Instances packs the Pulse Prop actors of a level (cm), one instances actor per cell, level, data layers and runtime grid (editor).
bBuildPropInstancesOnSave false Prop instances: saving a level with built prop instances that are out of date builds them first (editor).
FigureHeight 180 Height of the comparison figure of the prop editor (cm).
SnapDistance 15 Parts dragged or dropped in the prop editor snap to a socket within this distance (cm).
CheckTolerance 1 The Check reports parts that go into each other by more than this beyond their overlap at rest (cm).
CheckSamplesPerSecond 30 Poses per second of a cycle or an event that the Check tests; each blend is tested at 5 poses.
bCheckOnValidate true The validation of a prop (Validate, Pulse Check, Content Browser) runs the Check too.

PulseFoundation plugin documentation.

This site uses Just the Docs, a documentation theme for Jekyll.