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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(ecs): Time.scale — a paused world that is still a running frame
esengine41c986db67ef
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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 ofa flag checked in nine systems.** `defineSystemSet` takes a `runIf` and its owndocumentation shows a pause as the example, but the only door to register onediff --git a/examples/celestial-heights/engine-gaps.mjs b/examples/celestial-heights/engine-gaps.mjsindex 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.tsindex 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.tsindex 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.mdindex b73c371d8..36efca25f 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -7740,6 +7740,8 @@ fixedAlpha: numberfixedDelta: numberfixedTick: numberframeCount: number+scale: number+unscaledDelta: number```## Timeline — constdiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 4680f8ed0..5ded1f28f 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -7933,6 +7933,8 @@ fixedAlpha: numberfixedDelta: numberfixedTick: numberframeCount: number+scale: number+unscaledDelta: number```## Timeline — constdiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 060091b10..6d99e9bc4 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -7735,6 +7735,8 @@ fixedAlpha: numberfixedDelta: numberfixedTick: numberframeCount: number+scale: number+unscaledDelta: number```## Timeline — constdiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 57f60a765..b2c3ebd3b 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -7980,6 +7980,8 @@ fixedAlpha: numberfixedDelta: numberfixedTick: numberframeCount: number+scale: number+unscaledDelta: number```## Timeline — constdiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex d748aa89d..8e4065539 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -7742,6 +7742,8 @@ fixedAlpha: numberfixedDelta: numberfixedTick: numberframeCount: number+scale: number+unscaledDelta: number```## Timeline — constdiff --git a/sdk/src/app/app.ts b/sdk/src/app/app.tsindex 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.tsindex 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.tsindex 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;