Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/sanchedev/tiny-engine/llms.txt

Use this file to discover all available pages before exploring further.

Transform is the fundamental layout node in tiny-engine. It has no visual representation of its own; instead it applies a position offset to the canvas context before drawing its children, so every descendant inherits the world-space coordinate system automatically. Use Transform whenever you want to group game objects under a shared coordinate system — a character body and its attached sprite, a UI panel with multiple children, or any logical hierarchy you want to move as one unit.

​
Usage

import { Vector2 } from 'tiny-engine'
import { useRefNode, useEvent } from 'tiny-engine/hooks'
import { PrimaryNode } from 'tiny-engine/nodes/enum'

function Player() {
  const body = useRefNode(PrimaryNode.Transform)

  useEvent(body, 'updated', (delta) => {
    body.node.position.x += delta * 120
  })

  return (
    <transform ref={body} position={new Vector2(100, 200)}>
      <sprite textureId={PLAYER_TEXTURE} sourceSize={new Vector2(32, 32)} />
    </transform>
  )
}

​
Props

​
position
VectorLike | SignalGetter<VectorLike>
The node’s local position in the 2D plane. Accepts a Vector2, a plain {x, y} object, a [x, y] tuple, or a single number (uniform). Defaults to Vector2.ZERO. Reactive when a SignalGetter is passed.
​
ref
NodeRef<PrimaryNode.Transform>
A ref object created by useRefNode(PrimaryNode.Transform). Attach it to access the underlying Transform instance at runtime.
​
script
TinyScript<PrimaryNode.Transform>
An optional script object whose lifecycle methods are called automatically alongside the node’s own lifecycle.
​
id
string | symbol
An optional identifier for this node. Must match [a-zA-Z][a-zA-Z0-9-_]* when a string. Used with node.child({ path, type }) to locate descendants by path.
​
zIndex
number
Draw order among siblings. Higher values are drawn on top. Defaults to 0.
​
deltaIncrease
number
Speed multiplier applied to delta for this node and all its descendants. 0.5 = half-speed, 2 = double-speed. Defaults to 1.
​
children
Node[]
Child nodes nested inside this transform. All children inherit the transform’s world-space coordinate system.

​
Events

Subscribe to node lifecycle events using useEvent.
Event nameCallback signatureDescription
started() => voidFires once when the node finishes start().
updated(delta: number) => voidFires every frame during the update cycle.
drawed(delta: number) => voidFires every frame during the draw cycle.
destroyed() => voidFires once when the node is destroyed.
const body = useRefNode(PrimaryNode.Transform)

// Move 120 px/s to the right
useEvent(body, 'updated', (delta) => {
  body.node.position.x += delta * 120
})

// Clean up when removed from scene
useEvent(body, 'destroyed', () => {
  console.log('Transform destroyed')
})

​
Nesting example

Nest any node type as a child. The child’s position is relative to the parent transform’s origin. 
import { Vector2 } from 'tiny-engine'
import { useRefNode, useEvent } from 'tiny-engine/hooks'
import { PrimaryNode } from 'tiny-engine/nodes/enum'

const PLAYER_TEXTURE = await loadTexture('/assets/player.png')
const SHIELD_TEXTURE = await loadTexture('/assets/shield.png')

function Player() {
  const body = useRefNode(PrimaryNode.Transform)

  // Move the whole group — sprite + shield move together
  useEvent(body, 'updated', (delta) => {
    body.node.position.x += delta * 100
  })

  return (
    <transform ref={body} position={new Vector2(64, 64)}>
      {/* Rendered at the parent's origin */}
      <sprite textureId={PLAYER_TEXTURE} sourceSize={new Vector2(32, 32)} />

      {/* Offset 4px to the left of the parent's origin */}
      <sprite
        textureId={SHIELD_TEXTURE}
        position={new Vector2(-4, 0)}
        sourceSize={new Vector2(8, 32)}
      />
    </transform>
  )
}
Transform itself never renders pixels. If you need a visible shape at the same position, add a Sprite node as a child.
  • Sprite — add a texture inside a transform
  • Collider — attach a physics shape as a child
  • useRefNode — access the node instance at runtime
  • useEvent — subscribe to node events

Build docs developers (and LLMs) love

Get started for freeTalk to us