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

Basis

Una matriz de 3×3 para representar la rotación y la escala 3D.

Descripción

The Basis built-in Variant type is a 3×3 matrix used to represent 3D rotation, scale, and shear. It is frequently used within a Transform3D.

A Basis is composed by 3 axis vectors, each representing a column of the matrix: x, y, and z. The length of each axis (Vector3.length()) influences the basis's scale, while the direction of all axes influence the rotation. Usually, these axes are perpendicular to one another. However, when you rotate any axis individually, the basis becomes sheared. Applying a sheared basis to a 3D model will make the model appear distorted.

A Basis is:

Orthogonal if its axes are perpendicular to each other.
Normalized if the length of every axis is 1.0.
Uniform if all axes share the same length (see get_scale()).
Orthonormal if it is both orthogonal and normalized, which allows it to only represent rotations (see orthonormalized()).
Conformal if it is both orthogonal and uniform, which ensures it is not distorted.

For a general introduction, see the Matrices and transforms tutorial.

Note: Godot uses a right-handed coordinate system, which is a common standard. For directions, the convention for built-in types like Camera3D is for -Z to point forward (+X is right, +Y is up, and +Z is back). Other objects may use different direction conventions. For more information, see the 3D asset direction conventions tutorial.

Note: The basis matrices are exposed as column-major order, which is the same as OpenGL. However, they are stored internally in row-major order, which is the same as DirectX.

Note: In a boolean context, a basis will evaluate to false if it's equal to IDENTITY. Otherwise, a basis will always evaluate to true.

Nota

Hay diferencias notables cuando usa esta API con C#. Véase Diferencias de la API de C# con GDScript para más información.

Tutoriales

Propiedades

Vector3	x	`Vector3(1, 0, 0)`
Vector3	y	`Vector3(0, 1, 0)`
Vector3	z	`Vector3(0, 0, 1)`

Constructores

Basis	Basis()
Basis	Basis(from: Basis)
Basis	Basis(axis: Vector3, angle: float)
Basis	Basis(from: Quaternion)
Basis	Basis(x_axis: Vector3, y_axis: Vector3, z_axis: Vector3)

Métodos

float	determinant() const
Basis	from_euler(euler: Vector3, order: int = 2) static
Basis	from_scale(scale: Vector3) static
Vector3	get_euler(order: int = 2) const
Quaternion	get_rotation_quaternion() const
Vector3	get_scale() const
Basis	inverse() const
bool	is_conformal() const
bool	is_equal_approx(b: Basis) const
bool	is_finite() const
bool	is_orthonormal() const
Basis	looking_at(target: Vector3, up: Vector3 = Vector3(0, 1, 0), use_model_front: bool = false) static
Basis	orthonormalized() const
Basis	rotated(axis: Vector3, angle: float) const
Basis	scaled(scale: Vector3) const
Basis	scaled_local(scale: Vector3) const
Basis	slerp(to: Basis, weight: float) const
float	tdotx(with: Vector3) const
float	tdoty(with: Vector3) const
float	tdotz(with: Vector3) const
Basis	transposed() const

Operadores

bool	operator !=(right: Basis)
Basis	operator *(right: Basis)
Vector3	operator *(right: Vector3)
Basis	operator *(right: float)
Basis	operator *(right: int)
Basis	operator /(right: float)
Basis	operator /(right: int)
bool	operator ==(right: Basis)
Vector3	operator [](index: int)

Constantes

IDENTITY = Basis(1, 0, 0, 0, 1, 0, 0, 0, 1) 🔗

La identidad Basis. Esta es una base ortonormal sin rotación, sin cizallamiento y con una escala de Vector3.ONE. Esto también significa que:

El elemento x apunta a la derecha (Vector3.RIGHT);
El elemento y apunta hacia arriba (Vector3.UP);
El elemento z apunta hacia atrás (Vector3.BACK).

