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 matrice 3×3 per rappresentare la rotazione e la scala 3D.

Descrizione

Il tipo di Variant integrato Basis è una matrice 3×3 utilizzata per rappresentare rotazione, scala e deformazione. Viene spesso utilizzato all'interno di un Transform3D.

Una Basis è composta da 3 vettori di assi, ciascuno dei quali rappresenta una colonna della matrice: x, y e z. La lunghezza di ciascun asse (Vector3.length()) influenza la scala della base, mentre la direzione di tutti gli assi influenza la rotazione. Di solito questi assi sono perpendicolari tra loro. Tuttavia, quando si ruota un asse individualmente, la base diventa inclinata. L'applicazione di una base inclinata a un modello 3D farà apparire il modello distorto.

Una Basis è:

Ortogonale se i suoi assi sono perpendicolari tra loro.
Normalizzata se la lunghezza di ogni asse è 1.0.
Uniforme se tutti gli assi condividono la stessa lunghezza (vedi get_scale()).
Ortonormale se è sia ortogonale che normalizzata, il che le consente di rappresentare solo rotazioni. (vedi orthonormalized()).
Conforme se è sia ortogonale sia uniforme, il che garantisce che non sia distorta.

Per un'introduzione generale, consulta il tutorial Matrici e trasformazioni.

Nota: Godot utilizza un sistema di coordinate destrorso, che è uno standard comune. Per le direzioni, la convenzione per i tipi integrati come Camera3D prevede che -Z punti in avanti (+X è destra, +Y è su e +Z è indietro). Altri oggetti possono utilizzare convenzioni di direzione diverse. Per ulteriori informazioni, consulta il tutorial Convenzioni sulla direzione delle risorse 3D.

Nota: Le matrici di base sono esposte come ordine di colonna prima, che è lo stesso di OpenGL. Tuttavia, sono memorizzati internamente in ordine di riga prima, che è lo stesso di DirectX.

Nota: In un contesto booleano, una base sarà valutata come false se è uguale a IDENTITY. Altrimenti, una base sarà sempre valutata come true.

Nota

Ci sono differenze sostanziali quando si usa questa API con C#. Vedi Differenze dell'API C# rispetto a GDScript per maggiori informazioni.

Tutorial

Proprietà

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

Costruttori

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)

Metodi

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

Operatori

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)

Costanti

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

La Basis di identità. Questa è una base senza rotazione, senza inclinazione e con una scala pari a Vector3.ONE. Ciò significa anche che:

La x punta a destra (Vector3.RIGHT);
La y punta in alto (Vector3.UP);
La z punta indietro (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])
# Stampa:
# | X | Y | Z
# | 1 | 0 | 0
# | 0 | 1 | 0
# | 0 | 0 | 1

Se un Vector3 o un altra Basis viene trasformata (moltiplicata) per questa costante, non si verifica alcuna trasformazione.

Nota: In GDScript, questa costante è identica alla creazione di una Basis senza parametri. Questa costante può essere usata per rendere il codice più chiaro e per coerenza con C#.

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

Quando qualsiasi base è moltiplicata per FLIP_X, nega tutti i componenti dell'asse x (la colonna X).

Quando FLIP_X è moltiplicata per qualsiasi base, nega il componente Vector3.x di tutti gli assi (la riga X).

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

Quando qualsiasi base è moltiplicata per FLIP_Y, nega tutti i componenti dell'asse y (la colonna Y).

Quando FLIP_Y è moltiplicata per qualsiasi base, nega il componente Vector3.y di tutti gli assi (la riga Y).

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

Quando qualsiasi base è moltiplicata per FLIP_Z, nega tutti i componenti dell'asse z (la colonna Z).

Quando FLIP_Z è moltiplicata per qualsiasi base, nega il componente Vector3.z di tutti gli assi (la riga Z).

Descrizioni delle proprietà

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

L'asse X della base e la colonna 0 della matrice.

