Manual

Manual

Characters

A character is moved as your code tells it, not pushed about as a body is: it walks up slopes and steps, stays on the ground going down, rides moving platforms and stops at walls. This page covers the Character Controller 3D, how to walk and jump it from code, and what it tells your code after each step.

Character Controller 3D

A Character Controller 3D makes its entity a character, built on Jolt's own character. It moves the entity's Rigidbody 3D as a Kinematic body, whatever its Type says, as the shape of the entity's own collider:

  • a Capsule Collider 3D, standing up whatever its Direction says: the usual shape of a person;
  • or a Box Collider 3D, square to the world and flat underneath. A box stands on an edge as long as any of it is over it and meets a wall flat, where a capsule rolls off an edge and up a low step: what a game of blocks wants.

Added in the editor, a Character Controller 3D brings what it moves with, in the same step of the undo: a Rigidbody 3D set to Kinematic, and a Capsule Collider 3D fitted to what the entity draws, unless the entity has them already. The Inspector says under the controller when its entity has neither a capsule nor a box, and so does not move as a character, and when its capsule lies along X or Z, since it stands up anyway.

FieldWhat it does
Slope LimitThe steepest slope it stands on and walks up, in degrees from level, 0 to 90. 45 at first. A steeper slope is a wall: it does not climb it, and slides down it.
Step OffsetThe highest step it walks up onto, in meters. 0.3 at first.
Snap To GroundHow far below it ground is looked for as it walks down a slope or off a step, in meters, so it stays on the ground. 0.3 at first.
Max StrengthThe most it pushes a dynamic body in its way with, in newtons. 100 at first: a person shoves a crate, not a truck.

The Rigidbody 3D still matters:

  • Its Linear Velocity is where the character goes: what your code sets to walk it and to jump.
  • Its Gravity Scale is how hard it falls. Up is against the Gravity of the Physics 3D settings.
  • Its Mass is how hard it pushes what it walks into, and what it weighs on what it stands on.
  • Its Interpolate draws it smoothly between steps, as for any body.

What it does in each step

Each fixed step moves the character along what it meets instead of into it:

  • Slopes: it walks up one no steeper than Slope Limit and stands on it without sliding. One steeper it does not climb, and slides down from.
  • Steps: it walks up onto a step no higher than Step Offset.
  • Going down: walking down a slope or off a step, it keeps to the ground within Snap To Ground.
  • Platforms: standing on a moving platform or an elevator, it is carried along. Jumping or walking off, it keeps the platform's speed.
  • Pushing: a dynamic body in its way is pushed as the character's mass says, by no more than Max Strength. What it stands on bears its weight.
  • Being found: the rest of the world meets it as a Kinematic body of the same shape. Raycasts and overlaps hit it, triggers find it, what falls on it rests on it, and other characters stop against it.

After the step, its Linear Velocity is what your code set, less what went into a wall or a ceiling and, on the ground, its speed downward.

What the last step left

The Character Controller 3D holds what the last step found, for your systems to read. These fields are hidden from the Inspector's normal view; turn on Debug to see them.

FieldWhat it holds
IsGroundedWhether it stands on ground: something no steeper than Slope Limit under it.
GroundNormalThe normal of the ground it stands on, a unit long; zero off the ground.
GroundThe body it stands on, the entity with the Rigidbody 3D or the ground's entity; 0 for none.
OnWallWhether something steeper than Slope Limit is beside it.
OnCeilingWhether something is over it, facing down as steeply as a wall stands.

Walk and jump from code

Set the body's velocity in a system that runs at the fixed rate, after the physics step. Keep what the character falls with in Y, and replace X and Z with where the player steers. Actions.Player.Move and Actions.Player.Jump are input actions every project starts with (see Input actions):

using System.Numerics;using Abyss.Core;using Abyss.Physics3D;using MyGame;
[assembly: AbyssPlugin<WalkingPlugin>]
namespace MyGame;
public sealed class WalkingPlugin : IPlugin{    private const float Speed = 4f;    private const float JumpSpeed = 5f;
    public void Build(Schedule schedule)    {        World world = schedule.World;        ComponentType<Rigidbody3D> rigidbody = world.Component<Rigidbody3D>();        ComponentType<CharacterController3D> character = world.Component<CharacterController3D>();        bool jump = false;
        // A press belongs to a frame, and a frame may have no fixed step: keep it until a step takes it.        schedule.Add("Read jump", [character.Read()], context => jump |= context.Input.Pressed(Actions.Player.Jump));
        schedule.Fixed.Add("Walk", [rigidbody.Write(), character.Read()], context =>        {            Vector2 move = context.Input.Vector(Actions.Player.Move);            foreach (Chunk chunk in context.Chunks)            {                Span<Rigidbody3D> bodies = chunk.GetSpan<Rigidbody3D>(0);                ReadOnlySpan<CharacterController3D> characters = chunk.GetReadOnlySpan<CharacterController3D>(1);                for (int row = 0; row < bodies.Length; row++)                {                    Vector3 velocity = bodies[row].LinearVelocity;                    velocity.X = move.X * Speed;                    velocity.Z = -move.Y * Speed;                    if (jump && characters[row].IsGrounded)                    {                        velocity.Y = JumpSpeed;                    }
                    bodies[row].LinearVelocity = velocity;                }            }
            jump = false;        });    }}

Jump only from the ground, as this does, by reading IsGrounded. OnWall and OnCeiling are there for a wall jump or to end a jump early.

Forces and moves

What you ask of Physics3D acts on a character as its mass says:

  • AddImpulse and AddForce change its velocity: an impulse at once, a force over the next step. Torques turn nothing, since a character always stands up.
  • MovePosition puts it at a place at once, and so does setting its Transform from code.
  • MoveRotation turns it, as setting its Transform's rotation does. Its shape stays upright either way.

See Move a body from code for those calls. A joint never holds a character.

In the Scripting API