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.

useRefNode creates a typed reference to a scene-graph node. Pass the returned NodeReference as the ref prop on a JSX node; once the node mounts, ref.node is populated with the live instance. This is the primary way to imperatively access a node’s properties and events from inside a component.

​
useRefNode

​
Signature

useRefNode<T extends PrimaryNode>(type: T): NodeReference<T>

​
Parameters

​
type
PrimaryNode
required
The node type to reference. Must be one of the PrimaryNode enum values. The type parameter T is inferred automatically from this argument, so ref.node is fully typed.Available values: PrimaryNode.Transform, PrimaryNode.Sprite, PrimaryNode.AnimationPlayer, PrimaryNode.Collider, PrimaryNode.RayCast, PrimaryNode.Clickable, PrimaryNode.Timer, PrimaryNode.Rectangle.

​
Return value

NodeReference<T> — an object with a node getter that returns the live node instance. Accessing node before the node has mounted throws a NodeNotInitializedError. 
class NodeReference<T extends PrimaryNode> {
  get node(): NodeInstances[T]  // throws if not yet mounted
  set node(node: NodeInstances[T])
}

​
Example — ref to a sprite

Player.tsx
import { useRefNode, useMount } from 'tiny-engine/hooks'
import { PrimaryNode } from 'tiny-engine'

function Player() {
  const sprite = useRefNode(PrimaryNode.Sprite)

  useMount(() => {
    // sprite.node is available here — node has started
    console.log('Sprite position:', sprite.node.position)
  })

  return (
    <transform>
      <sprite ref={sprite} textureId={PLAYER_TEXTURE} />
    </transform>
  )
}

​
Example — ref used with useSpawn

Arena.tsx
import { useRefNode, useSpawn } from 'tiny-engine/hooks'
import { PrimaryNode } from 'tiny-engine'

function Arena() {
  const container = useRefNode(PrimaryNode.Transform)
  const spawn = useSpawn(container)

  return (
    <transform ref={container}>
      <clickable size={[64, 32]} onClick={() => spawn(<Enemy />)} />
    </transform>
  )
}

​
useChild

useChild retrieves a descendant node by path and type after the root node has started. Use it when you need a reference to a node that is deep inside the JSX tree rather than a direct child.

​
Signature

useChild<T extends PrimaryNode>(
  path: (string | symbol)[],
  type: T,
): NodeReference<T>

​
Parameters

​
path
(string | symbol)[]
required
An ordered array of node id values that form the path from the component’s root node to the target. Each segment must match a node’s id prop.
​
type
PrimaryNode
required
The expected node type at the end of the path. Throws NodeTypeMismatchError if the found node has a different type.

​
Example

Arena.tsx
import { useChild } from 'tiny-engine/hooks'
import { PrimaryNode } from 'tiny-engine'

function Arena() {
  // Finds <sprite id="playerSprite" /> nested inside <transform id="playerBody" />
  const playerSprite = useChild(['playerBody', 'playerSprite'], PrimaryNode.Sprite)

  return (
    <transform>
      <transform id="playerBody">
        <sprite id="playerSprite" textureId={PLAYER_TEXTURE} />
      </transform>
    </transform>
  )
}
useChild requires a single root node in the component. It throws HookRequiresNodeRootError if the component returns multiple root-level nodes. The reference is resolved when the root node fires its started event.

​
useScript

useScript retrieves the TinyScript instance attached to a node reference. The script is available inside useMount or event callbacks — not synchronously at component setup time.

​
Signature

useScript<T extends TinyScript<PrimaryNode>>(
  node: NodeReference<PrimaryNode>,
): Reference<T | undefined>

​
Parameters

​
node
NodeReference<PrimaryNode>
required
A node reference whose script property should be read. Create this with useRefNode.

​
Return value

Reference<T | undefined> — a mutable ref whose .current property is the script instance once the node has mounted, or undefined before that.

​
Example

Player.tsx
import { useRefNode, useScript, useMount } from 'tiny-engine/hooks'
import { PrimaryNode, TinyScript } from 'tiny-engine'

class PlayerScript extends TinyScript<PrimaryNode.Sprite> {
  health = 100
  setup() {}
}

function Player() {
  const sprite = useRefNode(PrimaryNode.Sprite)
  const script = useScript<PlayerScript>(sprite)

  useMount(() => {
    console.log('Player health:', script.current?.health) // 100
  })

  return <sprite ref={sprite} textureId={PLAYER_TEXTURE} script={new PlayerScript()} />
}

​
useRef

useRef stores any mutable value that must survive across renders without triggering reactive updates. It is equivalent to a plain box with a .current property.

​
Signature

useRef<T>(value: T): Reference<T>

​
Parameters

​
value
T
required
The initial value to store in the reference.

​
Return value

class Reference<T> {
  current: T
}
A Reference instance whose .current property can be read and written freely.

​
Example

ClickCounter.tsx
import { useRef } from 'tiny-engine/hooks'

function ClickCounter() {
  // Mutable counter — does NOT cause re-renders or reactive updates
  const clickCount = useRef(0)

  const handleClick = () => {
    clickCount.current++
    console.log('Total clicks:', clickCount.current)
  }

  return <clickable size={[64, 32]} onClick={handleClick} />
}
Use useRef when you need to track state imperatively (e.g. counting frames, storing timers) without the overhead of signal subscriptions. If you need the value to drive JSX or useEffect, use useSignal instead.

Build docs developers (and LLMs) love

Get started for freeTalk to us