unreal-chaos-physics

Unreal 5.8 Chaos Physics

---
name: unreal-chaos-physics
description: Design, implement, tune, replicate, optimize, and debug Chaos Physics systems in Unreal Engine 5.8. Use for collision channels and shapes, scene queries, rigid bodies, mass, damping, friction, restitution, CCD, forces and impulses, Physics Constraints and drives, substepping, async/fixed physics, networked physics replication modes and resimulation, Physics Assets, ragdolls, physical animation, Geometry Collections, fracture and clustering, Chaos Fields, destruction caches, Chaos Cloth, Chaos Visual Debugger, unstable simulation, tunneling, jitter, explosions, or physics performance.
---

# Unreal 5.8 Chaos Physics

## Choose the physical contract first

Read [`references/system-selector.md`](references/system-selector.md).

1. Define which interactions are authoritative gameplay and which are cosmetic simulation.
2. Choose query-only, simple rigid body, skeletal Physics Asset, constraint assembly, Geometry
   Collection, cloth, or cached playback.
3. Define collision object/trace channels, shape representation, mass/inertia, timestep, sleep, and
   network authority before tuning forces.
4. Build the smallest stable case at target scale and frame-rate range.
5. Add constraints, drives, fields, fracture, cloth, and replication incrementally.
6. Reproduce worst contact counts, piece counts, player latency, and frame spikes on target hardware.
7. Capture Chaos Visual Debugger plus Timing/Network Insights when the failure is not visible in one
   component's settings.

Use `unreal-replication` for general Actor/property/RPC ownership. This skill owns physics-specific
replication modes, inputs/state history, correction, and resimulation.

Load only what applies:

- [`references/collision-and-queries.md`](references/collision-and-queries.md)
- [`references/rigid-bodies-forces-and-sleep.md`](references/rigid-bodies-forces-and-sleep.md)
- [`references/constraints-and-drives.md`](references/constraints-and-drives.md)
- [`references/timestep-substepping-and-async.md`](references/timestep-substepping-and-async.md)
- [`references/networked-physics.md`](references/networked-physics.md)
- [`references/physics-assets-and-ragdolls.md`](references/physics-assets-and-ragdolls.md)
- [`references/destruction-collections-and-fields.md`](references/destruction-collections-and-fields.md)
- [`references/cloth.md`](references/cloth.md)
- [`references/debugging-and-performance.md`](references/debugging-and-performance.md)
- [`references/use-case-recipes.md`](references/use-case-recipes.md)

## Required answer format

Return:

1. **Gameplay authority and chosen physics representation**.
2. **Collision/query matrix**, shapes, scale, mass/inertia, and physical material.
3. **Timestep/threading/substep assumptions** and failure frame-rate.
4. **Forces, impulses, constraints, drives, fields, or fracture/cloth settings** with units/effects.
5. **Network replication mode**, input/state ownership, correction, and latency test if multiplayer.
6. **Performance budget** for bodies, contacts, constraints, pieces, cloth vertices, events, and traces.
7. **Chaos Visual Debugger/Insights evidence** and acceptance checks.

## Hard rules

- Prefer simple primitives/convex collision for simulation; `Use Complex Collision As Simple` cannot
  simulate the object itself.
- Separate Query Only, Physics Only, and Query and Physics behavior deliberately.
- Enable overlap/hit events only for consumers that need them; event generation has work and both sides'
  response settings matter.
- Use force for sustained acceleration and impulse for an instantaneous change. Apply at location only
  when induced torque is intended.
- Do not repair scale, mass, collision, or timestep errors by arbitrary extreme damping/solver values.
- Treat UE 5.8 substepping, async substepping, and async physics settings as Experimental and test every
  platform/gameplay dependency.
- Physics callbacks under substepping may produce multiple ordered contact transitions in one game frame.
- Default, Predictive Interpolation, and Resimulation solve different network problems; Resimulation is
  more costly and the Network Physics Component requires manual C++ integration.
- Chaos Cloth is Production Ready in UE 5.8; Chaos Caching remains Experimental.
- Bound destruction piece/contact/event lifetime with clustering, sleep/disable/removal, and pooling.
- Do not make authoritative damage depend on nondeterministic cosmetic debris or cloth contacts.
- Profile the complete scene; a stable isolated asset can fail under real contact and solver load.

See [`references/sources.md`](references/sources.md) for the UE 5.8 primary-source trail.

## Choose the physical contract first

Read [`references/system-selector.md`](/unreal/unreal-chaos-physics/system-selector/).

1. Define which interactions are authoritative gameplay and which are cosmetic simulation.
2. Choose query-only, simple rigid body, skeletal Physics Asset, constraint assembly, Geometry
   Collection, cloth, or cached playback.
3. Define collision object/trace channels, shape representation, mass/inertia, timestep, sleep, and
   network authority before tuning forces.
4. Build the smallest stable case at target scale and frame-rate range.
5. Add constraints, drives, fields, fracture, cloth, and replication incrementally.
6. Reproduce worst contact counts, piece counts, player latency, and frame spikes on target hardware.
7. Capture Chaos Visual Debugger plus Timing/Network Insights when the failure is not visible in one
   component's settings.

Use `unreal-replication` for general Actor/property/RPC ownership. This skill owns physics-specific
replication modes, inputs/state history, correction, and resimulation.

Load only what applies:

- [`references/collision-and-queries.md`](/unreal/unreal-chaos-physics/collision-and-queries/)
- [`references/rigid-bodies-forces-and-sleep.md`](/unreal/unreal-chaos-physics/rigid-bodies-forces-and-sleep/)
- [`references/constraints-and-drives.md`](/unreal/unreal-chaos-physics/constraints-and-drives/)
- [`references/timestep-substepping-and-async.md`](/unreal/unreal-chaos-physics/timestep-substepping-and-async/)
- [`references/networked-physics.md`](/unreal/unreal-chaos-physics/networked-physics/)
- [`references/physics-assets-and-ragdolls.md`](/unreal/unreal-chaos-physics/physics-assets-and-ragdolls/)
- [`references/destruction-collections-and-fields.md`](/unreal/unreal-chaos-physics/destruction-collections-and-fields/)
- [`references/cloth.md`](/unreal/unreal-chaos-physics/cloth/)
- [`references/debugging-and-performance.md`](/unreal/unreal-chaos-physics/debugging-and-performance/)
- [`references/use-case-recipes.md`](/unreal/unreal-chaos-physics/use-case-recipes/)

## Required answer format

Return:

1. **Gameplay authority and chosen physics representation**.
2. **Collision/query matrix**, shapes, scale, mass/inertia, and physical material.
3. **Timestep/threading/substep assumptions** and failure frame-rate.
4. **Forces, impulses, constraints, drives, fields, or fracture/cloth settings** with units/effects.
5. **Network replication mode**, input/state ownership, correction, and latency test if multiplayer.
6. **Performance budget** for bodies, contacts, constraints, pieces, cloth vertices, events, and traces.
7. **Chaos Visual Debugger/Insights evidence** and acceptance checks.

## Hard rules

- Prefer simple primitives/convex collision for simulation; `Use Complex Collision As Simple` cannot
  simulate the object itself.
- Separate Query Only, Physics Only, and Query and Physics behavior deliberately.
- Enable overlap/hit events only for consumers that need them; event generation has work and both sides'
  response settings matter.
- Use force for sustained acceleration and impulse for an instantaneous change. Apply at location only
  when induced torque is intended.
- Do not repair scale, mass, collision, or timestep errors by arbitrary extreme damping/solver values.
- Treat UE 5.8 substepping, async substepping, and async physics settings as Experimental and test every
  platform/gameplay dependency.
- Physics callbacks under substepping may produce multiple ordered contact transitions in one game frame.
- Default, Predictive Interpolation, and Resimulation solve different network problems; Resimulation is
  more costly and the Network Physics Component requires manual C++ integration.
- Chaos Cloth is Production Ready in UE 5.8; Chaos Caching remains Experimental.
- Bound destruction piece/contact/event lifetime with clustering, sleep/disable/removal, and pooling.
- Do not make authoritative damage depend on nondeterministic cosmetic debris or cloth contacts.
- Profile the complete scene; a stable isolated asset can fail under real contact and solver load.

See [`references/sources.md`](/unreal/unreal-chaos-physics/sources/) for the UE 5.8 primary-source trail.

