Class SerpentineLocomotion

Owns native Body Front-guided movement, produces the procedural locomotion pose and optionally guards the complete creature against surface penetration. Feature implementations live in focused partial source files and internal solver collaborators.

Inheritance

object

SerpentineLocomotion

Namespace: CreatureKit.Serpentine

Assembly: CreatureKit.Serpentine.Runtime.dll

Syntax

public sealed class SerpentineLocomotion : MonoBehaviour

Constructors

SerpentineLocomotion()

Declaration

public SerpentineLocomotion()

Properties

AccumulatedActualTravelDistance

World distance actually travelled since motion tracking was reset.

Declaration

public float AccumulatedActualTravelDistance { get; }

Property Value

Type	Description
float

AccumulatedSignedPhaseDistance

Signed distance used to advance the procedural wave.

Declaration

public float AccumulatedSignedPhaseDistance { get; }

Property Value

Type	Description
float

ActiveSelfContactCount

Number of non-neighboring Body contacts detected in the last pose.

Declaration

public int ActiveSelfContactCount { get; }

Property Value

Type	Description
int

AnticipatedSelfContactCount

Contacts detected inside the crossing look-ahead envelope.

Declaration

public int AnticipatedSelfContactCount { get; }

Property Value

Type	Description
int

BodyFrontCollision

Current world collision constraining Body Front movement.

Declaration

public SerpentineHeadCollision BodyFrontCollision { get; }

Property Value

Type	Description
SerpentineHeadCollision

BodyFrontMotionState

Current native movement state of Body Front.

Declaration

public SerpentineHeadMotionState BodyFrontMotionState { get; }

Property Value

Type	Description
SerpentineHeadMotionState

BodyFrontSupport

Current support detected beneath Body Front.

Declaration

public SerpentineHeadSupport BodyFrontSupport { get; }

Property Value

Type	Description
SerpentineHeadSupport

BodyGroundFollowAcceleratingJointCount

Body articulations whose supported descent accelerated during the latest pose.

Declaration

public int BodyGroundFollowAcceleratingJointCount { get; }

Property Value

Type	Description
int

BodyGroundFollowActivationDistance

Excess support gap required to start Body Ground Follow from rest.

Declaration

public float BodyGroundFollowActivationDistance { get; }

Property Value

Type	Description
float

BodyGroundFollowDescendingJointCount

Body articulations that requested a progressive downward step.

Declaration

public int BodyGroundFollowDescendingJointCount { get; }

Property Value

Type	Description
int

BodyGroundFollowReconstructionCount

Length-preserving Ground Follow reconstructions during the latest pose.

Declaration

public int BodyGroundFollowReconstructionCount { get; }

Property Value

Type	Description
int

BodyGroundFollowSupportedJointCount

Body articulations with an accepted support during the latest pose.

Declaration

public int BodyGroundFollowSupportedJointCount { get; }

Property Value

Type	Description
int

BodyGroundFollowTimeToMaximumSpeed

Seconds needed to reach the configured Ground Follow maximum speed from rest.

Declaration

public float BodyGroundFollowTimeToMaximumSpeed { get; }

Property Value

Type	Description
float

CurrentPhase

Current normalized locomotion phase.

Declaration

public float CurrentPhase { get; }

Property Value

Type	Description
float

EffectiveLateralBendDegrees

Lateral bend currently evaluated by locomotion.

Declaration

public float EffectiveLateralBendDegrees { get; }

Property Value

Type	Description
float

GravityAcceleration

Shared Body Front and Body acceleration along World Probe Direction.

Declaration

public float GravityAcceleration { get; }

Property Value

Type	Description
float

GuidanceCenterWorldDirection

Rate-limited central locomotion heading.

Declaration

public Vector3 GuidanceCenterWorldDirection { get; }

Property Value

Type	Description
Vector3

GuidancePathPointCount

Number of resampled points retained behind the Head guide.

Declaration

public int GuidancePathPointCount { get; }

Property Value

Type	Description
int

GuidanceSelfContactLift

Transient Head lift excluded from the persistent Body path.

Declaration

public float GuidanceSelfContactLift { get; }

Property Value

Type	Description
float

