Skip to content
Download
API reference

Spatial2D

Inherits: CanvasItem < Actor < Object

Inherited by: AnimatedSprite2D, AudioListener2D, AudioStreamPlayer2D, BackBufferCopy, Bone2D, CPUParticles2D, Camera2D, CanvasGroup, CanvasModulate, CollisionObject2D, CollisionPolygon2D, CollisionShape2D, GPUParticles2D, Joint2D, Light2D, LightOccluder2D, Line2D, Marker2D, MeshInstance2D, MultiMeshInstance2D, NavigationLink2D, NavigationObstacle2D, NavigationRegion2D, Parallax2D, Path2D, PathFollow2D, PlayerStart2D, Polygon2D, ProceduralGenerator2D, ProceduralSource2D, RayCast2D, RemoteTransform2D, ShapeCast2D, Skeleton2D, Sprite2D, TileMapLayer, TouchScreenButton, VisibleOnScreenNotifier2D

A 2D game object, inherited by all 2D-related actors. Has a position, rotation, scale, and skew.

A 2D game object, with a transform (position, rotation, and scale). All 2D actors, including physics objects and sprites, inherit from Spatial2D. Use Spatial2D as a parent actor to move, scale and rotate children in a 2D project. Also gives control of the actor’s render order.

Note: Since both Spatial2D and Control inherit from CanvasItem, they share several concepts from the class such as the CanvasItem.z_index and CanvasItem.visible properties.

TypeNameDefault
Vector2global_position
floatglobal_rotation
floatglobal_rotation_degrees
Vector2global_scale
floatglobal_skew
Transform2Dglobal_transform
Vector2positionVector2(0, 0)
floatrotation0.0
floatrotation_degrees
Vector2scaleVector2(1, 1)
floatskew0.0
Transform2Dtransform
ReturnsMethod
voidapply_scale(ratio)
floatget_angle_to(point)
Transform2Dget_relative_transform_to_parent(parent)
voidglobal_translate(offset)
voidlook_at(point)
voidmove_local_x(delta, scaled)
voidmove_local_y(delta, scaled)
voidrotate(radians)
Vector2to_global(local_point)
Vector2to_local(global_point)
voidtranslate(offset)

Vector2 global_position

Setter/getter: set_global_position(), get_global_position()

Global position. See also position.

float global_rotation

Setter/getter: set_global_rotation(), get_global_rotation()

Global rotation in radians. See also rotation.

float global_rotation_degrees

Setter/getter: set_global_rotation_degrees(), get_global_rotation_degrees()

Helper property to access global_rotation in degrees instead of radians. See also rotation_degrees.

Vector2 global_scale

Setter/getter: set_global_scale(), get_global_scale()

Global scale. See also scale.

float global_skew

Setter/getter: set_global_skew(), get_global_skew()

Global skew in radians. See also skew.

Transform2D global_transform

Setter/getter: set_global_transform(), get_global_transform()

Global Transform2D. See also transform.

Vector2 position = Vector2(0, 0)

Setter/getter: set_position(), get_position()

Position, relative to the actor’s parent. See also global_position.

float rotation = 0.0

Setter/getter: set_rotation(), get_rotation()

Rotation in radians, relative to the actor’s parent. See also global_rotation.

Note: This property is edited in the inspector in degrees. If you want to use degrees in a script, use rotation_degrees.

float rotation_degrees

Setter/getter: set_rotation_degrees(), get_rotation_degrees()

Helper property to access rotation in degrees instead of radians. See also global_rotation_degrees.

Vector2 scale = Vector2(1, 1)

Setter/getter: set_scale(), get_scale()

The actor’s scale, relative to the actor’s parent. Unscaled value: (1, 1). See also global_scale.

Note: Negative X scales in 2D are not decomposable from the transformation matrix. Due to the way scale is represented with transformation matrices in Gobu, negative scales on the X axis will be changed to negative scales on the Y axis and a rotation of 180 degrees when decomposed.

float skew = 0.0

Setter/getter: set_skew(), get_skew()

If set to a non-zero value, slants the actor in one direction or another. This can be used for pseudo-3D effects. See also global_skew.

Note: Skew is performed on the X axis only, and between rotation and scaling.

Note: This property is edited in the inspector in degrees. If you want to use degrees in a script, use skew = deg_to_rad(value_in_degrees).

Transform2D transform

Setter/getter: set_transform(), get_transform()

The actor’s Transform2D, relative to the actor’s parent. See also global_transform.

void apply_scale(ratio: Vector2)

Multiplies the current scale by the ratio vector.

float get_angle_to(point: Vector2) const

Returns the angle between the actor and the point in radians. See also look_at().

Illustration of the returned angle.

Transform2D get_relative_transform_to_parent(parent: Actor) const

Returns the Transform2D relative to this actor’s parent.

void global_translate(offset: Vector2)

Adds the offset vector to the actor’s global position.

void look_at(point: Vector2)

Rotates the actor so that its local +X axis points towards the point, which is expected to use global coordinates. This method is a combination of both rotate() and get_angle_to().

point should not be the same as the actor’s position, otherwise the actor always looks to the right.

void move_local_x(delta: float, scaled: bool = false)

Applies a local translation on the actor’s X axis with the amount specified in delta. If scaled is false, normalizes the movement to occur independently of the actor’s scale.

void move_local_y(delta: float, scaled: bool = false)

Applies a local translation on the actor’s Y axis with the amount specified in delta. If scaled is false, normalizes the movement to occur independently of the actor’s scale.

void rotate(radians: float)

Applies a rotation to the actor, in radians, starting from its current rotation. This is equivalent to rotation += radians.

Vector2 to_global(local_point: Vector2) const

Transforms the provided local position into a position in global coordinate space. The input is expected to be local relative to the Spatial2D it is called on. e.g. Applying this method to the positions of child actors will correctly transform their positions into the global coordinate space, but applying it to an actor’s own position will give an incorrect result, as it will incorporate the actor’s own transformation into its global position.

Vector2 to_local(global_point: Vector2) const

Transforms the provided global position into a position in local coordinate space. The output will be local relative to the Spatial2D it is called on. e.g. It is appropriate for determining the positions of child actors, but it is not appropriate for determining its own position relative to its parent.

void translate(offset: Vector2)

Translates the actor by the given offset in local coordinates. This is equivalent to position += offset.