Attention: Here be dragons
This is the latest
(unstable) version of this documentation, which may document features
not available in or compatible with released stable versions of Godot.
Checking the stable version of the documentation...
CharacterBody3D
Hereda: PhysicsBody3D < CollisionObject3D < Node3D < Node < Object
Cuerpo de physics 3D especializado para personajes movidos por script.
Descripción
CharacterBody3D es una clase especializada para cuerpos físicos destinados a ser controlados por el usuario. No se ven afectados por la física en absoluto, pero afectan a otros cuerpos físicos en su trayectoria. Se utilizan principalmente para proporcionar una API de alto nivel para mover objetos con detección de paredes y pendientes (método move_and_slide()), además de la detección de colisiones general proporcionada por PhysicsBody3D.move_and_collide(). Esto los hace útiles para cuerpos físicos altamente configurables que deben moverse de formas específicas y colisionar con el mundo, como suele ser el caso de los personajes controlados por el usuario.
Para objetos de juego que no requieren un movimiento complejo o detección de colisiones, como plataformas móviles, AnimatableBody3D es más sencillo de configurar.
Tutoriales
Propiedades
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
Métodos
void |
|
get_floor_angle(up_direction: Vector3 = Vector3(0, 1, 0)) const |
|
get_floor_normal() const |
|
get_last_motion() const |
|
get_platform_angular_velocity() 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
Se aplica cuando las nociones de paredes, techo y suelo son relevantes. En este modo, el movimiento del cuerpo reaccionará a las pendientes (aceleración/desaceleración). Este modo es adecuado para juegos basados en el suelo, como los de plataformas.
MotionMode MOTION_MODE_FLOATING = 1
Se aplica cuando no existen las nociones de suelo o techo. Todas las colisiones se reportarán como on_wall. En este modo, al deslizarse, la velocidad será siempre constante. Este modo es adecuado para juegos sin suelo, como los juegos espaciales.
enum PlatformOnLeave: 🔗
PlatformOnLeave PLATFORM_ON_LEAVE_ADD_VELOCITY = 0
Añade la velocidad de la última plataforma a velocity al abandonar una plataforma móvil.
PlatformOnLeave PLATFORM_ON_LEAVE_ADD_UPWARD_VELOCITY = 1
Añade la velocidad de la última plataforma a velocity al abandonar una plataforma móvil, pero se ignora cualquier motion hacia abajo. Es útil para mantener la altura total del salto incluso cuando la plataforma se mueve hacia abajo.
PlatformOnLeave PLATFORM_ON_LEAVE_DO_NOTHING = 2
No hacer nada al salir de una plataforma.
Descripciones de Propiedades
bool floor_block_on_wall = true 🔗
Si es true, el cuerpo solo podrá moverse por el suelo. Esta opción impide caminar por las paredes, aunque permite deslizarse hacia abajo por ellas.
bool floor_constant_speed = false 🔗
Si es false (por defecto), el cuerpo se moverá más rápido en pendientes descendentes y más lento en pendientes ascendentes.
Si es true, el cuerpo siempre se moverá a la misma velocidad en el suelo, independientemente de la pendiente. Ten en cuenta que debes usar floor_snap_length para seguir a lo largo de una pendiente descendente a una velocidad constante.
float floor_max_angle = 0.7853982 🔗
Ángulo máximo (en radianes) en el que una pendiente se sigue considerando un suelo (o un techo), en lugar de una pared, al llamar a move_and_slide(). El valor predeterminado equivale a 45 grados.
float floor_snap_length = 0.1 🔗
Establece una distancia de snap. Cuando se establece en un value distinto de 0.0, el cuerpo se mantiene attached a las pendientes al llamar a move_and_slide(). El vector de snap se determina por la distancia dada en la dirección opuesta a up_direction.
Mientras el vector de snap esté en contacto con el suelo y el cuerpo se mueva contra up_direction, el cuerpo permanecerá attached a la superficie. El snap no se aplica si el cuerpo se mueve a lo largo de up_direction, lo que significa que contiene velocidad de ascenso vertical, por lo que podrá despegarse del suelo al saltar o cuando el cuerpo sea empujado hacia arriba por algo. Si deseas aplicar un snap sin tener en cuenta la velocidad, usa apply_floor_snap().
bool floor_stop_on_slope = true 🔗
Si es true, el cuerpo no se deslizará por las pendientes al llamar a move_and_slide() cuando esté quieto.
Si es false, el cuerpo se deslizará por las pendientes del suelo cuando velocity aplique una fuerza hacia abajo.
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 🔗
Capas de colisión que se incluirán para detectar cuerpos en el suelo que actuarán como plataformas móviles seguidas por el CharacterBody3D. Por defecto, se detectan todos los cuerpos en el suelo y propagan su velocidad.
PlatformOnLeave platform_on_leave = 0 🔗
void set_platform_on_leave(value: PlatformOnLeave)
PlatformOnLeave get_platform_on_leave()
Establece el comportamiento a aplicar al abandonar una plataforma móvil. Por defecto, para ser físicamente preciso, cuando abandonas la última plataforma se aplica su velocidad.
int platform_wall_layers = 0 🔗
Capas de colisión que se incluirán para detectar cuerpos en las paredes que actuarán como plataformas móviles seguidas por el CharacterBody3D. Por defecto, se ignoran todos los cuerpos en las paredes.
Margen adicional utilizado para la recuperación de colisiones al llamar a move_and_slide().
Si el cuerpo está al menos a esta distancia de otro cuerpo, se considerará que están colisionando y será empujado antes de realizar el motion real.
Un value más alto significa que es más flexible para detectar colisiones, lo que ayuda a detectar paredes y suelos de forma consistente.
Un value más bajo obliga al algoritmo de colisión a utilizar una detección más exacta, por lo que puede usarse en casos que requieran precisión específicamente, por ejemplo, a una escala muy baja para evitar vibraciones visibles, o para lograr estabilidad con una pila de cuerpos de personaje.
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.
Vector3 up_direction = Vector3(0, 1, 0) 🔗
Vector que apunta hacia arriba, utilizado para determinar qué es una pared y qué es un suelo (o un techo) al llamar a move_and_slide(). Por defecto es Vector3.UP. Dado que el vector se normalizará, no puede ser igual a Vector3.ZERO; si deseas que todas las colisiones se reporten como paredes, considera usar MOTION_MODE_FLOATING como motion_mode.
Vector3 velocity = Vector3(0, 0, 0) 🔗
Vector de velocidad actual (normalmente en metros por segundo), utilizado y modificado durante las llamadas a move_and_slide().
Nota: Un error común es establecer esta propiedad con la velocidad deseada multiplicada por delta, lo que produce un vector de movimiento (normalmente en metros).
float wall_min_slide_angle = 0.2617994 🔗
Ángulo mínimo (en radianes) en el que el cuerpo tiene permitido deslizarse cuando encuentra una pared. El valor por defecto es igual a 15 grados. Cuando motion_mode es MOTION_MODE_GROUNDED, solo afecta al movimiento si floor_block_on_wall es true.
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: Vector3 = Vector3(0, 1, 0)) const 🔗
Returns the floor's collision angle at the last collision point according to up_direction, which is Vector3.UP by default. This value is always positive and only valid after calling move_and_slide() and when is_on_floor() returns true.
Vector3 get_floor_normal() const 🔗
Devuelve la normal de colisión del suelo en el último punto de colisión. Solo 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.
Vector3 get_last_motion() const 🔗
Devuelve el último movimiento aplicado al CharacterBody3D durante la última llamada a move_and_slide(). El movimiento puede dividirse en múltiples desplazamientos cuando ocurre un deslizamiento, y este método devuelve el último de ellos, lo cual es útil para obtener la dirección actual del movimiento.
KinematicCollision3D get_last_slide_collision() 🔗
Devuelve un KinematicCollision3D si ocurrió una colisión. El valor devuelto contiene información sobre la colisión más reciente que ocurrió durante la última llamada a move_and_slide(). Devuelve null si no ocurrió ninguna colisión. Consulte también get_slide_collision().
Vector3 get_platform_angular_velocity() const 🔗
Devuelve la velocidad angular de la plataforma en el último punto de colisión. Solo es válido tras llamar a move_and_slide().
Vector3 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().
Vector3 get_position_delta() const 🔗
Devuelve el recorrido (posición delta) que se produjo durante la última llamada a move_and_slide().
Vector3 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.
KinematicCollision3D get_slide_collision(slide_idx: int) 🔗
Returns a KinematicCollision3D, which contains information about a collision that occurred during the last call to move_and_slide(). Since the body can collide several times in a single call to move_and_slide(), you must specify the index of the collision in the range 0 to (get_slide_collision_count() - 1). See also get_last_slide_collision().
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().
Vector3 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.
Devuelve true si el cuerpo colisionó con el techo en la última llamada de move_and_slide(). De lo contrario, devuelve false. Se utilizan up_direction y floor_max_angle para determinar si una superficie es «techo» o no.
bool is_on_ceiling_only() const 🔗
Devuelve true si el cuerpo colisionó solo con el techo en la última llamada de move_and_slide(). De lo contrario, devuelve false. Se utilizan up_direction y floor_max_angle para determinar si una superficie es «techo» o no.
Devuelve true si el cuerpo colisionó con el suelo en la última llamada de move_and_slide(). De lo contrario, devuelve false. Se utilizan up_direction y floor_max_angle para determinar si una superficie es «suelo» o no.
bool is_on_floor_only() const 🔗
Devuelve true si el cuerpo colisionó solo con el suelo en la última llamada de move_and_slide(). De lo contrario, devuelve false. Se utilizan up_direction y floor_max_angle para determinar si una superficie es «suelo» o no.
Devuelve true si el cuerpo colisionó con una pared en la última llamada de move_and_slide(). De lo contrario, devuelve false. Se utilizan up_direction y floor_max_angle para determinar si una superficie es «pared» o no.
bool is_on_wall_only() const 🔗
Devuelve true si el cuerpo colisionó solo con una pared en la última llamada de move_and_slide(). De lo contrario, devuelve false. Se utilizan up_direction y floor_max_angle para determinar si una superficie es «pared» o no.
Mueve el cuerpo basándose en velocity. Si el cuerpo colisiona con otro, se deslizará a lo largo del otro cuerpo en lugar de detenerse inmediatamente. Si el otro cuerpo es un CharacterBody3D o un RigidBody3D, también se verá afectado por el movimiento del otro cuerpo. Puedes usar esto para crear plataformas móviles y rotatorias, o para hacer que los nodos empujen a otros nodos.
Este método debe utilizarse en Node._physics_process() (o en un método llamado por Node._physics_process()), ya que utiliza automáticamente el valor delta del paso de física en los cálculos. De lo contrario, la simulación se ejecutará a una velocidad incorrecta.
Modifica velocity si ocurrió una colisión con deslizamiento. Para obtener la colisión más reciente, llama a get_last_slide_collision(). Para obtener información más detallada sobre las colisiones ocurridas, utiliza get_slide_collision().
Cuando el cuerpo toca una plataforma móvil, la velocidad de la plataforma se añade automáticamente al movimiento del cuerpo. Si ocurre una colisión debido al movimiento de la plataforma, esta será siempre la primera en las colisiones por deslizamiento.
Devuelve true si el cuerpo colisionó; de lo contrario, devuelve false.