CharacterBody2D
Hereda: PhysicsBody2D < CollisionObject2D < Node2D < CanvasItem < Node < Object
Un cuerpo de física 2D especializado para characters movidos por script.
Descripción
CharacterBody2D es una clase especializada para cuerpos físicos diseñados para ser controlados por el usuario. No están afectados por la física en absoluto, pero sí afectan a otros cuerpos físicos en su trayectoria. Principalmente, se utilizan para proporcionar una API de alto nivel que permite mover objetos con detección de paredes y pendientes (método move_and_slide()), además de la detección general de colisiones que ofrece PhysicsBody2D.move_and_collide(). Esto los hace útiles para cuerpos físicos altamente configurables que deben moverse de maneras específicas y colisionar con el mundo, como suele ser el caso de los personajes controlados por el usuario.
Para los objetos del juego que no requieren un movimiento complejo ni detección de colisiones, como plataformas móviles, AnimatableBody2D es más sencillo de configurar.
Tutoriales
Propiedades
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
Métodos
void |
|
get_floor_angle(up_direction: Vector2 = Vector2(0, -1)) const |
|
get_floor_normal() const |
|
get_last_motion() const |
|
get_platform_velocity() const |
|
get_position_delta() const |
|
get_real_velocity() const |
|
get_slide_collision(slide_idx: int) |
|
get_slide_collision_count() const |
|
get_wall_normal() const |
|
is_on_ceiling() const |
|
is_on_ceiling_only() const |
|
is_on_floor() const |
|
is_on_floor_only() const |
|
is_on_wall() const |
|
is_on_wall_only() const |
|
Enumeraciones
enum MotionMode: 🔗
MotionMode MOTION_MODE_GROUNDED = 0
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.
MotionMode MOTION_MODE_FLOATING = 1
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.
enum PlatformOnLeave: 🔗
PlatformOnLeave PLATFORM_ON_LEAVE_ADD_VELOCITY = 0
Add the last platform velocity to the velocity when you leave a moving platform.
PlatformOnLeave PLATFORM_ON_LEAVE_ADD_UPWARD_VELOCITY = 1
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.
PlatformOnLeave PLATFORM_ON_LEAVE_DO_NOTHING = 2
No hacer nada al salir de una plataforma.
Descripciones de Propiedades
bool floor_block_on_wall = true 🔗
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.
bool floor_constant_speed = false 🔗
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 floor_snap_length to stick along a downward slope at constant speed.
float floor_max_angle = 0.7853982 🔗
Maximum angle (in radians) where a slope is still considered a floor (or a ceiling), rather than a wall, when calling move_and_slide(). The default value equals 45 degrees.
float floor_snap_length = 1.0 🔗
Sets a snapping distance. When set to a value different from 0.0, the body is kept attached to slopes when calling move_and_slide(). The snapping vector is determined by the given distance along the opposite direction of the up_direction.
As long as the snapping vector is in contact with the ground and the body moves against up_direction, the body will remain attached to the surface. Snapping is not applied if the body moves along up_direction, 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 apply_floor_snap().
bool floor_stop_on_slope = true 🔗
If true, the body will not slide on slopes when calling move_and_slide() when the body is standing still.
If false, the body will slide on floor's slopes when velocity applies a downward force.
Maximum number of times the body can change direction before it stops when calling move_and_slide(). Must be greater than zero.
MotionMode motion_mode = 0 🔗
void set_motion_mode(value: MotionMode)
MotionMode get_motion_mode()
Sets the motion mode which defines the behavior of move_and_slide().
int platform_floor_layers = 4294967295 🔗
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.
PlatformOnLeave platform_on_leave = 0 🔗
void set_platform_on_leave(value: PlatformOnLeave)
PlatformOnLeave get_platform_on_leave()
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.
int platform_wall_layers = 0 🔗
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.
Extra margin used for collision recovery when calling move_and_slide().
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.
bool slide_on_ceiling = true 🔗
If true, during a jump against the ceiling, the body will slide, if false it will be stopped and will fall vertically.
Vector2 up_direction = Vector2(0, -1) 🔗
Vector pointing upwards, used to determine what is a wall and what is a floor (or a ceiling) when calling move_and_slide(). 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 MOTION_MODE_FLOATING as motion_mode.
Vector2 velocity = Vector2(0, 0) 🔗
Current velocity vector in pixels per second, used and modified during calls to move_and_slide().
This property should not be set to a value multiplied by delta, because this happens internally in move_and_slide(). Otherwise, the simulation will run at an incorrect speed.
float wall_min_slide_angle = 0.2617994 🔗
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 motion_mode is MOTION_MODE_FLOATING.
Descripciones de Métodos
void apply_floor_snap() 🔗
Permite aplicar manualmente un ajuste al suelo sin importar la velocidad del cuerpo. Esta función no hace nada cuando is_on_floor() devuelve true.
float get_floor_angle(up_direction: Vector2 = Vector2(0, -1)) const 🔗
Devuelve el ángulo de colisión del suelo en el último punto de colisión según up_direction, que es Vector2.UP por defecto. Este valor es siempre positivo y solo es válido después de llamar a move_and_slide() y cuando is_on_floor() devuelve true.
Vector2 get_floor_normal() const 🔗
Devuelve la normal de colisión del suelo en el último punto de colisión. Sólo es válido después de llamar a move_and_slide() y cuando is_on_floor() devuelve true.
Advertencia: La normal de colisión no siempre es la misma que la normal de la superficie.
Vector2 get_last_motion() const 🔗
Devuelve el último movimiento aplicado al CharacterBody2D durante la última llamada a move_and_slide(). El movimiento se puede dividir en múltiples movimientos cuando se produce un deslizamiento, y este método devuelve el último, que es útil para recuperar la dirección actual del movimiento.
KinematicCollision2D get_last_slide_collision() 🔗
Devuelve una KinematicCollision2D, que contiene información sobre la última colisión que ocurrió durante la última llamada a move_and_slide().
Vector2 get_platform_velocity() const 🔗
Devuelve la velocidad lineal de la plataforma en el último punto de colisión. Solo es válido después de llamar a move_and_slide().
Vector2 get_position_delta() const 🔗
Devuelve el recorrido (posición delta) que se produjo durante la última llamada a move_and_slide().
Vector2 get_real_velocity() const 🔗
Devuelve la velocidad real actual desde la última llamada a move_and_slide(). Por ejemplo, al subir una pendiente, te moverás en diagonal aunque la velocidad sea horizontal. Este método devuelve el movimiento diagonal, a diferencia de velocity que devuelve la velocidad solicitada.
KinematicCollision2D get_slide_collision(slide_idx: int) 🔗
Devuelve un KinematicCollision2D, que contiene información sobre una colisión que ocurrió durante la última llamada a move_and_slide(). Dado que el cuerpo puede colisionar varias veces en una sola llamada a move_and_slide(), debes especificar el índice de la colisión en el rango 0 a (get_slide_collision_count() - 1).
Ejemplo: Iterar a través de las colisiones con un bucle for:
for i in get_slide_collision_count():
var collision = get_slide_collision(i)
print("Colisionó con: ", collision.get_collider().name)
for (int i = 0; i < GetSlideCollisionCount(); i++)
{
KinematicCollision2D collision = GetSlideCollision(i);
GD.Print("Colisionó con: ", (collision.GetCollider() as Node).Name);
}
int get_slide_collision_count() const 🔗
Devuelve el número de veces que el cuerpo chocó y cambió de dirección durante la última llamada a move_and_slide().
Vector2 get_wall_normal() const 🔗
Devuelve la normal de la colisión de la pared en el último punto de colisión. Solo es válido después de llamar a move_and_slide() y cuando is_on_wall() devuelve true.
Advertencia: La normal de colisión no siempre es la misma que la normal de la superficie.
Returns true if the body collided with the ceiling on the last call of move_and_slide(). Otherwise, returns false. The up_direction and floor_max_angle are used to determine whether a surface is "ceiling" or not.
bool is_on_ceiling_only() const 🔗
Returns true if the body collided only with the ceiling on the last call of move_and_slide(). Otherwise, returns false. The up_direction and floor_max_angle are used to determine whether a surface is "ceiling" or not.
Returns true if the body collided with the floor on the last call of move_and_slide(). Otherwise, returns false. The up_direction and floor_max_angle are used to determine whether a surface is "floor" or not.
bool is_on_floor_only() const 🔗
Returns true if the body collided only with the floor on the last call of move_and_slide(). Otherwise, returns false. The up_direction and floor_max_angle are used to determine whether a surface is "floor" or not.
Returns true if the body collided with a wall on the last call of move_and_slide(). Otherwise, returns false. The up_direction and floor_max_angle are used to determine whether a surface is "wall" or not.
bool is_on_wall_only() const 🔗
Returns true if the body collided only with a wall on the last call of move_and_slide(). Otherwise, returns false. The up_direction and floor_max_angle are used to determine whether a surface is "wall" or not.
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.
This method should be used in Node._physics_process() (or in a method called by Node._physics_process()), as it uses the physics step's delta value automatically in calculations. Otherwise, the simulation will run at an incorrect speed.
Modifies velocity if a slide collision occurred. To get the latest collision call get_last_slide_collision(), for detailed information about collisions that occurred, use get_slide_collision().
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 motion_mode.
Returns true if the body collided, otherwise, returns false.