GuidanceTargetWorldDirection

Unfiltered world direction most recently requested by the application.

Declaration

public Vector3 GuidanceTargetWorldDirection { get; }

Property Value

Type	Description
Vector3

GuidanceWorldDirection

Effective world direction owned by the selected guiding Head.

Declaration

public Vector3 GuidanceWorldDirection { get; }

Property Value

Type	Description
Vector3

GuidingHead

The generated Head that currently owns locomotion guidance.

Declaration

public SerpentineHeadPart GuidingHead { get; }

Property Value

Type	Description
SerpentineHeadPart

GuidingHeadIndex

Zero-based serialized index of the explicit guiding Head.

Declaration

public int GuidingHeadIndex { get; }

Property Value

Type	Description
int

HeadCollision

Legacy alias for the current Body Front world collision.

Declaration

public SerpentineHeadCollision HeadCollision { get; }

Property Value

Type	Description
SerpentineHeadCollision

HeadMotionState

Current native movement state inferred from Body Front.

Declaration

public SerpentineHeadMotionState HeadMotionState { get; }

Property Value

Type	Description
SerpentineHeadMotionState

HeadSupport

Legacy alias for the current Body Front support.

Declaration

public SerpentineHeadSupport HeadSupport { get; }

Property Value

Type	Description
SerpentineHeadSupport

HeadSurfacePenetrationCorrection

Largest terrain correction requested by the guiding Head volume.

Declaration

public float HeadSurfacePenetrationCorrection { get; }

Property Value

Type	Description
float

HorizontalSteeringPhase

Normalized spatial phase of the lateral Body wave.

Declaration

public float HorizontalSteeringPhase { get; }

Property Value

Type	Description
float

HorizontalSteeringYawDegrees

Legacy diagnostic retained for compatibility. Body wave no longer rotates the movement direction, so the automatic guidance yaw is always zero.

Declaration

public float HorizontalSteeringYawDegrees { get; }

Property Value

Type	Description
float

IsBodyFrontSupported

True while Body Front has an accepted Ground sample.

Declaration

public bool IsBodyFrontSupported { get; }

Property Value

Type	Description
bool

IsHeadSupported

Legacy alias indicating whether Body Front has a support.

Declaration

public bool IsHeadSupported { get; }

Property Value

Type	Description
bool

LastActualWorldDisplacement

Most recently reported or observed achieved displacement.

Declaration

public Vector3 LastActualWorldDisplacement { get; }

Property Value

Type	Description
Vector3

LastGuidanceRequestedDisplacement

Most recent displacement submitted to the Head constraint query.

Declaration

public Vector3 LastGuidanceRequestedDisplacement { get; }

Property Value

Type	Description
Vector3

LastGuidanceResolvedDisplacement

Most recent displacement returned after all Head constraints.

Declaration

public Vector3 LastGuidanceResolvedDisplacement { get; }

Property Value

Type	Description
Vector3

LastGuidanceTurnStepDegrees

Accepted angular change applied during the latest guidance step.

Declaration

public float LastGuidanceTurnStepDegrees { get; }

Property Value

Type	Description
float

LastGuidanceWorldDisplacement

Most recent displacement after scene collision constraints.

Declaration

public Vector3 LastGuidanceWorldDisplacement { get; }

Property Value

Type	Description
Vector3

MaximumAppliedSelfContactAngle

Largest additional per-interval bend currently applied by self contact.

Declaration

public float MaximumAppliedSelfContactAngle { get; }

Property Value

Type	Description
float

MaximumBodyGroundFollowBendAngle

Largest angle between adjacent segments in the resolved gravity pose.

Declaration

public float MaximumBodyGroundFollowBendAngle { get; }

Property Value

Type	Description
float

MaximumBodyGroundFollowFallSpeed

Largest current supported Body Ground Follow descent speed.

Declaration

public float MaximumBodyGroundFollowFallSpeed { get; }

Property Value

Type	Description
float

MaximumBodyGroundFollowOffset

Largest persistent downward Body Ground Follow offset.

Declaration

public float MaximumBodyGroundFollowOffset { get; }

Property Value

Type	Description
float

MaximumBodyGroundFollowPathDeviation