unreal 5.8 chaos physics design, implement, tune, replicate, optimize, and debug chaos physics systems in unreal engine 5.8. use for collision channels and shapes, scene queries, rigid bodies, mass, damping, friction, restitution, ccd, forces and impulses, physics constraints and drives, substepping, async/fixed physics, networked physics replication modes and resimulation, physics assets, ragdolls, physical animation, geometry collections, fracture and clustering, chaos fields, destruction caches, chaos cloth, chaos visual debugger, unstable simulation, tunneling, jitter, explosions, or physics performance. chaos cloth chaos cloth chaos cloth is production ready in ue 5.8. prefer the chaos cloth asset/dataflow workflow for new authoring and convert legacy skeletal-mesh cloth when continued editing/round-trip needs justify it. authoring sequence 1. import/build the render and simulation meshes; keep simulation topology only as dense as deformation requires. 2. define skin weights, fixed/kinematic regions, seam/panel construction, and cloth-to-character mapping. 3. paint/author constraint masks for max distance, stiffness, damping, bending, and related properties. 4. add collision primitives/physics asset with simple, stable shapes. 5. configure gravity, wind, animation drive, self/intersection behavior, and solver iterations deliberately. 6. build cloth simulation lods and validate transition behavior. parameter directions: - more simulation vertices/iterations/collision shapes improve potential fidelity and raise cpu cost; - higher stiffness resists stretch/bend but can require finer timesteps/iterations; - damping reduces oscillation but can deaden motion; - stronger animation drive holds cloth closer to animated pose and reduces free secondary motion; - self-collision can be expensive; enable only where visible intersections justify it. test worst animation speed, teleports, spawn, lod changes, wind, frame spikes, character scaling, multiple characters, and collision extremes. reset/teleport cloth state explicitly when discontinuous movement would stretch history across the world. authoritative gameplay must not depend on cloth particle contacts. use separate collision/gameplay shapes. collision and queries collision and queries configure the matrix 1. define stable object channels for categories and trace channels for questions. 2. give each component a preset: collision enabled mode, object type, and per-channel block/overlap/ignore. 3. use query only when no solver contact is required; physics only when only simulation contacts matter; use query and physics only when both are consumed. 4. enable generate overlap events or simulation generates hit events only where the callback is needed. 5. test both participants' response rows; the interaction resolves from both settings. shape selection - sphere/capsule/box: cheapest stable approximation for many props/characters; - multiple simple primitives: preserve concavity with bounded shape count; - convex hulls: irregular simulated bodies, avoiding excessive hull detail; - complex trimesh: detailed scene queries/static collision when justified. collision complexity: | mode | behavior | |---|---| | simple and complex | simple shapes for simple queries/simulation, trimesh for complex queries | | use simple as complex | complex queries use simple shapes; saves trimesh memory/expense | | use complex as simple | simple queries/other bodies collide with trimesh; this object cannot simulate | use ccd on fast small bodies only after proving tunneling. it increases collision work and cannot repair bad collision geometry, teleportation, or an excessively large timestep. validate at gameplay scale, maximum speed, rotating thin obstacles, low frame rate, and cooked collision. constraints and drives constraints and drives build order 1. place body shapes, centers of mass, and constraint frames correctly. 2. disable collision between constrained bodies when their shapes should not fight the joint. 3. lock/free/limit x/y/z and swing1/swing2/twist to form the intended hinge, slider, ball, or fixed joint. 4. test hard limits before enabling soft limits or motors. 5. add position/orientation and velocity drives with bounded max force. 6. add break/plasticity rules only after stable normal operation. parameter effects: - higher stiffness/drive strength reaches the target harder but can oscillate or demand more solver work; - higher damping opposes target-relative velocity and reduces oscillation but can feel sluggish; - restitution adds bounce at a violated limit; - lower max force allows lag/compliance; unlimited/excess force can overpower the assembly; - slerp angular drive handles full orientation but does not work when an angular axis is locked; - twist and swing drive works with decomposed axes/locked configurations. projection is a post-solve correction. it can stiffen a chain at lower iterations but works poorly while the chain interacts with other objects and may inject nonphysical correction. shock propagation stiffens chains by increasing parent mass on the last solve iteration but can inject energy. use both as measured, bounded tools—not default fixes. validate constraint-frame alignment, extreme pose, dropped frame, contact load, break threshold, scale, and network correction. debugging and performance debugging and performance chaos visual debugger open tools -> debug -> chaos visual debugger. record local/remote pie, client/server, or packaged development/test sessions. capture only needed data channels; cvd data volume and recording overhead can be substantial. test builds may omit object debug names. inspect particles, position/velocity/mass/state, collision geometry/channels, contact constraints, joint constraints, character ground constraints, sync/async frames, and resimulated frames. save recordings for cross-team reproduction without requiring project assets. symptom matrix | symptom | inspect first | |---|---| | falls through thin wall | collision shape, speed/timestep, ccd, teleport versus sweep | | jitters at rest | penetration, shape seams, mass ratio, contact/constraint, per-frame writes | | constraint stretches/explodes | frames, limits, collision, mass ratio, timestep, drive/projection | | overlap/hit fires twice | both-side settings, substep callback queue, duplicate components | | ragdoll explodes | overlapping bodies, bad constraints, scale, pose penetration | | debris never settles | sleep thresholds, ongoing field/contact, removal policy | | network object rubber-bands | replication mode, authority, send/latency, predicted forces | | cloth stretches/explodes | teleport reset, collision penetration, timestep, stiffness/iterations | profile timing insights/stat physics plus active/dynamic/sleeping bodies, shapes, broadphase pairs, contacts, constraints/iterations, substeps, cloth vertices/iterations, destruction pieces/events, and cvd/trace overhead. disable visualization/recording for final timing. destruction, geometry collections, and fields destruction, geometry collections, and fields author a bounded collection 1. create a geometry collection from suitable source meshes in fracture mode. 2. fracture only to the piece scale visible/interactive in play. 3. cluster pieces into hierarchy levels; higher clusters simulate as fewer bodies until broken. 4. configure collision/size-specific data, damage thresholds, material interiors, and initial state. 5. anchor structural regions with construction fields or authored support. 6. trigger external strain/velocity with a bounded transient field. 7. sleep, disable, remove, or swap settled small debris according to gameplay authority. field types: - transient: execute temporary strain/force/velocity and disappear. - construction: establish initial persistent structure such as anchors. - persistent: evaluate every physics tick until removed; scope narrowly because cost persists. external strain must exceed the relevant cluster damage threshold. num strain hits can advance multiple cluster levels. sleep pieces can wake from collision; disabled pieces cannot unless explicitly activated. use field metadata/culling to restrict particle state, object type, position, and volume. unbounded persistent fields can affect unintended particles and add per-tick work. budget unbroken collections, active bodies, contacts, constraints, break events, renderer pieces, niagara/ audio callbacks, replication, and removal. cache deterministic cinematic destruction when live interaction is unnecessary; chaos caching and achaoscachemanager are experimental in ue 5.8. networked physics networked physics the server remains authoritative. select replication per actor interaction pattern: | mode | use | tradeoff | |---|---|---| | default | simple replicated simulated props with limited local interaction | legacy correction overwrites local alterations; interactions degrade | | predictive interpolation | server-authoritative props that clients predictably push/interact with | better local interaction, cheaper/less network intensive than resimulation | | resimulation | physics pawns/actors needing full local prediction and authoritative replay | input/state history, rewinds/replays, higher cpu/memory/network complexity | default mode applies velocity/correction toward the forward-predicted server state. predictive interpolation includes local velocity and correction timing so predicted interactions can survive. resimulation runs the client ahead and rewinds/replays when authoritative state diverges. for resimulation, implement the low-level network physics component in c++: 1. define serializable input and state structures. 2. capture player input at physics-step cadence. 3. apply identical deterministic-enough forces/actions during prediction and replay. 4. cache bounded history for latency/jitter budget. 5. compare authoritative state and trigger resimulation/correction through the framework. 6. separate cosmetic events from replayable authoritative effects to avoid duplicates. ue 5.8 supports predictive interpolation and resimulation simultaneously on different actors and adds networked actions. inspect np2.predictiveinterpolation, np2.resim, and p.resim console families for current tuning options rather than copying stale cvar recipes. test packet loss, jitter, latency, low send rate, high velocity, collisions between modes, ownership transfer, sleep/wake, spawn/despawn, and correction visibility. physics assets, ragdolls, and physical animation physics assets, ragdolls, and physical animation author 1. open the physics asset editor and fit minimal capsules/boxes/spheres/convex bodies to meaningful bones. 2. remove or simplify tiny bodies that do not affect collision/readability. 3. disable collision for adjacent bodies that should not contact. 4. align constraint frames at anatomical/mechanical joints. 5. set swing/twist limits from the intended range, then test animation extremes. 6. assign mass, damping, physical materials, and body/constraint profiles by gameplay state. 7. simulate in-editor with representative collision and impulses; then test in the actual character. choose the behavior - full ragdoll: transition the required bodies to simulation and define capsule/movement/camera ownership. - partial ragdoll: simulate below a bone while animation controls the rest. - physical animation component: drive simulated bodies toward animation using a named profile. - rigid body animation node: secondary physics inside the animation graph when its world/collision mode fits. blend in/out with an explicit state machine. on recovery, stop gameplay authority from reading unstable limb contacts, choose a valid get-up pose/orientation, reconcile the character capsule, and return body control in a known order. profile body/contact/constraint counts across all characters. skeletal visual lod does not automatically guarantee a cheap physics representation; use physics asset/body/constraint profiles and distance/state policy appropriate to the game. rigid bodies, forces, and sleep rigid bodies, forces, and sleep body setup - fit collision around the mass-bearing shape; remove tiny snagging features. - set density/physical material or mass in kg deliberately; inspect center of mass and inertia behavior. - use linear/angular damping for real resistive behavior, not to mask unstable contacts. - set friction/restitution through physical materials and test combined material behavior. - enable gravity, ccd, hit/wake events, and simulation only when required. apply motion | intent | use | notes | |---|---|---| | sustained thruster/wind | add force each physics/game update for duration | mass matters unless accel change | | instantaneous kick/explosion | add impulse once | mass matters unless vel change | | sustained force causing rotation | add force at location | off-center application creates torque | | instant off-center strike | add impulse at location | changes linear and angular motion | | direct kinematic placement | move/teleport/sweep policy | do not mix arbitrary transform writes with free simulation | sleep settled bodies to remove solver work. if an object wakes repeatedly, inspect contact jitter, moving supports, thresholds, tiny penetrations, constraints, and per-frame property/transform writes before forcing sleep. disabled destruction pieces cannot be collision-woken; use only when the lifecycle allows it. test mass ratios. very light bodies constrained/contacting extremely heavy bodies can destabilize stacks and joints; correct representation and scale before raising iterations or projection. ue 5.8 primary sources ue 5.8 primary sources - physics in unreal engine - collision overview - simple versus complex collision - physics bodies reference - physics constraint reference - physics sub-stepping - physics project settings - networked physics overview - physics asset editor - destruction overview - cluster geometry collections - chaos fields user guide - physics fields overview - chaos visual debugger - capturing with chaos visual debugger - clothing tool - ue 5.8 release notes - chaos caching api - add force at location - add impulse pages were checked against ue 5.8 documentation on 2026-07-19. reconfirm maturity labels, replication apis/modes, threading/timestep behavior, defaults, field nodes, and chaos caching after an engine upgrade. system selector system selector | need | prefer | |---|---| | detect without physical response | query/overlap or trace with explicit channel | | block/move kinematically | collision component + swept movement | | free simulated prop | simple/convex rigid body | | hinge, slider, tether, suspension | physics constraint component/constraint profile | | skeletal collision/ragdoll | physics asset | | animation with localized physical response | physical animation component/profile | | breakable authored object | geometry collection + clustering/fields | | region-based force/strain/state | transient/construction/persistent chaos field | | deforming garment | chaos cloth asset/solver | | repeatable cinematic heavy simulation | authored/cache playback, noting chaos caching is experimental | | server-authoritative interactive physics | predictive interpolation or resimulation by interaction needs | decision questions: 1. must the result affect authoritative movement, damage, cover, or navigation? 2. is continuous collision response required, or only a query/event? 3. what is the smallest collision representation preserving the gameplay silhouette? 4. what frame-rate/latency/piece/contact worst case must remain stable? 5. can distant/settled results sleep, disable, remove, swap representation, or play a cache? timestep, substepping, and async physics timestep, substepping, and async physics physics stability depends on maximum step size. ue's frame delta varies; large steps reduce contact and constraint accuracy. project settings -> physics exposes: | setting | effect | |---|---| | max physics delta time | caps simulated step; a lower cap may slow simulation during long frames | | substepping | divides a frame step into smaller solves; improves stability at cpu/bookkeeping cost | | max substep delta time | smaller permits finer/more steps and higher cost | | max substeps | caps catch-up work; beyond it, simulation cannot maintain the requested resolution | | tick physics async | moves simulation to async thread; experimental in ue 5.8 | | async fixed time step size | fixed async step; experimental and requires thread-safe integration | substepping, substepping async, and async physics are marked experimental in ue 5.8 project settings. do not enable them merely because an asset jitters. first correct scale, penetration, collision shape, constraint frames, mass ratios, and force application. collision callbacks are queued until the final substep and may include begin and end contact for the same pair in one game frame. make event consumers idempotent and state-based; do not award damage twice from callback multiplicity. async/fixed simulation creates a game-thread/physics-thread boundary. read/write physics state through supported apis and schedule authoritative forces/inputs at the intended physics step. test 30/60/120 fps, frame spikes, pause/time dilation, slow motion, and network resimulation. use-case recipes use-case recipes hinged door use one simulated door body plus world/frame constraint. lock linear axes; free or limit one angular axis; lock the others. add angular drive only for self-closing. limit max force so players can resist it. disable frame-door collision if shapes fight. test both push directions, edge impacts, low fps, and replication. explosive prop use a radial impulse or transient field once, not a per-frame force. keep gameplay damage authoritative and separate from debris. bound affected object types/radius, enable ccd only for fast critical fragments, and cap/sleep/disable/remove cosmetic pieces. partial hit reaction use a physics asset plus physical animation profile below the hit bone. apply a bounded impulse at the hit location, blend physics weight, then restore animation/body state. keep character movement/capsule authoritative unless the design intentionally enters ragdoll. breakable wall use clustered geometry collection, anchored supports, size-specific collision, and thresholded transient strain. break large clusters first; disable/remove settled small fragments. test worst simultaneous walls, event-driven vfx/audio, navigation/cover authority, and network representation. physics pawn use resimulation only when full predicted interaction is required; otherwise evaluate predictive interpolation. implement step-indexed inputs/state/actions in c++, keep cosmetic events replay-safe, and test latency/loss/jitter/corrections against non-player physics objects.

