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

Примечание: Распространенная ошибка — установка этого свойства равным желаемой скорости, умноженной на 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 🔗

Возвращает последнее движение, примененное к 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. Member up_direction и floor_max_angle используются для определения того, является ли поверхность «стеной» или нет.

bool is_on_wall_only() const 🔗

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

bool move_and_slide() 🔗

Перемещает тело на основе speed. При столкновении с другим телом оно будет скользить вдоль другого тела, а не останавливаться немедленно. В случие других тел — CharacterBody3D или RigidBody3D, оно также будет подвержено влиянию движения другого тела. Это можно использовать для создания движущихся и вращающихся платформ, а также для того, чтобы узлы толкали другие узлы.

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

Изменяет velocity, если произошло скользящее столкновение. Чтобы получить последнее столкновение, вызовите get_last_slide_collision(). Для получения более подробной информации о произошедших столкновениях используйте get_slide_collision().

При касании телом движущейся платформы скорость платформы автоматически добавляется к движению тела. Если столкновение происходит из-за движения платформы, оно всегда будет первым в списке столкновений при скольжении.

Возвращает true, если тело столкнулось, в противном случае возвращает false.