Interface ScreenTransform

Used for positioning objects in 2d screen space. It overrides the regular Transform component on the SceneObject it's attached to.

See the Screen Transform guide for more information.

Example

// @input Component.ScreenTransform screenTransform

// Move the ScreenTransform's anchor center
script.screenTransform.anchors.setCenter(new vec2(-0.25, 0.5));

// Change the ScreenTransform's anchor size
script.screenTransform.anchors.setSize(new vec2(0.25, 0.25));

// @input Component.ScreenTransform screenTransform

// Move the ScreenTransform to match the position of touch events
function onTouch(eventData) {
	var touchPos = eventData.getTouchPosition();
	var parentPos = script.screenTransform.screenPointToParentPoint(touchPos);
	script.screenTransform.anchors.setCenter(parentPos);
}

script.createEvent("TouchStartEvent").bind(onTouch);
script.createEvent("TouchMoveEvent").bind(onTouch);

// @input Component.ScreenTransform screenTransform

// Check if a touch starts inside the ScreenTransform
script.createEvent("TouchStartEvent").bind(function(eventData) {
	var touchPos = eventData.getTouchPosition();
	if (script.screenTransform.containsScreenPoint(touchPos)) {
		print("contains screen point!");
	}
});

// @input Component.ScreenTransform screenTransform
// @input Component.ScreenTransform other

// Move the ScreenTransform to match the world position of another ScreenTransform
var worldPos = script.other.localPointToWorldPoint(new vec2(0, 0));
var parentPos = script.screenTransform.worldPointToParentPoint(worldPos);
script.screenTransform.anchors.setCenter(parentPos);
interface ScreenTransform {
    anchors: Rect;
    enabled: boolean;
    enableDebugRendering: boolean;
    offsets: Rect;
    pivot: vec2;
    position: vec3;
    rotation: quat;
    scale: vec3;
    sceneObject: SceneObject;
    uniqueIdentifier: string;
    containsLocalPoint(localPoint: vec2): boolean;
    containsScreenPoint(screenPoint: vec2): boolean;
    containsWorldPoint(worldPoint: vec3): boolean;
    destroy(): void;
    getSceneObject(): SceneObject;
    getTransform(): Transform;
    getTypeName(): string;
    isInScreenHierarchy(): boolean;
    isOfType(type: string): boolean;
    isSame(other: ScriptObject): boolean;
    localPointToScreenPoint(relativeLocalPoint: vec2): vec2;
    localPointToWorldPoint(relativeLocalPoint: vec2): vec3;
    screenPointToLocalPoint(screenPoint: vec2): vec2;
    screenPointToParentPoint(screenPoint: vec2): vec2;
    worldPointToLocalPoint(worldPoint: vec3): vec2;
    worldPointToParentPoint(worldPoint: vec3): vec2;
}

Hierarchy (view full)

Properties

anchors enabled enableDebugRendering offsets pivot position rotation scale sceneObject uniqueIdentifier

Methods

containsLocalPoint containsScreenPoint containsWorldPoint destroy getSceneObject getTransform getTypeName isInScreenHierarchy isOfType isSame localPointToScreenPoint localPointToWorldPoint screenPointToLocalPoint screenPointToParentPoint worldPointToLocalPoint worldPointToParentPoint

Properties

anchors

anchors: Rect

The anchor rect positioning this ScreenTransform proportional to its parent's bounds. For each field, a value of 0 equals the parent's center point, and value of -1 or 1 (depending on the side) equals the parent's full boundary.

For example, a top value of 1.0 means this ScreenTransform's top edge will be exactly at the top edge of its parent.

A bottom value of -0.5 means this ScreenTransform's bottom edge will be halfway between its parent's bottom edge and center.

A right value of 0 means this ScreenTransform's right edge will be exactly at its parent's center.

A left value of -2 means this ScreenTransform's left edge will be twice as far from its parent's center as its parent's left edge is.

enabled

enabled: boolean

If disabled, the Component will stop enacting its behavior.

enableDebugRendering

enableDebugRendering: boolean

offsets

offsets: Rect