var basis = Basis.IDENTITY
print("| X | Y | Z")
print("| %.f | %.f | %.f" % [basis.x.x, basis.y.x, basis.z.x])
print("| %.f | %.f | %.f" % [basis.x.y, basis.y.y, basis.z.y])
print("| %.f | %.f | %.f" % [basis.x.z, basis.y.z, basis.z.z])
# Imprime:
# | X | Y | Z
# | 1 | 0 | 0
# | 0 | 1 | 0
# | 0 | 0 | 1

Si un Vector3 u otro Basis se transforma (multiplica) por esta constante, no se produce ninguna transformación.

Nota: En GDScript, esta constante equivale a crear un Basis sin argumentos. Se puede usar para que el código sea más claro y para mantener la coherencia con C#.

FLIP_X = Basis(-1, 0, 0, 0, 1, 0, 0, 0, 1) 🔗

Cuando cualquier base se multiplica por FLIP_X, se invierten todos los componentes del eje x (la columna X).

Cuando FLIP_X se multiplica por cualquier base, se invierte el componente Vector3.x de todos los ejes (la fila X).

FLIP_Y = Basis(1, 0, 0, 0, -1, 0, 0, 0, 1) 🔗

Cuando cualquier base se multiplica por FLIP_Y, se invierten todos los componentes del eje y (la columna Y).

Cuando FLIP_Y se multiplica por cualquier base, se invierte el componente Vector3.y de todos los ejes (la fila Y).

FLIP_Z = Basis(1, 0, 0, 0, 1, 0, 0, 0, -1) 🔗

Cuando cualquier base se multiplica por FLIP_Z, se anulan todos los componentes del eje z (la columna Z).

Cuando FLIP_Z se multiplica por cualquier base, se anula el componente Vector3.z de todos los ejes (la fila Z).

Descripciones de Propiedades

Vector3 x = Vector3(1, 0, 0) 🔗

El eje X de la base y la columna 0 de la matriz.

En la base identidad, este vector apunta a la derecha (Vector3.RIGHT).

Vector3 y = Vector3(0, 1, 0) 🔗

El eje Y de la base y la columna 1 de la matriz.

En la base identidad, este vector apunta hacia arriba (Vector3.UP).

Vector3 z = Vector3(0, 0, 1) 🔗

El eje Z de la base y la columna 2 de la matriz.

En la base identidad, este vector apunta hacia atrás (Vector3.BACK).

Descripciones de Constructores

Basis Basis() 🔗

Construye una Basis idéntica a IDENTITY.

Nota: En C#, esto construye una Basis con todos sus componentes establecidos a Vector3.ZERO.

Basis Basis(from: Basis)

Construye una Basis como una copia de la Basis dada.

Basis Basis(axis: Vector3, angle: float)

Construye una Basis que solo representa la rotación, girada alrededor del axis según el angle dado, en radianes. El eje debe ser un vector normalizado.

Nota: Esto es equivalente a usar rotated() en la base IDENTITY. Si se requiere más de un ángulo, considere usar from_euler().

Basis Basis(from: Quaternion)

Construye una Basis que solo representa la rotación del Quaternion dado.

Nota: Los cuaterniones solo almacenan rotación, no escala. Por esta razón, las conversiones de Basis a Quaternion no siempre se pueden revertir.

Basis Basis(x_axis: Vector3, y_axis: Vector3, z_axis: Vector3)

Construye una Basis a partir de tres vectores de eje. Estas son las columnas de la matriz base.

Descripciones de Métodos

float determinant() const 🔗

Returns the determinant of this basis's matrix. For advanced math, this number can be used to determine a few attributes:

If the determinant is exactly 0.0, the basis is not invertible (see inverse()).
If the determinant is a negative number, the basis represents a negative scale.

Note: If the basis's scale is the same for every axis, its determinant is always that scale by the power of 3.

Basis from_euler(euler: Vector3, order: int = 2) static 🔗

Constructs a new Basis that only represents rotation from the given Vector3 of Euler angles, in radians.

