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

Базовий об'єкт у 3D-просторі, успадкований усіма 3D-вузлами.

Опис

Вузол Node3D є базовим представленням вузла в 3D-просторі. Усі інші 3D-вузли успадковуються від цього класу.

Афінні операції (переміщення, обертання, масштабування) обчислюються в системі координат відносно батьківського вузла, якщо тільки значення 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()

Глобальне положення (переміщення) цього вузла в глобальному просторі (відносно світу). Це еквівалентно Transform3D.origin елемента global_transform.

Примітка: Якщо вузол не знаходиться всередині дерева, отримання цієї властивості завершується невдачею та повертається Vector3.ZERO.

Vector3 global_rotation 🔗

void set_global_rotation(value: Vector3)
Vector3 get_global_rotation()

Глобальне обертання цього вузла як кутів Ейлера, у радіанах та в глобальному просторі (відносно світу). Це значення отримується з обертання global_basis.

Vector3.x – це кут навколо глобальної осі X (тангаж);
Vector3.y – це кут навколо глобальної осі Y (рискання);
Vector3.z – це кут навколо глобальної осі Z (крен).

Примітка: На відміну від 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()

Позиція (зміщення) цього вузла в батьківському просторі (відносно батьківського вузла). Це еквівалентно Transform3D.origin елемента transform.

Quaternion quaternion 🔗

void set_quaternion(value: Quaternion)
Quaternion get_quaternion()

Обертання цього вузла, представленого як Quaternion у батьківському просторі (відносно батьківського вузла). Це значення отримується з обертання basis.

Примітка: Кватерніони набагато більше підходять для 3D-математики, але менш інтуїтивно зрозумілі. Встановлення цієї властивості може бути корисним для інтерполяції (див. Quaternion.slerp()).

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

void set_rotation(value: Vector3)
Vector3 get_rotation()

Обертання цього вузла як кутів Ейлера, у радіанах та в батьківському просторі (відносно батьківського вузла). Це значення отримується з обертання basis.

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 (asset front) розглядається як вісь вперед (означає, що +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 member значення 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, автоматично вмикають цю функцію для коректної роботи.

Примітка: У редакторі вузли поширюватимуть це сповіщення на свої дочірні об'єкти, якщо до них приєднано gizmo (див. 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, приєднані до цього вузла. Працює лише в редакторі.