CharacterBody2D

package
v0.0.0-...-357ca8a Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 20, 2025 License: MIT Imports: 30 Imported by: 0

Documentation

Overview

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 PhysicsBody2D.MoveAndCollide. 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.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Advanced 

type Advanced = class

Advanced exposes a 1:1 low-level instance of the class, undocumented, for those who know what they are doing.

type Any 

type Any interface {
	gd.IsClass
	AsCharacterBody2D() Instance
}

type Expanded 

type Expanded = MoreArgs

type Extension 

type Extension[T gdclass.Interface] struct{ gdclass.Extension[T, Instance] }

Extension can be embedded in a new struct to create an extension of this class. T should be the type that is embedding this Extension

func (*Extension[T]) AsCanvasItem 

func (self *Extension[T]) AsCanvasItem() CanvasItem.Instance

func (*Extension[T]) AsCharacterBody2D 

func (self *Extension[T]) AsCharacterBody2D() Instance

func (*Extension[T]) AsCollisionObject2D 

func (self *Extension[T]) AsCollisionObject2D() CollisionObject2D.Instance

func (*Extension[T]) AsNode 

func (self *Extension[T]) AsNode() Node.Instance

func (*Extension[T]) AsNode2D 

func (self *Extension[T]) AsNode2D() Node2D.Instance

func (*Extension[T]) AsObject 

func (self *Extension[T]) AsObject() [1]gd.Object

func (*Extension[T]) AsPhysicsBody2D 

func (self *Extension[T]) AsPhysicsBody2D() PhysicsBody2D.Instance

type ID 

type ID Object.ID

ID is a typed object ID (reference) to an instance of this class, use it to store references to objects with unknown lifetimes, as an ID will not panic on use if the underlying object has been destroyed.

func (ID) Instance 

func (id ID) Instance() (Instance, bool)

type Instance 

type Instance [1]gdclass.CharacterBody2D

Instance of the class with convieniently typed arguments and results. 

var Nil Instance

Nil is a nil/null instance of the class. Equivalent to the zero value.

func New 

func New() Instance

func (Instance) ApplyFloorSnap 

func (self Instance) ApplyFloorSnap()

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

func (Instance) AsCanvasItem 

func (self Instance) AsCanvasItem() CanvasItem.Instance

func (Instance) AsCharacterBody2D 

func (self Instance) AsCharacterBody2D() Instance

func (Instance) AsCollisionObject2D 

func (self Instance) AsCollisionObject2D() CollisionObject2D.Instance

func (Instance) AsNode 

func (self Instance) AsNode() Node.Instance

func (Instance) AsNode2D 

func (self Instance) AsNode2D() Node2D.Instance

func (Instance) AsObject 

func (self Instance) AsObject() [1]gd.Object

func (Instance) AsPhysicsBody2D 

func (self Instance) AsPhysicsBody2D() PhysicsBody2D.Instance

func (Instance) FloorBlockOnWall 

func (self Instance) FloorBlockOnWall() bool

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.

func (Instance) FloorConstantSpeed 

func (self Instance) FloorConstantSpeed() bool

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.

func (Instance) FloorMaxAngle 

func (self Instance) FloorMaxAngle() Angle.Radians

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.

func (Instance) FloorSnapLength 

func (self Instance) FloorSnapLength() Float.X

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.

func (Instance) FloorStopOnSlope 

func (self Instance) FloorStopOnSlope() bool

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.

func (Instance) GetFloorAngle 

func (self Instance) GetFloorAngle() Angle.Radians

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

func (Instance) GetFloorNormal 

func (self Instance) GetFloorNormal() Vector2.XY

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

Warning: The collision normal is not always the same as the surface normal.

func (Instance) GetLastMotion 

func (self Instance) GetLastMotion() Vector2.XY

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.

func (Instance) GetLastSlideCollision 

func (self Instance) GetLastSlideCollision() KinematicCollision2D.Instance

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

