Table of Contents

Class CharacterBody2D

Namespace
Godot
Assembly
GodotSharp.dll

CharacterBody2D is a specialized class for physics bodies that are meant to be user-controlled. They are not affected by physics at all, but they affect other physics bodies in their path. They are mainly used to provide high-level API to move objects with wall and slope detection (MoveAndSlide() method) in addition to the general collision detection provided by MoveAndCollide(Vector2, bool, float, bool). This makes it useful for highly configurable physics bodies that must move in specific ways and collide with the world, as is often the case with user-controlled characters.

For game objects that don't require complex movement or collision detection, such as moving platforms, AnimatableBody2D is simpler to configure.

public class CharacterBody2D : PhysicsBody2D, IDisposable
Inheritance
CharacterBody2D
Implements
Inherited Members

Constructors

CharacterBody2D() 

public CharacterBody2D()

Properties

FloorBlockOnWall

If true, the body will be able to move on the floor only. This option avoids to be able to walk on walls, it will however allow to slide down along them.

public bool FloorBlockOnWall { get; set; }

Property Value

bool

FloorConstantSpeed

If false (by default), the body will move faster on downward slopes and slower on upward slopes.

If true, the body will always move at the same speed on the ground no matter the slope. Note that you need to use FloorSnapLength to stick along a downward slope at constant speed.

public bool FloorConstantSpeed { get; set; }

Property Value

bool

FloorMaxAngle

Maximum angle (in radians) where a slope is still considered a floor (or a ceiling), rather than a wall, when calling MoveAndSlide(). The default value equals 45 degrees.

public float FloorMaxAngle { get; set; }

Property Value

float

FloorSnapLength

Sets a snapping distance. When set to a value different from 0.0, the body is kept attached to slopes when calling MoveAndSlide(). The snapping vector is determined by the given distance along the opposite direction of the UpDirection.

As long as the snapping vector is in contact with the ground and the body moves against UpDirection, the body will remain attached to the surface. Snapping is not applied if the body moves along UpDirection, meaning it contains vertical rising velocity, so it will be able to detach from the ground when jumping or when the body is pushed up by something. If you want to apply a snap without taking into account the velocity, use ApplyFloorSnap().

public float FloorSnapLength { get; set; }

Property Value

float

FloorStopOnSlope

If true, the body will not slide on slopes when calling MoveAndSlide() when the body is standing still.

If false, the body will slide on floor's slopes when Velocity applies a downward force.

public bool FloorStopOnSlope { get; set; }

Property Value

bool

MaxSlides

Maximum number of times the body can change direction before it stops when calling MoveAndSlide().

public int MaxSlides { get; set; }

Property Value

int

MotionMode

Sets the motion mode which defines the behavior of MoveAndSlide(). See CharacterBody2D.MotionModeEnum constants for available modes.

public CharacterBody2D.MotionModeEnum MotionMode { get; set; }

Property Value

CharacterBody2D.MotionModeEnum

PlatformFloorLayers

Collision layers that will be included for detecting floor bodies that will act as moving platforms to be followed by the CharacterBody2D. By default, all floor bodies are detected and propagate their velocity.

public uint PlatformFloorLayers { get; set; }

Property Value

uint

PlatformOnLeave

Sets the behavior to apply when you leave a moving platform. By default, to be physically accurate, when you leave the last platform velocity is applied. See CharacterBody2D.PlatformOnLeaveEnum constants for available behavior.

public CharacterBody2D.PlatformOnLeaveEnum PlatformOnLeave { get; set; }

Property Value

CharacterBody2D.PlatformOnLeaveEnum

PlatformWallLayers

Collision layers that will be included for detecting wall bodies that will act as moving platforms to be followed by the CharacterBody2D. By default, all wall bodies are ignored.

public uint PlatformWallLayers { get; set; }

Property Value

uint

SafeMargin

Extra margin used for collision recovery when calling MoveAndSlide().

