Manual

Manual

Characters

A Character Controller 2D makes an entity a character: moved as your code tells it rather than pushed about as a body is, walking up slopes and steps, standing on moving platforms, and pushing crates. This page covers the controller, how it moves, what it reports after each step, and the code that walks and jumps it.

Character Controller 2D

A character moves the Rigidbody 2D on its entity, as a Kinematic body whatever its Type says, and moves as the shape of the Capsule Collider 2D on its own entity. Added in the editor, the controller brings both where the entity has none: a Rigidbody 2D that is Kinematic with Freeze Rotation ticked, and a capsule fitted to what the entity draws, all in one Ctrl+Z. A character with no capsule on its own entity is moved by its velocity through whatever is in its way.

FieldWhat it does
Slope LimitThe steepest slope it stands on and walks up, in degrees from level. A steeper one is a wall it walks into, or slides down from the air. 45 to begin with.
Step OffsetThe highest ledge it steps up onto as it walks, in meters. 0.2 to begin with.
Snap To GroundHow far below it ground is looked for as it walks down a slope or off a step, in meters, so it keeps to the ground rather than leaving it. 0.1 to begin with.

Its Rigidbody 2D says the rest:

  • Linear Velocity is where it goes: set its X to walk and its Y to jump.
  • Gravity Scale is how hard it falls: 0 for a game seen from above.
  • Mass is its weight as it pushes things and stands on them.
  • Interpolate draws it smoothly between steps, as for any body.

How a character moves

Each fixed step, the character goes as its velocity says and slides along what it meets instead of going into it. The step leaves its velocity as your code set it, less what went into a wall or a ceiling and, on the ground, its speed down. So walking up a slope or over an edge sends it no higher, and landing on a slope starts no slide.

  • Slopes: it walks up a slope no steeper than Slope Limit and stands on it without sliding down.
  • Steps: it steps up onto a ledge no higher than Step Offset as it walks.
  • Going down: walking down a slope or off a step, it keeps to the ground within Snap To Ground.
  • Moving ground: standing on a moving platform or an elevator, it is carried with it. Jumping or walking off, it keeps the platform's speed.
  • Pushing: a dynamic body in its way is pushed as the two masses say, so a crate of its own weight slides along and a heavy one barely moves. What it stands on bears its weight.
  • Being met: other bodies meet it as a Kinematic body. What falls on it rests on it, and triggers and queries find it.
  • One-way platforms: it jumps up through a Platform Effector 2D and lands on it, and walks through its side.

Up, for a character, is against the gravity of the Physics 2D settings.

What the last step left

After each step, the controller says what the character touches. These fields are hidden in the Inspector's normal view and shown in its Debug view; a system reads them to decide what the character does next, such as jumping only from the ground.

FieldWhat it says
IsGroundedIt stands on ground: something no steeper than Slope Limit under it.
GroundThe body it stands on, the entity with its Rigidbody 2D, or ground; 0 for none.
GroundNormalThe normal of the ground it stands on, a unit long; zero off the ground.
OnWallSomething steeper than Slope Limit is beside it.
OnCeilingSomething is over it, facing down.

Walk and jump

Move a character from a fixed system, which runs after Physics 2D's step and sees what it left. A button press belongs to a frame, and a frame may have no fixed step, so the press is caught by a frame system and held until a step takes it:

using System.Numerics;using Abyss.Core;using Abyss.Physics2D;using MyGame;
[assembly: AbyssPlugin<WalkingPlugin>]
namespace MyGame;
public sealed class WalkingPlugin : IPlugin{    private const float Speed = 4f;    private const float JumpSpeed = 7f;
    public void Build(Schedule schedule)    {        World world = schedule.World;        ComponentType<Rigidbody2D> rigidbody = world.Component<Rigidbody2D>();        ComponentType<CharacterController2D> character = world.Component<CharacterController2D>();        bool jump = false;
        schedule.Add("Jump input", [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<Rigidbody2D> bodies = chunk.GetSpan<Rigidbody2D>(0);                ReadOnlySpan<CharacterController2D> characters = chunk.GetReadOnlySpan<CharacterController2D>(1);                for (int row = 0; row < bodies.Length; row++)                {                    Vector2 velocity = bodies[row].LinearVelocity;                    velocity.X = move.X * Speed;                    if (jump && characters[row].IsGrounded)                    {                        velocity.Y = JumpSpeed;   // seven meters a second up, from the ground only                    }
                    bodies[row].LinearVelocity = velocity;                }            }
            jump = false;        });    }}

Actions.Player.Move and Actions.Player.Jump are actions of the game's input settings; see Actions.

For a game seen from above, set the Rigidbody 2D's Gravity Scale to 0 and set both X and Y of the velocity from the move.

Drop through a one-way platform

To let a character drop down through a one-way platform it stands on, keep the two from meeting until it has fallen clear, then let them meet again so it lands on the platform next time. Here a Drop action of the game's input settings starts it:

// In the plugin's Build, beside the walking systems above.ComponentId oneWay = world.Component<PlatformEffector2D>().Id;var dropped = new Dictionary<ulong, (ulong Platform, double Until)>();bool drop = false;
schedule.Add("Drop input", [character.Read()], context => drop |= context.Input.Pressed(Actions.Player.Drop));
schedule.Fixed.Add("Drop through", [character.Read()], context =>{    Physics2D physics = context.Services.Get<Physics2D>();    double now = world.Time.ElapsedTime;    foreach (Chunk chunk in context.Chunks)    {        ReadOnlySpan<CharacterController2D> characters = chunk.GetReadOnlySpan<CharacterController2D>(0);        ReadOnlySpan<ulong> entities = chunk.Entities;        for (int row = 0; row < entities.Length; row++)        {            ulong under = characters[row].Ground;            if (drop && characters[row].IsGrounded && world.ComponentsOf(under).Contains(oneWay))            {                physics.IgnoreCollision(entities[row], under);   // falls through it from the next step                dropped[entities[row]] = (under, now + 0.4);            }        }    }
    foreach (var (player, (platform, until)) in dropped.ToArray())    {        if (now >= until)        {            physics.IgnoreCollision(player, platform, false);   // met again, from above            dropped.Remove(player);        }    }
    drop = false;});

See Layers and what collides for IgnoreCollision.

In the Scripting API