func (Instance) GetPlatformVelocity 

func (self Instance) GetPlatformVelocity() Vector2.XY

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

func (Instance) GetPositionDelta 

func (self Instance) GetPositionDelta() Vector2.XY

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

func (Instance) GetRealVelocity 

func (self Instance) GetRealVelocity() Vector2.XY

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.

func (Instance) GetSlideCollision 

func (self Instance) GetSlideCollision(slide_idx int) KinematicCollision2D.Instance

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: Iterate through the collisions with a for loop: 

for i := range characterBody2D.GetSlideCollisionCount() {
	var collision = characterBody2D.GetSlideCollision(i)
	fmt.Println("Collided with: ", Object.To[Node.Instance](collision.GetCollider()).Name())
}

func (Instance) GetSlideCollisionCount 

func (self Instance) GetSlideCollisionCount() int

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

func (Instance) GetWallNormal 

func (self Instance) GetWallNormal() Vector2.XY

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

Warning: The collision normal is not always the same as the surface normal.

func (Instance) ID 

func (self Instance) ID() ID

func (Instance) IsOnCeiling 

func (self Instance) IsOnCeiling() bool

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.

func (Instance) IsOnCeilingOnly 

func (self Instance) IsOnCeilingOnly() bool

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.

func (Instance) IsOnFloor 

func (self Instance) IsOnFloor() bool

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.

func (Instance) IsOnFloorOnly 

func (self Instance) IsOnFloorOnly() bool

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.

func (Instance) IsOnWall 

func (self Instance) IsOnWall() bool

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.

func (Instance) IsOnWallOnly 

func (self Instance) IsOnWallOnly() bool

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.

func (Instance) MaxSlides 

func (self Instance) MaxSlides() int

Maximum number of times the body can change direction before it stops when calling MoveAndSlide. Must be greater than zero.

func (Instance) MoreArgs 

func (self Instance) MoreArgs() MoreArgs

MoreArgs enables certain functions to be called with additional 'optional' arguments.

func (Instance) MotionMode 

func (self Instance) MotionMode() MotionMode

Sets the motion mode which defines the behavior of MoveAndSlide.

func (Instance) MoveAndSlide 

func (self Instance) MoveAndSlide() bool

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.

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.

func (Instance) PlatformFloorLayers 

func (self Instance) PlatformFloorLayers() int

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.

func (Instance) PlatformOnLeave 

func (self Instance) PlatformOnLeave() 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.

func (Instance) PlatformWallLayers 

func (self Instance) PlatformWallLayers() int

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.

func (Instance) SafeMargin 

func (self Instance) SafeMargin() Float.X

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.

func (Instance) SetFloorBlockOnWall 

func (self Instance) SetFloorBlockOnWall(value bool)

SetFloorBlockOnWall sets the property returned by [IsFloorBlockOnWallEnabled].

func (Instance) SetFloorConstantSpeed 

func (self Instance) SetFloorConstantSpeed(value bool)

SetFloorConstantSpeed sets the property returned by [IsFloorConstantSpeedEnabled].

func (Instance) SetFloorMaxAngle 

func (self Instance) SetFloorMaxAngle(value Angle.Radians)

SetFloorMaxAngle sets the property returned by [GetFloorMaxAngle].

func (Instance) SetFloorSnapLength 

func (self Instance) SetFloorSnapLength(value Float.X)

SetFloorSnapLength sets the property returned by [GetFloorSnapLength].

func (Instance) SetFloorStopOnSlope 

func (self Instance) SetFloorStopOnSlope(value bool)

SetFloorStopOnSlope sets the property returned by [IsFloorStopOnSlopeEnabled].

func (Instance) SetMaxSlides 

func (self Instance) SetMaxSlides(value int)

SetMaxSlides sets the property returned by [GetMaxSlides].

func (Instance) SetMotionMode 

