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
Heredado por: 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
Objeto base en el espacio 3D, del que heredan todos los nodos 3D.
Descripción
El nodo Node3D es la representación base de un nodo en el espacio 3D. Todos los demás nodos 3D heredan de esta clase.
Las operaciones afines (traslación, rotación, escala) se calculan en el sistema de coordenadas relativo al padre, a menos que el top_level del Node3D sea true. En este sistema de coordenadas, las operaciones afines corresponden a operaciones afines directas sobre el transform del Node3D. El término espacio del padre se refiere a este sistema de coordenadas. El sistema de coordenadas que está asociado al propio Node3D se conoce como sistema de coordenadas objeto-local, o espacio local.
Nota: A menos que se especifique lo contrario, todos los métodos que necesiten parámetros de ángulo deben recibir los ángulos en radianes. Para convertir grados a radianes, usa @GlobalScope.deg_to_rad().
Nota: En Godot 3 y anteriores, Node3D se llamaba Spatial.
Tutoriales
Propiedades
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
Métodos
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 |
Señales
visibility_changed() 🔗
Se emite cuando la visibilidad de este nodo cambia (véase visible y is_visible_in_tree()).
Esta señal se emite después de la notificación relacionada NOTIFICATION_VISIBILITY_CHANGED.
Enumeraciones
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 rotación se edita utilizando una Basis. En este modo, los ejes sin procesar de basis se pueden modificar libremente, pero la propiedad scale no está disponible.
Constantes
NOTIFICATION_TRANSFORM_CHANGED = 2000 🔗
Notificación recibida cuando la global_transform de este nodo cambia, si is_transform_notification_enabled() es true. Véase también set_notify_transform().
Nota: La mayoría de los nodos 3D, como VisualInstance3D o CollisionObject3D, habilitan esto automáticamente para que funcionen correctamente.
Nota: En el editor, los nodos propagarán esta notificación a sus hijos si se adjunta un gizmo (véase add_gizmo()).
NOTIFICATION_ENTER_WORLD = 41 🔗
Notificación recibida cuando este nodo se registra en un nuevo World3D (véase get_world_3d()).
NOTIFICATION_EXIT_WORLD = 42 🔗
Notificación recibida cuando este nodo se da de baja del World3D actual (véase get_world_3d()).
Esta notificación se envía en orden inverso.
NOTIFICATION_VISIBILITY_CHANGED = 43 🔗
Notificación recibida cuando cambia la visibilidad de este nodo (consulta visible y is_visible_in_tree()).
Esta notificación se recibe antes de la señal relacionada visibility_changed.
NOTIFICATION_LOCAL_TRANSFORM_CHANGED = 44 🔗
Notificación recibida cuando la transform de este nodo cambia, si is_local_transform_notification_enabled() es true. Esto no se recibe cuando la transform de un Node3D padre cambia. Véase también set_notify_local_transform().
Nota: Algunos nodos 3D como CSGShape3D o CollisionShape3D habilitan esto automáticamente para que funcionen correctamente.
Descripciones de Propiedades
Basis of the transform property. Represents the rotation, scale, and shear of this node in parent space (relative to the parent node).
Basis of the global_transform property. Represents the rotation, scale, and shear of this node in global space (relative to the world).
Note: If the node is not inside the tree, getting this property fails and returns Basis.IDENTITY.
Posición global (traslación) de este nodo en el espacio global (relativo al mundo). Esto es equivalente al Transform3D.origin de la global_transform.
Nota: Si el nodo no está dentro del árbol, obtener esta propiedad falla y devuelve Vector3.ZERO.
Rotación global de este nodo como ángulos de Euler, en radianes y en el espacio global (relativo al mundo). Este valor se obtiene de la rotación de global_basis.
El Vector3.x es el ángulo alrededor del eje X global (cabeceo);
El Vector3.y es el ángulo alrededor del eje Y global (guiñada);
El Vector3.z es el ángulo alrededor del eje Z global (balanceo).
Nota: A diferencia de rotation, esta propiedad siempre sigue la convención YXZ (@GlobalScope.EULER_ORDER_YXZ).
Nota: Si el nodo no está dentro del árbol, obtener esta propiedad falla y devuelve Vector3.ZERO.
Vector3 global_rotation_degrees 🔗
La global_rotation de este nodo, en grados en lugar de radianes.
Nota: Si el nodo no está dentro del árbol, obtener esta propiedad falla y devuelve Vector3.ZERO.
Transform3D global_transform 🔗
void set_global_transform(value: Transform3D)
Transform3D get_global_transform()
La transformación de este nodo, en el espacio global (relativo al mundo). Contiene y representa la global_position, la global_rotation y la escala global de este nodo.
Nota: Si el nodo no está dentro del árbol, obtener esta propiedad falla y devuelve Transform3D.IDENTITY.
Vector3 position = Vector3(0, 0, 0) 🔗
Posición (traslación) de este nodo en el espacio padre (relativo al nodo padre). Esto es equivalente al Transform3D.origin de transform.
Quaternion quaternion 🔗
void set_quaternion(value: Quaternion)
Quaternion get_quaternion()
Rotación de este nodo representada como un Quaternion en el espacio padre (relativo al nodo padre). Este valor se obtiene de la rotación de basis.
Nota: Los cuaterniones son mucho más adecuados para las matemáticas 3D, pero son menos intuitivos. Establecer esta propiedad puede ser útil para la interpolación (véase 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 de este nodo, en grados en lugar de radianes.
Nota: Esta no es la propiedad disponible en el dock Inspector.
RotationEditMode rotation_edit_mode = 0 🔗
void set_rotation_edit_mode(value: RotationEditMode)
RotationEditMode get_rotation_edit_mode()
Cómo se muestran la rotación y la escala de este nodo en el dock Inspector.
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) 🔗
Escala de este nodo en el espacio local (relativa a este nodo). Este valor se obtiene de la escala de basis.
Nota: El comportamiento de algunos tipos de nodo 3D no se ve afectado por esta propiedad. Estos incluyen Light3D, Camera3D, AudioStreamPlayer3D y más.
Advertencia: Los componentes de la escala deben ser todos positivos o todos negativos, y no exactamente 0.0. De lo contrario, no será posible obtener la escala de la basis. Esto puede causar que la escala prevista se pierda al recargarla del disco, y potencialmente otros comportamientos inestables.
Si es true, el nodo no hereda sus transformaciones de su padre. Como tal, las transformaciones del nodo solo estarán en el espacio global, lo que también significa que global_transform y transform serán idénticas.
Transform3D transform = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0) 🔗
void set_transform(value: Transform3D)
Transform3D get_transform()
La transformación local de este nodo, en el espacio padre (relativo al nodo padre). Contiene y representa la position, la rotation y la scale de este nodo.
NodePath visibility_parent = NodePath("") 🔗
Ruta al padre del rango de visibilidad para este nodo y sus descendientes. El padre de visibilidad debe ser un GeometryInstance3D.
Cualquier instancia visual solo será visible si el padre de visibilidad (y todos sus ancestros de visibilidad) está oculto por estar más cerca de la cámara que su propio GeometryInstance3D.visibility_range_begin. Los nodos ocultos a través de la propiedad visible se eliminan esencialmente del árbol de dependencias de visibilidad, por lo que las instancias dependientes no tendrán en cuenta el nodo oculto ni sus descendientes.
Si es true, este nodo puede ser visible. El nodo solo se renderiza cuando todos sus ancestros son visibles también. Esto significa que is_visible_in_tree() debe devolver true.
Descripciones de Métodos
void add_gizmo(gizmo: Node3DGizmo) 🔗
Adjunta el gizmo dado a este nodo. Solo funciona en el editor.
Nota: gizmo debería ser un EditorNode3DGizmo. El tipo de argumento es Node3DGizmo para evitar depender de las clases del editor en Node3D.
void clear_gizmos() 🔗
Limpia todos los objetos EditorNode3DGizmo adjuntos a este nodo. Solo funciona en el editor.
void clear_subgizmo_selection() 🔗
Deselecciona todos los subgizmos para este nodo. Útil para llamar cuando el subgizmo seleccionado puede que ya no exista después de un cambio de propiedad. Solo funciona en el editor.
void force_update_transform() 🔗
Fuerza la actualización del global_transform del nodo, enviando NOTIFICATION_TRANSFORM_CHANGED. Falla si el nodo no está dentro del árbol.
Nota: Por razones de rendimiento, los cambios de transformación se suelen acumular y aplicar una sola vez al final del fotograma. La actualización se propaga también a través de los hijos Node3D. Por lo tanto, usa este método solo cuando necesites una transformación actualizada (como durante las operaciones de física).
Array[Node3DGizmo] get_gizmos() const 🔗
Devuelve todos los objetos EditorNode3DGizmo adjuntos a este nodo. Solo funciona en el editor.
Transform3D get_global_transform_interpolated() 🔗
Al usar la interpolación física, habrá circunstancias en las que querrás saber la transformación interpolada (mostrada) de un nodo en lugar de la transformación estándar (que puede ser precisa solo hasta el tick de física más reciente).
Esto es particularmente importante para operaciones basadas en fotogramas que tienen lugar en Node._process(), en lugar de Node._physics_process(). Los ejemplos incluyen Camera3Ds enfocándose en un nodo, o encontrar desde dónde disparar láseres en un fotograma en lugar de en un tick de física.
Nota: Esta función crea una 'bomba de interpolación' en el Node3D la primera vez que se llama, la cual puede responder a los reinicios de interpolación física. Si tienes problemas de "rayas" al seguir inicialmente un Node3D, asegúrate de llamar a get_global_transform_interpolated() al menos una vez antes de reiniciar la interpolación física del Node3D.
Node3D get_parent_node_3d() const 🔗
Devuelve el Node3D padre que afecta directamente a la global_transform de este nodo. Devuelve null si no existe un padre, si el padre no es un Node3D, o si top_level es true.
Nota: Este método no siempre es equivalente a Node.get_parent(), que no tiene en cuenta top_level.
World3D get_world_3d() const 🔗
Devuelve el World3D al que está registrado este nodo.
Normalmente, este es el mismo que el mundo utilizado por el viewport de este nodo (véase Node.get_viewport() y Viewport.find_world_3d()).
void global_rotate(axis: Vector3, angle: float) 🔗
Rota la global_basis de este nodo alrededor del axis global por el angle dado, en radianes. Esta operación se calcula en el espacio global (relativo al mundo) y conserva la global_position.
void global_scale(scale: Vector3) 🔗
Escala la global_basis de este nodo por el factor de scale dado. Esta operación se calcula en el espacio global (relativo al mundo) y conserva la global_position.
Nota: Este método no debe confundirse con la propiedad scale.
void global_translate(offset: Vector3) 🔗
Añade la traslación offset dada a la global_position del nodo en el espacio global (relativo al mundo).
void hide() 🔗
Prevents this node from being rendered. Equivalent to setting visible to false. This is the opposite of show().
bool is_local_transform_notification_enabled() const 🔗
Returns true if the node receives NOTIFICATION_LOCAL_TRANSFORM_CHANGED whenever transform changes. This is enabled with set_notify_local_transform().
bool is_scale_disabled() const 🔗
Devuelve true si la global_transform de este nodo se ortonormaliza automáticamente. Esto hace que este nodo no aparezca distorsionado, como si su escala global estuviera establecida en Vector3.ONE (o su contraparte negativa). Véase también set_disable_scale() y orthonormalize().
Nota: transform no se ve afectada por esta configuración.
bool is_transform_notification_enabled() const 🔗
Devuelve true si el nodo recibe NOTIFICATION_TRANSFORM_CHANGED cada vez que global_transform cambia. Esto se habilita con set_notify_transform().
bool is_visible_in_tree() const 🔗
Devuelve true si este nodo está dentro del árbol de escenas y si la propiedad visible es true para este nodo y todos sus ancestros Node3D en secuencia. Un ancestro de cualquier otro tipo (como Node o Node2D) rompe la secuencia. Véase también Node.get_parent().
Nota: Este método no puede tener en cuenta VisualInstance3D.layers, por lo que incluso si este método devuelve true, es posible que el nodo no se renderice.
void look_at(target: Vector3, up: Vector3 = Vector3(0, 1, 0), use_model_front: bool = false) 🔗
Rota el nodo de forma que el eje frontal local (-Z, Vector3.FORWARD) apunte hacia la posición target. Esta operación se calcula en el espacio global (relativo al mundo).
El eje local hacia arriba (+Y) apunta lo más cerca posible al vector up, manteniéndose perpendicular al eje frontal local. La transformación resultante es ortogonal y la escala se conserva. El escalado no uniforme puede no funcionar correctamente.
La posición target no puede ser la misma que la posición del nodo, el vector up no puede ser Vector3.ZERO. Además, la dirección desde la posición del nodo a la posición target no puede ser paralela al vector up, para evitar una rotación no deseada alrededor del eje Z local.
Si use_model_front es true, el eje +Z (frontal del activo) se trata como frontal (implica que +X es la izquierda) y apunta hacia la posición target. Por defecto, el eje -Z (frontal de la cámara) se trata como frontal (implica que +X es la derecha).
Nota: Este método falla si el nodo no está en el árbol de escenas. Si es necesario, usa look_at_from_position() en su lugar.
void look_at_from_position(position: Vector3, target: Vector3, up: Vector3 = Vector3(0, 1, 0), use_model_front: bool = false) 🔗
Mueve el nodo a la position especificada y luego rota el nodo para que apunte hacia la posición target, similar a look_at(). Esta operación se calcula en el espacio global (relativo al mundo).
void orthonormalize() 🔗
Ortonormaliza la basis de este nodo. Este método establece la scale de este nodo a Vector3.ONE (o su contraparte negativa), pero conserva la position y la rotation. Véase también Transform3D.orthonormalized().
void rotate(axis: Vector3, angle: float) 🔗
Rota la basis de este nodo alrededor del axis por el angle dado, en radianes. Esta operación se calcula en el espacio padre (relativo al padre) y conserva la position.
void rotate_object_local(axis: Vector3, angle: float) 🔗
Rota la basis de este nodo alrededor del axis por el angle dado, en radianes. Esta operación se calcula en el espacio local (relativo a este nodo) y conserva la position.
Rota la basis de este nodo alrededor del eje X por el angle dado, en radianes. Esta operación se calcula en el espacio padre (relativo al padre) y conserva la position.
Rota la basis de este nodo alrededor del eje Y por el angle dado, en radianes. Esta operación se calcula en el espacio padre (relativo al padre) y conserva la position.
Rota la basis de este nodo alrededor del eje Z por el angle dado, en radianes. Esta operación se calcula en el espacio padre (relativo al padre) y conserva la position.
void scale_object_local(scale: Vector3) 🔗
Escala la basis de este nodo por el factor de scale dado. Esta operación se calcula en el espacio local (relativo a este nodo) y conserva la position.
void set_disable_scale(disable: bool) 🔗
Si es true, la global_transform de este nodo se ortonormaliza automáticamente. Esto hace que este nodo no aparezca distorsionado, como si su escala global estuviera establecida en Vector3.ONE (o su contraparte negativa). Véase también is_scale_disabled() y orthonormalize().
Nota: transform no se ve afectada por esta configuración.
void set_identity() 🔗
Establece la transform de este nodo a Transform3D.IDENTITY, lo que restablece todas las transformaciones en el espacio padre (position, rotation y scale).
void set_ignore_transform_notification(enabled: bool) 🔗
Si es true, el nodo no recibirá NOTIFICATION_TRANSFORM_CHANGED ni NOTIFICATION_LOCAL_TRANSFORM_CHANGED.
Puede ser útil llamar a este método al manejar estas notificaciones para evitar la recursión infinita.
void set_notify_local_transform(enable: bool) 🔗
Si es true, el nodo recibirá NOTIFICATION_LOCAL_TRANSFORM_CHANGED cada vez que cambie transform.
Nota: Algunos nodos 3D, como CSGShape3D o CollisionShape3D, habilitan esto automáticamente para que funcionen correctamente.
void set_notify_transform(enable: bool) 🔗
Si es true, el nodo recibirá NOTIFICATION_TRANSFORM_CHANGED cada vez que global_transform cambie.
Nota: La mayoría de los nodos 3D como VisualInstance3D o CollisionObject3D habilitan esto automáticamente para que funcionen correctamente.
Nota: En el editor, los nodos propagarán esta notificación a sus hijos si se adjunta un gizmo (véase add_gizmo()).
void set_subgizmo_selection(gizmo: Node3DGizmo, id: int, transform: Transform3D) 🔗
Selecciona el subgizmo del gizmo con el id dado y establece su transformación. Solo funciona en el editor.
Nota: El objeto gizmo normalmente sería una instancia de EditorNode3DGizmo, pero el tipo de argumento se mantiene genérico para evitar crear una dependencia de las clases del editor en Node3D.
void show() 🔗
Permite que este nodo se renderice. Equivalente a establecer visible como true. Esto es lo opuesto a hide().
Vector3 to_global(local_point: Vector3) const 🔗
Devuelve el local_point convertido del espacio local de este nodo al espacio global. Esto es lo opuesto a to_local().
Vector3 to_local(global_point: Vector3) const 🔗
Devuelve el global_point convertido del espacio global al espacio local de este nodo. Esto es lo opuesto a to_global().
void translate(offset: Vector3) 🔗
Añade la traslación dada offset a la posición del nodo, en espacio local (relativo a este nodo).
Nota: Es preferible usar translate_object_local(), en su lugar, ya que este método podría cambiar en una futura versión.
Nota: A pesar de la convención de nombres, esta operación no se calcula en el espacio del padre por razones de compatibilidad. Para trasladar en el espacio del padre, añade offset a la position (node_3d.position += offset).
void translate_object_local(offset: Vector3) 🔗
Añade la traslación offset dada a la posición del nodo, en el espacio local (relativo a este nodo).
void update_gizmos() 🔗
Actualiza todos los objetos EditorNode3DGizmo adjuntos a este nodo. Solo funciona en el editor.