Chaos Cloth

# Chaos Cloth

Chaos Cloth is **Production Ready in UE 5.8**. Prefer the Chaos Cloth Asset/Dataflow workflow for new
authoring and convert legacy skeletal-mesh cloth when continued editing/round-trip needs justify it.

## Authoring sequence

1. Import/build the render and simulation meshes; keep simulation topology only as dense as deformation
   requires.
2. Define skin weights, fixed/kinematic regions, seam/panel construction, and cloth-to-character mapping.
3. Paint/author constraint masks for max distance, stiffness, damping, bending, and related properties.
4. Add collision primitives/physics asset with simple, stable shapes.
5. Configure gravity, wind, animation drive, self/intersection behavior, and solver iterations deliberately.
6. Build cloth simulation LODs and validate transition behavior.

Parameter directions:

- more simulation vertices/iterations/collision shapes improve potential fidelity and raise CPU cost;
- higher stiffness resists stretch/bend but can require finer timesteps/iterations;
- damping reduces oscillation but can deaden motion;
- stronger animation drive holds cloth closer to animated pose and reduces free secondary motion;
- self-collision can be expensive; enable only where visible intersections justify it.

Test worst animation speed, teleports, spawn, LOD changes, wind, frame spikes, character scaling, multiple
characters, and collision extremes. Reset/teleport cloth state explicitly when discontinuous movement
would stretch history across the world.

Authoritative gameplay must not depend on cloth particle contacts. Use separate collision/gameplay shapes.

Collision and queries

# Collision and queries

## Configure the matrix

1. Define stable Object Channels for categories and Trace Channels for questions.
2. Give each component a preset: Collision Enabled mode, Object Type, and per-channel Block/Overlap/Ignore.
3. Use Query Only when no solver contact is required; Physics Only when only simulation contacts matter;
   use Query and Physics only when both are consumed.
4. Enable Generate Overlap Events or Simulation Generates Hit Events only where the callback is needed.
5. Test both participants' response rows; the interaction resolves from both settings.

## Shape selection

- sphere/capsule/box: cheapest stable approximation for many props/characters;
- multiple simple primitives: preserve concavity with bounded shape count;
- convex hulls: irregular simulated bodies, avoiding excessive hull detail;
- complex trimesh: detailed scene queries/static collision when justified.

Collision Complexity:

| Mode | Behavior |
|---|---|
| Simple And Complex | simple shapes for simple queries/simulation, trimesh for complex queries |
| Use Simple As Complex | complex queries use simple shapes; saves trimesh memory/expense |
| Use Complex As Simple | simple queries/other bodies collide with trimesh; this object cannot simulate |

Use CCD on fast small bodies only after proving tunneling. It increases collision work and cannot repair
bad collision geometry, teleportation, or an excessively large timestep.

Validate at gameplay scale, maximum speed, rotating thin obstacles, low frame rate, and cooked collision.

Constraints and drives

# Constraints and drives

## Build order

1. Place body shapes, centers of mass, and constraint frames correctly.
2. Disable collision between constrained bodies when their shapes should not fight the joint.
3. Lock/free/limit X/Y/Z and Swing1/Swing2/Twist to form the intended hinge, slider, ball, or fixed joint.
4. Test hard limits before enabling soft limits or motors.
5. Add position/orientation and velocity drives with bounded Max Force.
6. Add break/plasticity rules only after stable normal operation.

Parameter effects:

- higher stiffness/drive strength reaches the target harder but can oscillate or demand more solver work;
- higher damping opposes target-relative velocity and reduces oscillation but can feel sluggish;
- restitution adds bounce at a violated limit;
- lower Max Force allows lag/compliance; unlimited/excess force can overpower the assembly;
- SLERP angular drive handles full orientation but does not work when an angular axis is locked;
- Twist and Swing drive works with decomposed axes/locked configurations.

Projection is a post-solve correction. It can stiffen a chain at lower iterations but works poorly while
the chain interacts with other objects and may inject nonphysical correction. Shock Propagation stiffens
chains by increasing parent mass on the last solve iteration but can inject energy. Use both as measured,
bounded tools—not default fixes.

Validate constraint-frame alignment, extreme pose, dropped frame, contact load, break threshold, scale,
and network correction.

Debugging and performance

# Debugging and performance

## Chaos Visual Debugger

Open Tools -> Debug -> Chaos Visual Debugger. Record local/remote PIE, client/server, or packaged
Development/Test sessions. Capture only needed data channels; CVD data volume and recording overhead can
be substantial. Test builds may omit object debug names.

Inspect particles, position/velocity/mass/state, collision geometry/channels, contact constraints, joint
constraints, character ground constraints, sync/async frames, and resimulated frames. Save recordings for
cross-team reproduction without requiring project assets.

## Symptom matrix

| Symptom | Inspect first |
|---|---|
| falls through thin wall | collision shape, speed/timestep, CCD, teleport versus sweep |
| jitters at rest | penetration, shape seams, mass ratio, contact/constraint, per-frame writes |
| constraint stretches/explodes | frames, limits, collision, mass ratio, timestep, drive/projection |
| overlap/hit fires twice | both-side settings, substep callback queue, duplicate components |
| ragdoll explodes | overlapping bodies, bad constraints, scale, pose penetration |
| debris never settles | sleep thresholds, ongoing field/contact, removal policy |
| network object rubber-bands | replication mode, authority, send/latency, predicted forces |
| cloth stretches/explodes | teleport reset, collision penetration, timestep, stiffness/iterations |

Profile Timing Insights/`stat physics` plus active/dynamic/sleeping bodies, shapes, broadphase pairs,
contacts, constraints/iterations, substeps, cloth vertices/iterations, destruction pieces/events, and
CVD/trace overhead. Disable visualization/recording for final timing.

# Destruction, Geometry Collections, and Fields

## Author a bounded collection

1. Create a Geometry Collection from suitable source meshes in Fracture Mode.
2. Fracture only to the piece scale visible/interactive in play.
3. Cluster pieces into hierarchy levels; higher clusters simulate as fewer bodies until broken.
4. Configure collision/size-specific data, damage thresholds, material interiors, and initial state.
5. Anchor structural regions with construction fields or authored support.
6. Trigger external strain/velocity with a bounded transient field.
7. Sleep, disable, remove, or swap settled small debris according to gameplay authority.

