CharacterBody2D

继承： PhysicsBody2D < CollisionObject2D < Node2D < CanvasItem < Node < Object

专门用于通过脚本移动的角色的 2D 物理物体。

描述

CharacterBody2D 是针对用户控制的物理体的特化类。它们不会受到物理的影响，但会影响路径上的其他物理体。除了由 PhysicsBody2D.move_and_collide() 提供的常见的碰撞检测之外，它们主要用于提供移动对象的高阶 API，能够检测墙壁和斜坡（move_and_slide() 方法）。因此适用于需要高度可配置的物理体，因为通常是用户控制的角色，所以必须按照特定的方式移动、与世界发生碰撞。

如果是移动平台等不需要复杂移动和碰撞检测的游戏对象，AnimatableBody2D 更方便配置。

教程

属性

bool

floor_block_on_wall

true

bool

floor_constant_speed

false

float

floor_max_angle

0.7853982

float

floor_snap_length

1.0

bool

floor_stop_on_slope

true

int

max_slides

4

MotionMode

motion_mode

0

int

platform_floor_layers

4294967295

PlatformOnLeave

platform_on_leave

0

int

platform_wall_layers

0

float

safe_margin

0.08

bool

slide_on_ceiling

true

Vector2

up_direction

Vector2(0, -1)

Vector2

velocity

Vector2(0, 0)

float

wall_min_slide_angle

0.2617994

方法

void

apply_floor_snap()

float

get_floor_angle(up_direction: Vector2 = Vector2(0, -1)) const

Vector2

get_floor_normal() const

Vector2

get_last_motion() const

KinematicCollision2D

get_last_slide_collision()

Vector2

get_platform_velocity() const

Vector2

get_position_delta() const

Vector2

get_real_velocity() const

KinematicCollision2D

get_slide_collision(slide_idx: int)

int

get_slide_collision_count() const

Vector2

get_wall_normal() const

bool

is_on_ceiling() const

bool

is_on_ceiling_only() const

bool

is_on_floor() const

bool

is_on_floor_only() const

bool

is_on_wall() const

bool

is_on_wall_only() const

bool

move_and_slide()

枚举

enum MotionMode: 🔗

MotionMode MOTION_MODE_GROUNDED = 0

请在墙壁、天花板、地板等概念有意义时应用。在该模式下，物体运动会对斜坡作出反应（加减速）。该模式适合平台跳跃等侧视角游戏。

MotionMode MOTION_MODE_FLOATING = 1

请在没有地板和天花板等概念时应用。所有碰撞都会作为 on_wall（撞墙）汇报。在该模式下，滑动时的速度恒定。该模式适合俯视角游戏。

enum PlatformOnLeave: 🔗

PlatformOnLeave PLATFORM_ON_LEAVE_ADD_VELOCITY = 0

离开移动平台时，将最后的平台速度添加到 velocity 中。

PlatformOnLeave PLATFORM_ON_LEAVE_ADD_UPWARD_VELOCITY = 1

离开移动平台时，将最后的平台速度添加到 velocity 中，但是忽略向下的运动。如果想要在平台向下移动时保持完整的跳跃高度，就非常有用。

PlatformOnLeave PLATFORM_ON_LEAVE_DO_NOTHING = 2

离开平台时什么也不做。

属性说明

bool floor_block_on_wall = true 🔗

  • void set_floor_block_on_wall_enabled(value: bool)

  • bool is_floor_block_on_wall_enabled()

如果为 true，则该物体将只能在地板上移动。此选项能够避免在墙壁上行走，但允许沿墙壁向下滑动。

bool floor_constant_speed = false 🔗

  • void set_floor_constant_speed_enabled(value: bool)

  • bool is_floor_constant_speed_enabled()

如果为 false（默认），则该物体在下坡时会移动得更快，在上坡时会移动得更慢。

如果为 true，则无论坡度如何，该物体在地面上都会以相同的速度移动。请注意，你需要使用 floor_snap_length 以恒定速度粘着至向下的斜坡。

float floor_max_angle = 0.7853982 🔗

  • void set_floor_max_angle(value: float)

  • float get_floor_max_angle()

调用 move_and_slide() 时，斜坡仍被视为地板（或天花板）而不是墙壁的最大角度（单位为弧度）。默认值等于 45 度。

float floor_snap_length = 1.0 🔗

  • void set_floor_snap_length(value: float)

  • float get_floor_snap_length()