If the body is at least this close to another body, it will consider them to be colliding and will be pushed away before performing the actual motion.

A higher value means it's more flexible for detecting collision, which helps with consistently detecting walls and floors.

A lower value forces the collision algorithm to use more exact detection, so it can be used in cases that specifically require precision, e.g at very low scale to avoid visible jittering, or for stability with a stack of character bodies.

public float SafeMargin { get; set; }

Property Value

float

SlideOnCeiling

If true, during a jump against the ceiling, the body will slide, if false it will be stopped and will fall vertically.

public bool SlideOnCeiling { get; set; }

Property Value

bool

UpDirection

Vector pointing upwards, used to determine what is a wall and what is a floor (or a ceiling) when calling MoveAndSlide(). Defaults to Vector2.UP. As the vector will be normalized it can't be equal to Vector2.ZERO, if you want all collisions to be reported as walls, consider using Floating as MotionMode.

public Vector2 UpDirection { get; set; }

Property Value

Vector2

Velocity

Current velocity vector in pixels per second, used and modified during calls to MoveAndSlide().

public Vector2 Velocity { get; set; }

Property Value

Vector2

WallMinSlideAngle

Minimum angle (in radians) where the body is allowed to slide when it encounters a slope. The default value equals 15 degrees. This property only affects movement when MotionMode is Floating.

public float WallMinSlideAngle { get; set; }

Property Value

float

Methods

ApplyFloorSnap()

Allows to manually apply a snap to the floor regardless of the body's velocity. This function does nothing when IsOnFloor() returns true.

public void ApplyFloorSnap()

GetFloorAngle(Vector2?)

Returns the floor's collision angle at the last collision point according to upDirection, which is Vector2.UP by default. This value is always positive and only valid after calling MoveAndSlide() and when IsOnFloor() returns true.

public float GetFloorAngle(Vector2? upDirection = null)

Parameters

upDirection Vector2?

If the parameter is null, then the default value is new Vector2(0, -1).

Returns

float

GetFloorNormal()

Returns the surface normal of the floor at the last collision point. Only valid after calling MoveAndSlide() and when IsOnFloor() returns true.

public Vector2 GetFloorNormal()

Returns

Vector2

GetLastMotion()

Returns the last motion applied to the CharacterBody2D during the last call to MoveAndSlide(). The movement can be split into multiple motions when sliding occurs, and this method return the last one, which is useful to retrieve the current direction of the movement.

public Vector2 GetLastMotion()

Returns

Vector2

GetLastSlideCollision()

Returns a KinematicCollision2D, which contains information about the latest collision that occurred during the last call to MoveAndSlide().

public KinematicCollision2D GetLastSlideCollision()

Returns

KinematicCollision2D

GetPlatformVelocity()

Returns the linear velocity of the platform at the last collision point. Only valid after calling MoveAndSlide().

public Vector2 GetPlatformVelocity()

Returns

Vector2

GetPositionDelta()

Returns the travel (position delta) that occurred during the last call to MoveAndSlide().

public Vector2 GetPositionDelta()

Returns

Vector2

GetRealVelocity()

Returns the current real velocity since the last call to MoveAndSlide(). For example, when you climb a slope, you will move diagonally even though the velocity is horizontal. This method returns the diagonal movement, as opposed to Velocity which returns the requested velocity.

public Vector2 GetRealVelocity()

Returns

Vector2

GetSlideCollision(int)

Returns a KinematicCollision2D, which contains information about a collision that occurred during the last call to MoveAndSlide(). Since the body can collide several times in a single call to MoveAndSlide(), you must specify the index of the collision in the range 0 to (GetSlideCollisionCount() - 1).

Example usage: 

for (int i = 0; i < GetSlideCollisionCount(); i++)
  {
      KinematicCollision2D collision = GetSlideCollision(i);
      GD.Print("Collided with: ", (collision.GetCollider() as Node).Name);
  }
public KinematicCollision2D GetSlideCollision(int slideIdx)

Parameters

slideIdx int

Returns

