Node3D

Наследует: Node < Object

Наследуется от: AudioListener3D, AudioStreamPlayer3D, BoneAttachment3D, Camera3D, CollisionObject3D, CollisionPolygon3D, CollisionShape3D, GridMap, ImporterMeshInstance3D, Joint3D, LightmapProbe, Marker3D, NavigationLink3D, NavigationObstacle3D, NavigationRegion3D, OpenXRCompositionLayer, OpenXRHand, OpenXRRenderModel, OpenXRRenderModelManager, Path3D, PathFollow3D, RayCast3D, RemoteTransform3D, ShapeCast3D, Skeleton3D, SkeletonModifier3D, SpringArm3D, SpringBoneCollision3D, VehicleWheel3D, VisualInstance3D, XRFaceModifier3D, XRNode3D, XROrigin3D

Базовый объект в трехмерном пространстве, наследуемый всеми трехмерными узлами.

Описание

Узел Node3D является базовым представлением узла в трехмерном пространстве. Все остальные трехмерные узлы наследуются от этого класса.

Аффинные операции (перемещение, вращение, масштабирование) вычисляются в системе координат относительно родительского узла, если только top_level Node3D не равен true. В этой системе координат аффинные операции соответствуют прямым аффинным операциям над transform Node3D. Термин родительское пространство относится к этой системе координат. Система координат, прикрепленная к самому Node3D, называется локальной системой координат объекта или локальным пространством.

Примечание: Если не указано иное, все методы, которым требуются параметры угла, должны получать углы в радианах. Чтобы преобразовать градусы в радианы, используйте @GlobalScope.deg_to_rad().

Примечание: В Godot 3 и более ранних версиях Node3D назывался Spatial.

Обучающие материалы

Свойства

Basis	basis
Basis	global_basis
Vector3	global_position
Vector3	global_rotation
Vector3	global_rotation_degrees
Transform3D	global_transform
Vector3	position	`Vector3(0, 0, 0)`
Quaternion	quaternion
Vector3	rotation	`Vector3(0, 0, 0)`
Vector3	rotation_degrees
RotationEditMode	rotation_edit_mode	`0`
EulerOrder	rotation_order	`2`
Vector3	scale	`Vector3(1, 1, 1)`
bool	top_level	`false`
Transform3D	transform	`Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0)`
NodePath	visibility_parent	`NodePath("")`
bool	visible	`true`

Методы

void	add_gizmo(gizmo: Node3DGizmo)
void	clear_gizmos()
void	clear_subgizmo_selection()
void	force_update_transform()
Array[Node3DGizmo]	get_gizmos() const
Transform3D	get_global_transform_interpolated()
Node3D	get_parent_node_3d() const
World3D	get_world_3d() const
void	global_rotate(axis: Vector3, angle: float)
void	global_scale(scale: Vector3)
void	global_translate(offset: Vector3)
void	hide()
bool	is_local_transform_notification_enabled() const
bool	is_scale_disabled() const
bool	is_transform_notification_enabled() const
bool	is_visible_in_tree() const
void	look_at(target: Vector3, up: Vector3 = Vector3(0, 1, 0), use_model_front: bool = false)
void	look_at_from_position(position: Vector3, target: Vector3, up: Vector3 = Vector3(0, 1, 0), use_model_front: bool = false)
void	orthonormalize()
void	rotate(axis: Vector3, angle: float)
void	rotate_object_local(axis: Vector3, angle: float)
void	rotate_x(angle: float)
void	rotate_y(angle: float)
void	rotate_z(angle: float)
void	scale_object_local(scale: Vector3)
void	set_disable_scale(disable: bool)
void	set_identity()
void	set_ignore_transform_notification(enabled: bool)
void	set_notify_local_transform(enable: bool)
void	set_notify_transform(enable: bool)
void	set_subgizmo_selection(gizmo: Node3DGizmo, id: int, transform: Transform3D)
void	show()
Vector3	to_global(local_point: Vector3) const
Vector3	to_local(global_point: Vector3) const
void	translate(offset: Vector3)
void	translate_object_local(offset: Vector3)
void	update_gizmos()