设置吸附距离。设为非 0.0 值时，该物体在调用 move_and_slide() 时会保持附着到斜坡上。吸附向量会根据给定的距离和 up_direction 反方向决定。

只要吸附向量与地面有接触，该物体就会逆 up_direction 移动，保持附着到表面。如果该物体是沿着 up_direction 移动的，则不会应用吸附，这样跳跃时或者被其他物体推动时就能够不再附着地面。如果想要在应用吸附时无视速度，请使用 apply_floor_snap()。

bool floor_stop_on_slope = true 🔗

  • void set_floor_stop_on_slope_enabled(value: bool)

  • bool is_floor_stop_on_slope_enabled()

如果为 true，则该物体静止时，调用 move_and_slide() 不会让它在斜坡上发生滑动。

如果为 false，则 velocity 施加向下的力时，该物体会在地板的斜坡上发生滑动。

int max_slides = 4 🔗

  • void set_max_slides(value: int)

  • int get_max_slides()

调用 move_and_slide() 时，物体在停止之前可以改变方向的最大次数。必须大于零。

MotionMode motion_mode = 0 🔗

设置运动模式，定义 move_and_slide() 的行为。

int platform_floor_layers = 4294967295 🔗

  • void set_platform_floor_layers(value: int)

  • int get_platform_floor_layers()

用于检测地板物体的碰撞层，该地板物体会被用作 CharacterBody2D 所要跟随的移动平台。默认情况下会检测所有地板物体并传播其速度。

PlatformOnLeave platform_on_leave = 0 🔗

设置离开移动平台时要应用的行为。为了达到物理准确，默认会应用你离开时最后的平台速度。

int platform_wall_layers = 0 🔗

  • void set_platform_wall_layers(value: int)

  • int get_platform_wall_layers()

用于检测墙壁物体的碰撞层，该墙壁物体会被用作 CharacterBody2D 所要跟随的移动平台。默认情况下会忽略所有墙壁物体。

float safe_margin = 0.08 🔗

  • void set_safe_margin(value: float)

  • float get_safe_margin()

额外边距，用于在调用 move_and_slide() 时进行碰撞恢复。

如果该物体与另一个物体至少有这么近，就会认为它们正在碰撞，并在执行实际运动前推开。

值较高时，对碰撞的检测会更加灵活，有助于持续检测墙壁和地板。

值较低时，会强制碰撞算法进行更精确的检测，因此可以在特别需要精度的情况下使用，例如在非常低的缩放下避免可见的抖动，或者为了让一堆角色物体的达到稳定。

bool slide_on_ceiling = true 🔗

  • void set_slide_on_ceiling_enabled(value: bool)

  • bool is_slide_on_ceiling_enabled()

如果为 true，则该物体在跳到天花板时会滑动；如果为 false，则会停止并垂直下落。

Vector2 up_direction = Vector2(0, -1) 🔗

指向上方的向量，用于在调用 move_and_slide() 时决定什么是墙壁、什么是地板（或者天花板）。默认为 Vector2.UP。因为会对该向量进行归一化，所以不能等于 Vector2.ZERO，如果你想要让所有碰撞都被报告为墙壁，请考虑使用 MOTION_MODE_FLOATING 作为 motion_mode。

Vector2 velocity = Vector2(0, 0) 🔗

当前的速度向量，单位为像素每秒。该属性会在调用 move_and_slide() 时被使用和修改。

注意：一个常见的错误是将此属性设置为期望速度乘以 delta。这得到的是一个以像素为单位的移动向量。

float wall_min_slide_angle = 0.2617994 🔗

  • void set_wall_min_slide_angle(value: float)

  • float get_wall_min_slide_angle()

物体遇到墙面时允许发生滑动的最小角度（单位为弧度）。默认值等于 15 度。只有在 motion_mode 为 MOTION_MODE_FLOATING 时该属性才会影响运动。

方法说明

void apply_floor_snap() 🔗

允许手动应用向地板的吸附，无论该物体的速度多大。is_on_floor() 返回 true 时这个函数什么都不做。

float get_floor_angle(up_direction: Vector2 = Vector2(0, -1)) const 🔗

返回地板在最近一次碰撞点的碰撞角度，依据为 up_direction，默认为 Vector2.UP。该值始终为正数，只有在调用了 move_and_slide() 并且 is_on_floor() 返回值为 true 时才有效。

Vector2 get_floor_normal() const 🔗