Sulla base di identità, questo vettore punta a destra (Vector3.RIGHT).

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

L'asse Y della base e la colonna 1 della matrice.

Sulla base di identità, questo vettore punta in alto (Vector3.UP).

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

L'asse Z della base e la colonna 2 della matrice.

Sulla base di identità, questo vettore punta indietro (Vector3.BACK).

Descrizioni dei costruttori

Basis Basis() 🔗

Costruisce una Basis identica a IDENTITY.

Nota: In C#, costruisce una Basis con tutti i suoi componenti impostati su Vector3.ZERO.

Basis Basis(from: Basis)

Costruisce un Basis come copia del Basis specificato.

Basis Basis(axis: Vector3, angle: float)

Costruisce un Basis che rappresenta solo la rotazione, ruotato intorno all'asse axis per l'angolo angle, in radianti. L'asse deve essere un vettore normalizzato.

Nota: Questo è lo stesso di usare rotated() sulla base IDENTITY. Con più di un angolo considera usare from_euler(), invece.

Basis Basis(from: Quaternion)

Costruisce un Basis che rappresenta solo la rotazione dal Quaternion specificato.

Nota: I quaternioni memorizzano solo la rotazione, non la scala. Per questo motivo, le conversioni da Basis a Quaternion non possono essere sempre invertite.

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

Costruisce un Basis da 3 vettori assi. Queste sono le colonne della matrice base.

Descrizioni dei metodi

float determinant() const 🔗

Restituisce il determinante della matrice di questa base. Per la matematica avanzata, questo numero può servire per determinare alcuni attributi:

Se il determinante è esattamente 0.0, la base non è invertibile (vedi inverse()).
Se il determinante è un numero negativo, la base rappresenta una scala negativa.

Nota: Se la scala della base è la stessa per ogni asse, il suo determinante è sempre quella scala elevata alla potenza di 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 🔗

Costruisce una nuova Basis che rappresenta solo la scala, senza rotazione o inclinazione, dal vettore scale specificato.

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

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

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

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

Nota: Nell'algebra lineare, la matrice di questa base è anche conosciuta come matrice diagonale.

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 🔗

Restituisce la rotazione di questa base come Quaternion.

Nota: I quaternioni sono molto più adatti alla matematica 3D ma sono meno intuitivi. Per le interfacce utente, considera l'utilizzo del metodo get_euler(), che restituisce angoli di Eulero.

Vector3 get_scale() const 🔗

Restituisce la lunghezza di ogni asse di questa base, come Vector3. Se la base non è inclinata, questo è il fattore di scala. Non è influenzato dalla rotazione.

var my_basis = Basis(
    Vector3(2, 0, 0),
    Vector3(0, 4, 0),
    Vector3(0, 0, 8)
)
# Ruotando la base in qualsiasi modo conserva la sua scala.
my_basis = my_basis.rotated(Vector3.UP, TAU / 2)
my_basis = my_basis.rotated(Vector3.RIGHT, TAU / 4)

print(my_basis.get_scale()) # Prints (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)
);
// Ruotando la base in qualsiasi modo conserva la sua scala.
myBasis = myBasis.Rotated(Vector3.Up, Mathf.Tau / 2.0f);
myBasis = myBasis.Rotated(Vector3.Right, Mathf.Tau / 4.0f);

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

Nota: Se il valore restituito da determinant() è negativo, anche la scala è negativa.

Basis inverse() const 🔗

Restituisce l'inverso della matrice di questa base.

bool is_conformal() const 🔗

Restituisce true se questa base è conforme. Una base conforme è sia ortogonale (gli assi sono perpendicolari tra loro) sia uniforme (gli assi condividono la stessa lunghezza). Questo metodo può essere particolarmente utile durante i calcoli di fisica.

bool is_equal_approx(b: Basis) const 🔗

Restituisce true se questa base e b sono approssimativamente eguali, chiamando @GlobalScope.is_equal_approx() su tutti i componenti vettoriali.