The Vector3.x should contain the angle around the x axis (pitch);
The Vector3.y should contain the angle around the y axis (yaw);
The Vector3.z should contain the angle around the z axis (roll).

# Creates a Basis whose z axis points down.
var my_basis = Basis.from_euler(Vector3(TAU / 4, 0, 0))

print(my_basis.z) # Prints (0.0, -1.0, 0.0)

// Creates a Basis whose z axis points down.
var myBasis = Basis.FromEuler(new Vector3(Mathf.Tau / 4.0f, 0.0f, 0.0f));

GD.Print(myBasis.Z); // Prints (0, -1, 0)

The order of each consecutive rotation can be changed with order (see EulerOrder constants). In Godot, Euler angles always use intrinsic order. By default, the intrinsic YXZ convention is used (@GlobalScope.EULER_ORDER_YXZ): the basis rotates first around the local Y axis (yaw), then local X (pitch), and lastly local Z (roll). When using the opposite method get_euler() to decompose a rotation, this order is reversed.

Basis from_scale(scale: Vector3) static 🔗

Construye una nueva Basis que solo representa la escala, sin rotación ni deformación, a partir del vector scale dado.

var my_basis = Basis.from_scale(Vector3(2, 4, 8))

print(my_basis.x) # Imprime (2.0, 0.0, 0.0)
print(my_basis.y) # Imprime (0.0, 4.0, 0.0)
print(my_basis.z) # Imprime (0.0, 0.0, 8.0)

var myBasis = Basis.FromScale(new Vector3(2.0f, 4.0f, 8.0f));

GD.Print(myBasis.X); // Imprime (2, 0, 0)
GD.Print(myBasis.Y); // Imprime (0, 4, 0)
GD.Print(myBasis.Z); // Imprime (0, 0, 8)

Nota: En álgebra lineal, la matriz de esta base también se conoce como matriz diagonal.

Vector3 get_euler(order: int = 2) const 🔗

Returns this basis's rotation as a Vector3 of Euler angles, in radians. For the returned value:

The Vector3.x contains the angle around the x axis (pitch);
The Vector3.y contains the angle around the y axis (yaw);
The Vector3.z contains the angle around the z axis (roll).

The order of each consecutive rotation can be changed with order (see EulerOrder constants). In Godot, Euler angles always use intrinsic order. By default, the intrinsic YXZ convention is used (@GlobalScope.EULER_ORDER_YXZ): since we are decomposing, local Z (roll) is calculated first, then local X (pitch), and lastly local Y (yaw). When using the opposite method from_euler() to compose a rotation, this order is reversed.

Note: For this method to return correctly, the basis needs to be orthonormal (see orthonormalized()).

Note: Euler angles are much more intuitive but are not suitable for 3D math. Because of this, consider using the get_rotation_quaternion() method instead, which returns a Quaternion.

Note: In the Inspector dock, a basis's rotation is often displayed in Euler angles (in degrees), as is the case with the Node3D.rotation property.

Quaternion get_rotation_quaternion() const 🔗

Devuelve la rotación de esta base como un Quaternion.

Nota: Los cuaterniones son mucho más adecuados para matemáticas 3D, pero son menos intuitivos. Para interfaces de usuario, considere usar el método get_euler(), que devuelve ángulos de Euler.

Vector3 get_scale() const 🔗

Devuelve la longitud de cada eje de esta base como un Vector3. Si la base no se deforma, este valor es el factor de escala. No se ve afectado por la rotación.

var my_basis = Basis(
    Vector3(2, 0, 0),
    Vector3(0, 4, 0),
    Vector3(0, 0, 8)
)
# Cualquier rotación de la base conserva su escala.
my_basis = my_basis.rotated(Vector3.UP, TAU / 2)
my_basis = my_basis.rotated(Vector3.RIGHT, TAU / 4)

print(my_basis.get_scale()) # Imprime (2.0, 4.0, 8.0)

