Transform

Position, rotation, and scale for an entity, as the authoring face of the transform the entity holds. Add it to an entity to reach these fields and methods.

Public fields: positionX/Y/Z, rotationX/Y/Z/W (quaternion), scaleX/Y/Z. They hold the entity's LOCAL transform — where it stands relative to its parent — and an entity with no parent stands at those coordinates in the world.

The entity's transform is what the component reports, and the fields mirror it. Adding the component to an entity that already stands somewhere reads that placement into the fields and leaves the entity where it is. A field the init table names is written onto the entity instead, so component.add("Transform", { positionX = 1, positionY = 2, positionZ = 3 }) moves the entity to (1, 2, 3); every axis the table says nothing about keeps the value the entity already holds, so adding it with { scaleY = 2 } alone stretches the entity on Y and leaves it standing where it stood.

Writing one field moves the entity on the axis that field names. The other axes of the same vector are read off the entity first, so a position written after something else moved the entity keeps the move on the axes it says nothing about.

Methods take one table each and are called with a colon:

Method	Argument
t:setPosition({x, y, z})	position table, {x, y, z} or {x =, y =, z =}
t:addPosition({dx, dy, dz})	offset table, added to where the entity stands now
t:setRotation({x, y, z, w})	quaternion table, {x, y, z, w} or {x =, y =, z =, w =}
t:rotateAxisAngle({ax, ay, az}, angle)	axis table, and an angle in radians
t:setScale(2) or t:setScale({x, y, z})	one number for a uniform scale, or a table
t:lookAt(target)	a position table, or an entity id / name / proxy
t:getPosition() / t:getRotation() / t:getScale()	none

setPosition, addPosition, setRotation, rotateAxisAngle and setScale write the entity's local transform. rotateAxisAngle composes onto the rotation the entity already holds, and reads its axis in the frame that rotation is relative to — the parent's, and the world's for an entity with no parent.

The three getters report what the entity's transform holds at the moment they are called, so a rotation written by lookAt — or a position written by another script — reads back through them.

lookAt is the one method on a WORLD position. It takes one target: a position table ({x, y, z} or {x =, y =, z =}), or an entity — an id string, an entity name, or an entity proxy — whose world position is aimed at. It answers whether the rotation was written, and the reason when it was not. The Camera component's lookAt reads the same slot.

local t = entity(id).component.get("Transform")
t:setPosition({ 0, 5, 0 })
t:setScale({ 2, 2, 2 })
t:rotateAxisAngle({ 0, 1, 0 }, math.pi / 2)
local pos = t:getPosition()