Field types:

- **Transient**: execute temporary strain/force/velocity and disappear.
- **Construction**: establish initial persistent structure such as anchors.
- **Persistent**: evaluate every physics tick until removed; scope narrowly because cost persists.

External Strain must exceed the relevant cluster Damage Threshold. `Num Strain Hits` can advance multiple
cluster levels. Sleep pieces can wake from collision; Disabled pieces cannot unless explicitly activated.

Use field metadata/culling to restrict particle state, object type, position, and volume. Unbounded
persistent fields can affect unintended particles and add per-tick work.

Budget unbroken collections, active bodies, contacts, constraints, break events, renderer pieces, Niagara/
audio callbacks, replication, and removal. Cache deterministic cinematic destruction when live interaction
is unnecessary; Chaos Caching and `AChaosCacheManager` are Experimental in UE 5.8.

Networked physics

# Networked physics

The server remains authoritative. Select replication per Actor interaction pattern:

| Mode | Use | Tradeoff |
|---|---|---|
| Default | simple replicated simulated props with limited local interaction | legacy correction overwrites local alterations; interactions degrade |
| Predictive Interpolation | server-authoritative props that clients predictably push/interact with | better local interaction, cheaper/less network intensive than Resimulation |
| Resimulation | physics Pawns/Actors needing full local prediction and authoritative replay | input/state history, rewinds/replays, higher CPU/memory/network complexity |

Default mode applies velocity/correction toward the forward-predicted server state. Predictive
Interpolation includes local velocity and correction timing so predicted interactions can survive.
Resimulation runs the client ahead and rewinds/replays when authoritative state diverges.

For Resimulation, implement the low-level Network Physics Component in C++:

1. Define serializable input and state structures.
2. Capture player input at physics-step cadence.
3. Apply identical deterministic-enough forces/actions during prediction and replay.
4. Cache bounded history for latency/jitter budget.
5. Compare authoritative state and trigger resimulation/correction through the framework.
6. Separate cosmetic events from replayable authoritative effects to avoid duplicates.

UE 5.8 supports Predictive Interpolation and Resimulation simultaneously on different Actors and adds
networked Actions. Inspect `np2.PredictiveInterpolation`, `np2.Resim`, and `p.Resim` console families for
current tuning options rather than copying stale CVar recipes.

Test packet loss, jitter, latency, low send rate, high velocity, collisions between modes, ownership
transfer, sleep/wake, spawn/despawn, and correction visibility.

# Physics Assets, ragdolls, and physical animation

## Author

1. Open the Physics Asset Editor and fit minimal capsules/boxes/spheres/convex bodies to meaningful bones.
2. Remove or simplify tiny bodies that do not affect collision/readability.
3. Disable collision for adjacent bodies that should not contact.
4. Align constraint frames at anatomical/mechanical joints.
5. Set Swing/Twist limits from the intended range, then test animation extremes.
6. Assign mass, damping, physical materials, and body/constraint profiles by gameplay state.
7. Simulate in-editor with representative collision and impulses; then test in the actual character.

## Choose the behavior

- Full ragdoll: transition the required bodies to simulation and define capsule/movement/camera ownership.
- Partial ragdoll: simulate below a bone while animation controls the rest.
- Physical Animation Component: drive simulated bodies toward animation using a named profile.
- Rigid Body animation node: secondary physics inside the animation graph when its world/collision mode fits.

Blend in/out with an explicit state machine. On recovery, stop gameplay authority from reading unstable
limb contacts, choose a valid get-up pose/orientation, reconcile the character capsule, and return body
control in a known order.

Profile body/contact/constraint counts across all characters. Skeletal visual LOD does not automatically
guarantee a cheap physics representation; use Physics Asset/body/constraint profiles and distance/state
policy appropriate to the game.

Rigid bodies, forces, and sleep

# Rigid bodies, forces, and sleep

## Body setup

- Fit collision around the mass-bearing shape; remove tiny snagging features.
- Set density/physical material or Mass in KG deliberately; inspect center of mass and inertia behavior.
- Use Linear/Angular Damping for real resistive behavior, not to mask unstable contacts.
- Set friction/restitution through Physical Materials and test combined material behavior.
- Enable gravity, CCD, hit/wake events, and simulation only when required.

## Apply motion

| Intent | Use | Notes |
|---|---|---|
| sustained thruster/wind | Add Force each physics/game update for duration | mass matters unless Accel Change |
| instantaneous kick/explosion | Add Impulse once | mass matters unless Vel Change |
| sustained force causing rotation | Add Force at Location | off-center application creates torque |
| instant off-center strike | Add Impulse at Location | changes linear and angular motion |
| direct kinematic placement | move/teleport/sweep policy | do not mix arbitrary transform writes with free simulation |

Sleep settled bodies to remove solver work. If an object wakes repeatedly, inspect contact jitter, moving
supports, thresholds, tiny penetrations, constraints, and per-frame property/transform writes before
forcing sleep. Disabled destruction pieces cannot be collision-woken; use only when the lifecycle allows it.

Test mass ratios. Very light bodies constrained/contacting extremely heavy bodies can destabilize stacks
and joints; correct representation and scale before raising iterations or projection.

UE 5.8 primary sources

# UE 5.8 primary sources

