Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(ecs): Time.scale — a paused world that is still a running frame

esengine41c986db67ef
diff --git a/CHANGELOG.md b/CHANGELOG.md
index bca2f90f7..95fa02bd1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,22 @@ published separately; it ships inside the editor.
### Added
+- **`Time.scale`: a paused world that is still a running frame.** Stopping a game
+ meant stopping the loop, and `App.setPaused` runs only `Schedule.Last` — which
+ also stops UI layout, so the menu a pause exists to show could not be drawn. A
+ project could gate its own systems with a `SystemSet` run condition, but that
+ reaches half the loop: the character controller kept integrating the velocity
+ last written to it, and navigation, behaviour trees and perception are engine
+ plugins outside any set a project can name.
+
+ `Time` now carries a `scale` applied to `delta` and to the fixed-step
+ accumulation, plus `unscaledDelta` for whatever must keep moving. At 0 the
+ frame still runs — systems tick, UI lays out, a menu draws and can dismiss
+ itself — while everything that advances by `delta` advances by nothing, the
+ physics step included, because the accumulator is scaled too. Measured on the
+ flagship, two captures 80 frames into a pause: 6.6% of the frame changed
+ before, 0.019% after.
+
- **A project can register a system set, so a pause is one condition instead of
a flag checked in nine systems.** `defineSystemSet` takes a `runIf` and its own
documentation shows a pause as the example, but the only door to register one
diff --git a/examples/celestial-heights/engine-gaps.mjs b/examples/celestial-heights/engine-gaps.mjs
index dd1d6985e..2afd07e36 100644
--- a/examples/celestial-heights/engine-gaps.mjs
+++ b/examples/celestial-heights/engine-gaps.mjs
@@ -31,23 +31,4 @@
*/
/** @type {Array<{id: string, hurts: string, workaround: string, fix: string, issue?: string, allows?: string[]}>} */
-export const GAPS = [
- {
- id: 'no-simulation-pause',
- hurts:
- 'A pause stops only the project\'s own systems. Measured: with the overlay up, two '
- + 'captures 80 frames apart differ across the WHOLE frame — the character controller '
- + 'keeps integrating the velocity the player system last wrote, so Lyra walks on, and '
- + 'the wisps keep pathing because perception, navigation and behaviour trees are '
- + 'engine plugins outside any set a project can gate. A run condition reaches half '
- + 'the loop, and the half it cannot reach is the simulation.',
- workaround:
- 'Gate the project\'s systems with a SystemSet runIf and show the overlay. Everything '
- + 'the engine drives keeps running behind it.',
- fix:
- 'The runtime needs a paused simulation its own plugin systems honour — a Time scale '
- + 'that everything integrating dt reads would do it, and Time has no scale today. '
- + 'App.setPaused exists but runs only Schedule.Last, which stops UI layout too, so a '
- + 'menu cannot be drawn while it is on.',
- },
-];
+export const GAPS = [];
diff --git a/examples/celestial-heights/src/main.ts b/examples/celestial-heights/src/main.ts
index ce212a9a0..4547cee51 100644
--- a/examples/celestial-heights/src/main.ts
+++ b/examples/celestial-heights/src/main.ts
@@ -10,7 +10,7 @@ import {
} from './systems/combat';
import { healthBarSystem, hitFlashSystem, vitalityMeterSystem } from './systems/feedback';
import { cameraBindSystem, navFromTerrainSystem, gateSystem } from './systems/world';
-import { pauseInputSystem, pauseOverlaySystem } from './systems/pause';
+import { pauseInputSystem, pauseTimeSystem, pauseOverlaySystem } from './systems/pause';
import { cycleLanguageSystem } from './systems/settings';
import { perceiverFacingSystem } from './ai/wisp';
@@ -40,6 +40,7 @@ addSystemSetToSchedule(Schedule.PostUpdate, defineSystemSet('combat', {
// The pause itself and everything that reports state keep running: one has to be
// able to lift the pause, the rest have to be able to show it.
addSystemToSchedule(Schedule.Update, pauseInputSystem);
+addSystemToSchedule(Schedule.Update, pauseTimeSystem);
addSystemToSchedule(Schedule.Update, cycleLanguageSystem);
addSystemToSchedule(Schedule.PostUpdate, pauseOverlaySystem);
addSystemToSchedule(Schedule.PostUpdate, healthBarSystem);
diff --git a/examples/celestial-heights/src/systems/pause.ts b/examples/celestial-heights/src/systems/pause.ts
index 886d932e3..1f354b757 100644
--- a/examples/celestial-heights/src/systems/pause.ts
+++ b/examples/celestial-heights/src/systems/pause.ts
@@ -1,12 +1,11 @@
-import { defineSystem, Query, Mut, Res, Input, UINode, UIDisplay } from 'esengine';
+import {
+ defineSystem, Query, Mut, Res, ResMut, Input, Time, UINode, UIDisplay,
+} from 'esengine';
import { PauseOverlay } from '../components';
import { session } from '../state';
-// Both systems stay OUT of the gameplay set: one has to be able to lift the
-// pause, and the other has to be able to draw it.
-
-// ENGINE-GAP(no-simulation-pause): this pause reaches the project's systems and
-// nothing the engine drives, so the world keeps moving behind the overlay.
+// These systems stay OUT of the gameplay set: one has to be able to lift the
+// pause, and the others have to be able to draw it and to stop the world.
export const pauseInputSystem = defineSystem(
[Res(Input)],
@@ -16,6 +15,21 @@ export const pauseInputSystem = defineSystem(
{ name: 'PauseInputSystem' },
);
+/**
+ * Stops the simulation. The run condition on the gameplay set only reaches this
+ * project's systems; everything the engine drives — the character controller
+ * integrating the velocity last written, navigation, behaviour trees — advances
+ * by `Time.delta`, so setting the scale to zero is what actually holds the world.
+ */
+export const pauseTimeSystem = defineSystem(
+ [ResMut(Time)],
+ (time) => {
+ const scale = session.paused ? 0 : 1;
+ if (time.get().scale !== scale) time.modify((t) => { t.scale = scale; });
+ },
+ { name: 'PauseTimeSystem' },
+);
+
export const pauseOverlaySystem = defineSystem(
[Query(Mut(UINode), PauseOverlay)],
(overlays) => {
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index b73c371d8..36efca25f 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -7740,6 +7740,8 @@ fixedAlpha: number
fixedDelta: number
fixedTick: number
frameCount: number
+scale: number
+unscaledDelta: number
```
## Timeline — const
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 4680f8ed0..5ded1f28f 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -7933,6 +7933,8 @@ fixedAlpha: number
fixedDelta: number
fixedTick: number
frameCount: number
+scale: number
+unscaledDelta: number
```
## Timeline — const
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 060091b10..6d99e9bc4 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -7735,6 +7735,8 @@ fixedAlpha: number
fixedDelta: number
fixedTick: number
frameCount: number
+scale: number
+unscaledDelta: number
```
## Timeline — const
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 57f60a765..b2c3ebd3b 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -7980,6 +7980,8 @@ fixedAlpha: number
fixedDelta: number
fixedTick: number
frameCount: number
+scale: number
+unscaledDelta: number
```
## Timeline — const
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index d748aa89d..8e4065539 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -7742,6 +7742,8 @@ fixedAlpha: number
fixedDelta: number
fixedTick: number
frameCount: number
+scale: number
+unscaledDelta: number
```
## Timeline — const
diff --git a/sdk/src/app/app.ts b/sdk/src/app/app.ts
index 48e5f64c3..24a07903c 100644
--- a/sdk/src/app/app.ts
+++ b/sdk/src/app/app.ts
@@ -728,7 +728,7 @@ export class App {
this.runner_.setTimingEnabled(true);
}
if (!this.resources_.has(Time)) {
- this.resources_.insert(Time, { delta: 0, elapsed: 0, frameCount: 0, fixedDelta: this.fixedTimestep_, fixedAlpha: 0, fixedTick: 0 });
+ this.resources_.insert(Time, { delta: 0, elapsed: 0, frameCount: 0, fixedDelta: this.fixedTimestep_, fixedAlpha: 0, fixedTick: 0, scale: 1, unscaledDelta: 0 });
}
this.finishPlugins_();
}
@@ -784,7 +784,7 @@ export class App {
this.runner_.setTimingEnabled(true);
}
if (!this.resources_.has(Time)) {
- this.resources_.insert(Time, { delta: 0, elapsed: 0, frameCount: 0, fixedDelta: this.fixedTimestep_, fixedAlpha: 0, fixedTick: 0 });
+ this.resources_.insert(Time, { delta: 0, elapsed: 0, frameCount: 0, fixedDelta: this.fixedTimestep_, fixedAlpha: 0, fixedTick: 0, scale: 1, unscaledDelta: 0 });
}
this.finishPlugins_();
}
@@ -877,7 +877,9 @@ export class App {
} else {
await this.runSchedule(Schedule.First);
- this.fixedAccumulator_ += delta;
+ // The SCALED delta, so Time.scale = 0 stops the fixed steps too —
+ // otherwise physics would keep stepping through a paused world.
+ this.fixedAccumulator_ += this.resources_.get(Time).delta;
let fixedSteps = 0;
// Fixed steps read the input edge mirrors (which persist across frames
// until a step consumes them) so a press on a sub-timestep frame isn't
@@ -1164,8 +1166,10 @@ export class App {
private updateTime(delta: number): void {
const time = this.resources_.get(Time);
- time.delta = delta;
- time.elapsed += delta;
+ const scale = time.scale >= 0 ? time.scale : 0;
+ time.unscaledDelta = delta;
+ time.delta = delta * scale;
+ time.elapsed += time.delta;
time.frameCount++;
time.fixedDelta = this.fixedTimestep_;
}
diff --git a/sdk/src/ecs/resource.ts b/sdk/src/ecs/resource.ts
index bb35dabaf..edb69face 100644
--- a/sdk/src/ecs/resource.ts
+++ b/sdk/src/ecs/resource.ts
@@ -177,6 +177,15 @@ export interface TimeData {
* Netcode stamps snapshots and input commands with this.
*/
fixedTick: number;
+ /**
+ * Multiplier on `delta` and on the fixed-step accumulation; negatives clamp
+ * to 0. At 0 the frame still runs — systems tick and a menu draws — while
+ * everything advancing by `delta` (movement, navigation, behaviour trees,
+ * the physics step) advances by nothing.
+ */
+ scale: number;
+ /** Real frame time, unaffected by `scale`, for whatever must keep moving. */
+ unscaledDelta: number;
}
export const Time = defineResource<TimeData>({
@@ -186,5 +195,7 @@ export const Time = defineResource<TimeData>({
fixedDelta: 1 / 60,
fixedAlpha: 0,
fixedTick: 0,
+ scale: 1,
+ unscaledDelta: 0,
}, 'Time');
diff --git a/sdk/tests/app-tick.test.ts b/sdk/tests/app-tick.test.ts
index 45b0eeaad..b1d514fb3 100644
--- a/sdk/tests/app-tick.test.ts
+++ b/sdk/tests/app-tick.test.ts
@@ -19,6 +19,27 @@ describe('App.tick()', () => {
expect(time.delta).toBeCloseTo(1 / 60);
});
+ it('scales delta and stops the fixed steps at scale 0', async () => {
+ const app = App.new();
+ let fixedSteps = 0;
+ app.addSystemToSchedule(Schedule.FixedUpdate, defineSystem([], () => { fixedSteps++; }));
+
+ await app.tick(1 / 30);
+ expect(fixedSteps).toBeGreaterThan(0);
+
+ const before = fixedSteps;
+ app.getResource(Time).scale = 0;
+ for (let i = 0; i < 10; i++) await app.tick(1 / 30);
+
+ const time = app.getResource(Time);
+ expect(time.delta).toBe(0);
+ // Real time keeps flowing — whatever must move while the world does not
+ // has something to move by.
+ expect(time.unscaledDelta).toBeCloseTo(1 / 30);
+ // The whole point: physics is a fixed step, and a paused world takes none.
+ expect(fixedSteps).toBe(before);
+ });
+
it('should run Startup schedule only once', async () => {
const app = App.new();
let startupCount = 0;