Transform
The Transform class represents an object's position, rotation, and scale within a 3D space. It facilitates common operations such as moving an object to a new position or by a specified offset, rotating it to face a target point and much more making it essential for handling object transformations in 3D environments and game development scenarios.
Usage
To use this class, add the following require at the top of your script:
Reference
new
Creates a transform object from existing position, rotation, and scale.
Parameters
position(Vector3): The position.rotation(Quaternion): The rotation.scale(Vector3): The scale.
Returns
Transform: new Transform object.
fromJson
Creates a transform object from JSON.
Parameters
json(string): The JSON string.
Returns
Transform: new Transform object.
fromData
Creates a transform object from data.
Parameters
data(table): The data object containing position, rotation, and scale.
Returns
Transform: new Transform object.
toData
Converts the transform into a table representation.
Returns
table: data table.
clone
Clones the transform
Returns
table: cloned transform
toMatrix
Converts this transform to a 4x4 transformation matrix (TRS). The returned matrix follows the same indexing convention as `engine/math/matrix`: m[row][col]. Translation is stored in column 4 (the last column).
Returns
Matrix: transformation matrix
fromMatrix
Decomposes a 4x4 TRS transformation matrix back into a Transform. The matrix is expected to follow the Transform:toMatrix() layout (m[row][col], translation stored in column 4).
Parameters
m(Matrix): The 4x4 transformation matrix.
Returns
Transform: decomposed Transform.
toLocal
Converts this transform (assumed to be expressed in world space) into a transform that is local relative to the given parent transform.
This is the inverse of composing with the parent: if parent is the world transform of a parent object, the returned transform can be applied as the local transform of a child so that the child ends up exactly at this world transform.
Parameters
parent(Transform): The parent (reference) transform in world space.
Returns
Transform: new transform expressed relative to parent.
Example
-- Convert a world-space hit point into a transform local to a parent object,
-- so a spawned child ends up exactly at the hit point:
local worldHit = Transform.new(hitPoint)
local localTransform = worldHit:toLocal(parentObject:getWorldTransform())
child:setTransform(localTransform)
moveTo
Moves the transform to a new position.
Parameters
x(number|Vector3): The x coordinate or a Vector3 position.y(number): The y coordinate (if x is a number).z(number): The z coordinate (if x is a number).
moveBy
Moves the transform by a given offset.
Parameters
x(number|Vector3): The x offset or a Vector3 offset.y(number): The y offset (if x is a number).z(number): The z offset (if x is a number).
scaleTo
Scales the transform to a new scale.
Parameters
x(number|Vector3): The x scale or a Vector3 scale.y(number): The y scale (if x is a number).z(number): The z scale (if x is a number).
scaleBy
Scales the transform by a given factor (component-wise).
Parameters
x(number|Vector3): The x scale factor or a Vector3 scale factor.y(number): The y scale factor (if x is a number).z(number): The z scale factor (if x is a number).
lookAt
Rotates the transform to look at a target position.
Parameters
x(number|Vector3): The target x coordinate or a Vector3 target.y(number|Vector3): The target y coordinate (if x is a number) or the up vector in case x is the look at Vector.z(number): The target z coordinate (if x is a number).up(Vector3): The up direction (default is Vector3(0,1,0)).
rotateTo
Rotates the transform to a specific orientation. Angles are specified in degrees.
Parameters
x(number|Vector3): Rotation around the x-axis, or a Vector3 representing rotation.y(number): Rotation around the y-axis (if x is a number).z(number): Rotation around the z-axis (if x is a number).
rotateBy
Rotates the transform by the given amount. Angles are specified in degrees.
Parameters
x(number|Vector3): Rotation to apply around the x-axis, or a Vector3 representing rotation.y(number): Rotation to apply around the y-axis (if x is a number).z(number): Rotation to apply around the z-axis (if x is a number).
Class: Transform
new
Creates a transform object from existing position, rotation, and scale.
Parameters
position(Vector3): The position.rotation(Quaternion): The rotation.scale(Vector3): The scale.
Returns
Transform: new Transform object.
fromJson
Creates a transform object from JSON.
Parameters
json(string): The JSON string.
Returns
Transform: new Transform object.
fromData
Creates a transform object from data.
Parameters
data(table): The data object containing position, rotation, and scale.
Returns
Transform: new Transform object.
toData
Converts the transform into a table representation.
Returns
table: data table.
clone
Clones the transform
Returns
table: cloned transform
toMatrix
Converts this transform to a 4x4 transformation matrix (TRS). The returned matrix follows the same indexing convention as `engine/math/matrix`: m[row][col]. Translation is stored in column 4 (the last column).
Returns
Matrix: transformation matrix
fromMatrix
Decomposes a 4x4 TRS transformation matrix back into a Transform. The matrix is expected to follow the Transform:toMatrix() layout (m[row][col], translation stored in column 4).
Parameters
m(Matrix): The 4x4 transformation matrix.
Returns
Transform: decomposed Transform.
toLocal
Converts this transform (assumed to be expressed in world space) into a transform that is local relative to the given parent transform.
This is the inverse of composing with the parent: if parent is the world transform of a parent object, the returned transform can be applied as the local transform of a child so that the child ends up exactly at this world transform.
Parameters
parent(Transform): The parent (reference) transform in world space.
Returns
Transform: new transform expressed relative to parent.
Example
-- Convert a world-space hit point into a transform local to a parent object,
-- so a spawned child ends up exactly at the hit point:
local worldHit = Transform.new(hitPoint)
local localTransform = worldHit:toLocal(parentObject:getWorldTransform())
child:setTransform(localTransform)
moveTo
Moves the transform to a new position.
Parameters
x(number|Vector3): The x coordinate or a Vector3 position.y(number): The y coordinate (if x is a number).z(number): The z coordinate (if x is a number).
moveBy
Moves the transform by a given offset.
Parameters
x(number|Vector3): The x offset or a Vector3 offset.y(number): The y offset (if x is a number).z(number): The z offset (if x is a number).
scaleTo
Scales the transform to a new scale.
Parameters
x(number|Vector3): The x scale or a Vector3 scale.y(number): The y scale (if x is a number).z(number): The z scale (if x is a number).
scaleBy
Scales the transform by a given factor (component-wise).
Parameters
x(number|Vector3): The x scale factor or a Vector3 scale factor.y(number): The y scale factor (if x is a number).z(number): The z scale factor (if x is a number).
lookAt
Rotates the transform to look at a target position.
Parameters
x(number|Vector3): The target x coordinate or a Vector3 target.y(number|Vector3): The target y coordinate (if x is a number) or the up vector in case x is the look at Vector.z(number): The target z coordinate (if x is a number).up(Vector3): The up direction (default is Vector3(0,1,0)).
rotateTo
Rotates the transform to a specific orientation. Angles are specified in degrees.
Parameters
x(number|Vector3): Rotation around the x-axis, or a Vector3 representing rotation.y(number): Rotation around the y-axis (if x is a number).z(number): Rotation around the z-axis (if x is a number).
rotateBy
Rotates the transform by the given amount. Angles are specified in degrees.
Parameters
x(number|Vector3): Rotation to apply around the x-axis, or a Vector3 representing rotation.y(number): Rotation to apply around the y-axis (if x is a number).z(number): Rotation to apply around the z-axis (if x is a number).