Settings

The brush is your primary painting tool. It's a sphere-shaped gizmo rendered in the viewport showing where the next cluster of meshes will spawn.

Brush gizmo colors

• Green wireframe - paint mode (default)

• Yellow wireframe - erase mode (shift held)

The brush draws as a hemisphere on the impact surface plus vertical arcs for depth perception.

Brush Settings

Found in the Brush Settings section of the toolkit panel.

Brush Radius

The radius of the spawn sphere, in Unreal units (1 unit = 1 cm by default).

• Default: 100

• Range: 10-500 (slider), 10+ via direct entry

• Effect: larger radius spawns meshes spread across a larger area per click. Smaller radius packs them tight.

• Tip: match the radius to the visual scale of your meshes. Painting individual rocks with radius 30; painting large boulders with radius 800.

Stroke Spacing

Controls how far you must drag the brush before another spawn cluster fires. Expressed as a fraction of the brush radius.

• Default: 0.5

• Range: 0.05-2.0

• Effect: at 0.5, the next cluster fires when you've moved half a brush radius. At 2.0, you must move two full radii. At 0.05, clusters fire almost continuously as you drag.

• Tip: lower spacing for dense coverage, higher spacing for sparse scatter. Spacing of 0.1 with cluster size 1 produces a continuous "spray" feel.

Cluster Size

The number of mesh instances spawned per click or per spacing-tick during a drag.

• Default: 5

• Range: 1-20

• Effect: a click with cluster size 5 spawns 5 cubes simultaneously inside the brush radius. With cluster size 1, only one spawns per click/tick.

• Tip: cluster size and spacing interact. To paint 100 rocks across a 10-meter trail: cluster size 5, spacing 0.3, drag the trail. To paint isolated landmarks: cluster size 1, spacing 1.0+, click each one individually.

Min Scale / Max Scale

Global scale randomization for spawned meshes. Each spawn picks a uniform random scale between Min and Max, multiplied by the per-mesh multipliers from the palette entry (see Mesh Palette section).

• Defaults: Min = 0.8, Max = 1.2

• Range: 0.01-10.0

• Effect: all meshes spawn somewhere between 80% and 120% of their authored size. A 10×10×10 cm cube becomes 8-12 cm.

• Tip: wider ranges produce more visual variety. For natural scatter (rocks, foliage), use 0.6-1.4 or wider.

Random Rotation

When checked, each spawned mesh gets a fully random rotation (yaw, pitch, roll). When unchecked, all spawns face their authored forward direction.

• Default: on

• Effect: rotation is applied at spawn. The physics simulation may further rotate the mesh during settling, but the initial orientation is randomized.

• Tip: turn off for upright objects (trees, signs, lamps). Leave on for natural scatter (rocks, debris, leaves).

The palette holds the pool of meshes the brush picks from. Each entry has a weight (relative pick probability) and per-mesh scale multipliers (which combine with the global Min/Max Scale). 

Adding meshes

Drag a static mesh asset from the content browser into the palette section. The drop target highlights when you're hovering with a valid asset. Multiple meshes can be dropped at once.

Each new entry defaults to:

• Weight = 1.0

• MinScaleMultiplier = 1.0

• MaxScaleMultiplier = 1.0

Empty slots show a placeholder thumbnail. Slots can hold any UStaticMesh asset; physics behavior depends on whether the asset has authored simple collision.

The "Clear" button

Removes all entries from the palette. Once cleared, drag new meshes back in.

Per-row controls

Each palette row has two sub-rows of controls:

Top row:

• Mesh thumbnail

• Mesh name

• X button (remove this entry only)

Bottom row:

• W spinbox: Weight (0.0 to 10.0)

• Min spinbox: MinScaleMultiplier (0.01 to 5.0)

• Max spinbox: MaxScaleMultiplier (0.01 to 5.0)

Weight

Relative probability of being picked vs other entries.

• Default: 1.0 (uniform with siblings)

• 0.0 means never picked. Effectively disables an entry without removing it.

• Higher values bias toward this mesh. Three entries with weights 1, 1, 8 means the third mesh is picked 8/10 of the time.

• Tip: for natural-looking variety, use weights like 5, 3, 2, 1 to create a clear primary mesh with diminishing accents. Pure 1, 1, 1 distributions look algorithmic.

MinScaleMultiplier / MaxScaleMultiplier

