Skip to content
vgai Learn

Detect overlaps with triggers

quick start Beginner ⏱ 6 min vgai 0.1.0

Prerequisites: Installed vgai and run the editor

What you'll learn

  • Make a collider a sensor (isSensor) so it detects overlaps without blocking
  • React to overlaps with onTriggerEnter / onTriggerExit on a GameComponent
  • See a zone light up green while a body is inside it

What you'll build: A sensor zone that turns green while a moving cube is inside it.

Walkthrough — Detect overlaps with triggers · generated by site/media/lessons/learn-triggers.lesson.ts (5 steps)

A trigger (sensor) is a collider that detects overlaps without physically blocking. Mark a collider isSensor: true and the engine calls onTriggerEnter / onTriggerExit on the overlapping entities’ GameComponents. This scene has a fixed sensor zone and a Mover cube that sweeps through it — the zone lights up green while the cube is inside.

Steps

Section titled “Steps”

  1. Open the scene. The scene is already open — if you followed the link above, the triggers scene is loaded and rendering (in the local dev editor: VGAI_PROJECT=examples/learn-triggers npm run dev): a red sensor zone and a blue mover cube beside it.

    The triggers scene: a red zone and a blue cube
    A sensor zone (isSensor collider) + a mover cube.

  2. Enter play — the Mover heads toward the zone. The Mover drives a dynamic body across the scene; the zone is still red (no overlap yet).

    The mover approaching the red zone
    No overlap yet — the zone stays red.

  3. The Mover enters — onTriggerEnter fires. Rapier reports the sensor overlap; the engine’s trigger dispatch calls TriggerZone.onTriggerEnter, which turns the zone green.

    The cube inside the now-green zone
    Overlap → onTriggerEnter → the zone turns green.

  4. The Mover exits the far side — onTriggerExit fires. As the cube leaves, onTriggerExit runs and the zone returns to red.

    The cube past the zone, which is red again
    Overlap ends → onTriggerExit → back to red.

  5. Stop play mode. Press Stop (or Escape).

// learn-triggers/components.ts — behavior lives in the trigger callbacks
export class TriggerZone extends GameComponent {
  update() {}                                  // base update is abstract
  onTriggerEnter(_other, _ctx) { /* turn green */ }
  onTriggerExit(_other, _ctx)  { /* turn red   */ }
}

Recap

New functionality

  • Made a collider a sensor (isSensor)
  • Reacted to overlaps with onTriggerEnter / onTriggerExit
  • Watched a zone turn green while a body was inside

New concepts & skills

  • A sensor detects overlaps without blocking
  • The engine dispatches onTriggerEnter/onTriggerExit to the entities' GameComponents
  • A fixed sensor needs a dynamic (not kinematic) body to generate events by default

Next lesson → Manual: collisions & triggers

On Your Own!

Extend what you built:

  • Make the zone count how many times it was entered and show it in a HUD
  • Use onTriggerEnter as a pickup: hide the mover and increment a score
  • Add a second sensor with a different reaction (e.g., a damage zone)

See also

Section titled “See also”