bool is_finite() const 🔗

Restituisce true se i valori di questa base sono finiti, chiamando Vector2.is_finite() su tutti i componenti vettoriali.

bool is_orthonormal() const 🔗

Restituisce true se questa base è ortonormale. Una base ortonormale è sia ortogonale (gli assi sono perpendicolari tra loro) sia normalizzata (la lunghezza di ogni asse è 1.0.). Questo metodo può essere particolarmente utile durante i calcoli di fisica.

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

Crea una nuova Basis con una rotazione tale che l'asse in avanti (-Z) punti verso la posizione target.

Come predefinito, l'asse -Z (avanti per la telecamera) viene trattato come "in avanti" (implica che +X sia a destra). 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.

L'asse in alto (+Y) punta il più vicino possibile al vettore up pur rimanendo perpendicolare all'asse in avanti. La base restituita è ortonormalizzata (vedi orthonormalized()).

I vettori target e up non possono essere Vector3.ZERO e non dovrebbero essere collineari per evitare una rotazione involontaria attorno all'asse Z locale.

Basis orthonormalized() const 🔗

Restituisce la versione ortonormalizzata di questa base. Una base ortonormale è sia ortogonale (gli assi sono perpendicolari tra loro) sia normalizzata (gli assi hanno una lunghezza di 1.0), il che significa inoltre che può rappresentare solo la rotazione.

Spesso è utile chiamare questo metodo per evitare errori di arrotondamento su una base in rotazione:

# Ruota questo Node3D ogni frame.
func _process(delta):
    basis = basis.rotated(Vector3.UP, TAU * delta)
    basis = basis.rotated(Vector3.RIGHT, TAU * delta)
    basis = basis.orthonormalized()

// Ruota questo Node3D ogni frame.
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 🔗

Restituisce questa base ruotata attorno all'asse axis di angle (in radianti).

axis deve essere un vettore normalizzato (vedi Vector3.normalized()). Se angle è positivo, la base viene ruotata in senso antiorario attorno all'asse.

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

my_basis = my_basis.rotated(Vector3.UP, angle)    # Ruota intorno all'asse superiore (imbardata).
my_basis = my_basis.rotated(Vector3.RIGHT, angle) # Ruota intorno all'asse destro (beccheggio).
my_basis = my_basis.rotated(Vector3.BACK, angle)  # Ruota intorno all'asse posteriore (rollio).

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

myBasis = myBasis.Rotated(Vector3.Up, angle);    // Ruota intorno all'asse superiore (imbardata).
myBasis = myBasis.Rotated(Vector3.Right, angle); // Ruota intorno all'asse destro (beccheggio).
myBasis = myBasis.Rotated(Vector3.Back, angle);  // Ruota intorno all'asse posteriore (rollio).

Basis scaled(scale: Vector3) const 🔗

Restituisce questa base con i componenti di ciascun asse ridimensionati in base ai componenti di scale.

Le righe della matrice base sono moltiplicate per i componenti di scale. Questa operazione è una scala globale (relativa al genitore).

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) # Stampa (0.0, 2.0, -2.0)
print(my_basis.y) # Stampa (0.0, 4.0, -4.0)
print(my_basis.z) # Stampa (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); // Stampa (0, 2, -2)
GD.Print(myBasis.Y); // Stampa (0, 4, -4)
GD.Print(myBasis.Z); // Stampa (0, 6, -6)

Basis scaled_local(scale: Vector3) const 🔗

Restituisce questa base con i componenti di ciascun asse ridimensionati in base ai componenti di scale.

Le righe della matrice base sono moltiplicate per i componenti di scale. Questa operazione è una scala locale (relativa a se stesso).

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) # Stampa (0.0, 0.0, 0.0)
print(my_basis.y) # Stampa (4.0, 4.0, 4.0)
print(my_basis.z) # Stampa (-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.Scaled(new Vector3(0.0f, 2.0f, -2.0f));

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

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