返回最近一次碰撞点的地面法线。只有在调用了 move_and_slide() 并且 is_on_floor() 返回值为 true 时才有效。

警告：碰撞法线并不总是与表面法线相同。

Vector2 get_last_motion() const 🔗

返回最近一次调用 move_and_slide() 时施加给该 CharacterBody2D 的最后一次运动。如果发生了滑动，则该移动可以拆分为多次运动，此方法返回的是最后一次，可用于获取当前的移动方向。

KinematicCollision2D get_last_slide_collision() 🔗

如发生碰撞则返回一个 KinematicCollision2D。返回值包含了最近一次调用 move_and_slide() 期间发生的最后一次碰撞的信息。若无碰撞发生，则返回 null。另见 get_slide_collision()。

Vector2 get_platform_velocity() const 🔗

返回位于最近一次碰撞点的平台线速度。仅在调用 move_and_slide() 后有效。

Vector2 get_position_delta() const 🔗

返回最近一次调用 move_and_slide() 所产生的运动（位置增量）。

Vector2 get_real_velocity() const 🔗

返回最近一次调用 move_and_slide() 之后的当前真实速度。例如，即便速度为水平方向，爬坡时你也会斜向移动。此方法返回的就是那个斜向移动，与返回请求速度的 velocity 相对。

KinematicCollision2D get_slide_collision(slide_idx: int) 🔗

Returns a KinematicCollision2D, 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().

Example: Iterate through the collisions with a for loop:

for i in get_slide_collision_count():
    var collision = get_slide_collision(i)
    print("Collided with: ", collision.get_collider().name)

int get_slide_collision_count() const 🔗

返回最近一次调用 move_and_slide() 时，该物体发生碰撞并改变方向的次数。

Vector2 get_wall_normal() const 🔗

返回最近一次碰撞点的墙面法线。只有在调用了 move_and_slide() 并且 is_on_wall() 返回值为 true 时才有效。

警告：碰撞法线并不总是与表面法线相同。

bool is_on_ceiling() const 🔗

如果最近一次调用 move_and_slide() 时，该物体和天花板发生了碰撞，则返回 true。否则返回 false。决定表面是否为“天花板”的是 up_direction 和 floor_max_angle。

bool is_on_ceiling_only() const 🔗

如果最近一次调用 move_and_slide() 时，该物体仅和天花板发生了碰撞，则返回 true。否则返回 false。决定表面是否为“天花板”的是 up_direction 和 floor_max_angle。

bool is_on_floor() const 🔗

如果最近一次调用 move_and_slide() 时，该物体和地板发生了碰撞，则返回 true。否则返回 false。决定表面是否为“地板”的是 up_direction 和 floor_max_angle。

bool is_on_floor_only() const 🔗

如果最近一次调用 move_and_slide() 时，该物体仅和地板发生了碰撞，则返回 true。否则返回 false。决定表面是否为“地板”的是 up_direction 和 floor_max_angle。

bool is_on_wall() const 🔗

如果最近一次调用 move_and_slide() 时，该物体和墙壁发生了碰撞，则返回 true。否则返回 false。决定表面是否为“墙壁”的是 up_direction 和 floor_max_angle。

bool is_on_wall_only() const 🔗

如果最近一次调用 move_and_slide() 时，该物体仅和墙壁发生了碰撞，则返回 true。否则返回 false。决定表面是否为“墙壁”的是 up_direction 和 floor_max_angle。

bool move_and_slide() 🔗

根据 velocity 移动该物体。该物体如果与其他物体发生碰撞，则会沿着对方滑动（默认只在地板上滑动），不会立即停止移动。如果对方是 CharacterBody2D 或 RigidBody2D，还会受到对方运动的影响。可以用于制作移动、旋转的平台，也可用于推动其他节点。

该方法在计算时会自动使用物理步骤的 delta，所以应当在 Node._physics_process()（或 Node._physics_process() 中调用的方法）中使用。否则运行仿真会使用错误的速度。

发生滑动碰撞时会改变 velocity。要获取最后一次碰撞，请调用 get_last_slide_collision()，要获取碰撞的更多信息，请使用 get_slide_collision()。

该物体接触到移动平台时，平台的速度会自动加入到该物体的运动中。平台运动所造成的碰撞始终为所有滑动碰撞中的第一个。

通用行为和可用属性会根据 motion_mode 发生改变。

如果该物体发生了碰撞，则返回 true，否则返回 false。