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...
Node3D
Ereditato da: 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
Oggetto base nello spazio 3D, ereditato da tutti i nodi 3D.
Descrizione
Il nodo Node3D è la rappresentazione base di un nodo nello spazio 3D. Tutti gli altri nodi 3D ereditano da questa classe.
Le operazioni affini (traslazione, rotazione, scala) sono calcolate nel sistema di coordinate relativo al padre, a meno che il top_level del Node3D non sia true. In questo sistema di coordinate, le operazioni affini corrispondono alle operazioni affini dirette sulla transform del Node3D. Il termine spazio padre si riferisce a questo sistema di coordinate. Il sistema di coordinate che è associato all'oggetto Node3D stesso è riferito come sistema di coordinate locale all'oggetto, o spazio locale.
Nota: Salvo diversamente specificato, tutti i metodi che hanno parametri di angolo devono avere angoli specificati in radianti. Per convertire i gradi in radianti, usa @GlobalScope.deg_to_rad().
Nota: In Godot 3 e versioni precedenti, Node3D aveva il nome Spatial.
Tutorial
Proprietà
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
Metodi
void |
add_gizmo(gizmo: Node3DGizmo) |
void |
|
void |
|
void |
|
get_gizmos() const |
|
get_parent_node_3d() const |
|
get_world_3d() const |
|
void |
global_rotate(axis: Vector3, angle: float) |
void |
global_scale(scale: Vector3) |
void |
global_translate(offset: Vector3) |
void |
hide() |
is_scale_disabled() const |
|
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 |
|
void |
|
void |
rotate_object_local(axis: Vector3, angle: float) |
void |
|
void |
|
void |
|
void |
scale_object_local(scale: Vector3) |
void |
set_disable_scale(disable: bool) |
void |
|
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() |
void |
|
void |
translate_object_local(offset: Vector3) |
void |
Segnali
visibility_changed() 🔗
Emesso quando la visibilità di questo nodo cambia (vedi visible e is_visible_in_tree()).
Questo segnale viene emesso dopo la notifica corrispondente NOTIFICATION_VISIBILITY_CHANGED.
Enumerazioni
enum RotationEditMode: 🔗
RotationEditMode ROTATION_EDIT_MODE_EULER = 0
The rotation is edited using a Vector3 in Euler angles. In Godot, Euler angles always use intrinsic order, meaning that rotation happens around the local axes of the object.
RotationEditMode ROTATION_EDIT_MODE_QUATERNION = 1
The rotation is edited using a Quaternion. Quaternions avoid gimbal lock and having to choose an order of rotation, but are less intuitive. Quaternion rotation is mostly the same as rotors in 3D geometric algebra, except that the numbers are labeled differently.
RotationEditMode ROTATION_EDIT_MODE_BASIS = 2
La rotazione è modificata tramite una Basis. In questa modalità, le assi di basis si possono modificare liberamente, ma la proprietà scale non è disponibile.
Costanti
NOTIFICATION_TRANSFORM_CHANGED = 2000 🔗
Notifica ricevuta quando global_transform di questo nodo cambia, se is_transform_notification_enabled() è true. Vedi anche set_notify_transform().
Nota: Molti nodi 3D come VisualInstance3D o CollisionObject3D abilitano questo automaticamente per funzionare correttamente.
Nota: Nell'editor, i nodi propagheranno questa notifica ai loro figli se vi è associato un gizmo (vedi add_gizmo()).
NOTIFICATION_ENTER_WORLD = 41 🔗
Notifica ricevuta quando questo nodo è registrato in un nuovo World3D (vedi get_world_3d()).
NOTIFICATION_EXIT_WORLD = 42 🔗
Notifica ricevuta quando la registrazione di questo nodo al World3D attuale viene annullata (vedi get_world_3d()).
Questa notifica è inviata in ordine inverso.
NOTIFICATION_VISIBILITY_CHANGED = 43 🔗
Notifica ricevuta quando la visibilità di questo nodo cambia (vedi visible e is_visible_in_tree()).
Questa notifica viene ricevuta prima del segnale corrispondente visibility_changed.
NOTIFICATION_LOCAL_TRANSFORM_CHANGED = 44 🔗
Notifica ricevuta quando transform di questo nodo cambia, se is_local_transform_notification_enabled() è true. Questa non è ricevuta quando cambia la transform di un Node3D padre. Vedi anche set_notify_local_transform().
Nota: Alcuni nodi 3D come CSGShape3D o CollisionShape3D abilitano questo automaticamente per funzionare correttamente.
Descrizioni delle proprietà
Base della proprietà transform. Rappresenta la rotazione, la scala e l'inclinazione di questo nodo nello spazio padre (relativa al nodo padre).
Base della proprietà global_transform. Rappresenta la rotazione, la scala e l'inclinazione di questo nodo nello spazio globale (relativa al mondo).
Nota: Se il nodo non è all'interno dell'albero, il recupero di questa proprietà fallisce e restituisce Basis.IDENTITY.
Posizione globale (traslazione) di questo nodo nello spazio globale (relativa al mondo). Equivale a Transform3D.origin di global_transform.
Nota: Se il nodo non è all'interno dell'albero, il recupero di questa proprietà fallisce e restituisce Vector3.ZERO.
Rotazione globale di questo nodo come angoli di Eulero, in radianti e nello spazio globale (relativo al mondo). Questo valore è ottenuto dalla rotazione di global_basis.
Il Vector3.x è l'angolo attorno all'asse X globale (beccheggio);
Il Vector3.y è l'angolo attorno all'asse Y globale (imbardata);
Il Vector3.z è l'angolo attorno all'asse Z globale (rollio).
Nota: A differenza di rotation, questa proprietà segue sempre la convenzione YXZ (@GlobalScope.EULER_ORDER_YXZ).
Nota: Se il nodo non è all'interno dell'albero, il recupero di questa proprietà fallisce e restituisce Vector3.ZERO.
Vector3 global_rotation_degrees 🔗
La global_rotation di questo nodo, in gradi anziché in radianti.
Nota: Se il nodo non è all'interno dell'albero, il recupero di questa proprietà fallisce e restituisce Vector3.ZERO.
Transform3D global_transform 🔗
void set_global_transform(value: Transform3D)
Transform3D get_global_transform()
La trasformazione di questo nodo nello spazio globale (relativa al mondo). Contiene e rappresenta la global_position, la global_rotation e la scala globale di questo nodo.
Nota: Se il nodo non è all'interno dell'albero, il recupero di questa proprietà fallisce e restituisce Transform3D.IDENTITY.
Vector3 position = Vector3(0, 0, 0) 🔗
Posizione (traslazione) di questo nodo nello spazio padre (relativa al nodo padre). Questa equivale a Transform3D.origin di transform.
Quaternion quaternion 🔗
void set_quaternion(value: Quaternion)
Quaternion get_quaternion()
Rotazione di questo nodo rappresentata come un Quaternion nello spazio padre (relativa al nodo padre). Questo valore è ottenuto dalla rotazione di basis.
Nota: I quaternioni sono molto più adatti alla matematica 3D, ma sono meno intuitivi. Impostare questa proprietà può essere utile per interpolare (vedi Quaternion.slerp()).
Vector3 rotation = Vector3(0, 0, 0) 🔗
Rotation of this node as Euler angles, in radians and in parent space (relative to the parent node). This value is obtained from basis's rotation.
The Vector3.x is the angle around the local X axis (pitch);
The Vector3.y is the angle around the local Y axis (yaw);
The Vector3.z is the angle around the local Z axis (roll).
The order of each consecutive rotation can be changed with rotation_order (see EulerOrder constants). In Godot, Euler angles always use intrinsic order. By default, the intrinsic YXZ convention is used (@GlobalScope.EULER_ORDER_YXZ).
Note: This property is edited in degrees in the inspector. If you want to use degrees in a script, use rotation_degrees.
La rotation di questo nodo, in gradi anziché in radianti.
Nota: Questa non è la proprietà disponibile nel pannello Ispettore.
RotationEditMode rotation_edit_mode = 0 🔗
void set_rotation_edit_mode(value: RotationEditMode)
RotationEditMode get_rotation_edit_mode()
Come la rotazione e la scala di questo nodo sono presentate nel pannello Ispettore.
EulerOrder rotation_order = 2 🔗
void set_rotation_order(value: EulerOrder)
EulerOrder get_rotation_order()
The axis rotation order of the rotation property. In Godot, Euler angles always use intrinsic order, meaning that the final orientation is calculated by rotating around the local axes in this order.
Vector3 scale = Vector3(1, 1, 1) 🔗
Scala di questo nodo nello spazio locale (relativa a questo nodo). Questo valore è ottenuto dalla scala di basis.
Nota: Il comportamento di alcuni tipi di nodi 3D non è influenzato da questa proprietà. Tra questi, Light3D, Camera3D, AudioStreamPlayer3D e altri.
Attenzione: I componenti della scala devono essere tutti positivi o tutti negativi e non esattamente 0.0. Se no, non sarà possibile ottenere la scala da basis. Ciò potrebbe causare la perdita della scala desiderata al ricaricamento da disco, nonché altri eventuali comportamenti instabili.
Se true, il nodo non erediterà le sue trasformazioni dal suo genitore. Pertanto, le trasformazioni del nodo saranno solo nello spazio globale, il che significa anche che global_transform e transform saranno identici.
Transform3D transform = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0) 🔗
void set_transform(value: Transform3D)
Transform3D get_transform()
La trasformazione locale di questo nodo, nello spazio padre (relativa al nodo padre). Contiene e rappresenta la position, la rotation e la scale di questo nodo.
NodePath visibility_parent = NodePath("") 🔗
Percorso al genitore dell'intervallo di visibilità per questo nodo e i suoi discendenti. Il genitore di visibilità deve essere un GeometryInstance3D.
Qualsiasi istanza visiva sarà visibile solo se il genitore di visibilità (e tutti i suoi antenati di visibilità) è nascosto perché più vicino alla telecamera rispetto al suo GeometryInstance3D.visibility_range_begin. I nodi nascosti tramite la proprietà visible sono essenzialmente rimossi dall'albero delle dipendenze di visibilità, quindi le istanze dipendenti non terranno conto del nodo nascosto o dei suoi antenati.
Se true, questo nodo può essere visibile. Il nodo è renderizzato soltanto se sono visibili anche tutti i suoi antenati. Ciò significa che is_visible_in_tree() deve restituire true.
Descrizioni dei metodi
void add_gizmo(gizmo: Node3DGizmo) 🔗
Associa il gizmo specificato a questo nodo. Funziona solo nell'editor.
Nota: gizmo dovrebbe essere un EditorNode3DGizmo. Il tipo di argomento è Node3DGizmo per evitare di dipendere dalle classi dell'editor in Node3D.
void clear_gizmos() 🔗
Cancella tutti gli oggetti EditorNode3DGizmo associati a questo nodo. Funziona solo nell'editor.
void clear_subgizmo_selection() 🔗
Deseleziona tutti i sub-gizmo per questo nodo. Utile da chiamare quando il sub-gizmo selezionato potrebbe non esistere più dopo un cambiamento a una proprietà. Funziona solo nell'editor.
void force_update_transform() 🔗
Forza l'aggiornamento del global_transform del nodo, inviando NOTIFICATION_TRANSFORM_CHANGED. Fallisce se il nodo non si trova all'interno dell'albero.
Nota: Per motivi di prestazioni, le modifiche alle trasformazioni sono solitamente accumulate e applicate una sola volta alla fine del frame. L'aggiornamento si propaga anche attraverso i figli di Node3D. Pertanto, utilizzare questo metodo solo quando è necessaria una trasformazione aggiornata (ad esempio durante le operazioni di fisica).
Array[Node3DGizmo] get_gizmos() const 🔗
Restituisce tutti gli oggetti EditorNode3DGizmo associati a questo nodo. Funziona solo nell'editor.
Transform3D get_global_transform_interpolated() 🔗
Quando si utilizza l'interpolazione della fisica, in alcune circostanze si desidera conoscere la trasformazione interpolata (visualizzata) di un nodo anziché la solita trasformazione (che potrebbe essere accurata solo fino al tick di fisica più recente).
Questo è particolarmente importante per le operazioni basate sui frame che avvengono in Node._process(), anziché in Node._physics_process(). Alcuni esempi includono focalizzare un nodo per i Camera3D o ricavare la posizione da cui sparare i laser su un frame anziché su un tick di fisica.
Nota: Questa funzione crea un "pompaggio" di interpolazione sul Node3D la prima volta che viene chiamata, il quale può rispondere al riavvio dell'interpolazione della fisica. Se si verificano problemi di "striature" quando si segue inizialmente un Node3D, assicurarsi di chiamare get_global_transform_interpolated() almeno una volta prima di riavviare l'interpolazione fisica del Node3D.
Node3D get_parent_node_3d() const 🔗
Restituisce il nodo Node3D genitore che influenza direttamente il global_transform di questo nodo. Restituisce null se nessun genitore esiste, se il nodo genitore non è un Node3D o se top_level è true.
Nota: Questo metodo non è sempre equivalente a Node.get_parent(), il quale non tiene conto di top_level.
World3D get_world_3d() const 🔗
Restituisce il World3D in cui è registrato questo nodo.
Di solito, questo è lo stesso utilizzato dalla viewport di questo nodo (vedi Node.get_viewport() e Viewport.find_world_3d()).
void global_rotate(axis: Vector3, angle: float) 🔗
Ruota la global_basis di questo nodo attorno all'asse globale axis dell'angolo angle specificato, in radianti. Questa operazione è calcolata nello spazio globale (relativa al mondo) e preserva la global_position.
void global_scale(scale: Vector3) 🔗
Cambia la scala della global_basis di questo per il fattore scale specificato. Questa operazione è calcolata nello spazio globale (relativa al mondo) e preserva la global_position.
Nota: Questo metodo è da non confondere con la proprietà scale.
void global_translate(offset: Vector3) 🔗
Aggiunge la traslazione offset specificata alla global_position del nodo nello spazio globale (relativa al mondo).
void hide() 🔗
Impedisce di renderizzare questo nodo. Equivale a impostare visible su false. È l'opposto di show().
bool is_local_transform_notification_enabled() const 🔗
Restituisce true se il nodo riceve NOTIFICATION_LOCAL_TRANSFORM_CHANGED quando cambia transform. Ciò è abilitato con set_notify_local_transform().
bool is_scale_disabled() const 🔗
Restituisce true se il global_transform di questo nodo è automaticamente ortonormalizzato. Ciò assicura che il nodo non appaia distorto, come se la sua scala globale fosse impostata su Vector3.ONE (o la sua controparte negativa). Vedi anche set_disable_scale() e orthonormalize().
Nota: Il transform non è influenzato da questa impostazione.
bool is_transform_notification_enabled() const 🔗
Restituisce true se il nodo riceve NOTIFICATION_TRANSFORM_CHANGED quando cambia global_transform. Ciò è abilitato con set_notify_transform().
bool is_visible_in_tree() const 🔗
Restituisce true se il nodo è presente nell'albero di scene e la proprietà visible è true per questo nodo e per tutti i suoi Node3D antenati in sequenza. Un antenato di qualsiasi altro tipo (ad esempio Node o Node2D) interrompe la sequenza. Vedi anche Node.get_parent().
Nota: Questo metodo non tiene conto di VisualInstance3D.layers, quindi anche se questo metodo restituisce true, il nodo potrebbe non essere renderizzato.
void look_at(target: Vector3, up: Vector3 = Vector3(0, 1, 0), use_model_front: bool = false) 🔗
Ruota il nodo in modo che l'asse locale in avanti (-Z, Vector3.FORWARD) punti verso la posizione target. Questa operazione è calcolata nello spazio globale (relativa al mondo)
L'asse locale in alto (+Y) punta il più vicino possibile al vettore up, pur rimanendo perpendicolare all'asse locale in avanti. La trasformazione risultante è ortogonale e la scala è conservata. Una scala non uniforme potrebbe non funzionare correttamente.
La posizione target non può essere la stessa della posizione del nodo, il vettore up non può essere zero. Inoltre, la direzione dalla posizione del nodo alla posizione target non può essere parallela al vettore up, per evitare una rotazione involontaria attorno all'asse Z locale.
Se use_model_front è true, l'asse +Z (avanti per gli asset) viene trattato come in avanti (implica che +X sia a sinistra) e punta verso la posizione target. Come predefinito, l'asse -Z (avanti per la telecamera) viene trattato come in avanti (implica che +X sia a destra).
Nota: Questo metodo fallisce se il nodo non si trova nell'albero di scene. Se necessario, utilizzare invece look_at_from_position().
void look_at_from_position(position: Vector3, target: Vector3, up: Vector3 = Vector3(0, 1, 0), use_model_front: bool = false) 🔗
Sposta il nodo nella posizione position, quindi ruota il nodo in modo che punti verso target come con look_at(). Questa operazione è calcolata nello spazio globale (relativa al mondo).
void orthonormalize() 🔗
Ortonormalizza la basis di questo nodo. Questo metodo imposta la scale di questo nodo su Vector3.ONE (o la sua controparte negativa), ma preserva la position e la rotation. Vedi anche Transform3D.orthonormalized().
void rotate(axis: Vector3, angle: float) 🔗
Ruota la basis di questo nodo attorno all'asse axis dell'angolo angle, in radianti. Questa operazione è calcolata nello spazio padre (relativa al padre) e preserva la position.
void rotate_object_local(axis: Vector3, angle: float) 🔗
Ruota la basis di questo nodo attorno all'asse axis dell'angolo angle, in radianti. Questa operazione è calcolata nello spazio locale (relativa a questo nodo) e preserva la position.
Ruota la basis di questo nodo attorno all'asse X dell'angolo angle, in radianti. Questa operazione è calcolata nello spazio padre (relativa al padre) e preserva la position.
Ruota la basis di questo nodo attorno all'asse Y dell'angolo angle, in radianti. Questa operazione è calcolata nello spazio padre (relativa al padre) e preserva la position.
Ruota la basis di questo nodo attorno all'asse Z dell'angolo angle, in radianti. Questa operazione è calcolata nello spazio padre (relativa al padre) e preserva la position.
void scale_object_local(scale: Vector3) 🔗
Scala la basis di questo nodo in base al fattore scale specificato. Questa operazione è calcolata nello spazio locale (relativa a questo nodo) e preserva la position.
void set_disable_scale(disable: bool) 🔗
Se true, il global_transform di questo nodo è automaticamente ortonormalizzato. Ciò assicura che il nodo non appaia distorto, come se la sua scala globale fosse impostata su Vector3.ONE (o la sua controparte negativa). Vedi anche set_disable_scale() e orthonormalize().
Nota: Il transform non è influenzato da questa impostazione.
void set_identity() 🔗
Imposta la transform di questo nodo su Transform3D.IDENTITY, il che ripristina tutte le trasformazioni nello spazio padre (position, rotation e scale).
void set_ignore_transform_notification(enabled: bool) 🔗
Se true, il nodo non riceverà NOTIFICATION_TRANSFORM_CHANGED o NOTIFICATION_LOCAL_TRANSFORM_CHANGED.
Potrebbe essere utile chiamare questo metodo quando si gestiscono queste notifiche per evitare una ricorsione infinita.
void set_notify_local_transform(enable: bool) 🔗
Se true, il nodo riceverà NOTIFICATION_LOCAL_TRANSFORM_CHANGED quando transform cambia.
Nota: Alcuni nodi 3D come CSGShape3D o CollisionShape3D abilitano questo automaticamente per funzionare correttamente.
void set_notify_transform(enable: bool) 🔗
Se true, il nodo riceverà NOTIFICATION_TRANSFORM_CHANGED quando global_transform cambia.
Nota: Molti nodi 3D come VisualInstance3D o CollisionObject3D abilitano questo automaticamente per funzionare correttamente.
Nota: Nell'editor, i nodi propagheranno questa notifica ai loro figli se vi è associato un gizmo (vedi add_gizmo()).
void set_subgizmo_selection(gizmo: Node3DGizmo, id: int, transform: Transform3D) 🔗
Seleziona il subgizmo del gizmo con l'id specificato e ne imposta la trasformazione. Funziona solo nell'editor.
Nota: L'oggetto gizmo sarebbe in genere un'istanza di EditorNode3DGizmo, ma il tipo di argomento è mantenuto generico per evitare di creare una dipendenza dalle classi dell'editor in Node3D.
void show() 🔗
Permette di renderizzare questo nodo. Equivale a impostare visible su true. È l'opposto di hide().
Vector3 to_global(local_point: Vector3) const 🔗
Restituisce il punto local_point convertito dallo spazio locale di questo nodo allo spazio mondiale. Questo è l'opposto di to_local().
Vector3 to_local(global_point: Vector3) const 🔗
Restituisce il punto global_point convertito dallo spazio globale di questo nodo allo spazio locale. Questo è l'opposto di to_global().
void translate(offset: Vector3) 🔗
Aggiunge la traslazione offset alla posizione del nodo, nello spazio locale (relativa a questo nodo).
Nota: Si consiglia di utilizzare invece il metodo translate_object_local(), poiché questo metodo potrebbe cambiare in una versione futura.
Nota: Nonostante la convenzione di denominazione, questa operazione non è calcolata nello spazio padre per motivi di compatibilità. Per traslare nello spazio padre, aggiungere offset alla position (node_3d.position += offset).
void translate_object_local(offset: Vector3) 🔗
Aggiunge la traslazione offset alla posizione del nodo, nello spazio locale (relativa a questo nodo).
void update_gizmos() 🔗
Aggiorna tutti gli oggetti EditorNode3DGizmo attaccati a questo nodo. Funziona solo nell'editor.