KinematicCollision2D

GetSlideCollisionCount()

Returns the number of times the body collided and changed direction during the last call to MoveAndSlide().

public int GetSlideCollisionCount()

Returns

int

GetWallNormal()

Returns the surface normal of the wall at the last collision point. Only valid after calling MoveAndSlide() and when IsOnWall() returns true.

public Vector2 GetWallNormal()

Returns

Vector2

HasGodotClassMethod(in godot_string_name)

Check if the type contains a method with the given name. This method is used by Godot to check if a method exists before invoking it. Do not call or override this method.

protected override bool HasGodotClassMethod(in godot_string_name method)

Parameters

method godot_string_name

Name of the method to check for.

Returns

bool

HasGodotClassSignal(in godot_string_name)

Check if the type contains a signal with the given name. This method is used by Godot to check if a signal exists before raising it. Do not call or override this method.

protected override bool HasGodotClassSignal(in godot_string_name signal)

Parameters

signal godot_string_name

Name of the signal to check for.

Returns

bool

InvokeGodotClassMethod(in godot_string_name, NativeVariantPtrArgs, out godot_variant)

Invokes the method with the given name, using the given arguments. This method is used by Godot to invoke methods from the engine side. Do not call or override this method.

protected override bool InvokeGodotClassMethod(in godot_string_name method, NativeVariantPtrArgs args, out godot_variant ret)

Parameters

method godot_string_name

Name of the method to invoke.

args NativeVariantPtrArgs

Arguments to use with the invoked method.

ret godot_variant

Value returned by the invoked method.

Returns

bool

IsOnCeiling()

Returns true if the body collided with the ceiling on the last call of MoveAndSlide(). Otherwise, returns false. The UpDirection and FloorMaxAngle are used to determine whether a surface is "ceiling" or not.

public bool IsOnCeiling()

Returns

bool

IsOnCeilingOnly()

Returns true if the body collided only with the ceiling on the last call of MoveAndSlide(). Otherwise, returns false. The UpDirection and FloorMaxAngle are used to determine whether a surface is "ceiling" or not.

public bool IsOnCeilingOnly()

Returns

bool

IsOnFloor()

Returns true if the body collided with the floor on the last call of MoveAndSlide(). Otherwise, returns false. The UpDirection and FloorMaxAngle are used to determine whether a surface is "floor" or not.

public bool IsOnFloor()

Returns

bool

IsOnFloorOnly()

Returns true if the body collided only with the floor on the last call of MoveAndSlide(). Otherwise, returns false. The UpDirection and FloorMaxAngle are used to determine whether a surface is "floor" or not.

public bool IsOnFloorOnly()

Returns

bool

IsOnWall()

Returns true if the body collided with a wall on the last call of MoveAndSlide(). Otherwise, returns false. The UpDirection and FloorMaxAngle are used to determine whether a surface is "wall" or not.

public bool IsOnWall()

Returns

bool

IsOnWallOnly()

Returns true if the body collided only with a wall on the last call of MoveAndSlide(). Otherwise, returns false. The UpDirection and FloorMaxAngle are used to determine whether a surface is "wall" or not.

public bool IsOnWallOnly()

Returns

bool

MoveAndSlide()

Moves the body based on Velocity. If the body collides with another, it will slide along the other body (by default only on floor) rather than stop immediately. If the other body is a CharacterBody2D or RigidBody2D, it will also be affected by the motion of the other body. You can use this to make moving and rotating platforms, or to make nodes push other nodes.

Modifies Velocity if a slide collision occurred. To get the latest collision call GetLastSlideCollision(), for detailed information about collisions that occurred, use GetSlideCollision(int).

When the body touches a moving platform, the platform's velocity is automatically added to the body motion. If a collision occurs due to the platform's motion, it will always be first in the slide collisions.

The general behavior and available properties change according to the MotionMode.

Returns true if the body collided, otherwise, returns false.

public bool MoveAndSlide()

Returns

bool
Edit this page