Copy LinkCopied!Transform

A transform is a mathematical representation that combines position, rotation, and scale into a single data structure. It defines where an object is placed and oriented in 2D or 3D space, as well as its size.

Rather than storing these properties separately, a transform uses a matrix (a grid of numbers) to represent them all at once. Transforms are used under the hood by game engines to efficiently calculate the final position, rotation, and scale of objects in the running game, with much better performance than if they were calculated separately.

In Godot, every Node2D and Node3D has a transform property:

• In 2D, it's a value of type Transform2D, a 3×2 matrix (6 numbers total)
• In 3D, it's a value of type Transform3D, a 4×4 matrix (16 numbers total)

Concretely, a transform is made up of the following components:

• Position: The object's location in the game world, either relative to its parent or to the origin of the game world
• Axes: The object's orientation, represented by perpendicular vectors that define the object's local coordinate system

Working directly with transforms is common in 3D space because the position, rotation, and scale of an object are often interdependent. Very often, you want to move 3D characters in the direction they are facing, and for that we use the transform's basis vectors (the object's orientation axes).

Here's a minimal example of moving a character forward along its own negative z-axis (forward direction) in 3D:

func _physics_process(delta: float) -> void:
	const MOVE_SPEED := 5.0
	var forward_direction := -transform.basis.z
	position += forward_direction * MOVE_SPEED * delta