Сигналы

visibility_changed() 🔗

Выдается при изменении видимости этого узла (см. visible и is_visible_in_tree()).

Этот сигнал выдается после связанного NOTIFICATION_VISIBILITY_CHANGED уведомления.

Перечисления

enum RotationEditMode: 🔗

RotationEditMode ROTATION_EDIT_MODE_EULER = 0

Вращение редактируется с помощью Vector3 в Углах Эйлера.

RotationEditMode ROTATION_EDIT_MODE_QUATERNION = 1

Вращение редактируется с помощью Quaternion.

RotationEditMode ROTATION_EDIT_MODE_BASIS = 2

Вращение редактируется с использованием Basis. В этом режиме оси необработанного basis могут быть свободно изменены, но свойство scale недоступно.

Константы

NOTIFICATION_TRANSFORM_CHANGED = 2000 🔗

Уведомление получено, когда global_transform этого узла изменяется, если is_transform_notification_enabled() имеет значение true. См. также set_notify_transform().

Примечание: Большинство 3D-узлов, таких как VisualInstance3D или CollisionObject3D, автоматически включают это для корректной работы.

Примечание: В редакторе узлы будут распространять это уведомление своим дочерним элементам, если присоединен гизмо (см. add_gizmo()).

NOTIFICATION_ENTER_WORLD = 41 🔗

Уведомление получено, когда этот узел зарегистрирован в новом World3D (см. get_world_3d()).

NOTIFICATION_EXIT_WORLD = 42 🔗

Уведомление получено, когда этот узел удаляется из текущего World3D (см. get_world_3d()).

Это уведомление отправляется в обратном порядке.

NOTIFICATION_VISIBILITY_CHANGED = 43 🔗

Уведомление получено, когда видимость этого узла изменяется (см. visible и is_visible_in_tree()).

Это уведомление получено до связанного сигнала visibility_changed.

NOTIFICATION_LOCAL_TRANSFORM_CHANGED = 44 🔗

Уведомление получено, когда изменяется transform этого узла, если is_local_transform_notification_enabled() равно true. Это не получено, когда изменяется transform родительского Node3D. См. также set_notify_local_transform().

Примечание: Некоторые 3D-узлы, такие как CSGShape3D или CollisionShape3D, автоматически включают это для правильной работы.

Описания свойств

Basis basis 🔗

void set_basis(value: Basis)
Basis get_basis()

Базис свойства transform. Представляет поворот, масштаб и сдвиг этого узла в родительском пространстве (относительно родительского узла).

Basis global_basis 🔗

void set_global_basis(value: Basis)
Basis get_global_basis()

Базис свойства global_transform. Представляет поворот, масштаб и сдвиг этого узла в глобальном пространстве (относительно мира).

Примечание: Если узел не находится внутри дерева, получение этого свойства завершается неудачей и возвращается Basis.IDENTITY.

Vector3 global_position 🔗

void set_global_position(value: Vector3)
Vector3 get_global_position()

Глобальное положение (перемещение) этого узла в глобальном пространстве (относительно мира). Это эквивалентно global_transform и Transform3D.origin.

Примечание: Если узел не находится внутри дерева, получение этого свойства завершается неудачей и возвращается Vector3.ZERO.

Vector3 global_rotation 🔗

void set_global_rotation(value: Vector3)
Vector3 get_global_rotation()

Глобальное вращение этого узла как углы Эйлера, в радианах и в глобальном пространстве (относительно мира). Это значение получается из вращения global_basis.

Vector3.x — это угол вокруг глобальной оси X (pitch);
Vector3.y — это угол вокруг глобальной оси Y (yaw);
Vector3.z — это угол вокруг глобальной оси Z (roll).

Примечание: В отличие от rotation, это свойство всегда следует соглашению YXZ (@GlobalScope.EULER_ORDER_YXZ).

Примечание: Если узел не находится внутри дерева, получение этого свойства завершается ошибкой и возвращается Vector3.ZERO.