Largest three-dimensional deviation of the gravity pose from the Head path.

Declaration

public float MaximumBodyGroundFollowPathDeviation { get; }

Property Value

Type	Description
float

MaximumBodyGroundFollowStep

Largest resolved Body Ground Follow step requested this frame.

Declaration

public float MaximumBodyGroundFollowStep { get; }

Property Value

Type	Description
float

MaximumBodyGroundFollowTargetDistance

Largest remaining support distance observed by Body Ground Follow.

Declaration

public float MaximumBodyGroundFollowTargetDistance { get; }

Property Value

Type	Description
float

MaximumBodyPathDeviation

Largest current distance between the nominal Head path and Body path.

Declaration

public float MaximumBodyPathDeviation { get; }

Property Value

Type	Description
float

MaximumFallSpeed

Shared Body Front and Body maximum falling speed.

Declaration

public float MaximumFallSpeed { get; }

Property Value

Type	Description
float

MaximumGuidancePathTurnDegrees

Largest turn between adjacent intervals of the current Head path.

Declaration

public float MaximumGuidancePathTurnDegrees { get; }

Property Value

Type	Description
float

MaximumPathCurvatureWaveSuppression

Largest wave reduction required by the current Head-path curvature.

Declaration

public float MaximumPathCurvatureWaveSuppression { get; }

Property Value

Type	Description
float

MaximumSelfContactWaveSuppression

Largest local reduction currently applied to the lateral wave.

Declaration

public float MaximumSelfContactWaveSuppression { get; }

Property Value

Type	Description
float

MaximumSurfacePenetrationCorrection

Largest correction currently requested by the penetration guard.

Declaration

public float MaximumSurfacePenetrationCorrection { get; }

Property Value

Type	Description
float

NativeFallSpeed

Current Body Front falling speed along World Probe Direction.

Declaration

public float NativeFallSpeed { get; }

Property Value

Type	Description
float

PreventedPenetrationCount

Number of axial joints corrected by the final penetration guard.

Declaration

public int PreventedPenetrationCount { get; }

Property Value

Type	Description
int

RemainingGuidanceTurnDegrees

Angle still remaining before locomotion reaches its requested direction.

Declaration

public float RemainingGuidanceTurnDegrees { get; }

Property Value

Type	Description
float

SelfContactCapsuleCount

Current number of adaptive analytical Body contact capsules.

Declaration

public int SelfContactCapsuleCount { get; }

Property Value

Type	Description
int

UsesHeadGuidedPath

True when a generated Head currently owns the axial path guide.

Declaration

public bool UsesHeadGuidedPath { get; }

Property Value

Type	Description
bool

VerticalTravelDistancePerCycle

Distance that advances the vertical wave by one cycle.

Declaration

public float VerticalTravelDistancePerCycle { get; }

Property Value

Type	Description
float

WholeBodySelfContactWaveSuppression

Current whole-Body reduction retained after a self contact.

Declaration

public float WholeBodySelfContactWaveSuppression { get; }

Property Value

Type	Description
float

Methods

AdvancePreview(float)

Advances virtual Head travel and evaluates one complete preview pose.

Declaration

public void AdvancePreview(float deltaTime)

Parameters

Type	Name	Description
float	deltaTime

ApplyPreviewPose()

Applies the current preview pose without moving the root.

Declaration

public void ApplyPreviewPose()

Move(Vector3)

Applies one native movement step using the current frame duration.

Declaration

public SerpentineMoveResult Move(Vector3 requestedWorldDisplacement)

Parameters

Type	Name	Description
Vector3	requestedWorldDisplacement

Returns

Type	Description
SerpentineMoveResult

Move(Vector3, float)

Applies one complete native movement step. The caller supplies intent; Serpentine owns Body Front collision, support following, falling, root translation and path reporting. Call this once per frame, including with zero requested displacement while support and falling state must continue to update.

Declaration

public SerpentineMoveResult Move(Vector3 requestedWorldDisplacement, float deltaTime)

Parameters

Type	Name	Description
Vector3	requestedWorldDisplacement
float	deltaTime

Returns

Type	Description
SerpentineMoveResult

