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

繼承： PhysicsBody3D < CollisionObject3D < Node3D < Node < Object

專門用於通過腳本移動的角色的 3D 物理物體。

說明

CharacterBody3D 是針對使用者控制的物理體的特化類。它們不會受到物理的影響，但會影響路徑上的其他物理體。除了由 PhysicsBody3D.move_and_collide() 提供的常見的碰撞偵測之外，它們主要用於提供移動對象的高階 API，能夠偵測牆壁和斜坡（move_and_slide() 方法）。因此適用於需要高度可配置的物理體，因為通常是使用者控制的角色，所以必須按照特定的方式移動、與世界發生碰撞。

如果是移動平臺等不需要複雜移動和碰撞偵測的遊戲物件，AnimatableBody3D 更方便配置。

教學

屬性

bool

floor_block_on_wall

true

bool

floor_constant_speed

false

float

floor_max_angle

0.7853982

float

floor_snap_length

0.1

bool

floor_stop_on_slope

true

int

max_slides

6

MotionMode

motion_mode

0

int

platform_floor_layers

4294967295

PlatformOnLeave

platform_on_leave

0

int

platform_wall_layers

0

float

safe_margin

0.001

bool

slide_on_ceiling

true

Vector3

up_direction

Vector3(0, 1, 0)

Vector3

velocity

Vector3(0, 0, 0)

float

wall_min_slide_angle

0.2617994

方法

void

apply_floor_snap()

float

get_floor_angle(up_direction: Vector3 = Vector3(0, 1, 0)) const

Vector3

get_floor_normal() const

Vector3

get_last_motion() const

KinematicCollision3D

get_last_slide_collision()

Vector3

get_platform_angular_velocity() const

Vector3

get_platform_velocity() const

Vector3

get_position_delta() const

Vector3

get_real_velocity() const

KinematicCollision3D

get_slide_collision(slide_idx: int)

int

get_slide_collision_count() const

Vector3

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 = 0.1 🔗

  • 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 = 6 🔗

  • void set_max_slides(value: int)

  • int get_max_slides()

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 🔗

Sets the motion mode which defines the behavior of move_and_slide().

int platform_floor_layers = 4294967295 🔗

  • void set_platform_floor_layers(value: int)

  • int get_platform_floor_layers()

用於偵測地板物體的碰撞層，該地板物體會被用作 CharacterBody3D 所要跟隨的移動平臺。預設情況下會偵測所有地板物體並傳播其速度。

PlatformOnLeave platform_on_leave = 0 🔗

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 🔗

  • void set_platform_wall_layers(value: int)

  • int get_platform_wall_layers()

用於偵測牆壁物體的碰撞層，該牆壁物體會被用作 CharacterBody3D 所要跟隨的移動平臺。預設情況下會忽略所有牆壁物體。

float safe_margin = 0.001 🔗

  • 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，則會停止並垂直下落。

Vector3 up_direction = Vector3(0, 1, 0) 🔗

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 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 MOTION_MODE_FLOATING as motion_mode.

Vector3 velocity = Vector3(0, 0, 0) 🔗

Current velocity vector (typically meters per second), used and modified during calls to move_and_slide().

Note: A common mistake is setting this property to the desired velocity multiplied by delta, which produces a motion vector (typically in meters).

float wall_min_slide_angle = 0.2617994 🔗

  • void set_wall_min_slide_angle(value: float)

  • float get_wall_min_slide_angle()

Minimum angle (in radians) where the body is allowed to slide when it encounters a wall. The default value equals 15 degrees. When motion_mode is MOTION_MODE_GROUNDED, it only affects movement if floor_block_on_wall is true.

方法說明

void apply_floor_snap() 🔗

允許手動套用向地板的吸附，無論該物體的速度多大。is_on_floor() 返回 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 🔗

Returns the collision normal of the floor at the last collision point. Only valid after calling move_and_slide() and when is_on_floor() returns true.

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

Vector3 get_last_motion() const 🔗

返回最近一次呼叫 move_and_slide() 時施加給該 CharacterBody3D 的最後一次運動。如果發生了滑動，則該移動可以拆分為多次運動，此方法返回的是最後一次，可用於獲取目前的移動方向。

KinematicCollision3D get_last_slide_collision() 🔗

Returns a KinematicCollision3D if a collision occurred. The returned value contains information about the latest collision that occurred during the last call to move_and_slide(). Returns null if no collision occurred. See also get_slide_collision().

Vector3 get_platform_angular_velocity() const 🔗

返回位於最近一次碰撞點的平臺角速度。僅在呼叫 move_and_slide() 後有效。

Vector3 get_platform_velocity() const 🔗

返回位於最近一次碰撞點的平臺線速度。僅在呼叫 move_and_slide() 後有效。

Vector3 get_position_delta() const 🔗

返回最近一次呼叫 move_and_slide() 所產生的運動（位置差異量）。

Vector3 get_real_velocity() const 🔗

返回最近一次呼叫 move_and_slide() 之後的目前真實速度。例如，即便速度為水平方向，爬坡時你也會斜向移動。此方法返回的就是那個斜向移動，與返回請求速度的 velocity 相對。

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 🔗

返回最近一次呼叫 move_and_slide() 時，該物體發生碰撞並改變方向的次數。

Vector3 get_wall_normal() const 🔗

Returns the collision normal of the wall at the last collision point. Only valid after calling move_and_slide() and when is_on_wall() returns true.

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

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() 🔗

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.

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 more 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.

Returns true if the body collided, otherwise, returns false.