Vector3 global_rotation_degrees 🔗

void set_global_rotation_degrees(value: Vector3)
Vector3 get_global_rotation_degrees()

global_rotation этого узла в градусах вместо радиан.

Примечание: Если узел не находится внутри дерева, получение этого свойства завершается неудачей и возвращается Vector3.ZERO.

Transform3D global_transform 🔗

void set_global_transform(value: Transform3D)
Transform3D get_global_transform()

Преобразование этого узла в глобальном пространстве (относительно мира). Содержит и представляет global_position, global_rotation и глобальный масштаб этого узла.

Примечание: Если узел не находится внутри дерева, получение этого свойства завершается неудачей и возвращается Transform3D.IDENTITY.

Vector3 position = Vector3(0, 0, 0) 🔗

void set_position(value: Vector3)
Vector3 get_position()

Положение (перемещение) этого узла в родительском пространстве (относительно родительского узла). Это эквивалентно transform Transform3D.origin.

Quaternion quaternion 🔗

void set_quaternion(value: Quaternion)
Quaternion get_quaternion()

Вращение этого узла, представленного как Quaternion в родительском пространстве (относительно родительского узла). Это значение получается из вращения basic.

Примечание: Кватернионы гораздо больше подходят для трехмерной математики, но менее интуитивны. Установка этого свойства может быть полезна для интерполяции (см. Quaternion.slerp()).

Vector3 rotation = Vector3(0, 0, 0) 🔗

void set_rotation(value: Vector3)
Vector3 get_rotation()

Вращение этого узла как углы Эйлера, в радианах и в родительском пространстве (относительно родительского узла). Это значение получается из вращения basic.

Vector3.x - это угол вокруг локальной оси X (тангаж);
Vector3.y - это угол вокруг локальной оси Y (рыскание);
Vector3.z - это угол вокруг локальной оси Z (крен).

Порядок каждого последовательного вращения можно изменить с помощью rotation_order (см. константы EulerOrder). По умолчанию используется соглашение YXZ (@GlobalScope.EULER_ORDER_YXZ).

Примечание: Это свойство редактируется в градусах в инспекторе. Если вы хотите использовать градусы в скрипте, используйте rotation_degrees.

Vector3 rotation_degrees 🔗

void set_rotation_degrees(value: Vector3)
Vector3 get_rotation_degrees()

rotation этого узла в градусах вместо радиан.

Примечание: Это не свойство, доступное во вкладке инспектора.

RotationEditMode rotation_edit_mode = 0 🔗

void set_rotation_edit_mode(value: RotationEditMode)
RotationEditMode get_rotation_edit_mode()

Как поворот и масштаб этого узла отображаются в доке инспектора.

EulerOrder rotation_order = 2 🔗

void set_rotation_order(value: EulerOrder)
EulerOrder get_rotation_order()

Порядок вращения осей свойства rotation. Окончательная ориентация вычисляется путем вращения вокруг локальных осей X, Y и Z в этом порядке.

Vector3 scale = Vector3(1, 1, 1) 🔗

void set_scale(value: Vector3)
Vector3 get_scale()

Масштаб этого узла в локальном пространстве (относительно этого узла). Это значение получается из масштаба basis.

Примечание: Поведение некоторых типов 3D-узлов не зависит от этого свойства. К ним относятся Light3D, Camera3D, AudioStreamPlayer3D и другие.

Предупреждение: Компоненты масштаба должны быть либо все положительными, либо все отрицательными и не точно 0.0. В противном случае будет невозможно получить масштаб из basis. Это может привести к потере предполагаемого масштаба при перезагрузке с диска и потенциально к другому нестабильному поведению.

bool top_level = false 🔗

void set_as_top_level(value: bool)
bool is_set_as_top_level()

Если true, узел не наследует свои преобразования от своего родителя. Таким образом, преобразования узлов будут только в глобальном пространстве, что также означает, что global_transform и transform будут идентичны.

Transform3D transform = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0) 🔗

void set_transform(value: Transform3D)
Transform3D get_transform()

