Pause, resume & step — play control with per-world pausable

tutorial lesson Intermediate ⏱ 8 min vgai 0.1.0

Prerequisites: Build a multi-world game

What you'll learn

• Pause, resume, and single-step a running game from the play bar
• Exempt a menu/HUD world from pause with "pausable": false
• Know why the loop never stops (frozen worlds render with dt = 0)

What you'll build: A two-world game where Pause freezes the 3D sim while a pixijs menu overlay keeps spinning, then single-stepping the frozen world.

Walkthrough — Pause, resume & step — play control with per-world pausable · generated by site/media/lessons/learn-playcontrol.lesson.ts (4 steps)

Game.play is the one game-level control surface: pause, resume, and step, with per-world "pausable" semantics. The classic use is a pause menu: the simulation freezes, but the menu world declares "pausable": false and keeps running. The editor’s play bar drives this surface directly — so does the CLI (vgai pause / vgai resume / vgai step). (Concept reference: Multi-world games & play control.)

Follow along in a project

This lesson’s game is two worlds: a threejs sim world whose cube spins via a Spinner GameComponent, and a pixijs menu overlay marked "pausable": false (an entry-backed 2D world that spins an orange square from a gameLogic system):

vgai.game.json

{
  "manifestVersion": 2,
  "roots": [
    { "id": "sim",  "adapter": "threejs", "scene": "scenes/sim.vscn.json" },
    { "id": "menu", "adapter": "pixijs", "entry": "src/scripts/menu2d.ts",
      "zOrder": 10, "pausable": false }
  ]
}

Any spinning/moving thing works — the point is motion you can watch freeze.

Steps

1. Press Play. Both worlds run: the teal cube spins in the sim world (pausable by default), the orange square spins in the menu overlay ("pausable": false).

   

   Two worlds, one loop — the play bar's pause and step buttons drive Game.play.

2. Pause. The play bar’s pause button calls game.play.pause(). Every pausable world freezes — the teal cube stops mid-turn. The menu world is exempt: the orange square keeps spinning, because the loop itself never stops.

   

   Pause freezes pausable worlds; pausable: false keeps ticking.

3. Step. Each click of the step button calls game.play.step() — it advances exactly the frozen worlds by one fixed substep. The teal cube creeps forward one frame per click; the menu world is untouched (the still-running loop already ticks it).

   

   Step advances only the frozen worlds — one fixed substep per click.

4. Resume. The inverse of pause; both are idempotent. The teal cube spins again.

Why the screen never goes black while paused

Pause does not stop the loop (that’s a recorded design decision — D10). A frozen world still runs its render phase every frame with dt = 0: the screen keeps drawing, and time-based render effects don’t creep while paused. While the game is not paused, step() is a no-op. Worlds that can’t be gated (self-driven mounts with no pause capability) are reported loudly, once — never silently ignored.

Recap

New functionality

• Paused, resumed, and single-stepped a running two-world game from the play bar
• Exempted a menu overlay from pause with "pausable": false
• Watched Step advance exactly the frozen world, one fixed substep per click

New concepts & skills

• Game.play is the one game-level control surface (editor play bar and CLI both drive it)
• pausable is per-world; false keeps a menu/HUD world ticking through pause
• the loop never stops — frozen worlds render with dt = 0
• step() advances only frozen worlds and is a no-op while unpaused

Next lesson → React worlds

On Your Own!

Extend what you built:

• Mark the sim world pausable: false too and see pause become a visual no-op
• Drive the same controls from the CLI: vgai pause, vgai step, vgai resume
• Put a falling physics body in the sim world and single-step the fall

See also

• Multi-world games & play control (manual) · Build a multi-world game · Scaffold a project & drive the editor (CLI)