CharacterController#

Namespace: PlushEngine.Physics (using PlushEngine.Physics;)

A feet-origin capsule aligned with UpDirection. Place on an unscaled root without a Rigid Body; put scaled/animated visuals on children. The scene solves movement after gameplay callbacks.

public sealed class CharacterController : Script

Usage and examples

Members: ClearMotionIntent · Drive · GravityOverride · GravityScale · GroundNormal · GroundSnapDistance · Height · IsGrounded · Jump · JumpSpeed · Layer · MaxSlopeDegrees · Move · OnAttach · Radius · StepHeight · Suspended · UpDirection · Velocity

ClearMotionIntent#

public void ClearMotionIntent();

Clear pending Move/Jump/Drive requests without teleporting or erasing solved physical velocity. Gravity continues on the next ordinary step. Stop an active NavigationAgent first.

Drive#

public bool Drive(Vector3 velocity);

Request world-space velocity for the next physics step, including vertical motion. Collision stays authoritative; gravity, floor snapping and stepping are suppressed for this step only. Call from BeforePhysics for each driven step. This clears ordinary Move/Jump intent; omitting the next request resumes gravity with the solver's remaining velocity. A traversal owner must compare solved movement with its requested path and handle obstruction. Stop an active NavigationAgent before requesting driven movement.

GravityOverride#

public Vector3? GravityOverride { get; set; }

Optional finite world-space acceleration in m/s² for this character, multiplied by GravityScale. Null uses scene gravity; zero disables acceleration. Drive suppresses it for its requested step.

Remarks: This does not change UpDirection, other characters or rigid-body gravity. The character's weight on a dynamic support still uses scene gravity.

GravityScale#

[DefaultValue(1f)]
public float GravityScale;

GroundNormal#

public Vector3 GroundNormal { get; }

GroundSnapDistance#

[DefaultValue(.3f)]
public float GroundSnapDistance;

Height#

[DefaultValue(1.8f)]
public float Height;

Total capsule height, including both round ends, in meters.

IsGrounded#

public bool IsGrounded { get; }

Jump#

public bool Jump();

Queue one jump from walkable ground. False in air, inactive, paused, already queued or owned by navigation.

JumpSpeed#

[DefaultValue(6f)]
public float JumpSpeed;

Layer#

public CollisionLayerReference Layer;

Collision layer of the capsule; it collides with what that layer collides with. Unset = the default layer.

MaxSlopeDegrees#

[DefaultValue(45f)]
public float MaxSlopeDegrees;

Move#

public void Move(Vector3 velocity);

Set persistent world-space velocity tangent to UpDirection (m/s). The component along up is discarded. Call Move(Vector3.Zero) to stop. Air steering is allowed. Acceleration, input mappings and facing belong to gameplay. Stop an active NavigationAgent before requesting manual movement.

OnAttach#

public override void OnAttach();

Radius#

[DefaultValue(.3f)]
public float Radius;

StepHeight#

[DefaultValue(.25f)]
public float StepHeight;

Suspended#

public bool Suspended { get; set; }

Runtime ownership handoff: removes the capsule on the next physics step without deactivating the entity or its children. Resume recreates it at the current root, at rest. Gameplay must stop movement writers and choose a safe root pose before resuming.

UpDirection#

public Vector3 UpDirection { get; set; }

World-space up for capsule alignment, ground, jumping, stairs and snapping; world +Y by default. Finite nonzero values are normalized; align the root's local Y before the next physics step or Teleport.

Remarks: A live change rotates around the capsule center and retains native velocity, so the reported feet move to the new bottom. Creation and Teleport use a feet origin.

Velocity#

public Vector3 Velocity { get; }

CollisionLayerReference · Script

Source#

CharacterController.cs