Intermediate Tutorial


Transform Scripting


20 minutes

Posted on: October 21, 2017

Learn Sumerian
Transform Scripting

Tags

scripting
translation
rotation
scale
lookAt
coordinates
hierarchies

In this tutorial you will learn about:

Transform matrix
Scripting transformations
Scripting rotation
Scripting scale,

In this tutorial, we show you how to control the translation, rotation, and scale using scripts in Amazon Sumerian.

You’ll learn about:

  • Transform scripting
  • Hierarchies

Prerequisites

Before you begin, you should have completed the following tasks and tutorials:

Scene Setup

From the Dashboard, create a new scene or open an existing one.

Rotation, Translation, and Scale

The Transform component positions an entity and all of its vertices in a scene. A typical 3D Transform consists of three properties: Translation, Rotation, and Scale.

Translation

The Translation is simply a three-dimensional vector, describing an entity’s position as 3D coordinates (X, Y, Z). Its default value is the scene origin, (0, 0, 0).

The following script moves the entity along the X axis.

var update = function(args, ctx) {
    ctx.entity.transformComponent.setTranslation(Math.sin(ctx.world.time), 0, 0);
};

Rotation

The Rotation is used to specify an entity’s rotation. It’s represented by a 3x3 matrix, also called a rotation matrix.

The following sample script sets the entity rotation around the Y axis.

var update = function(args, ctx) {
    ctx.entity.transformComponent.setRotation(0, ctx.world.time, 0);
};

If you want to use rotation matrices instead, you can do something like the following code.

var setup = function(args, ctx) {
    ctx.matrix = new sumerian.Matrix3();
};

var update = function(args, ctx) {
    ctx.matrix.fromAngles(0, ctx.world.time, 0);
    ctx.entity.transformComponent.setRotationMatrix(ctx.matrix);
};

If you want to use quaternions values, use the following code.

var setup = function(args, ctx) {
    ctx.quaternion = new sumerian.Quaternion();
    ctx.matrix = new sumerian.Matrix3();
};

var update = function(args, ctx) {
    ctx.quaternion.fromAngleAxis(ctx.world.time, sumerian.Vector3.UNIT_Y);
    ctx.matrix.copyQuaternion(ctx.quaternion);
    ctx.entity.transformComponent.setRotationMatrix(ctx.matrix);
};

Scale

Like the Translation, the Scale is a three-dimensional vector. Its default value is (1, 1, 1) meaning that the entity’s scale is equally proportionate on all three axes. If we use the vector (2, 2, 2) instead, it means that the entity is twice as big on each axis. If we use (2, 1, 1), it means the the entity is twice the size on the X axis compared to the Y and Z axes.

The following script animates the scale of the entity along the X direction.

var update = function(args, ctx) {
    ctx.entity.transformComponent.setScale(2 * Math.abs(Math.sin(ctx.world.time)), 1, 1);
};

Transform Matrix

Now that you have an understanding of the three Transform component properties, you can grasp the full Transform a little better. A Transform is a combination of a translation, a rotation, a scale. These three quantities (two vectors and one matrix), and scaleRotation (a matrix which is not exposed to client), are multiplied into a final Transform matrix. This matrix represents the total, combined result of the transform components. The Transform matrix is always 4x4.

Transform API

You’ve seen that the matrix and vector classes already have some helper functions, and the Transform class brings some more. It’s essentially another matrix (after combining), which means you can combine this matrix with other Transform matrices, apply points or vectors to it, or invert it. There might be special cases where those kinds of operations are necessary if you’re writing an app using advanced Transforms. There are other useful functions, but these functions will also be accessible from the Transform component directly, and we recommend you use them on that level.

Transform Component

The Sumerian engine implements Transform values in the Transform component. The component effectively takes care of all the details, and ensures everything happens in the correct order. Moreover, the Transform component API adds a lot of useful methods.

Transform Component API

The API has functions for adding or directly setting rotation, translation, or scale. There are also getters for accessing these values. To build hierarchies and parent/child relationships between entities, use the attachChild and detachChild functions. You can use the lookAt function to orient an entity in a certain direction.

// Have the entity (Cone) look at the Sphere
// Sphere is moving with the super simple translation script above

var setup = function(args, ctx) {
    ctx.entityToFollow = ctx.world.by.name('Sphere').first();
};

var update = function(args, ctx) {
    ctx.entity.lookAt(ctx.entityToFollow.getTranslation());
    // Could also have used ctx.entity.transformComponent.lookAt(...
    // No need to call setUpdated() when we use the helper functions!
};

Local and Global Coordinates and Hierarchies

The 3D world contains two different coordinate systems and corresponding Transforms. The local Transform orients an entity relative to its parent, and the global Transform is the resulting Transform relative to the root, or the world coordinate. The root is represented by the scene in Sumerian. The Transform component has two Transform members: local transform (local) and world transform.

In the previous examples, we have called setUpdated() on the Transform component after manually editing the individual parts. This tells the engine that the Transforms need to be updated. This is done for efficiency reasons. The engine won’t update unchanged values.

For more control, you could manually call updateTransform() or updateWorldTransform () to trigger these recalculations. When you use the helper methods of the Transform component, you don’t have to call setUpdated()! The engine does this for you automatically.

Now publish and share the scene!

You’ve learned how to control the Translation values using a custom script. To learn more, see the following tutorials:

Back to Tutorials

© 2019 Amazon Web Services, Inc or its affiliates. All rights reserved.