This rect is applied after anchors to determine the final boundaries of the ScreenTransform. It adds an offset in world units (based on the parent Camera's size property) to each edge of the ScreenTransform's boundaries.

For example, a value of 0 for any side will have no effect on boundaries.

A value of 1.0 for any side will offset that edge by 1.0 world unit.

pivot

pivot: vec2

Normalized (x, y) position of the center point used in rotation. (-1, -1) being bottom left, (0, 0) being center, and (1, 1) being top right of the image.

position

position: vec3

Basic local position in world units relative to the parent's center. Useful for animating screen elements with a simple offset.

rotation

rotation: quat

Basic local rotation applied to the SceneObject.

scale

scale: vec3

Basic local scaling applied to the SceneObject.

ReadonlysceneObject

sceneObject: SceneObject

ReadonlyuniqueIdentifier

uniqueIdentifier: string

Methods

containsLocalPoint

  • containsLocalPoint(localPoint): boolean

  • Returns true if the local point is within the boundaries of this ScreenTransform--that is: its position is within -1 and 1 in both the x and y coordinates.

    Parameters

    Returns boolean

containsScreenPoint

  • containsScreenPoint(screenPoint): boolean

  • Returns true if the screen position is within the boundaries of this ScreenTransform. Useful for checking if a touch event overlaps with this object. This function will calculate the ScreenPoint by heuristically looking for a camera: first checking for a camera in it's parent's hierarchy, then looking for a camera with the same render layer, and finally just choosing the first camera in the scene.

    Parameters

    Returns boolean

containsWorldPoint

  • containsWorldPoint(worldPoint): boolean

  • Returns true if the world position is within the boundaries of this ScreenTransform. The z value of the world position is ignored.

    Parameters

    Returns boolean

destroy

  • destroy(): void

  • Destroys the component.

    Returns void

getSceneObject

getTransform

getTypeName

  • getTypeName(): string

  • Returns the name of this object's type.

    Returns string

isInScreenHierarchy

  • isInScreenHierarchy(): boolean

  • Returns true if this ScreenTransform is in a valid screen hierarchy, which is required for anchoring to work. To be in a valid screen hierarchy there must be a Camera component upward in the parent hierarchy, and every object between the Camera and this one must also have a ScreenTransform.

    Returns boolean

isOfType

  • isOfType(type): boolean

  • Returns true if the object matches or derives from the passed in type.

    Parameters

    • type: string

    Returns boolean

isSame

  • isSame(other): boolean

  • Returns true if this object is the same as other. Useful for checking if two references point to the same thing.

    Parameters

    Returns boolean

localPointToScreenPoint

  • localPointToScreenPoint(relativeLocalPoint): vec2

  • Converts from a normalized (-1 to 1) position within this ScreenTransform's bounds to a screen position. This function will calculate the ScreenPoint by heuristically looking for a camera: first checking for a camera in it's parent's hierarchy, then looking for a camera with the same render layer, and finally just choosing the first camera in the scene.

    Parameters

    • relativeLocalPoint: vec2

    Returns vec2

localPointToWorldPoint

  • localPointToWorldPoint(relativeLocalPoint): vec3

  • Converts from a normalized (-1 to 1) position within this ScreenTransform's bounds to a world position.

    Parameters

    • relativeLocalPoint: vec2

    Returns vec3

screenPointToLocalPoint

  • screenPointToLocalPoint(screenPoint): vec2

  • Converts from a screen position to a normalized (-1 to 1) position within this ScreenTransform's bounds.

    Parameters

    Returns vec2

screenPointToParentPoint

  • screenPointToParentPoint(screenPoint): vec2

  • Converts from a screen position to a normalized (-1 to 1) position within the parent object's bounds. This value is useful because it can be used directly for this ScreenTransform's anchor positioning.

    Parameters

    Returns vec2

worldPointToLocalPoint

  • worldPointToLocalPoint(worldPoint): vec2

  • Converts from a world position to a normalized (-1 to 1) position within this ScreenTransform's bounds.

    Parameters

    Returns vec2

worldPointToParentPoint

  • worldPointToParentPoint(worldPoint): vec2

  • Converts from a world position to a normalized (-1 to 1) position within the parent object's bounds. This value is useful because it can be used directly for this ScreenTransform's anchor positioning.

    Parameters

    Returns vec2

Settings

Member Visibility

On This Page

Properties
Methods