Per-mesh scale range, multiplied with the brush's global Min/Max Scale.

• Defaults: 1.0 / 1.0 (no per-mesh modification)

• Final scale formula:

The math is forgiving: if you accidentally set Min > Max, the tool sorts them internally so you don't crash on inverted ranges.

Tip: use per-mesh multipliers to pack meshes of dramatically different scales into one palette. A "boulder" entry with multipliers 2.0/3.0, a "small rock" entry with 0.3/0.7, and a "pebble" entry with 0.05/0.15 - all coexist in one palette and share the same brush.

Drag-drop UX

• Dragging a non-static-mesh asset into the palette is rejected (no add).

• Dropping the same mesh twice creates two separate entries (deliberate - you may want different weights for the same mesh).

• Reordering entries is not currently supported. Workaround: clear and re-add in desired order.

Every paint stroke creates a layer. The Layers section of the toolkit shows all current layers with their instance counts and provides controls for managing them. 

What a layer contains (Technical)

Internally, each layer holds:

• A unique ID (GUID, used internally; not shown in UI)

• A display name (editable; defaults to "Layer 1", "Layer 2", etc.)

• A brush snapshot - the brush settings at the time the stroke began (radius, spacing, cluster size, scale range, rotation flag). Frozen at stroke open.

• A per-mesh array of HISM instance indices - the baked instances this layer owns.

• A list of still-simulating actors (transient - populated during a stroke, drained as meshes settle).

• A creation timestamp.

The brush snapshot is currently informational; it doesn't drive any replay logic. Future versions could use it for "stroke replay" features.

The Layers panel

The panel lists all layers in creation order, with multi-select support.

Each row shows:

• A selection indicator (highlight when selected; click row to select, ctrl-click for multi-select)

• The layer name (editable inline; see Renaming below)

• The instance count (sum of baked HISM instances + still-simulating actors)

• A delete button (X) on the row

The header shows total layer count.

Renaming a layer

Two ways:

1. Single click on the name twice (the engine's default activation pattern): click the row to select it, then click the name once more. The text becomes editable.

2. Double-click the name directly. Edit mode activates immediately.

Type a new name, press Enter to commit. Empty names are rejected (the rename is silently dropped).

Caveat: if the layer has actively simulating cubes (count is changing as cubes bake), the rename field may close itself as the count refreshes. Wait for all cubes to settle before renaming, or click "Force Bake All" to bake them immediately.

Deleting a layer

Click the X button on the layer's row. The layer is deleted immediately:

• All baked HISM instances belonging to this layer are removed (with proper index-shift handling so other layers' instances stay correct).

• Any still-simulating actors that were spawned by this stroke are destroyed.

• If the deleted layer was the only one referencing a particular mesh, the mesh's HISM component is also destroyed (orphan cleanup).

• The layer record itself is removed from the panel.

Manual deletes are NOT undoable via the toolbar's "Undo Last Stroke" button. They're considered explicit deliberate edits, not strokes. If you need to recover a deleted layer, you'll need to repaint.

Merging layers

Select multiple layers (ctrl-click), then click the Merge Selected button in the panel header. All selected layers are combined into one - their instance index arrays merge, the live actor lists merge, and the result keeps the first selected layer's name and ID.

Merge is useful when you've painted several strokes that conceptually belong together (e.g. painted "rocks on this hillside" in three passes; merge them into one "Hillside Rocks" layer for cleaner organization).

Merge is NOT undoable via the toolbar button. Like delete, it's explicit.

Layer counter behavior

New layers are named "Layer 1", "Layer 2", etc. The counter increments on each new layer. When you delete all layers and start fresh, the counter resets to 1 — you don't end up with "Layer 47" after a full wipe. Counter resets are only triggered by going from N layers to 0; partial deletes keep the counter monotonic.

Hold Shift while clicking or dragging the brush to enter erase mode. The brush gizmo turns yellow.

What gets erased

Any FT_Chaos-spawned mesh in the brush radius:

• Baked HISM instances - removed from the HISM, with proper index fixups so other layers remain consistent.

• Still-simulating actors - destroyed mid-flight.

Note: erase scope is "any FT_Chaos mesh," not filtered by the current palette. If you painted with mesh A, then changed the palette to mesh B, you can still erase mesh A's instances. This makes erase forgiving — you can always remove what you previously painted.

Erase strokes are undoable

Each shift+drag is one erase stroke pushed to the undo stack. Click Undo Last Stroke to restore everything erased in that drag, including the live actors that were destroyed.

Erasing emptied layers

If your erase removes ALL instances of a layer (count drops to zero), the layer record stays in the panel with count = 0. This is intentional - it preserves the layer for undo restoration. You can manually delete the empty layer with the row X button if you don't want to keep it.

What erase does NOT do

• It doesn't reactivate baked instances back into simulating actors. (Reactivation/attract brush is a future feature.)

• It doesn't cross-level erase. Operating on one level only.

• It doesn't filter by mesh type - drag the eraser, everything in radius goes.

The "Undo Last Stroke" button in the toolkit panel reverses your most recent stroke — paint OR erase. 

What's on the undo stack

Every paint stroke and every erase stroke pushes one entry. Pressing the button pops the top entry and reverses it:

• Paint stroke → deletes the layer it created (same effect as the row X button).

• Erase stroke → restores the erased instances at their original transforms and respawns any destroyed live actors.

What's NOT on the undo stack

• Manual layer delete (the per-row X button) - not undoable. The button visually confirms the action.

• Layer merge (the Merge Selected button) - not undoable.

• Rename - not undoable, but you can rename again to set the name back.

• Mode settings changes - not undoable. Modify settings as you need; previous settings are not preserved across changes.

• Force Bake All - not undoable. The bake is destination-state; once cubes are HISM instances, they're permanent until layer-deleted or erased.

Ctrl+Z behavior

Ctrl+Z does not trigger FT_Chaos's undo stack. It triggers UE's global transaction system, which captures simulating-actor spawns from your stroke. So:

• During a paint stroke (meshes spawning, some still simulating), Ctrl+Z will destroy the still-simulating actors that were captured in the transaction. Baked HISM instances are NOT affected.

• After a stroke fully bakes, Ctrl+Z does nothing for that stroke - the actors that were in the transaction no longer exist.

To fully undo a stroke including baked instances, use the Undo Last Stroke button.

This split is intentional. UE's transaction system preempts mode-level Ctrl+Z handling for that specific keybind, and trying to override it created edge cases worse than the split. The button is the supported path for full-stroke undo.

Undo and the simulating actor cap

The cap (default 2000 simultaneous simulating actors, see Mode Settings) is a paint-time guardrail. Undo bypasses the cap - if undoing an erase respawns 50 cubes when 1990 were already simulating, all 50 spawn anyway. Undo prioritizes correctness over the cap.

Found in the Mode Settings section of the toolkit panel. These are session-scoped (reset to defaults when you exit/re-enter the mode). Organized into categories.

FT_Chaos | Capacity

MaxSimultaneousSimulatingBodies

The cap on how many simulating actors can exist at once.

• Default: 2000

• Effect: when reached, further spawns are blocked. The tool tries to bake settled cubes to free room; if that doesn't free any (cubes haven't settled yet), it logs a one-time warning per stroke and skips remaining spawns until room opens.

• Tip: raise for stress testing or larger paint passes. Lower if you're hitting performance issues on slower hardware. Each simulating actor costs CPU per physics tick; baked HISM instances cost almost nothing.

FT_Chaos | Settled Detection

These control when a simulating actor counts as "at rest" and gets baked into HISM.

LowLinearVelocityThresholdSq

The squared linear velocity below which an actor counts as "low velocity" for that tick. Squared because comparing Vel.SizeSquared() is faster than Vel.Size().

• Default: 2500 (i.e. ~50 cm/s linear speed)

• Range: 0-100000

• Tip: lower values are stricter (meshes must be more still to bake). Default is tuned for typical gravity-driven settling. Raise if you have piles that take forever to bake (you don't mind cubes being slightly mobile when they're called "settled"). Lower for ultra-precise placement.

LowAngularVelocityThresholdSq

Same idea for rotational velocity. Squared radians per second.

• Default: 5.0

• Range: 0-500

• Tip: small uneven meshes tend to wobble after they "land" — they roll back and forth before truly settling. If you're seeing extended wobble before bake, raise this threshold; if you want more precise rotational rest, lower it.

LowVelocityTicksToSettle

How many consecutive ticks an actor must stay below both velocity thresholds before being marked settled.

• Default: 60

• Range: 1-500

• Effect: at 60 ticks (about 1 second at 60 fps), an actor must remain calm for a full second before bake. Lower values bake more aggressively; higher values wait longer for true rest.

• Tip: if a few cubes never settle (the long tail), lower this to bake more aggressively. If cubes are baking while they're still visibly moving, raise it.

FT_Chaos | Damping

Per-tick velocity clamping. Off by default; useful for taming bouncy or chaotic settling.

EnableVelocityDamping

Master switch. When off, velocity-damping fields below are ignored.

• Default: off

MaxLinearVelocity

When damping is enabled, simulating actors with linear velocity above this are clamped down. Doesn't affect bodies below the threshold.

• Default: 500

• Effect: caps how fast a cube can move. Useful for taming "yeeting" cubes that fly across the map after a hard contact.

MaxAngularVelocity

Same idea for rotation. Radians per second.

• Default: 30

• Effect: caps tumble speed. Combines well with linear damping to produce calmer settling overall.

FT_Chaos | Physics Multipliers

Global multipliers applied to spawned cubes' physical material at spawn time. These scale the source mesh's UPhysicalMaterial values.

FrictionMultiplier

Scales the spawned body's friction.

• Default: 1.0 (no change from asset)

• Range: 0.0-5.0

• Effect: at 5.0, cubes settle quickly and slide less. At 0.0, cubes slide as if frictionless (note: contact friction combines with the OTHER body's material, so 0.0 friction on cubes against a 0.7 friction floor is not truly zero).

• Tip: when piling rocks on a slope, raise to 2.0-3.0 to encourage settling. When you want loose-feeling debris, drop to 0.3-0.5.

RestitutionMultiplier

Scales bounciness.

• Default: 1.0

• Range: 0.0-5.0

• Effect: at 5.0, cubes bounce dramatically. At 0.0, cubes hit and stop dead.

• Tip: for natural rock-pile feel, restitution at 0.0-0.3 looks right (rocks don't bounce). For ball-pit-style decoration, 1.5-2.0 produces lively cascades.

Important: these multipliers only affect simulating actors. Already-baked HISM instances have no physical material - they're static visual data. Changing multipliers and clicking already-baked instances has no effect.

Important: if your source mesh has no physical material assigned (the asset's body setup Phys Material slot is empty), the multipliers don't apply - Chaos uses its default behavior. If you want predictable multiplier effects, assign a UPhysicalMaterial to your source mesh asset.

FT_Chaos | Safety

KillZ

World-space Z below which simulating actors are auto-destroyed each tick. Catches the infinite-fall edge case where a cube spawns through surface geometry into the void.

• Default: -20000 (200 meters below world origin)

• Range: -100000 to 0

• Tip: lower (more negative) values give larger landscapes more headroom. Effectively disable by setting to e.g. -1000000.

FT_Chaos | Collision

SkipCollisionlessMeshes

When on, meshes without authored simple collision are refused at spawn time with a one-time warning per mesh.

• Default: on

• Effect (off): the tool spawns the mesh anyway. It will fall forever (no collision = nothing to land on), then get destroyed by KillZ. Useful only as a diagnostic - it lets you see exactly which mesh is collision-less.

• Tip: leave on. The warning tells you which mesh needs collision authored, which is the actual fix.

TraceComplexCollision

Controls whether the brush's surface trace honors complex (per-triangle) collision on the level geometry.

• Default: on

• Effect: when on, the brush hits the visible triangle mesh of your level geometry, even on collision-less meshes (the trace itself works without simple collision). When off, the trace only hits simple-collision shapes.

• Caveat: even with this on, spawned cubes WILL NOT collide with complex-only level geometry. That's a Chaos limitation we can't work around. The brush traces the visible surface; the cubes need authored simple collision on the level geometry to interact with it.

Force Bake All button

A button at the top of the toolkit panel (above the collapsible sections). Clicks bake every currently-simulating actor regardless of whether it's settled.

Use cases:

• A few stubborn cubes never settle (perfect-balance edge cases) and you don't want to wait.

• You want to "lock in" the current visual state before saving the level.

• You're stress-testing and want predictable bake timing.

Caveat: force-baking actors that haven't settled means they bake in mid-air or mid-tumble. The result may look unnatural. For natural piles, let normal settling do its work and use Force Bake All only for cleanup.

Undo Last Stroke button

The other always-visible button. Reverses the most recent paint or erase stroke. Greys out when the undo stack is empty.