Локальное преобразование этого узла в родительском пространстве (относительно родительского узла). Содержит и представляет position, rotation и scale этого узла.

NodePath visibility_parent = NodePath("") 🔗

void set_visibility_parent(value: NodePath)
NodePath get_visibility_parent()

Путь к родительскому узлу диапазона видимости для данного узла и его дочерних элементов. Родителем видимости должен быть GeometryInstance3D.

Любой визуальный экземпляр будет видимым только если его родитель видимости (и все вышестоящие элементы в иерархии видимости) скрыты из-за приближения к камере ближе, чем указано в GeometryInstance3D.visibility_range_begin. Узлы, скрытые через свойство visible, фактически исключаются из дерева зависимостей видимости, поэтому зависимые экземпляры не учитывают скрытый узел или его дочерние элементы.

bool visible = true 🔗

void set_visible(value: bool)
bool is_visible()

Если true, этот узел может быть видимым. Узел отображается только тогда, когда все его предки также видны. Это означает, что is_visible_in_tree() должен возвращать true.

Описания метода

void add_gizmo(gizmo: Node3DGizmo) 🔗

Прикрепляет заданный gizmo к этому узлу. Работает только в редакторе.

Примечание: gizmo должен быть EditorNode3DGizmo. Тип аргумента — Node3DGizmo, чтобы избежать зависимости от классов редактора в Node3D.

void clear_gizmos() 🔗

Очищает все объекты EditorNode3DGizmo, прикрепленные к этому узлу. Работает только в редакторе.

void clear_subgizmo_selection() 🔗

Отменяет выбор всех подэлементов для этого узла. Полезно вызывать, когда выбранный подэлемент может больше не существовать после изменения свойства. Работает только в редакторе.

void force_update_transform() 🔗

Заставляет обновить global_transform узла, отправляя NOTIFICATION_TRANSFORM_CHANGED. Не удается, если узел не находится внутри дерева.

Примечание: Из соображений производительности изменения преобразования обычно накапливаются и применяются один раз в конце кадра. Обновление также распространяется на дочерние элементы Node3D. Поэтому используйте этот метод только тогда, когда вам нужно актуальное преобразование (например, во время физических операций).

Array[Node3DGizmo] get_gizmos() const 🔗

Возвращает все объекты EditorNode3DGizmo, прикрепленные к этому узлу. Работает только в редакторе.

Transform3D get_global_transform_interpolated() 🔗

При использовании интерполяции физики могут возникнуть обстоятельства, в которых вам захочется узнать интерполированное (отображаемое) преобразование узла, а не стандартное преобразование (которое может быть точным только до последнего физического тика).

Это особенно важно для кадровых операций, которые выполняются в Node._process(), а не в Node._physics_process(). Примерами являются Camera3D-ы, фокусирующиеся на узле, или поиск места для стрельбы лазерами в кадре, а не в такте физики.

Примечание: Эта функция создает интерполяционный насос на Node3D при первом вызове, который может реагировать на сбросы интерполяции физики. Если у вас возникли проблемы с "полосами" при первоначальном следовании Node3D, обязательно вызовите get_global_transform_interpolated() хотя бы один раз перед сбросом интерполяции физики Node3D.

Node3D get_parent_node_3d() const 🔗

Возвращает родительский Node3D, который напрямую влияет на global_transform этого узла. Возвращает null, если родительского элемента не существует, родительский элемент не является Node3D или top_level равен true.

Примечание: Этот метод не всегда эквивалентен Node.get_parent(), который не учитывает top_level.

World3D get_world_3d() const 🔗

Возвращает World3D, в котором зарегистрирован этот узел.

Обычно это то же самое, что и мир, используемый областью просмотра этого узла (см. Node.get_viewport() и Viewport.find_world_3d()).

void global_rotate(axis: Vector3, angle: float) 🔗

Поворачивает global_basis этого узла вокруг глобальной axis на заданный angle, в радианах. Эта операция вычисляется в глобальном пространстве (относительно мира) и сохраняет global_position.

