Documentation
Home Animation Channels Guide Clips Guide No-Code Guide API Reference

Locomotion and Terrain

SerpentineLocomotion owns the complete V1 Body pose. It combines the Head path, optional vertical undulation and optional surface-penetration correction before writing the bones once:

  1. the achieved Head trajectory;
  2. the optional vertical wave;
  3. the optional volumetric penetration guard.

This makes locomotion more than a cosmetic animation while keeping root motion under the user's controller.

Explicit guiding Head

Head-guided path is enabled by default. Guiding Head selects one generated Head as the only locomotion authority; Locomotion never poses the other Heads. A controller or decision system calls SetGuidanceWorldDirection with the direction selected by that Head. Maximum Turn Speed rate-limits that target into GuidanceCenterWorldDirection. Locomotion then adds automatic Head yaw around the stable dorsal axis; read the resulting GuidanceWorldDirection before calculating requested travel.

The movement reference remains owned by the user's controller. Locomotion records its achieved positions after collision resolution, samples that path backward at constant Body articulation spacing, and anchors the front articulation to the guide. The Body therefore turns progressively behind Head instead of rotating around its center.

Before moving, a controller can call ResolveGuidanceDisplacement. The optional query sweeps a capsule fitted to the complete current Head assembly, including the independently rotated Lower Jaw. Scene hits project the remaining travel onto the contacted plane, allowing the guide to climb an incline instead of putting the visual Head through it. When optional Self Contact is enabled, the displacement query begins lifting the Head along the dorsal direction so it can initiate a crossing above the older Body. The method only returns a safe world displacement; the user controller still owns movement and performs final collision resolution. Without Self Contact, Head/Body crossings are deliberately not blocked.

The sampled Head path is the complete horizontal axial shape. During actual forward travel, Locomotion rotates the Head sinusoidally on either side of its central heading. Steering Amplitude sets the maximum yaw (32 degrees by default). Steering Cycles defines how many complete steering cycles are written over one Body length, so size and speed do not independently change the path wavelength. Application steering moves the central heading while this locomotion yaw continues around it; the resulting S-curves propagate naturally toward the Tail.

After a path reset, the seeded history is straight. The new S-curves replace it progressively, so a long creature must travel close to one Body length before its complete Body reflects the gait. Before the first longitudinal travel, purely transverse controller settling translates the complete seed instead of writing a vertical corner. Genuine height changes are recorded normally as soon as forward or backward travel begins.

Visual gaze or look animation must not call the locomotion-guidance API.

Vertical undulation and optional local penetration corrections are applied afterward, leaving room for future Body obstacle avoidance that may deviate from the exact Head track. Autonomous sensing and path decisions are not part of this first guidance stage.

Achieved travel

Phases advance from actual signed path distance. Forward movement advances them, backward movement reverses them and lateral-only displacement does not advance them. Automatic Head steering advances by signed distance * Steering Cycles / Body Length; it therefore freezes at rest. The optional vertical wave independently advances by signed distance * Vertical Wave Cycles / Body Length.

Automatic Transform observation is the default. ReportActualDisplacement is the precise API for controllers that resolve collisions or slopes. A manual report prevents automatic double-counting in the same frame. Use the Head's chosen direction as the explicit forward argument. ResetMotionTracking also clears travelled path memory after a teleport.

Vertical wave

The terrestrial default has Vertical Bend Degrees at zero. Increase it only when the Body should produce a deliberate three-dimensional or helical contribution. When the bend is zero, the inspector hides Vertical Wave Cycles, phase and amplitude profile because none of them can affect the pose.

Animate In Edit Mode feeds a virtual forward displacement through the normal Head Steering and path-history pipeline while leaving the root stationary. Preview Speed is expressed in Body lengths per second.

Optional Body self contact

Self Contact is a dedicated inspector foldout and is disabled by default. It approximates Body intervals with analytical capsules; it does not add Collider components or invoke a rigid-body simulation. Natural neighbors are ignored so ordinary curvature remains free. Non-neighboring contacts are resolved before the final dorsal-frame alignment and bone write:

  • crossing branches can stack vertically, with the newer Head-side branch preferred above;
  • near-parallel branches separate laterally, allowing a loose coil to form;
  • the Head/front articulation remains anchored and the Body arc length is reconstructed after every solver pass.

Quality controls the tradeoff. Capsule length is derived from the physical Body diameter, not from a fixed number of bones, and tight curvature automatically subdivides a volume. Longer or more curved creatures therefore receive more capsules. Low favors longer capsules and one pass, Medium uses a balanced density and two passes, and High uses shorter capsules and four passes while also looking farther ahead for a Head/Body crossing. Clearance adds space around the anatomical profile and Softness controls how much of a detected overlap is corrected per pass. Cost grows approximately with the square of the selected capsule count, so Low is the appropriate starting point for numerous creatures.

