Time scale & game speed

Slow motion, speed-up and freeze with time.scale, plus time.deltaTime, time.unscaledDeltaTime and time.elapsed.

#The time object

#Using time.scale

time.scale changes how fast the whole game runs, like Unity's Time.timeScale.

function onClick() {
  time.scale = 0.3;              // slow motion
  wait(1.5, function () {        // 1.5 GAME seconds = 5 real seconds at 0.3
    time.scale = 1;
  });
}

#What is and is not affected

• Affected: physics, animation, tween(), wait() and repeat(), onFixedUpdate, time.deltaTime and time.elapsed.
• Not affected: input, rendering and time.unscaledDeltaTime.

#Limits and gotchas

• Values must be numbers from 0 to 100. Anything else (negative, NaN, text) is ignored and a console warning says the previous value was kept. Values above 100 are clamped to 100.
• Each frame simulates at most half a second of game time, so on a 60 FPS screen speeds above roughly 30x will not go faster.
• A tab-out or long frame spike is clamped to 0.1 real seconds before the scale is applied.
• It stays set when you load or restart a scene. Set time.scale = 1 yourself if the next scene should run at normal speed.
• Physics catch-up steps are capped, so extreme speeds trade accuracy for stability.

#Pause menu pattern

function onUpdate() {
  if (input.keyPressed("Escape")) {
    time.scale = time.scale === 0 ? 1 : 0;
  }
  // Menu animation that keeps running while frozen:
  this.rotation += 90 * time.unscaledDeltaTime;
}

scene.pause() and scene.resume() are the other way to freeze gameplay; see Global API. Unlike time.scale = 0 (where scripts keep running with deltaTime = 0), scene.pause() stops scripts including onUpdate, physics, animation and audio from the next frame until scene.resume().