var myBasis = new Basis(
    Vector3(2.0f, 0.0f, 0.0f),
    Vector3(0.0f, 4.0f, 0.0f),
    Vector3(0.0f, 0.0f, 8.0f)
);
// Rotar la base de cualquier forma conserva su escala.
myBasis = myBasis.Rotated(Vector3.Up, Mathf.Tau / 2.0f);
myBasis = myBasis.Rotated(Vector3.Right, Mathf.Tau / 4.0f);

GD.Print(myBasis.Scale); // Imprime (2, 4, 8)

Nota: Si el valor devuelto por el método determinant() es negativo, la escala también es negativa.

Basis inverse() const 🔗

Devuelve la inversa de la matriz de esta base.

bool is_conformal() const 🔗

Devuelve true si esta base es conforme. Una base conforme es tanto ortogonal (los ejes son perpendiculares entre sí) como uniforme (los ejes comparten la misma longitud). Este método puede ser especialmente útil durante los cálculos físicos.

bool is_equal_approx(b: Basis) const 🔗

Devuelve true si esta base y b son aproximadamente iguales, llamando a @GlobalScope.is_equal_approx() en todos los componentes vectoriales.

bool is_finite() const 🔗

Devuelve true si esta base es finita, llamando a @GlobalScope.is_finite() en todos los componentes vectoriales.

bool is_orthonormal() const 🔗

Returns true if this basis is orthonormal. An orthonormal basis is both orthogonal (the axes are perpendicular to each other) and normalized (the length of every axis is 1.0). This method can be especially useful during physics calculations.

Basis looking_at(target: Vector3, up: Vector3 = Vector3(0, 1, 0), use_model_front: bool = false) static 🔗

Crea una nueva Basis con una rotación tal que el eje frontal (-Z) apunta hacia la posición target.

Por defecto, el eje -Z (frontal de la cámara) se considera frontal (lo que implica que +X apunta a la derecha). Si use_model_front es true, el eje +Z (frontal del objeto) se considera frontal (lo que implica que +X apunta a la izquierda) y apunta hacia la posición target.

El eje vertical (+Y) apunta lo más cerca posible del vector up, manteniéndose perpendicular al eje frontal. La base resultante está ortonormalizada (véase orthonormalized()).

target y up no pueden ser Vector3.ZERO y no deben ser colineales para evitar rotaciones no deseadas alrededor del eje Z local.

Basis orthonormalized() const 🔗

Devuelve la versión ortonormalizada de esta base. Una base ortonormal es tanto ortogonal (los ejes son perpendiculares entre sí) como normalizada (los ejes tienen una longitud de 1.0), lo que también significa que solo puede representar una rotación.

A menudo resulta útil llamar a este método para evitar errores de redondeo en una base giratoria:

# Rota este Node3D en cada fotograma.
func _process(delta):
    basic = basis.rotated(Vector3.UP, TAU * delta)
    basic = basis.rotated(Vector3.RIGHT, TAU * delta)
    basic = basis.orthonormalized()

// Rota este Node3D en cada fotograma.
public override void _Process(double delta)
{
    Basis = Basis.Rotated(Vector3.Up, Mathf.Tau * (float)delta)
            .Rotated(Vector3.Right, Mathf.Tau * (float)delta)
            .Orthonormalized();
}

Basis rotated(axis: Vector3, angle: float) const 🔗

Devuelve una copia de esta base rotada alrededor del eje axis dado, con el ángulo angle dado (en radianes).

El eje axis debe ser un vector normalizado (véase Vector3.normalized()). Si el ángulo angle es positivo, la base se rota en sentido antihorario alrededor del eje.

var my_basis = Basis.IDENTITY
var angle = TAU / 2

my_basis = my_basis.rotated(Vector3.UP, angle)     # Rotar alrededor del eje vertical (guiñada).
my_basis = my_basis.rotated(Vector3.RIGHT, angle) # Rotar alrededor del eje horizontal (cabeceo).
my_basis = my_basis.rotated(Vector3.BACK, angle)  # Rotar alrededor del eje vertical (balanceo).