ReportActualDisplacement(Vector3)

Reports a displacement applied by an exceptional external motion source. Native Move(Vector3, float) reports its own achieved displacement.

Declaration

public void ReportActualDisplacement(Vector3 actualWorldDisplacement)

Parameters

Type	Name	Description
Vector3	actualWorldDisplacement

ReportActualDisplacement(Vector3, Vector3)

Reports achieved displacement with an explicit direction used for its sign.

Declaration

public void ReportActualDisplacement(Vector3 actualWorldDisplacement, Vector3 worldForward)

Parameters

Type	Name	Description
Vector3	actualWorldDisplacement
Vector3	worldForward

ResetGuidancePath()

Clears travelled path memory and seeds a straight Body behind the current guide. Call this after teleporting or replacing the movement reference.

Declaration

public void ResetGuidancePath()

ResetMotionTracking()

Resets travel counters and the automatic Transform observation baseline.

Declaration

public void ResetMotionTracking()

ResolveGuidanceDisplacement(Vector3)

Constrains a requested world displacement with Body Front and the optional local Head obstacle guard. This low-level query can slide along scene geometry and optionally lift the Head branch over Body. Prefer Move(Vector3, float) for complete native movement.

Declaration

public Vector3 ResolveGuidanceDisplacement(Vector3 requestedWorldDisplacement)

Parameters

Type	Name	Description
Vector3	requestedWorldDisplacement

Returns

Type	Description
Vector3

SetGuidanceWorldDirection(Vector3)

Sets the selected Head's target guidance direction. In Play Mode, the Head-owned direction approaches it at Maximum Guidance Turn Speed; Body Front follows that heading while Body undulation remains independent from it.

Declaration

public void SetGuidanceWorldDirection(Vector3 worldDirection)

Parameters

Type	Name	Description
Vector3	worldDirection

SetGuidanceWorldDirection(Vector3, float)

Sets a target direction and advances the rate-limited locomotion heading with an explicit time step. A non-positive Edit Mode step applies it immediately.

Declaration

public void SetGuidanceWorldDirection(Vector3 worldDirection, float deltaTime)

Parameters

Type	Name	Description
Vector3	worldDirection
float	deltaTime

Events

BodyFrontCollisionEntered

Raised when Body Front first meets a world collider.

Declaration

public event Action<SerpentineHeadCollision> BodyFrontCollisionEntered

Event Type

Type	Description
Action<SerpentineHeadCollision>

BodyFrontCollisionExited

Raised when Body Front leaves a world collider.

Declaration

public event Action<SerpentineHeadCollision> BodyFrontCollisionExited

Event Type

Type	Description
Action<SerpentineHeadCollision>

BodyFrontCollisionStayed

Raised while Body Front remains constrained by one collider.

Declaration

public event Action<SerpentineHeadCollision> BodyFrontCollisionStayed

Event Type

Type	Description
Action<SerpentineHeadCollision>

BodyFrontSupportChanged

Raised when the support collider beneath Body Front changes.

Declaration

public event Action<SerpentineHeadSupport, SerpentineHeadSupport> BodyFrontSupportChanged

Event Type

Type	Description
Action<SerpentineHeadSupport, SerpentineHeadSupport>

HeadCollisionEntered

Legacy event raised when Body Front first meets a world collider.

Declaration

public event Action<SerpentineHeadCollision> HeadCollisionEntered

Event Type

Type	Description
Action<SerpentineHeadCollision>

HeadCollisionExited

Legacy event raised when Body Front leaves a world collider.

Declaration

public event Action<SerpentineHeadCollision> HeadCollisionExited

Event Type

Type	Description
Action<SerpentineHeadCollision>

HeadCollisionStayed

Legacy event raised while Body Front remains constrained.

Declaration

public event Action<SerpentineHeadCollision> HeadCollisionStayed

Event Type

Type	Description
Action<SerpentineHeadCollision>

HeadSupportChanged

Legacy event raised when the support collider beneath Body Front changes.

Declaration

public event Action<SerpentineHeadSupport, SerpentineHeadSupport> HeadSupportChanged

Event Type

Type	Description
Action<SerpentineHeadSupport, SerpentineHeadSupport>