Class CharacterBody3D
- Namespace
- Godot
- Assembly
- GodotSharp.dll
CharacterBody3D 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(Vector3, bool, float, bool, int). 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, AnimatableBody3D is simpler to configure.
public class CharacterBody3D : PhysicsBody3D, IDisposable- Inheritance
-
CharacterBody3D
- Implements
- Inherited Members
Constructors
CharacterBody3D()
public CharacterBody3D()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
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
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
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
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
MaxSlides
Maximum number of times the body can change direction before it stops when calling MoveAndSlide().
public int MaxSlides { get; set; }Property Value
MotionMode
Sets the motion mode which defines the behavior of MoveAndSlide(). See CharacterBody3D.MotionModeEnum constants for available modes.
public CharacterBody3D.MotionModeEnum MotionMode { get; set; }Property Value
PlatformFloorLayers
Collision layers that will be included for detecting floor bodies that will act as moving platforms to be followed by the CharacterBody3D. By default, all floor bodies are detected and propagate their velocity.
public uint PlatformFloorLayers { get; set; }Property Value
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 CharacterBody3D.PlatformOnLeaveEnum constants for available behavior.
public CharacterBody3D.PlatformOnLeaveEnum PlatformOnLeave { get; set; }Property Value
PlatformWallLayers
Collision layers that will be included for detecting wall bodies that will act as moving platforms to be followed by the CharacterBody3D. By default, all wall bodies are ignored.
public uint PlatformWallLayers { get; set; }Property Value
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
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
UpDirection
Vector pointing upwards, used to determine what is a wall and what is a floor (or a ceiling) when calling MoveAndSlide(). Defaults to Vector3.UP. As the vector will be normalized it can't be equal to Vector3.ZERO, if you want all collisions to be reported as walls, consider using Floating as MotionMode.
public Vector3 UpDirection { get; set; }Property Value
Velocity
Current velocity vector (typically meters per second), used and modified during calls to MoveAndSlide().
public Vector3 Velocity { get; set; }Property Value
WallMinSlideAngle
Minimum angle (in radians) where the body is allowed to slide when it encounters a slope. The default value equals 15 degrees. When MotionMode is Grounded, it only affects movement if FloorBlockOnWall is true.
public float WallMinSlideAngle { get; set; }Property Value
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(Vector3?)
Returns the floor's collision angle at the last collision point according to upDirection, which is Vector3.UP by default. This value is always positive and only valid after calling MoveAndSlide() and when IsOnFloor() returns true.
public float GetFloorAngle(Vector3? upDirection = null)Parameters
upDirectionVector3?If the parameter is null, then the default value is
new Vector3(0, 1, 0).
Returns
GetFloorNormal()
Returns the surface normal of the floor at the last collision point. Only valid after calling MoveAndSlide() and when IsOnFloor() returns true.
public Vector3 GetFloorNormal()Returns
GetLastMotion()
Returns the last motion applied to the CharacterBody3D 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 Vector3 GetLastMotion()Returns
GetLastSlideCollision()
Returns a KinematicCollision3D, which contains information about the latest collision that occurred during the last call to MoveAndSlide().
public KinematicCollision3D GetLastSlideCollision()Returns
GetPlatformAngularVelocity()
Returns the angular velocity of the platform at the last collision point. Only valid after calling MoveAndSlide().
public Vector3 GetPlatformAngularVelocity()Returns
GetPlatformVelocity()
Returns the linear velocity of the platform at the last collision point. Only valid after calling MoveAndSlide().
public Vector3 GetPlatformVelocity()Returns
GetPositionDelta()
Returns the travel (position delta) that occurred during the last call to MoveAndSlide().
public Vector3 GetPositionDelta()Returns
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 Vector3 GetRealVelocity()Returns
GetSlideCollision(int)
Returns a KinematicCollision3D, 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).
public KinematicCollision3D GetSlideCollision(int slideIdx)Parameters
slideIdxint
Returns
GetSlideCollisionCount()
Returns the number of times the body collided and changed direction during the last call to MoveAndSlide().
public int GetSlideCollisionCount()Returns
GetWallNormal()
Returns the surface normal of the wall at the last collision point. Only valid after calling MoveAndSlide() and when IsOnWall() returns true.
public Vector3 GetWallNormal()Returns
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
methodgodot_string_nameName of the method to check for.
Returns
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
signalgodot_string_nameName of the signal to check for.
Returns
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
methodgodot_string_nameName of the method to invoke.
argsNativeVariantPtrArgsArguments to use with the invoked method.
retgodot_variantValue returned by the invoked method.
Returns
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
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
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
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
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
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
MoveAndSlide()
Moves the body based on Velocity. If the body collides with another, it will slide along the other body rather than stop immediately. If the other body is a CharacterBody3D or RigidBody3D, 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 more 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.
Returns true if the body collided, otherwise, returns false.
public bool MoveAndSlide()