- [Physics in Unreal Engine](https://dev.epicgames.com/documentation/en-us/unreal-engine/physics-in-unreal-engine)
- [Collision Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/collision-in-unreal-engine---overview)
- [Simple versus Complex Collision](https://dev.epicgames.com/documentation/en-us/unreal-engine/simple-versus-complex-collision-in-unreal-engine)
- [Physics Bodies Reference](https://dev.epicgames.com/documentation/en-us/unreal-engine/physics-bodies-reference-for-unreal-engine)
- [Physics Constraint Reference](https://dev.epicgames.com/documentation/en-us/unreal-engine/physics-constraint-reference-in-unreal-engine)
- [Physics Sub-Stepping](https://dev.epicgames.com/documentation/en-us/unreal-engine/physics-sub-stepping-in-unreal-engine)
- [Physics Project Settings](https://dev.epicgames.com/documentation/en-us/unreal-engine/physics-settings-in-the-unreal-engine-project-settings)
- [Networked Physics Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/networked-physics-overview)
- [Physics Asset Editor](https://dev.epicgames.com/documentation/en-us/unreal-engine/physics-asset-editor-in-unreal-engine)
- [Destruction Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/destruction-overview)
- [Cluster Geometry Collections](https://dev.epicgames.com/documentation/en-us/unreal-engine/cluster-geometry-collections-user-guide-in-unreal-engine)
- [Chaos Fields User Guide](https://dev.epicgames.com/documentation/en-us/unreal-engine/chaos-fields-user-guide-in-unreal-engine)
- [Physics Fields Overview](https://dev.epicgames.com/documentation/en-us/unreal-engine/overview-of-physics-fields-in-unreal-engine)
- [Chaos Visual Debugger](https://dev.epicgames.com/documentation/en-us/unreal-engine/getting-started-with-chaos-visual-debugger)
- [Capturing with Chaos Visual Debugger](https://dev.epicgames.com/documentation/en-us/unreal-engine/capturing-data-with-chaos-visual-debugger)
- [Clothing Tool](https://dev.epicgames.com/documentation/en-us/unreal-engine/clothing-tool-in-unreal-engine)
- [UE 5.8 Release Notes](https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-5-8-release-notes)
- [Chaos Caching API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Plugins/ChaosCaching)
- [Add Force at Location](https://dev.epicgames.com/documentation/en-us/unreal-engine/BlueprintAPI/Physics/AddForceatLocation)
- [Add Impulse](https://dev.epicgames.com/documentation/en-us/unreal-engine/BlueprintAPI/Physics/AddImpulse)

Pages were checked against UE 5.8 documentation on 2026-07-19. Reconfirm maturity labels, replication
APIs/modes, threading/timestep behavior, defaults, field nodes, and Chaos caching after an engine upgrade.

System selector

# System selector

| Need | Prefer |
|---|---|
| detect without physical response | query/overlap or trace with explicit channel |
| block/move kinematically | collision component + swept movement |
| free simulated prop | simple/convex rigid body |
| hinge, slider, tether, suspension | Physics Constraint Component/constraint profile |
| skeletal collision/ragdoll | Physics Asset |
| animation with localized physical response | Physical Animation Component/profile |
| breakable authored object | Geometry Collection + clustering/fields |
| region-based force/strain/state | transient/construction/persistent Chaos Field |
| deforming garment | Chaos Cloth Asset/solver |
| repeatable cinematic heavy simulation | authored/cache playback, noting Chaos Caching is Experimental |
| server-authoritative interactive physics | Predictive Interpolation or Resimulation by interaction needs |

Decision questions:

1. Must the result affect authoritative movement, damage, cover, or navigation?
2. Is continuous collision response required, or only a query/event?
3. What is the smallest collision representation preserving the gameplay silhouette?
4. What frame-rate/latency/piece/contact worst case must remain stable?
5. Can distant/settled results sleep, disable, remove, swap representation, or play a cache?

# Timestep, substepping, and async physics

Physics stability depends on maximum step size. UE's frame delta varies; large steps reduce contact and
constraint accuracy.

Project Settings -> Physics exposes:

| Setting | Effect |
|---|---|
| Max Physics Delta Time | caps simulated step; a lower cap may slow simulation during long frames |
| Substepping | divides a frame step into smaller solves; improves stability at CPU/bookkeeping cost |
| Max Substep Delta Time | smaller permits finer/more steps and higher cost |
| Max Substeps | caps catch-up work; beyond it, simulation cannot maintain the requested resolution |
| Tick Physics Async | moves simulation to async thread; Experimental in UE 5.8 |
| Async Fixed Time Step Size | fixed async step; Experimental and requires thread-safe integration |

Substepping, Substepping Async, and async physics are marked Experimental in UE 5.8 Project Settings.
Do not enable them merely because an asset jitters. First correct scale, penetration, collision shape,
constraint frames, mass ratios, and force application.

Collision callbacks are queued until the final substep and may include begin and end contact for the same
pair in one game frame. Make event consumers idempotent and state-based; do not award damage twice from
callback multiplicity.

Async/fixed simulation creates a game-thread/physics-thread boundary. Read/write physics state through
supported APIs and schedule authoritative forces/inputs at the intended physics step. Test 30/60/120 fps,
frame spikes, pause/time dilation, slow motion, and network resimulation.

Use-case recipes

# Use-case recipes

## Hinged door

Use one simulated door body plus world/frame constraint. Lock linear axes; free or limit one angular axis;
lock the others. Add angular drive only for self-closing. Limit Max Force so players can resist it. Disable
frame-door collision if shapes fight. Test both push directions, edge impacts, low FPS, and replication.

## Explosive prop

Use a radial impulse or transient field once, not a per-frame force. Keep gameplay damage authoritative and
separate from debris. Bound affected object types/radius, enable CCD only for fast critical fragments, and
cap/sleep/disable/remove cosmetic pieces.

## Partial hit reaction

Use a Physics Asset plus Physical Animation profile below the hit bone. Apply a bounded impulse at the hit
location, blend physics weight, then restore animation/body state. Keep character movement/capsule
authoritative unless the design intentionally enters ragdoll.

## Breakable wall

Use clustered Geometry Collection, anchored supports, size-specific collision, and thresholded transient
strain. Break large clusters first; disable/remove settled small fragments. Test worst simultaneous walls,
event-driven VFX/audio, navigation/cover authority, and network representation.

## Physics Pawn

Use Resimulation only when full predicted interaction is required; otherwise evaluate Predictive
Interpolation. Implement step-indexed inputs/state/actions in C++, keep cosmetic events replay-safe, and
test latency/loss/jitter/corrections against non-player physics objects.


unreal-character-movement

Unreal 5.8 Character Movement

Tune and network Character Movement systems

---
name: unreal-character-movement
description: Design, tune, extend, network, and debug Character movement in Unreal Engine 5.8. Use for Character Movement Component selection, movement feel, walking, acceleration, braking, friction, rotation, jumping, gravity, air control, slopes, steps, crouching, moving platforms, custom movement modes, dashes, launches, teleports, root motion sources, client prediction, saved moves, corrections, smoothing, or evaluating experimental Mover.
---

# Unreal 5.8 Character Movement

## Select the movement framework

- Use `ACharacter` with `UCharacterMovementComponent` for standard capsule-based walking,
  falling, swimming, flying, crouching, root motion, and mature network prediction.
- Extend CMC with `MOVE_Custom` when one or more special modes must coexist with standard
  Character movement and its networking model.
- Use Root Motion Sources or GAS root-motion Ability Tasks for short, programmatic special
  moves that must participate in Character network prediction.
- Evaluate **Mover** only when its mode/layered-move architecture materially benefits the
  project. In UE 5.8 Epic still labels Mover Experimental; record that shipping risk.
- Use a bespoke Pawn movement component only when Character's capsule/mode model is a poor fit.

Read [`references/system-selector.md`](references/system-selector.md) before choosing.

## Tune in dependency order

1. Declare desired feel in measurable terms: target speed, time to speed, stopping distance,
   turn time, jump height/time, air steering, walkable slope, and step height.
2. Establish collision capsule and floor behavior.
3. Tune `MaxWalkSpeed`, `MaxAcceleration`, braking, and friction together.
4. Select rotation ownership: movement direction, controller desired rotation, or explicit
   gameplay rotation. Avoid competing rotation systems.
5. Tune `JumpZVelocity`, gravity, hold behavior, and `AirControl` as one jump model.
6. Add crouch, sprint, slopes, platforms, and special movement one at a time.
7. Integrate animation after the physical trajectory is stable.
8. Verify at varied frame rate, target hardware, slopes/steps/edges, and network conditions.

Read [`references/parameter-effects.md`](references/parameter-effects.md) for variable effects
and [`references/grounding-jumping.md`](references/grounding-jumping.md) for ground and jump
procedures.

## Network before polishing

Read [`references/networking.md`](references/networking.md) before adding replicated special
movement. Standard CMC prediction does not automatically serialize arbitrary custom state.
Extend saved moves/network move data when the server must reproduce new input or state.

Read [`references/special-movement.md`](references/special-movement.md) for dashes, launches,
teleports, custom modes, and root motion. Route action timing/input buffers to
`$unreal-enhanced-input`, action animation blending to `$unreal-animation-blending`, and
ability-owned movement to `$unreal-gas-abilities`.

## Required answer format

Return:

1. **Movement framework choice** and maturity risk.
2. **Desired feel metrics** and assumptions.
3. **Ordered parameter changes**, units, expected effects, and interactions.
4. **Movement/rotation/animation ownership**.
5. **Authority, prediction, saved-move, and smoothing design**.
6. **Test course and network verification matrix**.

Do not invent defaults, property names, prediction behavior, or safe values.

## Hard rules

- Tune coupled parameters together; speed alone does not define feel.
- Do not drive one movement simultaneously through CMC velocity, manual transforms, and root
  motion.
- Do not use client `SetActorLocation` as predicted multiplayer movement.
- Teleport on the server and mark the move as a teleport through the supported API path.
- Do not disable server corrections to hide a faulty movement implementation.
- Keep the collision capsule authoritative; mesh offset is presentation.
- Test custom movement with latency, packet loss, low frame rate, slopes, edges, and moving bases.

Use [`references/troubleshooting.md`](references/troubleshooting.md) for sliding, jitter,
corrections, slope/step failures, root-motion conflicts, and frame-rate dependence. See
[`references/sources.md`](references/sources.md) for the UE 5.8 source trail.

## Select the movement framework

- Use `ACharacter` with `UCharacterMovementComponent` for standard capsule-based walking,
  falling, swimming, flying, crouching, root motion, and mature network prediction.
- Extend CMC with `MOVE_Custom` when one or more special modes must coexist with standard
  Character movement and its networking model.
- Use Root Motion Sources or GAS root-motion Ability Tasks for short, programmatic special
  moves that must participate in Character network prediction.
- Evaluate **Mover** only when its mode/layered-move architecture materially benefits the
  project. In UE 5.8 Epic still labels Mover Experimental; record that shipping risk.
- Use a bespoke Pawn movement component only when Character's capsule/mode model is a poor fit.

Read [`references/system-selector.md`](/unreal/unreal-character-movement/system-selector/) before choosing.

## Tune in dependency order

1. Declare desired feel in measurable terms: target speed, time to speed, stopping distance,
   turn time, jump height/time, air steering, walkable slope, and step height.
2. Establish collision capsule and floor behavior.
3. Tune `MaxWalkSpeed`, `MaxAcceleration`, braking, and friction together.
4. Select rotation ownership: movement direction, controller desired rotation, or explicit
   gameplay rotation. Avoid competing rotation systems.
5. Tune `JumpZVelocity`, gravity, hold behavior, and `AirControl` as one jump model.
6. Add crouch, sprint, slopes, platforms, and special movement one at a time.
7. Integrate animation after the physical trajectory is stable.
8. Verify at varied frame rate, target hardware, slopes/steps/edges, and network conditions.

Read [`references/parameter-effects.md`](/unreal/unreal-character-movement/parameter-effects/) for variable effects
and [`references/grounding-jumping.md`](/unreal/unreal-character-movement/grounding-jumping/) for ground and jump
procedures.

## Network before polishing

Read [`references/networking.md`](/unreal/unreal-character-movement/networking/) before adding replicated special
movement. Standard CMC prediction does not automatically serialize arbitrary custom state.
Extend saved moves/network move data when the server must reproduce new input or state.

Read [`references/special-movement.md`](/unreal/unreal-character-movement/special-movement/) for dashes, launches,
teleports, custom modes, and root motion. Route action timing/input buffers to
`$unreal-enhanced-input`, action animation blending to `$unreal-animation-blending`, and
ability-owned movement to `$unreal-gas-abilities`.

## Required answer format

Return:

1. **Movement framework choice** and maturity risk.
2. **Desired feel metrics** and assumptions.
3. **Ordered parameter changes**, units, expected effects, and interactions.
4. **Movement/rotation/animation ownership**.
5. **Authority, prediction, saved-move, and smoothing design**.
6. **Test course and network verification matrix**.

Do not invent defaults, property names, prediction behavior, or safe values.

## Hard rules

- Tune coupled parameters together; speed alone does not define feel.
- Do not drive one movement simultaneously through CMC velocity, manual transforms, and root
  motion.
- Do not use client `SetActorLocation` as predicted multiplayer movement.
- Teleport on the server and mark the move as a teleport through the supported API path.
- Do not disable server corrections to hide a faulty movement implementation.
- Keep the collision capsule authoritative; mesh offset is presentation.
- Test custom movement with latency, packet loss, low frame rate, slopes, edges, and moving bases.

Use [`references/troubleshooting.md`](/unreal/unreal-character-movement/troubleshooting/) for sliding, jitter,
corrections, slope/step failures, root-motion conflicts, and frame-rate dependence. See
[`references/sources.md`](/unreal/unreal-character-movement/sources/) for the UE 5.8 source trail.

unreal 5.8 character movement design, tune, extend, network, and debug character movement in unreal engine 5.8. use for character movement component selection, movement feel, walking, acceleration, braking, friction, rotation, jumping, gravity, air control, slopes, steps, crouching, moving platforms, custom movement modes, dashes, launches, teleports, root motion sources, client prediction, saved moves, corrections, smoothing, or evaluating experimental mover. movement and animation seam movement and animation seam ownership - cmc/capsule owns authoritative collision, position, velocity, acceleration, movement mode, and floor state for code-driven locomotion. - animation blueprint reads those values and presents them. - montage root motion may temporarily drive movement when deliberately enabled. - mesh offsets, leaning, stride warping, and smoothing are presentation; do not move the authoritative capsule through arbitrary anim blueprint logic. in-place locomotion 1. derive speed from cmc velocity, using horizontal or local-space components as the graph requires. 2. derive direction from velocity relative to character/control rotation. 3. read falling, acceleration, crouch, and movement mode from the character/cmc. 4. match animation play rate/stride warping to approved physical speed. 5. keep gait thresholds derived from movement states/data, not duplicated magic values. root motion - animation asset must contain root-bone motion and have root motion enabled. - animation blueprint root-motion mode controls extraction/application. - epic warns that extracting root motion from everything moves animation graph work to the game thread; prefer the narrowest mode that satisfies the project, especially in networked gameplay. - while walking/falling, character physics still constrains vertical root motion; flying applies full root motion. - root motion takes precedence over standard movement physics. troubleshooting seam if feet slide but capsule trajectory is correct, fix animation stride/play rate/warping. if capsule trajectory is wrong, fix movement. if both systems rotate or translate the actor, select one owner before tuning either. grounding, slopes, steps, and jumping grounding, slopes, steps, and jumping ground test course build reusable geometry containing: - flat acceleration/braking lane with distance marks; - gradual slopes below, at, and above walkablefloorangle; - steps below, at, and above maxstepheight; - narrow ledges and corners for perching; - low ceilings for crouch/uncrouch; - moving and rotating bases; - seams between collision pieces. test capsule behavior first. the skeletal mesh is not the authoritative collision body. rotation ownership choose one primary path: - borientrotationtomovement: face acceleration using rotationrate; - busecontrollerdesiredrotation: rotate toward controller desired rotation using rotationrate; - explicit gameplay rotation: disable competing automatic rotation and own it in one system. also reconcile acharacter::busecontrollerrotationyaw. conflicting owners cause snapping, oscillation, or a facing direction that disagrees with movement/aim. jump model 1. define target apex height, time to apex, total airtime, horizontal control, and variable jump behavior. 2. tune jumpzvelocity and gravityscale together. 3. configure character jump-hold behavior (jumpmaxholdtime) only if variable-height jumps are desired; bind press to jump and release to stop jumping. 4. tune aircontrol, boost settings, falling friction, and lateral cap. 5. add coyote time and buffered jump as explicit gameplay forgiveness; route the timestamped input design to $unreal-enhanced-input. 6. test stepping off edges, ceilings, slopes, moving bases, repeated press, held input, and landing during a buffered request. use cmc's getmaxjumpheight/getmaxjumpheightwithjumptime as diagnostics, then verify in the actual level because collision, slopes, bases, and frame/network behavior matter. sprint and crouch - treat sprint as a state that changes desired max speed and perhaps acceleration, not as a second movement implementation. - decide hold versus toggle in the input layer. - keep the server authoritative over sprint/crouch eligibility. - use character crouch support so capsule changes and movement integration remain coherent. - test uncrouch obstruction; never force the capsule into a ceiling. character movement networking character movement networking standard flow - autonomous proxy performs local movement, records fsavedmovecharacter, and sends packed move data. - server reproduces and validates movement, then acknowledges or corrects. - owning client replays unacknowledged saved moves after a correction. - simulated proxies receive replicated movement and use network smoothing. standard cmc modes implement this. new custom state does not become predicted merely because it lives on an acharacter. custom predicted state when a custom movement flag/value changes physics: 1. add it to a custom fsavedmovecharacter and clear/store/combine it correctly. 2. extend fcharacternetworkmovedata with values the server must receive. 3. serialize them. 4. provide a custom fcharacternetworkmovedatacontainer. 5. install it through setnetworkmovedatacontainer in the custom cmc. 6. apply the data before the server reproduces movement. 7. test move combining; moves with incompatible state must not combine. use compressed flags only when their limited space and boolean semantics fit. follow current 5.8 engine headers/source for signatures. corrections and smoothing - fix deterministic divergence before tuning smoothing. - networksmoothingmode affects simulated-proxy presentation, not server authority. - location/rotation smoothing times and no-smooth distances are advanced levers; do not use them to conceal constant corrections. - keep visual mesh smoothing separate from authoritative capsule state. verification matrix run standalone, listen server, and dedicated server where relevant: - owning autonomous proxy; - server-controlled ai; - remote simulated proxy; - 0/medium/high artificial latency; - packet loss and jitter; - low and high frame rates; - sprint/crouch/custom-mode transitions while moves combine; - moving platforms and jump-off velocity; - root motion start/cancel/finish; - teleport; - server rejection/correction. log role, movement/custom mode, acceleration, velocity, location error, correction count, saved custom flags/data, and root-motion sources. never ship with client-authoritative position or correction bypasses enabled as a workaround. character movement parameter effects character movement parameter effects units follow unreal's centimeter-based world unless the project changes conventions. | parameter | primary effect | increasing it does | important coupling | |---|---|---|---| | maxwalkspeed (cm/s) | maximum ground speed; also maximum lateral falling speed | raises travel/top air-lateral cap | acceleration, braking, animation stride | | maxacceleration (cm/s²) | rate velocity can change from input | reaches desired velocity/direction faster | ground friction, analog magnitude | | brakingdecelerationwalking (cm/s²) | constant deceleration with no acceleration | shortens coast/stopping time | braking friction/factor | | groundfriction | ground movement control/friction | increases directional grip and braking when shared braking friction is used | buseseparatebrakingfriction | | buseseparatebrakingfriction | selects dedicated braking friction | separates turning grip from no-input stopping drag | brakingfriction, factor | | brakingfriction | drag coefficient while braking | shortens coast when separate braking friction is active | brakingfrictionfactor | | rotationrate (deg/s) | rotation change rate | turns facing faster | only used by controller-desired or orient-to-movement modes | | aircontrol | lateral control during falling | permits stronger steering in air | boost multiplier/threshold, falling friction | | fallinglateralfriction | drag on lateral falling motion | removes lateral velocity faster in air | braking deceleration falling | | jumpzvelocity (cm/s) | initial upward jump velocity | raises jump and airtime for fixed gravity | gravity scale, jump hold | | gravityscale | multiplier on character gravity | increases downward acceleration and shortens airtime | jump z velocity | | maxstepheight (cm) | maximum step-up height | traverses taller ledges without jumping | capsule, floor angle, geometry | | walkablefloorangle (0–90°) | maximum walkable slope | accepts steeper surfaces as floor | floor normals, slide design | | perchradiusthreshold (cm) | rejects edge contacts near capsule rim | requires more capsule support to perch | ledge behavior, capsule radius | | maxwalkspeedcrouched (cm/s) | crouched top speed | speeds crouched travel | crouched capsule and animation | | minanalogwalkspeed (cm/s) | speed at minimum analog tilt | raises low-stick movement floor | dead zone and response curve | tuning method 1. tune a clean flat test lane without animation-driven motion. 2. measure time to 90% speed and stopping distance, not just max speed. 3. tune direction reversal separately from release-to-stop. 4. add rotation ownership and rate. 5. test stick magnitudes, keyboard digital input, low and high frame rates. 6. add animation and correct stride/lean presentation after trajectory is approved. do not publish universal numeric presets. desired scale, camera, genre, capsule, animation, and network conditions change what feels correct. ue 5.8 primary sources ue 5.8 primary sources verified 2026-07-19. - movement components - ucharactermovementcomponent api - networked movement in the character movement component - set movement mode blueprint api - add movement input blueprint api - launch character blueprint api - acharacter::jump api - root motion - locomotion - mover features and concepts - unreal engine 5.8 release notes version note: these pages currently resolve to unreal engine 5.8. epic labels mover experimental. the 5.8 release notes describe expanded mover prediction/rollback work but do not remove that maturity warning. character movement remains the mature default for standard networked character locomotion. special movement patterns special movement patterns launch use launchcharacter for an impulse-like velocity change that should enter the character movement pipeline. decide independently whether xy/z override existing velocity. test authority, prediction/correction, landing, air control, and repeated launches. a launch is not a duration- controlled dash. teleport for network play: 1. validate the destination on the server. 2. use a supported setlocation path with teleport behavior or the teleport blueprint node. 3. ensure collision/encroachment policy matches the design. 4. expect clients to snap rather than smooth the teleport. do not move the owning client first with ordinary transform changes and expect cmc prediction to accept it. root motion source use for short programmatic motion needing character root-motion networking, such as move-to or jump-force behavior. 1. select/create the appropriate frootmotionsource variant. 2. set duration, priority/accumulation, start/target, and finish behavior. 3. apply through ucharactermovementcomponent::applyrootmotionsource on the appropriate prediction/authority path. 4. retain the returned handle/id. 5. remove with removerootmotionsource when canceled or finished if required by the pattern. 6. test server rejection, collision, moving targets, and montage/root-motion competition. gas provides ability tasks that use root motion sources; prefer those when the ability owns activation, cancellation, and prediction. custom movement mode 1. allocate a stable custom sub-mode byte/enum. 2. enter through setmovementmode(movecustom, submode). 3. implement updatecustommovement in character blueprint for prototypes, or override physcustom in a custom cmc for production control. 4. perform swept movement and define collision, floor, velocity, gravity, and exit rules. 5. serialize any custom input/state the server needs through saved-move/network move data. 6. return to walking/falling/etc. through an explicit exit condition. movecustom suspends normal movement physics. failing to implement gravity, collision, or velocity semantics is not an engine bug. montage root motion use for animation-authored committed actions. root motion takes priority over standard movement physics. in network games, ensure gameplay triggers the montage consistently; gas can synchronize ability-owned montages/root motion. route blend/slot details to $unreal-animation-blending. movement system selector movement system selector | need | use | reason / warning | |---|---|---| | standard humanoid capsule movement and mature multiplayer support | acharacter + ucharactermovementcomponent | walking/falling/swimming/flying/custom modes, prediction, correction, smoothing | | a special mode integrated with normal character movement | cmc movecustom + custom sub-mode | standard physics are suspended while custom physics run; custom state may need saved-move serialization | | short deterministic/programmatic ability movement | root motion source or gas root-motion ability task | participates in character root-motion networking when used correctly | | animation-authored committed movement | montage root motion | root motion takes priority over normal movement physics; gameplay must synchronize montage execution | | modular mode/layered-move architecture and willingness to carry experimental risk | mover | epic labels mover experimental in ue 5.8 | | vehicle, rolling body, non-capsule creature, or unconventional physics | purpose-built pawn/movement system | character and cmc are designed together around character movement assumptions | selection procedure 1. define collision shape and whether the entity must use acharacter. 2. list movement modes and which may overlap as temporary layered moves. 3. state single-player/multiplayer, authority, prediction, and rollback requirements. 4. state whether motion is code-driven, animation-driven, or selected per action. 5. choose the most mature framework that satisfies the requirements. 6. if choosing mover, record experimental status, engine-version lock, fallback cost, and a packaged multiplayer prototype milestone before committing production content. do not migrate from cmc merely because custom movement requires c++. the deciding question is whether cmc's character/capsule/mode/network model still fits the game. troubleshooting troubleshooting character slides after input release - raise braking deceleration and/or effective braking friction deliberately. - check buseseparatebrakingfriction, brakingfriction, and factor interaction. - distinguish no-input stopping from direction-change grip. direction changes feel slow despite high acceleration - check groundfriction and effective input magnitude. - check rotation ownership/rate if facing, not velocity, is the slow part. - measure velocity change separately from mesh turn animation. cannot climb a small step - compare collision height with maxstepheight. - confirm the upper surface is walkable and the capsule has clearance. - inspect collision seams and blocking channels. - test without decorative mesh collision overriding intended simple collision. stands on implausibly tiny edges - review perchradiusthreshold, capsule radius, and ledge geometry. - visualize collision/floor results; do not judge by skeletal mesh feet. jump varies with frame rate - remove manual per-frame velocity/position increments lacking delta-time/physics integration. - verify variable jump release is bound correctly. - check custom movement simulation time steps/iterations under low frame rate. constant server corrections - confirm client and server use identical parameters and custom state. - serialize state that changes movement physics. - prevent incompatible saved moves from combining. - remove client-only transform changes. - fix divergence before changing smoothing or correction thresholds. remote character jitters - first determine whether authoritative capsule is correcting or only mesh smoothing looks bad. - inspect update rate, packet conditions, moving base, and custom-mode replication. - tune smoothing only after deterministic movement is correct. root motion fights movement - confirm root-motion extraction mode and asset settings. - remember root motion takes precedence over normal movement physics. - do not also drive the same action with launch/setlocation/velocity. - ensure montage start/cancel is synchronized across network roles. custom mode floats or tunnels - movecustom suspends standard physics; implement gravity, velocity, swept collision, floor, sub-stepping, and exit behavior explicitly. - prefer c++ physcustom for complex production modes.

Movement and animation seam

# Movement and animation seam

## Ownership

- CMC/capsule owns authoritative collision, position, velocity, acceleration, movement mode,
  and floor state for code-driven locomotion.
- Animation Blueprint reads those values and presents them.
- Montage root motion may temporarily drive movement when deliberately enabled.
- Mesh offsets, leaning, stride warping, and smoothing are presentation; do not move the
  authoritative capsule through arbitrary Anim Blueprint logic.

## In-place locomotion

1. Derive speed from CMC velocity, using horizontal or local-space components as the graph
   requires.
2. Derive direction from velocity relative to character/control rotation.
3. Read falling, acceleration, crouch, and movement mode from the Character/CMC.
4. Match animation play rate/stride warping to approved physical speed.
5. Keep gait thresholds derived from movement states/data, not duplicated magic values.

## Root motion

- Animation asset must contain root-bone motion and have root motion enabled.
- Animation Blueprint root-motion mode controls extraction/application.
- Epic warns that extracting root motion from everything moves Animation Graph work to the
  Game Thread; prefer the narrowest mode that satisfies the project, especially in networked
  gameplay.
- While Walking/Falling, Character physics still constrains vertical root motion; Flying
  applies full root motion.
- Root motion takes precedence over standard movement physics.

## Troubleshooting seam

If feet slide but capsule trajectory is correct, fix animation stride/play rate/warping. If
capsule trajectory is wrong, fix movement. If both systems rotate or translate the actor,
select one owner before tuning either.

Grounding, slopes, steps, and jumping

# Grounding, slopes, steps, and jumping

## Ground test course

Build reusable geometry containing:

- flat acceleration/braking lane with distance marks;
- gradual slopes below, at, and above `WalkableFloorAngle`;
- steps below, at, and above `MaxStepHeight`;
- narrow ledges and corners for perching;
- low ceilings for crouch/uncrouch;
- moving and rotating bases;
- seams between collision pieces.

Test capsule behavior first. The skeletal mesh is not the authoritative collision body.

## Rotation ownership

Choose one primary path:

- `bOrientRotationToMovement`: face acceleration using `RotationRate`;
- `bUseControllerDesiredRotation`: rotate toward controller desired rotation using
  `RotationRate`;
- explicit gameplay rotation: disable competing automatic rotation and own it in one system.

Also reconcile `ACharacter::bUseControllerRotationYaw`. Conflicting owners cause snapping,
oscillation, or a facing direction that disagrees with movement/aim.

## Jump model

1. Define target apex height, time to apex, total airtime, horizontal control, and variable
   jump behavior.
2. Tune `JumpZVelocity` and `GravityScale` together.
3. Configure Character jump-hold behavior (`JumpMaxHoldTime`) only if variable-height jumps
   are desired; bind press to Jump and release to Stop Jumping.
4. Tune `AirControl`, boost settings, falling friction, and lateral cap.
5. Add coyote time and buffered jump as explicit gameplay forgiveness; route the timestamped
   input design to `$unreal-enhanced-input`.
6. Test stepping off edges, ceilings, slopes, moving bases, repeated press, held input, and
   landing during a buffered request.

Use CMC's `GetMaxJumpHeight`/`GetMaxJumpHeightWithJumpTime` as diagnostics, then verify in the
actual level because collision, slopes, bases, and frame/network behavior matter.

## Sprint and crouch

- Treat sprint as a state that changes desired max speed and perhaps acceleration, not as a
  second movement implementation.
- Decide hold versus toggle in the input layer.
- Keep the server authoritative over sprint/crouch eligibility.
- Use Character crouch support so capsule changes and movement integration remain coherent.
- Test uncrouch obstruction; never force the capsule into a ceiling.

Character movement networking

# Character movement networking

## Standard flow

- Autonomous proxy performs local movement, records `FSavedMove_Character`, and sends packed
  move data.
- Server reproduces and validates movement, then acknowledges or corrects.
- Owning client replays unacknowledged saved moves after a correction.
- Simulated proxies receive replicated movement and use network smoothing.

Standard CMC modes implement this. New custom state does not become predicted merely because it
lives on an `ACharacter`.

## Custom predicted state

When a custom movement flag/value changes physics:

1. Add it to a custom `FSavedMove_Character` and clear/store/combine it correctly.
2. Extend `FCharacterNetworkMoveData` with values the server must receive.
3. Serialize them.
4. Provide a custom `FCharacterNetworkMoveDataContainer`.
5. Install it through `SetNetworkMoveDataContainer` in the custom CMC.
6. Apply the data before the server reproduces movement.
7. Test move combining; moves with incompatible state must not combine.

Use compressed flags only when their limited space and boolean semantics fit. Follow current
5.8 engine headers/source for signatures.

## Corrections and smoothing

- Fix deterministic divergence before tuning smoothing.
- `NetworkSmoothingMode` affects simulated-proxy presentation, not server authority.
- Location/rotation smoothing times and no-smooth distances are advanced levers; do not use
  them to conceal constant corrections.
- Keep visual mesh smoothing separate from authoritative capsule state.

## Verification matrix

Run standalone, listen server, and dedicated server where relevant:

- owning autonomous proxy;
- server-controlled AI;
- remote simulated proxy;
- 0/medium/high artificial latency;
- packet loss and jitter;
- low and high frame rates;
- sprint/crouch/custom-mode transitions while moves combine;
- moving platforms and jump-off velocity;
- root motion start/cancel/finish;
- teleport;
- server rejection/correction.

Log role, movement/custom mode, acceleration, velocity, location error, correction count,
saved custom flags/data, and root-motion sources. Never ship with client-authoritative
position or correction bypasses enabled as a workaround.

Character Movement parameter effects

# Character Movement parameter effects

Units follow Unreal's centimeter-based world unless the project changes conventions.

| Parameter | Primary effect | Increasing it does | Important coupling |
|---|---|---|---|
| `MaxWalkSpeed` (cm/s) | Maximum ground speed; also maximum lateral falling speed | Raises travel/top air-lateral cap | Acceleration, braking, animation stride |
| `MaxAcceleration` (cm/s²) | Rate velocity can change from input | Reaches desired velocity/direction faster | Ground friction, analog magnitude |
| `BrakingDecelerationWalking` (cm/s²) | Constant deceleration with no acceleration | Shortens coast/stopping time | Braking friction/factor |
| `GroundFriction` | Ground movement control/friction | Increases directional grip and braking when shared braking friction is used | `bUseSeparateBrakingFriction` |
| `bUseSeparateBrakingFriction` | Selects dedicated braking friction | Separates turning grip from no-input stopping drag | `BrakingFriction`, factor |
| `BrakingFriction` | Drag coefficient while braking | Shortens coast when separate braking friction is active | `BrakingFrictionFactor` |
| `RotationRate` (deg/s) | Rotation change rate | Turns facing faster | Only used by controller-desired or orient-to-movement modes |
| `AirControl` | Lateral control during falling | Permits stronger steering in air | Boost multiplier/threshold, falling friction |
| `FallingLateralFriction` | Drag on lateral falling motion | Removes lateral velocity faster in air | Braking deceleration falling |
| `JumpZVelocity` (cm/s) | Initial upward jump velocity | Raises jump and airtime for fixed gravity | Gravity scale, jump hold |
| `GravityScale` | Multiplier on character gravity | Increases downward acceleration and shortens airtime | Jump Z velocity |
| `MaxStepHeight` (cm) | Maximum step-up height | Traverses taller ledges without jumping | Capsule, floor angle, geometry |
| `WalkableFloorAngle` (0–90°) | Maximum walkable slope | Accepts steeper surfaces as floor | Floor normals, slide design |
| `PerchRadiusThreshold` (cm) | Rejects edge contacts near capsule rim | Requires more capsule support to perch | Ledge behavior, capsule radius |
| `MaxWalkSpeedCrouched` (cm/s) | Crouched top speed | Speeds crouched travel | Crouched capsule and animation |
| `MinAnalogWalkSpeed` (cm/s) | Speed at minimum analog tilt | Raises low-stick movement floor | Dead zone and response curve |

## Tuning method

1. Tune a clean flat test lane without animation-driven motion.
2. Measure time to 90% speed and stopping distance, not just max speed.
3. Tune direction reversal separately from release-to-stop.
4. Add rotation ownership and rate.
5. Test stick magnitudes, keyboard digital input, low and high frame rates.
6. Add animation and correct stride/lean presentation after trajectory is approved.

Do not publish universal numeric presets. Desired scale, camera, genre, capsule, animation,
and network conditions change what feels correct.

UE 5.8 primary sources

# UE 5.8 primary sources

Verified 2026-07-19.

- [Movement Components](https://dev.epicgames.com/documentation/en-us/unreal-engine/movement-components-in-unreal-engine)
- [`UCharacterMovementComponent` API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/UCharacterMovementComponent)
- [Networked Movement in the Character Movement Component](https://dev.epicgames.com/documentation/en-us/unreal-engine/understanding-networked-movement-in-the-character-movement-component-for-unreal-engine)
- [Set Movement Mode Blueprint API](https://dev.epicgames.com/documentation/en-us/unreal-engine/BlueprintAPI/Pawn/Components/CharacterMovement/SetMovementMode)
- [Add Movement Input Blueprint API](https://dev.epicgames.com/documentation/en-us/unreal-engine/BlueprintAPI/Pawn/Input/AddMovementInput)
- [Launch Character Blueprint API](https://dev.epicgames.com/documentation/en-us/unreal-engine/BlueprintAPI/Character/LaunchCharacter)
- [`ACharacter::Jump` API](https://dev.epicgames.com/documentation/en-us/unreal-engine/API/Runtime/Engine/ACharacter/Jump)
- [Root Motion](https://dev.epicgames.com/documentation/en-us/unreal-engine/root-motion-in-unreal-engine)
- [Locomotion](https://dev.epicgames.com/documentation/en-us/unreal-engine/locomotion-in-unreal-engine)
- [Mover Features and Concepts](https://dev.epicgames.com/documentation/en-us/unreal-engine/mover-features-and-concepts-in-unreal-engine)
- [Unreal Engine 5.8 Release Notes](https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-5-8-release-notes)

Version note: these pages currently resolve to Unreal Engine 5.8. Epic labels Mover
Experimental. The 5.8 release notes describe expanded Mover prediction/rollback work but do
not remove that maturity warning. Character Movement remains the mature default for standard
networked Character locomotion.

Special movement patterns

# Special movement patterns

## Launch

Use `LaunchCharacter` for an impulse-like velocity change that should enter the Character
movement pipeline. Decide independently whether XY/Z override existing velocity. Test authority,
prediction/correction, landing, air control, and repeated launches. A launch is not a duration-
controlled dash.

## Teleport

For network play:

1. Validate the destination on the server.
2. Use a supported SetLocation path with teleport behavior or the Teleport Blueprint node.
3. Ensure collision/encroachment policy matches the design.
4. Expect clients to snap rather than smooth the teleport.

Do not move the owning client first with ordinary transform changes and expect CMC prediction
to accept it.

## Root Motion Source

Use for short programmatic motion needing Character root-motion networking, such as move-to or
jump-force behavior.

1. Select/create the appropriate `FRootMotionSource` variant.
2. Set duration, priority/accumulation, start/target, and finish behavior.
3. Apply through `UCharacterMovementComponent::ApplyRootMotionSource` on the appropriate
   prediction/authority path.
4. Retain the returned handle/ID.
5. Remove with `RemoveRootMotionSource` when canceled or finished if required by the pattern.
6. Test server rejection, collision, moving targets, and montage/root-motion competition.

GAS provides Ability Tasks that use Root Motion Sources; prefer those when the ability owns
activation, cancellation, and prediction.

## Custom movement mode

1. Allocate a stable custom sub-mode byte/enum.
2. Enter through `SetMovementMode(MOVE_Custom, SubMode)`.
3. Implement `UpdateCustomMovement` in Character Blueprint for prototypes, or override
   `PhysCustom` in a custom CMC for production control.
4. Perform swept movement and define collision, floor, velocity, gravity, and exit rules.
5. Serialize any custom input/state the server needs through saved-move/network move data.
6. Return to Walking/Falling/etc. through an explicit exit condition.

`MOVE_Custom` suspends normal movement physics. Failing to implement gravity, collision, or
velocity semantics is not an engine bug.

## Montage root motion

Use for animation-authored committed actions. Root motion takes priority over standard
movement physics. In network games, ensure gameplay triggers the montage consistently; GAS can
synchronize ability-owned montages/root motion. Route blend/slot details to
`$unreal-animation-blending`.

Movement system selector

# Movement system selector

| Need | Use | Reason / warning |
|---|---|---|
| Standard humanoid capsule movement and mature multiplayer support | `ACharacter` + `UCharacterMovementComponent` | Walking/falling/swimming/flying/custom modes, prediction, correction, smoothing |
| A special mode integrated with normal Character movement | CMC `MOVE_Custom` + custom sub-mode | Standard physics are suspended while custom physics run; custom state may need saved-move serialization |
| Short deterministic/programmatic ability movement | Root Motion Source or GAS root-motion Ability Task | Participates in Character root-motion networking when used correctly |
| Animation-authored committed movement | Montage root motion | Root motion takes priority over normal movement physics; gameplay must synchronize montage execution |
| Modular mode/layered-move architecture and willingness to carry experimental risk | Mover | Epic labels Mover Experimental in UE 5.8 |
| Vehicle, rolling body, non-capsule creature, or unconventional physics | Purpose-built Pawn/movement system | Character and CMC are designed together around Character movement assumptions |

## Selection procedure

1. Define collision shape and whether the entity must use `ACharacter`.
2. List movement modes and which may overlap as temporary layered moves.
3. State single-player/multiplayer, authority, prediction, and rollback requirements.
4. State whether motion is code-driven, animation-driven, or selected per action.
5. Choose the most mature framework that satisfies the requirements.
6. If choosing Mover, record experimental status, engine-version lock, fallback cost, and a
   packaged multiplayer prototype milestone before committing production content.

Do not migrate from CMC merely because custom movement requires C++. The deciding question is
whether CMC's Character/capsule/mode/network model still fits the game.

Troubleshooting

# Troubleshooting

## Character slides after input release

- Raise braking deceleration and/or effective braking friction deliberately.
- Check `bUseSeparateBrakingFriction`, `BrakingFriction`, and factor interaction.
- Distinguish no-input stopping from direction-change grip.

## Direction changes feel slow despite high acceleration

- Check GroundFriction and effective input magnitude.
- Check rotation ownership/rate if facing, not velocity, is the slow part.
- Measure velocity change separately from mesh turn animation.

## Cannot climb a small step

- Compare collision height with `MaxStepHeight`.
- Confirm the upper surface is walkable and the capsule has clearance.
- Inspect collision seams and blocking channels.
- Test without decorative mesh collision overriding intended simple collision.

## Stands on implausibly tiny edges

- Review `PerchRadiusThreshold`, capsule radius, and ledge geometry.
- Visualize collision/floor results; do not judge by skeletal mesh feet.

## Jump varies with frame rate

- Remove manual per-frame velocity/position increments lacking delta-time/physics integration.
- Verify variable jump release is bound correctly.
- Check custom movement simulation time steps/iterations under low frame rate.

## Constant server corrections

- Confirm client and server use identical parameters and custom state.
- Serialize state that changes movement physics.
- Prevent incompatible saved moves from combining.
- Remove client-only transform changes.
- Fix divergence before changing smoothing or correction thresholds.

## Remote character jitters

- First determine whether authoritative capsule is correcting or only mesh smoothing looks bad.
- Inspect update rate, packet conditions, moving base, and custom-mode replication.
- Tune smoothing only after deterministic movement is correct.

## Root motion fights movement

- Confirm root-motion extraction mode and asset settings.
- Remember root motion takes precedence over normal movement physics.
- Do not also drive the same action with Launch/SetLocation/velocity.
- Ensure montage start/cancel is synchronized across network roles.

## Custom mode floats or tunnels

- `MOVE_Custom` suspends standard physics; implement gravity, velocity, swept collision, floor,
  sub-stepping, and exit behavior explicitly.
- Prefer C++ `PhysCustom` for complex production modes.