Transform Components

Position, rotation, scale, and hierarchy components for 3D spatial representation.

Transform components define where entities exist in 3D space and how they relate to each other through parent-child hierarchies. Web Engine uses a dual-transform system with world and local transforms for efficient hierarchy management.

Transform#

The Transform component represents the final calculated position, rotation, and scale of an entity in world space. This is the authoritative transform used by rendering and physics systems.

Properties#

Property	Type	Default	Description
position	[f32, 3]	[0, 0, 0]	World position in meters [x, y, z]
rotation	[f32, 3]	[0, 0, 0]	Euler angles in radians [pitch, yaw, roll]
scale	[f32, 3]	[1, 1, 1]	Scale factors [x, y, z]
quaternion	[f32, 4]	[0, 0, 0, 1]	Rotation quaternion [x, y, z, w]
parent	eid	0	Optional parent entity ID for hierarchy

World Space

Transform values are always in world space. If an entity has a parent, the TransformSystem automatically computes world transform from LocalTransform.

Usage#

import { addComponent, Transform } from '@web-engine/core';
 
// Create entity with position
const entity = world.addEntity();
addComponent(world, Transform, entity);
Transform.position[entity][0] = 10.0; // x
Transform.position[entity][1] = 5.0;  // y
Transform.position[entity][2] = 0.0;  // z
 
// Set rotation (Euler angles in radians)
Transform.rotation[entity][0] = 0.0;        // pitch
Transform.rotation[entity][1] = Math.PI / 2; // yaw (90 degrees)
Transform.rotation[entity][2] = 0.0;        // roll
 
// Set scale
Transform.scale[entity][0] = 2.0; // double width
Transform.scale[entity][1] = 1.0;
Transform.scale[entity][2] = 1.0;

LocalTransform#

The LocalTransform component represents position, rotation, and scale relative to a parent entity. When an entity has no parent, local transform is equivalent to world transform.

Properties#

Property	Type	Default	Description
position	[f32, 3]	[0, 0, 0]	Position relative to parent [x, y, z]
rotation	[f32, 3]	[0, 0, 0]	Euler angles relative to parent [pitch, yaw, roll]
scale	[f32, 3]	[1, 1, 1]	Scale relative to parent [x, y, z]
quaternion	[f32, 4]	[0, 0, 0, 1]	Rotation quaternion relative to parent

Usage#

import { addComponent, LocalTransform, Parent } from '@web-engine/core';
 
// Create parent entity
const parent = world.addEntity();
addComponent(world, Transform, parent);
Transform.position[parent][1] = 10.0; // 10 meters above origin
 
// Create child entity
const child = world.addEntity();
addComponent(world, Transform, child);
addComponent(world, LocalTransform, child);
addComponent(world, Parent, child);
 
// Set parent relationship
Parent.eid[child] = parent;
 
// Set local transform (relative to parent)
LocalTransform.position[child][0] = 2.0; // 2 meters to the right of parent
LocalTransform.position[child][1] = 0.0;
LocalTransform.position[child][2] = 0.0;
 
// TransformSystem will compute world position as [2, 10, 0]

Parent#

The Parent component defines hierarchical relationships between entities. Entities with this component inherit transforms from their parent.

Properties#

Property	Type	Default	Description
eid	ui32	0	Entity ID of the parent entity

Transform Propagation

When a parent moves, all children automatically update their world transforms. This happens in the TransformSystem during the transform update phase.

SiblingIndex#

The SiblingIndex component stores the index of an entity among its siblings, preserving hierarchy order in the editor and scene serialization.

Properties#

Property	Type	Default	Description
value	ui32	0	Index among siblings (0-based)

TransformDirty#

The TransformDirty component marks entities whose transform has changed and needs synchronization with rendering/physics systems.

Properties#

Property	Type	Default	Description
flags	ui8	0	Bitmask of TransformDirtyFlag values

Performance

TransformDirty is automatically managed by the engine. Systems only process entities marked as dirty, avoiding unnecessary matrix computations.

Transform Hierarchy#

Web Engine supports nested entity hierarchies where children inherit parent transforms. This is essential for complex models, articulated objects, and scene organization.

Hierarchy Example#

// Create a tank with turret and barrel hierarchy
const tank = world.addEntity();
addComponent(world, Transform, tank);
Transform.position[tank] = [0, 0, 0];
 
const turret = world.addEntity();
addComponent(world, Transform, turret);
addComponent(world, LocalTransform, turret);
addComponent(world, Parent, turret);
Parent.eid[turret] = tank;
LocalTransform.position[turret] = [0, 1.5, 0]; // 1.5m above tank
 
const barrel = world.addEntity();
addComponent(world, Transform, barrel);
addComponent(world, LocalTransform, barrel);
addComponent(world, Parent, barrel);
Parent.eid[barrel] = turret;
LocalTransform.position[barrel] = [0, 0.5, 2]; // Front of turret
 
// Rotating turret rotates barrel too (hierarchy propagation)
LocalTransform.rotation[turret][1] = Math.PI / 4; // 45 degrees

Transform Math Utilities#

Web Engine provides utilities for common transform operations like looking at targets, computing forward vectors, and converting between Euler angles and quaternions.

Common Operations#

import { Transform } from '@web-engine/core';
import { Vector3, Quaternion, Euler } from 'three';
 
// Get forward vector from rotation
const forward = new Vector3(0, 0, -1);
const quat = new Quaternion(
  Transform.quaternion[entity][0],
  Transform.quaternion[entity][1],
  Transform.quaternion[entity][2],
  Transform.quaternion[entity][3]
);
forward.applyQuaternion(quat);
 
// Look at target
const position = new Vector3(...Transform.position[entity]);
const target = new Vector3(10, 0, 10);
const lookQuat = new Quaternion().setFromRotationMatrix(
  new Matrix4().lookAt(position, target, new Vector3(0, 1, 0))
);
Transform.quaternion[entity][0] = lookQuat.x;
Transform.quaternion[entity][1] = lookQuat.y;
Transform.quaternion[entity][2] = lookQuat.z;
Transform.quaternion[entity][3] = lookQuat.w;
 
// Convert Euler to Quaternion
const euler = new Euler(
  Transform.rotation[entity][0],
  Transform.rotation[entity][1],
  Transform.rotation[entity][2]
);
const quaternion = new Quaternion().setFromEuler(euler);
Transform.quaternion[entity][0] = quaternion.x;
Transform.quaternion[entity][1] = quaternion.y;
Transform.quaternion[entity][2] = quaternion.z;
Transform.quaternion[entity][3] = quaternion.w;

Three.js Integration

Web Engine uses Three.js math utilities internally. You can use the same Vector3, Quaternion, and Euler classes for transform calculations.

Best Practices#

Use LocalTransform + Parent for hierarchical objects (character limbs, vehicle parts)
Use Transform only for independent objects (props, projectiles)
Prefer quaternions for rotation when interpolating or avoiding gimbal lock
Update transforms in FixedUpdate for physics-driven objects
Use TransformDirty to track changes for efficient updates
Keep hierarchies shallow (2-4 levels max) for best performance

PreviousComponents OverviewAll component categories NextRendering ComponentsVisual and camera components