Transform

The transform component is a core component that provides an entity with a 3D orientation, position and uniform scale. For further details on all properties associated with this component and how to use this component with scripting, please see the API documentation.

All entities have a transform component. Transform components cannot be detached from entities.

Properties

The transform component properties that are accessible through the inspector.

Rotation

The local rotation of the entity. It is represented internally as a quaternion but displayed in the inspector using XYZ Euler angles.

Position

The local position of the entity.

Scale

The local uniform scale of the entity.

Coordinate System

The transform represents a coordinate system. Any children of the entity have orientation, position and scale in the coordinate system of the parent. Scaling the parent will affect the world scale of all descendant entities in the hierarchy. ProtoTwin does not support non-uniform scaling for transforms. This was a deliberate decision, since non-uniform scaling combined with rotation causes skewing. Instead, we support non-uniform scaling of the graphical mesh through a property on the graphics component.

Scripting

You can set the rotation, position and scale of the entity in world-space using the properties worldRotation, worldPosition and worldScale respectively. Similarly, the properties rotation, position and scale can be used to set the rotation, position and scale of the entity local to the coordinate system of the parent. For example, the scripted component below sets the local rotation of the entity to a unit quaternion that rotates 45 degrees about the x-axis, and the world position of the entity to (0, 1, 5) at initialization.

import { type Entity, Component, Quat, Vec3 } from "prototwin";

export class Script extends Component {
    constructor(entity: Entity) {
        super(entity);
    }

    public override initialize(): void {
        this.entity.rotation = Quat.x(Math.PI / 4);
        this.entity.worldPosition = new Vec3(0, 1, 5);
    }
}

Making the distinction of whether to set the position in local-space or worldPosition world-space is critical when the entity has a parent. If the entity does not have a parent, then setting the position or worldPosition are equivalent.

You can use the method localToWorldPoint() to transform a point from local-space to world-space. Conversely, the method worldToLocalPoint() transforms a point from world-space to local-space.