Esegue un'interpolazione sferico-lineare con la base to, dato un peso weight. Sia questa base che to dovrebbero rappresentare una rotazione.

Esempio: Ruota gradualmente un Node3D sulla base di destinazione nel corso del tempo, 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):
    basis = start_basis.slerp(target_basis, weight)

float tdotx(with: Vector3) const 🔗

Restituisce il prodotto scalare trasposto tra with e l'asse x (vedi transposed()).

Questo è equivalente a basis.x.dot(vector).

float tdoty(with: Vector3) const 🔗

Restituisce il prodotto scalare trasposto tra with e l'asse y (vedi transposed()).

Questo è equivalente a basis.y.dot(vector).

float tdotz(with: Vector3) const 🔗

Restituisce il prodotto scalare trasposto tra with e l'asse z (vedi transposed()).

Questo è equivalente a basis.z.dot(vector).

Basis transposed() const 🔗

Restituisce la versione trasposta di questa base. Ciò trasforma le colonne della matrice base in righe e le sue righe in colonne.

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) # Stampa (1.0, 4.0, 7.0).
print(my_basis.y) # Stampa (2.0, 5.0, 8.0).
print(my_basis.z) # Stampa (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); // Stampa (1, 4, 7).
GD.Print(myBasis.Y); // Stampa (2, 5, 8).
GD.Print(myBasis.Z); // Stampa (3, 6, 9).

Descrizioni degli operatori

bool operator !=(right: Basis) 🔗

Restituisce true se i componenti di entrambe le basi non sono eguali.

Note: A causa di errori di precisione per virgola mobile, considera invece utilizzare is_equal_approx(), che è più affidabile.

Basis operator *(right: Basis) 🔗

Trasforma (moltiplica) la base right per questa base.

Questa è l'operazione eseguita tra genitore e figlio Node3D.

Vector3 operator *(right: Vector3) 🔗

Trasforma (moltiplica) il vettore right per questa base, restituendo un Vector3.

# Base che scambia gli assi X/Z e raddoppia la scala.
var my_basis = Basis(Vector3(0, 2, 0), Vector3(2, 0, 0), Vector3(0, 0, 2))
print(my_basis * Vector3(1, 2, 3)) # Stampa (4.0, 2.0, 6.0)

// Base che scambia gli assi X/Z e raddoppia la scala.
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)); // Prints (4, 2, 6)

Basis operator *(right: float) 🔗

Moltiplica tutti i componenti del Basis per il float indicato. Ciò influenza la scala della base in modo uniforme, ridimensionando tutti e 3 gli assi del valore right.

Basis operator *(right: int) 🔗

Moltiplica tutti i componenti del Basis per l'int indicato. Ciò influenza la scala della base in modo uniforme, ridimensionando tutti e 3 gli assi del valore right.

Basis operator /(right: float) 🔗

Divide tutti i componenti di Basis per il float indicato. Ciò influenza la scala della base in modo uniforme, ridimensionando tutti e 3 gli assi del valore right.

Basis operator /(right: int) 🔗

Divide tutti i componenti di Basis per il int indicato. Ciò influenza la scala della base in modo uniforme, ridimensionando tutti e 3 gli assi del valore right.

bool operator ==(right: Basis) 🔗

Restituisce true se i componenti di entrambe le basi sono esattamente eguali.

Note: A causa di errori di precisione per virgola mobile, considera invece utilizzare is_equal_approx(), che è più affidabile.

Vector3 operator [](index: int) 🔗

Accede a ciascun asse (colonna) di questa base tramite il relativo indice. L'indice 0 è uguale a x, l'indice 1 è uguale a y e l'indice 2 è uguale a z.

Nota: In C++, questo operatore accede alle righe della matrice base, non alle colonne. Per lo stesso comportamento dei linguaggi di scripting, utilizza i metodi set_column e get_column.