Contact detection produces an instantaneous target, but the target is not written directly to the Body. Reaction Response eases each affected interval toward it, Maximum Speed caps the added bend in degrees per second, and Maximum Bend prevents a single interval from folding too far. A short built-in contact memory ignores one-frame losses; after that, Release Response returns the Body progressively to its unconstrained path. The final filtered chain remains front-anchored and preserves every segment length.

Anticipation Distance extends only the crossing look-ahead envelope. When two non-neighboring branches approach at a crossing angle, the Head-side branch starts building its vertical lift before the analytical capsules overlap. The final Body spacing still comes from Clearance; parallel coil contacts are not inflated by anticipation. Volumes that are still neighbors along the Body are excluded using exact centerline arc distance, with the anticipation envelope included, so an ordinary local undulation cannot collide with itself. The guiding Head uses the same rule: its attached proximal Body cannot request a lift, but a distant Body branch can.

The vertical displacement requested for that Head/Body crossing is measured separately from the world-constrained movement. Only the world movement is retained in SerpentineHeadPathHistory; the achieved crossing lift is reapplied to a short Head-side Body branch and removed again as the controller descends. Consequently, a self-contact bump is not replayed all the way to the Tail, while real terrain height changes remain in the persistent three-dimensional path.

The transient crossing lift does not enter the persistent Head path, and the optional vertical wave remains independent from that contact response.

Visual diagnostics

Select the creature and open the dedicated Diagnostics foldout at the bottom of the Locomotion inspector:

  • Head Guidance: white is the central heading, orange is the effective Head direction and Head/world sweep, and violet is Head/Body clearance;
  • Surface Penetration: cyan capsules are the transverse volumes tested by the optional guard;
  • Body Ground Follow: green shows a detected support target, orange the current velocity over a fixed 0.1-second preview, blue the accelerated per-frame request, and violet the spatially resolved step;
  • Self Contact: blue capsules are longitudinal Body intervals, orange marks an anticipated crossing, yellow marks active vertical stacking, and red marks a lateral constraint.

These gizmos render the actual procedural volumes used by the algorithms. They do not create scene objects and have no runtime rendering cost in a player build.

Optional surface penetration guard

The achieved three-dimensional Head path replaces the former distributed terrain sensors and smooth support envelope. Prevent Surface Penetration is retained as one isolated, optional safety guard during validation. It sweeps the complete Body cross-section at every articulation, keeps each collision query local, lightly shares a correction with immediate neighbors and reconstructs the length-preserving chain. Disable it to evaluate pure Head-path following.

Diagnostics report how many sections it corrected and the largest applied correction. If both remain zero through representative slopes, convex crests and ledges, the guard is inactive for that creature and scene. It preserves the controller root and does not replace collision resolution.

Optional Body Ground Follow

Body Ground Follow reuses the Body terrain hits already collected through Terrain Reach. It adds no dedicated raycast pass. A supported articulation accelerates from rest toward the detected surface using the same Gravity Acceleration and Maximum Fall Speed as Head, while an articulation with no accepted hit receives no independent fall and loses its accumulated velocity. Activation Distance is an excess-gap threshold: an articulation at rest does not start below it, but an active articulation continues to the surface. A remaining-distance arrival limit prevents velocity stored against chain constraints from being released as an overshooting impulse. The response is filtered across supported neighbors and reconstructed with the same exact-length Body invariant. Consequently a narrow deep hole causes a temporary sag rather than an immediate snap to its bottom, while a longer descent or ledge can progressively lower more of the Body. The achieved gravity pose is retained in world space instead of being reduced to a vertical offset from the nominal Head path. This lets exact-length segments slide longitudinally while Body Front remains Head-owned. Maximum Bend limits the turn added between adjacent segments, spreading a ledge transition across multiple articulations and avoiding accordion folds before Self Contact needs to intervene. The resolved path temporarily absorbs this persistent pose while the nominal Head history catches up. Actual Head movement reacquires only the path difference perpendicular to gravity, so stale vertical history cannot pull a supported Body back into the air. Assuming one Unity unit represents one metre, the shared defaults are 9.81 units/s² and 55 units/s. Their ratio is shown in the Inspector so configurations that reach terminal speed almost immediately remain explicit.

Measure Solver reports supported, accelerating and descending joints, maximum target distance, current descent speed, per-frame step, accumulated vertical offset, three-dimensional path deviation, largest adjacent-segment bend, and Ground Follow reconstructions separately from upward penetration.