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

Тривимірне фізичне тіло, спеціалізоване для персонажів, які переміщуються за сценарієм.

Опис

CharacterBody3D — це спеціалізований клас для фізичних тіл, які призначені для керування користувачем. На них зовсім не впливає фізика, але вони впливають на інші фізичні тіла на своєму шляху. Вони в основному використовуються для забезпечення API високого рівня для переміщення об’єктів із виявленням стін і схилів (методи move_and_slide()) на додаток до загального виявлення зіткнень, що забезпечується PhysicsBody3D.move_and_collide(). Це робить його корисним для фізичних тіл із широким набором конфігурацій, які мають рухатися певним чином і стикатися зі світом, як це часто буває з персонажами, керованими користувачем.

Для ігрових об’єктів, які не потребують складного виявлення руху чи зіткнення, наприклад рухомих платформ, 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 🔗

void set_motion_mode(value: MotionMode)
MotionMode get_motion_mode()

Встановлює режим руху, який визначає поведінку 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 🔗

void set_platform_on_leave(value: PlatformOnLeave)
PlatformOnLeave get_platform_on_leave()

Встановлює поведінку, яка застосовуватиметься, коли ви залишаєте рухому платформу. За замовчуванням, для фізичної точності, при відході від останньої платформи застосовується швидкість.

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

void set_up_direction(value: Vector3)
Vector3 get_up_direction()

Вектор, спрямований вгору, використовується для визначення того, що є стіною, а що — підлогою (або стелею) під час виклику move_and_slide(). За замовчуванням Vector3.UP. Оскільки вектор буде нормалізовано, він не може дорівнювати Vector3.ZERO, якщо ви хочете, щоб усі зіткнення повідомлялися як стіни, розгляньте можливість використання MOTION_MODE_FLOATING як motion_mode.

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

void set_velocity(value: Vector3)
Vector3 get_velocity()

Поточний вектор швидкості (зазвичай метри за секунду), який використовується та змінюється під час викликів move_and_slide().

Примітка: Поширеною помилкою є встановлення для цієї властивості значення бажаної швидкості, помноженої на дельта, що створює вектор руху (зазвичай у метрах).

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 🔗

Повертає останній рух, застосований до CharacterBody3D під час останнього виклику move_and_slide(). Рух можна розділити на кілька рухів, коли відбувається ковзання, і цей метод повертає останній, що корисно для отримання поточного напрямку руху.

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 🔗

Повертає true, якщо тіло зіткнулося зі стелею під час останнього виклику move_and_slide(). В іншому випадку повертає false. up_direction і floor_max_angle використовуються для визначення того, чи є поверхня «стелею» чи ні.

bool is_on_ceiling_only() const 🔗

Повертає true, якщо тіло зіткнулося лише зі стелею під час останнього виклику move_and_slide(). В іншому випадку повертає false. up_direction і floor_max_angle використовуються для визначення того, чи є поверхня «стелею» чи ні.

bool is_on_floor() const 🔗

Повертає true, якщо тіло зіткнулося з підлогою під час останнього виклику move_and_slide(). В іншому випадку повертає false. up_direction і floor_max_angle використовуються для визначення того, чи є поверхня «підлогою» чи ні.

bool is_on_floor_only() const 🔗

Повертає true, якщо тіло зіткнулося лише з підлогою під час останнього виклику move_and_slide(). В іншому випадку повертає false. up_direction і floor_max_angle використовуються для визначення того, чи є поверхня «підлогою» чи ні.

bool is_on_wall() const 🔗

Повертає true, якщо тіло зіткнулося зі стіною під час останнього виклику move_and_slide(). В іншому випадку повертає false. up_direction і floor_max_angle використовуються для визначення того, чи є поверхня «стіною» чи ні.

bool is_on_wall_only() const 🔗

Повертає true, якщо тіло зіткнулося лише зі стіною під час останнього виклику move_and_slide(). В іншому випадку повертає false. up_direction і floor_max_angle використовуються для визначення того, чи є поверхня «стіною» чи ні.

bool move_and_slide() 🔗

Переміщує тіло на основі velocity. Якщо тіло зіштовхується з іншим, воно буде ковзати по іншому тілу, а не зупинятися відразу. Якщо інше тіло є CharacterBody3D або RigidBody3D, воно також буде піддаватися впливу руху іншого тіла. Ви можете використовувати це для створення рухомих і обертових платформ або для того, щоб вузли штовхали інші вузли.

Цей метод слід використовувати в Node._physics_process() (або в методі, що викликається Node._physics_process()), оскільки він автоматично використовує значення delta фізичного кроку в обчисленнях. В іншому випадку симуляція буде працювати з неправильною швидкістю.

Змінює velocity, якщо відбулося зіткнення ковзання. Щоб отримати останнє зіткнення, викличте get_last_slide_collision(), для більш детальної інформації про зіткнення, що відбулися, використовуйте get_slide_collision().

Коли тіло торкається рухомої платформи, швидкість платформи автоматично додається до руху тіла. Якщо зіткнення відбувається через рух платформи, воно завжди буде першим у зіткненнях ковзання.

Повертає true, якщо тіло зіткнулося, інакше повертає false.