void global_scale(scale: Vector3) 🔗

Масштабирует global_basis этого узла на заданный коэффициент scale. Эта операция вычисляется в глобальном пространстве (относительно мира) и сохраняет global_position.

Примечание: Этот метод не следует путать со свойством scale.

void global_translate(offset: Vector3) 🔗

Добавляет заданное перемещение offset к global_position узла в глобальном пространстве (относительно мира).

void hide() 🔗

Предотвращает отображение этого узла. Эквивалентно установке visible в false. Это противоположно show().

bool is_local_transform_notification_enabled() const 🔗

Возвращает true, если узел получает NOTIFICATION_LOCAL_TRANSFORM_CHANGED всякий раз, когда изменяется transform. Это включается с помощью set_notify_local_transform().

bool is_scale_disabled() const 🔗

Возвращает true, если global_transform этого узла автоматически ортонормализован. Это приводит к тому, что этот узел не выглядит искаженным, как если бы его глобальный масштаб был установлен на Vector3.ONE (или его отрицательный аналог). См. также set_disable_scale() и orthonormalize().

Примечание: transform не затрагивается этой настройкой.

bool is_transform_notification_enabled() const 🔗

Возвращает true, если узел получает NOTIFICATION_TRANSFORM_CHANGED всякий раз, когда изменяется global_transform. Это включается с помощью set_notify_transform().

bool is_visible_in_tree() const 🔗

Возвращает true, если этот узел находится внутри дерева сцены и свойство visible равно true для этого узла и всех его предков Node3D в последовательности. Предок любого другого типа (например, Node или Node2D) нарушает последовательность. См. также Node.get_parent().

Примечание: Этот метод не может учитывать VisualInstance3D.layers, поэтому даже если этот метод возвращает true, узел может не быть отрисован.

void look_at(target: Vector3, up: Vector3 = Vector3(0, 1, 0), use_model_front: bool = false) 🔗

Поворачивает узел так, чтобы локальная прямая ось (-Z, Vector3.FORWARD) указывала на позицию target. Эта операция вычисляется в глобальном пространстве (относительно мира).

Локальная ось вверх (+Y) указывает как можно ближе к вектору up, оставаясь перпендикулярной локальной прямой оси. Результирующее преобразование ортогонально, и масштаб сохраняется. Неравномерное масштабирование может работать некорректно.

Позиция target не может совпадать с позицией узла, вектор up не может быть Vector3.ZERO. Кроме того, направление от позиции узла к позиции target не может быть параллельным вектору up, чтобы избежать непреднамеренного вращения вокруг локальной оси Z.

Если use_model_front равно true, ось +Z (фронт актива) рассматривается как прямая (подразумевается, что +X слева) и указывает на позицию target. По умолчанию ось -Z (камера вперед) рассматривается как передняя (подразумевается, что +X справа).

Примечание: Этот метод не работает, если узел не находится в дереве сцены. При необходимости используйте вместо этого look_at_from_position().

void look_at_from_position(position: Vector3, target: Vector3, up: Vector3 = Vector3(0, 1, 0), use_model_front: bool = false) 🔗

Перемещает узел в указанное position, затем поворачивает узел так, чтобы он указывал на позицию target, аналогично look_at(). Эта операция вычисляется в глобальном пространстве (относительно мира).

void orthonormalize() 🔗

Ортонормализует basis этого узла. Этот метод устанавливает scale этого узла на Vector3.ONE (или ее отрицательный эквивалент), но сохраняет position и rotation. См. также Transform3D.orthonormalized().

void rotate(axis: Vector3, angle: float) 🔗

Поворачивает basis этого узла вокруг axis на заданный angle в радианах. Эта операция вычисляется в родительском пространстве (относительно родителя) и сохраняет position.

void rotate_object_local(axis: Vector3, angle: float) 🔗

Поворачивает basis этого узла вокруг axis на заданный angle в радианах. Эта операция вычисляется в локальном пространстве (относительно этого узла) и сохраняет position.

void rotate_x(angle: float) 🔗

