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.

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

呼叫 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()

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


PlatformOnLeave platform_on_leave = 0 🔗

設定離開移動平台時要應用的行為。為了達到物理準確,預設會應用你離開時最後的平台速度。


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

指向上方的向量,用於在呼叫 move_and_slide() 時決定甚麼是牆壁、甚麼是地板(或者天花板)。預設為 Vector3.UP。因為會對該向量進行正規化,所以不能等於 Vector3.ZERO,如果你想要讓所有碰撞都被報告為牆壁,請考慮使用 MOTION_MODE_FLOATING 作為 motion_mode。


Vector3 velocity = Vector3(0, 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_GROUNDED 時,只有 floor_block_on_wall 為 true 才會影響運動。


方法說明

void apply_floor_snap() 🔗

允許手動套用向地板的吸附,無論該物體的速度多大。is_on_floor() 返回 true 時這個函式什麼都不做。


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

回傳地板在最近一次碰撞點的碰撞角度,依據為 up_direction,預設為 Vector3.UP。該值始終為正數,只有在呼叫了 move_and_slide() 並且 is_on_floor() 回傳值為 true 時才有效。


Vector3 get_floor_normal() const 🔗

回傳最近一次碰撞點的地面法線。只有在呼叫了 move_and_slide() 並且 is_on_floor() 回傳值為 true 時才有效。

警告:碰撞法線並不總是與表面法線相同。


Vector3 get_last_motion() const 🔗

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


KinematicCollision3D get_last_slide_collision() 🔗

如發生碰撞則回傳一個 KinematicCollision3D。回傳值包含了最近一次呼叫 move_and_slide() 期間發生的最後一次碰撞的資訊。若無碰撞發生,則回傳 null。另見 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) 🔗

回傳 KinematicCollision3D,包含最近一次呼叫 move_and_slide() 時發生的碰撞資訊。因為單次呼叫 move_and_slide() 可能發生多次碰撞,所以你必須指定碰撞索引,範圍為 0 到 (get_slide_collision_count() - 1)。另見 get_last_slide_collision()。


int get_slide_collision_count() const 🔗

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


Vector3 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 移動該物體。該物體如果與其他物體發生碰撞,則會沿著對方滑動,不會立即停止移動。如果對方是 CharacterBody3D 或 RigidBody3D,還會受到對方運動的影響。可以用於製作移動、旋轉的平台,也可用於推動其他節點。

該方法在計算時會自動使用物理步驟的 delta,所以應當在 Node._physics_process()(或 Node._physics_process() 中呼叫的方法)中使用。否則執行仿真會使用錯誤的速度。

發生滑動碰撞時會改變 velocity。要取得最後一次碰撞,請呼叫 get_last_slide_collision(),要取得碰撞的更多資訊,請使用 get_slide_collision()。

該物體接觸到移動平台時,平台的速度會自動加入到該物體的運動中。平台運動所造成的碰撞始終為所有滑動碰撞中的第一個。

如果該物體發生了碰撞,則回傳 true,否則回傳 false。