var myBasis = Basis.Identity;
var ángulo = Mathf.Tau / 2.0f;

myBasis = myBasis.Rotated(Vector3.Up, ángulo);      // Rotar alrededor del eje vertical (guiñada).
myBasis = myBasis.Rotated(Vector3.Right, ángulo); // Rotar alrededor del eje horizontal (cabeceo).
myBasis = myBasis.Rotated(Vector3.Back, ángulo);   // Rotar alrededor del eje vertical (balanceo).

Basis scaled(scale: Vector3) const 🔗

Devuelve esta base con los componentes de cada eje escalados según los componentes de scale especificados.

Las filas de la matriz base se multiplican por los componentes de scale. Esta operación aplica una escala global (relativa a la matriz padre).

var my_basis = Basis(
    Vector3(1, 1, 1),
    Vector3(2, 2, 2),
    Vector3(3, 3, 3)
)
my_basis = my_basis.scaled(Vector3(0, 2, -2))

print(my_basis.x) # Imprime (0.0, 2.0, -2.0)
print(my_basis.y) # Imprime (0.0, 4.0, -4.0)
print(my_basis.z) # Imprime (0.0, 6.0, -6.0)

var myBasis = new Basis(
    new Vector3(1.0f, 1.0f, 1.0f),
    new Vector3(2.0f, 2.0f, 2.0f),
    new Vector3(3.0f, 3.0f, 3.0f)

myBasis = myBasis.Scaled(new Vector3(0.0f, 2.0f, -2.0f));

GD.Print(myBasis.X); // Imprime (0, 2, -2)
GD.Print(myBasis.Y); // Imprime (0, 4, -4)
GD.Print(myBasis.Z); // Imprime (0, 6, -6)

Basis scaled_local(scale: Vector3) const 🔗

Devuelve esta base con cada eje escalado por el componente correspondiente en el parámetro scale.

Las columnas de la matriz base se multiplican por los componentes de scale. Esta operación es una escala local (relativa a sí misma).

var my_basis = Basis(
    Vector3(1, 1, 1),
    Vector3(2, 2, 2),
    Vector3(3, 3, 3)
)
my_basis = my_basis.scaled_local(Vector3(0, 2, -2))

print(my_basis.x) # Imprime (0.0, 0.0, 0.0)
print(my_basis.y) # Imprime (4.0, 4.0, 4.0)
print(my_basis.z) # Imprime (-6.0, -6.0, -6.0)

var myBasis = new Basis(
    new Vector3(1.0f, 1.0f, 1.0f),
    new Vector3(2.0f, 2.0f, 2.0f),
    new Vector3(3.0f, 3.0f, 3.0f)
);
myBasis = myBasis.ScaledLocal(new Vector3(0.0f, 2.0f, -2.0f));

GD.Print(myBasis.X); // Imprime (0, 0, 0)
GD.Print(myBasis.Y); // Imprime (4, 4, 4)
GD.Print(myBasis.Z); // Imprime (-6, -6, -6)

Basis slerp(to: Basis, weight: float) const 🔗

Realiza una interpolación esférica lineal con la base to, dado un weight. Tanto esta base como to deben representar una rotación.

Ejemplo: Rota suavemente un Node3D a la base objetivo a lo largo del tiempo, con un Tween:

var start_basis = Basis.IDENTITY
var target_basis = Basis.IDENTITY.rotated(Vector3.UP, TAU / 2)

func _ready():
    create_tween().tween_method(interpolate, 0.0, 1.0, 5.0).set_trans(Tween.TRANS_EXPO)

func interpolate(weight):
    basic = start_basis.slerp(target_basis, weight)

float tdotx(with: Vector3) const 🔗

Devuelve el producto escalar transpuesto entre with y el eje x (ver transposed()).

Esto es equivalente a basis.x.dot(vector).

float tdoty(with: Vector3) const 🔗

Devuelve el producto escalar transpuesto entre with y el eje y (ver transposed()).

Esto es equivalente a basis.y.dot(vector).

float tdotz(with: Vector3) const 🔗

Devuelve el producto escalar transpuesto entre with y el eje z (ver transposed()).

Esto es equivalente a basis.z.dot(vector).

Basis transposed() const 🔗

Devuelve la versión transpuesta de esta base. Esto convierte las columnas de la matriz base en filas y sus filas en columnas.

var my_basis = Basis(
    Vector3(1, 2, 3),
    Vector3(4, 5, 6),
    Vector3(7, 8, 9)
)
my_basis = my_basis.transposed()

print(my_basis.x) # Imprime (1.0, 4.0, 7.0)
print(my_basis.y) # Imprime (2.0, 5.0, 8.0)
print(my_basis.z) # Imprime (3.0, 6.0, 9.0)

var myBasis = new Basis(
    new Vector3(1.0f, 2.0f, 3.0f),
    new Vector3(4.0f, 5.0f, 6.0f),
    new Vector3(7.0f, 8.0f, 9.0f)
);
myBasis = myBasis.Transposed();

GD.Print(myBasis.X); // Imprime (1, 4, 7)
GD.Print(myBasis.Y); // Imprime (2, 5, 8)
GD.Print(myBasis.Z); // Imprime (3, 6, 9)

Descripciones de Operadores

bool operator !=(right: Basis) 🔗

Devuelve true si los componentes de ambas matrices Basis no son iguales.

Nota: Debido a errores de precisión de punto flotante, considera usar is_equal_approx() en su lugar, ya que es más confiable.

Basis operator *(right: Basis) 🔗

Transforma (multiplica) la base right por esta base.

Esta es la operación que se realiza entre los nodos Node3D padre e hijo.

Vector3 operator *(right: Vector3) 🔗

Transforma (multiplica) el vector right por esta base, devolviendo un Vector3.

# Base que intercambia los ejes X/Z y duplica la escala.
var my_basis = Basis(Vector3(0, 2, 0), Vector3(2, 0, 0), Vector3(0, 0, 2))
print(my_basis * Vector3(1, 2, 3)) # Imprime (4.0, 2.0, 6.0)

// Base que intercambia los ejes X/Z y duplica la escala.
var myBasis = new Basis(new Vector3(0, 2, 0), new Vector3(2, 0, 0), new Vector3(0, 0, 2));
GD.Print(myBasis * new Vector3(1, 2, 3)); // Imprime (4, 2, 6)

Basis operator *(right: float) 🔗

Multiplica todos los componentes de la Basis por el float dado. Esto afecta a la escala de la base de forma uniforme, redimensionando los 3 ejes por el valor de right.

Basis operator *(right: int) 🔗

Multiplica todos los componentes de la Basis por el int dado. Esto afecta a la escala de la base de forma uniforme, redimensionando los 3 ejes por el valor de right.

Basis operator /(right: float) 🔗

Divide todos los componentes de la Basis por el float dado. Esto afecta a la escala de la base de forma uniforme, redimensionando los 3 ejes por el valor de right.

Basis operator /(right: int) 🔗

Divide todos los componentes de la Basis por el int dado. Esto afecta a la escala de la base de forma uniforme, redimensionando los 3 ejes por el valor de right.

bool operator ==(right: Basis) 🔗

Devuelve true si los componentes de ambas matrices Basis son exactamente iguales.

Nota: Debido a errores de precisión de punto flotante, considera usar is_equal_approx() en su lugar, ya que es más confiable.

Vector3 operator [](index: int) 🔗

Accede a cada eje (columna) de esta base por su índice. El índice 0 es lo mismo que x, el índice 1 es lo mismo que y, y el índice 2 es lo mismo que z.

Nota: En C++, este operador accede a las filas de la matriz de la base, no a las columnas. Para el mismo comportamiento que los lenguajes de script, usa los métodos set_column y get_column.