Поворачивает basis этого узла вокруг оси X на заданный angle в радианах. Эта операция вычисляется в родительском пространстве (относительно родителя) и сохраняет position.

void rotate_y(angle: float) 🔗

Поворачивает basis этого узла вокруг оси Y на заданный angle в радианах. Эта операция вычисляется в родительском пространстве (относительно родителя) и сохраняет position.

void rotate_z(angle: float) 🔗

Поворачивает basis этого узла вокруг оси Z на заданный angle в радианах. Эта операция вычисляется в родительском пространстве (относительно родителя) и сохраняет position.

void scale_object_local(scale: Vector3) 🔗

Масштабирует basis этого узла на заданный фактор scale. Эта операция вычисляется в локальном пространстве (относительно этого узла) и сохраняет position.

void set_disable_scale(disable: bool) 🔗

Если true, global_transform этого узла автоматически ортонормализуется. Это приводит к тому, что этот узел не выглядит искаженным, как если бы его глобальный масштаб был установлен на Vector3.ONE (или его отрицательный аналог). См. также is_scale_disabled() и orthonormalize().

Примечание: transform не затрагивается этой настройкой.

void set_identity() 🔗

Устанавливает transform этого узла в Transform3D.IDENTITY, что сбрасывает все преобразования в родительском пространстве (position, rotation и scale).

void set_ignore_transform_notification(enabled: bool) 🔗

Если true, узел не получит NOTIFICATION_TRANSFORM_CHANGED или NOTIFICATION_LOCAL_TRANSFORM_CHANGED.

Может быть полезно вызвать этот метод при обработке этих уведомлений, чтобы предотвратить бесконечную рекурсию.

void set_notify_local_transform(enable: bool) 🔗

Если true, узел будет получать NOTIFICATION_LOCAL_TRANSFORM_CHANGED всякий раз, когда изменяется transform.

Примечание: Некоторые 3D-узлы, такие как CSGShape3D или CollisionShape3D, автоматически включают это для правильной работы.

void set_notify_transform(enable: bool) 🔗

Если true, узел будет получать NOTIFICATION_TRANSFORM_CHANGED всякий раз, когда изменяется global_transform.

Примечание: Большинство 3D-узлов, таких как VisualInstance3D или CollisionObject3D, автоматически включают это для корректной работы.

Примечание: В редакторе узлы будут распространять это уведомление своим дочерним элементам, если присоединен гизмо (см. add_gizmo()).

void set_subgizmo_selection(gizmo: Node3DGizmo, id: int, transform: Transform3D) 🔗

Выбирает подэлемент gizmo с заданным id и задает его преобразование. Работает только в редакторе.

Примечание: Объект gizmo обычно является экземпляром EditorNode3DGizmo, но тип аргумента сохраняется общим, чтобы избежать создания зависимости от классов редактора в Node3D.

void show() 🔗

Позволяет отображать этот узел. Эквивалентно установке visible в true. Это противоположно hide().

Vector3 to_global(local_point: Vector3) const 🔗

Возвращает local_point, преобразованный из локального пространства этого узла в глобальное пространство. Это противоположно to_local().

Vector3 to_local(global_point: Vector3) const 🔗

Возвращает global_point, преобразованный из глобального пространства в локальное пространство этого узла. Это противоположно to_global().

void translate(offset: Vector3) 🔗

Добавляет заданное смещение offset к позиции узла в локальном пространстве (относительно этого узла).

Примечание: Вместо этого предпочтительнее использовать translate_object_local(), так как этот метод может быть изменен в будущем выпуске.

Примечание: Несмотря на соглашение об именовании, эта операция не вычисляется в родительском пространстве по соображениям совместимости. Чтобы перевести в родительском пространстве, добавьте offset к position (node_3d.position += offset).

void translate_object_local(offset: Vector3) 🔗

Добавляет заданное смещение offset к положению узла в локальном пространстве (относительно этого узла).

void update_gizmos() 🔗

Обновляет все объекты EditorNode3DGizmo, прикрепленные к этому узлу. Работает только в редакторе.