func (self Instance) SetMotionMode(value MotionMode)

SetMotionMode sets the property returned by [GetMotionMode].

func (*Instance) SetObject 

func (self *Instance) SetObject(obj [1]gd.Object) bool

func (Instance) SetPlatformFloorLayers 

func (self Instance) SetPlatformFloorLayers(value int)

SetPlatformFloorLayers sets the property returned by [GetPlatformFloorLayers].

func (Instance) SetPlatformOnLeave 

func (self Instance) SetPlatformOnLeave(value PlatformOnLeave)

SetPlatformOnLeave sets the property returned by [GetPlatformOnLeave].

func (Instance) SetPlatformWallLayers 

func (self Instance) SetPlatformWallLayers(value int)

SetPlatformWallLayers sets the property returned by [GetPlatformWallLayers].

func (Instance) SetSafeMargin 

func (self Instance) SetSafeMargin(value Float.X)

SetSafeMargin sets the property returned by [GetSafeMargin].

func (Instance) SetSlideOnCeiling 

func (self Instance) SetSlideOnCeiling(value bool)

SetSlideOnCeiling sets the property returned by [IsSlideOnCeilingEnabled].

func (Instance) SetUpDirection 

func (self Instance) SetUpDirection(value Vector2.XY)

SetUpDirection sets the property returned by [GetUpDirection].

func (Instance) SetVelocity 

func (self Instance) SetVelocity(value Vector2.XY)

SetVelocity sets the property returned by [GetVelocity].

func (Instance) SetWallMinSlideAngle 

func (self Instance) SetWallMinSlideAngle(value Angle.Radians)

SetWallMinSlideAngle sets the property returned by [GetWallMinSlideAngle].

func (Instance) SlideOnCeiling 

func (self Instance) SlideOnCeiling() bool

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

func (Instance) UpDirection 

func (self Instance) UpDirection() Vector2.XY

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 MotionModeFloating as MotionMode.

func (Instance) Velocity 

func (self Instance) Velocity() Vector2.XY

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

func (Instance) Virtual 

func (self Instance) Virtual(name string) reflect.Value

func (Instance) WallMinSlideAngle 

func (self Instance) WallMinSlideAngle() Angle.Radians

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

type MoreArgs 

type MoreArgs [1]gdclass.CharacterBody2D

MoreArgs is a container for Instance functions with additional 'optional' arguments.

func (MoreArgs) GetFloorAngle 

func (self MoreArgs) GetFloorAngle(up_direction Vector2.XY) Angle.Radians

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

type MotionMode 

type MotionMode int //gd:CharacterBody2D.MotionMode

const (
	// Apply when notions of walls, ceiling and floor are relevant. In this mode the body motion will react to slopes (acceleration/slowdown). This mode is suitable for sided games like platformers.
	MotionModeGrounded MotionMode = 0
	// Apply when there is no notion of floor or ceiling. All collisions will be reported as on_wall. In this mode, when you slide, the speed will always be constant. This mode is suitable for top-down games.
	MotionModeFloating MotionMode = 1
)

type PlatformOnLeave 

type PlatformOnLeave int //gd:CharacterBody2D.PlatformOnLeave

const (
	// Add the last platform velocity to the [Velocity] when you leave a moving platform.
	//
	// [Velocity]: https://pkg.go.dev/graphics.gd/classdb/#Instance.Velocity
	PlatformOnLeaveAddVelocity PlatformOnLeave = 0
	// Add the last platform velocity to the [Velocity] when you leave a moving platform, but any downward motion is ignored. It's useful to keep full jump height even when the platform is moving down.
	//
	// [Velocity]: https://pkg.go.dev/graphics.gd/classdb/#Instance.Velocity
	PlatformOnLeaveAddUpwardVelocity PlatformOnLeave = 1
	// Do nothing when leaving a platform.
	PlatformOnLeaveDoNothing PlatformOnLeave = 2
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.