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.

Collider registers a geometric shape with the engine’s collision system and fires events when it starts overlapping, continues overlapping, or stops overlapping another collider. Shapes are either axis-aligned rectangles or circles, and collision filtering is controlled by two string-array props — group (what this collider is) and collidesWith (what it detects). Collider extends Node2D, so its position is inherited from parent Transform nodes in the scene tree.

​
Usage

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

function Player() {
  const col = useRefNode(PrimaryNode.Collider)

  useEvent(col, 'colliderEntered', (other) => {
    console.log('Collision started with', other)
  })

  useEvent(col, 'colliderExited', (other) => {
    console.log('Collision ended with', other)
  })

  return (
    <transform position={[100, 200]}>
      <sprite textureId={PLAYER_TEXTURE} sourceSize={[32, 32]} />
      <collider
        ref={col}
        shape={shapes.rectangle(32, 32)}
        group={['player']}
        collidesWith={['enemy', 'obstacle']}
      />
    </transform>
  )
}

​
Props

​
shape
Shape
required
The collision geometry. Create one with shapes.rectangle(width, height) or shapes.circle(radius). The shape is set at construction and cannot be changed afterwards.
​
group
string[]
required
The groups this collider belongs to. Other colliders whose collidesWith contains any of these strings will detect this collider. Must be set at construction — immutable after that.
​
collidesWith
string[]
required
The groups this collider actively checks against. Must be set at construction — immutable after that.
​
position
VectorLike | SignalGetter<VectorLike>
Local position offset from the parent node. Useful for aligning the collision shape with a sprite that is not centered at the origin.
​
ref
NodeRef<PrimaryNode.Collider>
A ref created by useRefNode(PrimaryNode.Collider). Use it to call methods or inspect state on the collider at runtime.
​
id
string | symbol
Optional node identifier. Must match [a-zA-Z][a-zA-Z0-9-_]* when a string.
​
zIndex
number
Draw order among siblings. Defaults to 0.

​
Events

Subscribe with useEvent. Each callback receives the other Collider instance.
Event nameCallback signatureDescription
colliderEntered(other: Collider) => voidFires once on the first frame two colliders overlap.
collided(other: Collider) => voidFires every frame while two colliders keep overlapping.
colliderExited(other: Collider) => voidFires once on the frame the overlap ends.
started() => voidFires once after the collider registers with the system.
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 removed.
useEvent(col, 'colliderEntered', (other) => {
  if (other.group.has('enemy')) {
    takeDamage()
  }
})

useEvent(col, 'collided', (other) => {
  // resolve push-back every frame while overlapping
  resolveOverlap(col.node, other)
})

​
Runtime properties

PropertyTypeDescription
shapeShapeRead-only. The collision geometry set at construction.
groupSet<string>Read-only. Groups this collider belongs to.
collidesWithSet<string>Read-only. Groups this collider checks against.
sizeVector2Read-only. Bounding dimensions (diameter for circles).
globalPositionVector2World-space position inherited from parent transforms.

​
Debug visualisation

Set testOptions.showColliders = true in your GameConfig to draw shapes as semi-transparent blue overlays at runtime. Rectangle colliders draw from the node’s top-left position. 
import { GameConfig } from 'tiny-engine'

GameConfig.testOptions.showColliders = true

​
Complete example — enemy takes damage

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

function Enemy() {
  const col = useRefNode(PrimaryNode.Collider)
  const [hp, setHp] = useSignal(3)

  useEvent(col, 'colliderEntered', (other) => {
    if (other.group.has('projectile')) {
      setHp((prev) => prev - 1)
    }
  })

  return (
    <transform>
      <sprite textureId={ENEMY_TEXTURE} sourceSize={[24, 24]} />
      <collider
        ref={col}
        shape={shapes.rectangle(24, 24)}
        group={['enemy']}
        collidesWith={['projectile']}
      />
    </transform>
  )
}
group and collidesWith are converted to Set<string> at construction time and cannot be modified afterwards. Design your group names upfront.
Enable testOptions.showColliders during development to verify shape alignment with your sprites before building game logic on top of collision events.
  • Collision guide — shapes, groups, spatial hashing, and resolve patterns
  • RayCast — line-based detection that queries collider groups
  • Transform — position the collider in world space
  • useEvent — subscribe to collision events

Build docs developers (and LLMs) love

Get started for freeTalk to us