Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

Basis

A 3×3 matrix for representing 3D rotation and scale.

Description

The Basis built-in Variant type is a 3x3 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. A basis is normalized if the length of every axis is 1. A basis is uniform if all axes share the same length (see get_scale). A basis is orthonormal if it is both orthogonal and normalized, which allows it to only represent rotations. A basis is 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 Importing 3D Scenes 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.

備註

There are notable differences when using this API with C#. See C# API 與 GDScript 的不同 for more information.

Tutorials

Properties

Vector3

x

Vector3(1, 0, 0)

Vector3

y

Vector3(0, 1, 0)

Vector3

z

Vector3(0, 0, 1)

Constructors

Basis

Basis ( )

Basis

Basis ( Basis from )

Basis

Basis ( Vector3 axis, float angle )

Basis

Basis ( Quaternion from )

Basis

Basis ( Vector3 x_axis, Vector3 y_axis, Vector3 z_axis )

Methods

float

determinant ( ) const

Basis

from_euler ( Vector3 euler, int order=2 ) static

Basis

from_scale ( Vector3 scale ) static

Vector3

get_euler ( int order=2 ) const

Quaternion

get_rotation_quaternion ( ) const

Vector3

get_scale ( ) const

Basis

inverse ( ) const

bool

is_conformal ( ) const

bool

is_equal_approx ( Basis b ) const

bool

is_finite ( ) const

Basis

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

Basis

orthonormalized ( ) const

Basis

rotated ( Vector3 axis, float angle ) const

Basis

scaled ( Vector3 scale ) const

Basis

slerp ( Basis to, float weight ) const

float

tdotx ( Vector3 with ) const

float

tdoty ( Vector3 with ) const

float

tdotz ( Vector3 with ) const

Basis

transposed ( ) const

Operators

bool

operator != ( Basis right )

Basis

operator * ( Basis right )

Vector3

operator * ( Vector3 right )

Basis

operator * ( float right )

Basis

operator * ( int right )

bool

operator == ( Basis right )

Vector3

operator [] ( int index )


Constants

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

The identity basis. This is a basis with no rotation, no shear, and its scale being 1. This means that:

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

This is identical to creating Basis without any parameters. This constant can be used to make your code clearer, and for consistency with C#.

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

When any basis is multiplied by FLIP_X, it negates all components of the x axis (the X column).

When FLIP_X is multiplied by any basis, it negates the Vector3.x component of all axes (the X row).

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

When any basis is multiplied by FLIP_Y, it negates all components of the y axis (the Y column).

When FLIP_Y is multiplied by any basis, it negates the Vector3.y component of all axes (the Y row).

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

When any basis is multiplied by FLIP_Z, it negates all components of the z axis (the Z column).

When FLIP_Z is multiplied by any basis, it negates the Vector3.z component of all axes (the Z row).


Property Descriptions

Vector3 x = Vector3(1, 0, 0)

The basis's X axis, and the column 0 of the matrix.

On the identity basis, this vector points right (Vector3.RIGHT).


Vector3 y = Vector3(0, 1, 0)

The basis's Y axis, and the column 1 of the matrix.

On the identity basis, this vector points up (Vector3.UP).


Vector3 z = Vector3(0, 0, 1)

The basis's Z axis, and the column 2 of the matrix.

On the identity basis, this vector points back (Vector3.BACK).


Constructor Descriptions

Basis Basis ( )

Constructs a Basis identical to the IDENTITY.


Basis Basis ( Basis from )

Constructs a Basis as a copy of the given Basis.


Basis Basis ( Vector3 axis, float angle )

Constructs a Basis that only represents rotation, rotated around the axis by the given angle, in radians. The axis must be a normalized vector.

Note: This is the same as using rotated on the IDENTITY basis. With more than one angle consider using from_euler, instead.


Basis Basis ( Quaternion from )

Constructs a Basis that only represents rotation from the given Quaternion.

Note: Quaternions only store rotation, not scale. Because of this, conversions from Basis to Quaternion cannot always be reversed.


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

Constructs a Basis from 3 axis vectors. These are the columns of the basis matrix.


Method Descriptions

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


Basis from_euler ( Vector3 euler, int order=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(TA