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): a system asks for a speculation the way it asks for anything else
esengineb48c748ef553
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.jsonindex 9b21c9c0a..98b4e07db 100644--- a/docs/astro/src/data/apiStability.generated.json+++ b/docs/astro/src/data/apiStability.generated.json@@ -3,10 +3,10 @@"counts": {"public": 114,"beta": 101,- "experimental": 1835,+ "experimental": 1838,"deprecated": 3},- "total": 2050,+ "total": 2053,"subsystems": [{"id": "ecs",diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex ae454b70e..d84d3aee2 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1,7 +1,7 @@# API surface — esengine/index<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 114 public · 94 beta · 1674 experimental · 3 deprecated+Symbols: 114 public · 94 beta · 1677 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -8039,6 +8039,23 @@ rolloff: numberOmit<PrefabOverride, 'prefabEntityId'> & { prefabEntityId?: string }```+## Speculation — const @experimental+```+ResourceDef<SpeculationInstance>+```++## SpeculationInstance — class @experimental+```+run: (body: (commands: CommandsInstance) => SpeculationOutcome) => SpeculationOutcome+static new (world: World, resources: ResourceStorage, events: EventRegistry | null): SpeculationInstance+static prototype: SpeculationInstance+```++## SpeculationOutcome — type @experimental+```+'commit' | 'abandon'+```+## SphereCollider3D — const @experimental```BuiltinComponentDef<SphereCollider3DData>diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 02500f721..c8779168d 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.native<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 114 public · 99 beta · 1693 experimental · 3 deprecated+Symbols: 114 public · 99 beta · 1696 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -8232,6 +8232,23 @@ rolloff: numberOmit<PrefabOverride, 'prefabEntityId'> & { prefabEntityId?: string }```+## Speculation — const @experimental+```+ResourceDef<SpeculationInstance>+```++## SpeculationInstance — class @experimental+```+run: (body: (commands: CommandsInstance) => SpeculationOutcome) => SpeculationOutcome+static new (world: World, resources: ResourceStorage, events: EventRegistry | null): SpeculationInstance+static prototype: SpeculationInstance+```++## SpeculationOutcome — type @experimental+```+'commit' | 'abandon'+```+## SphereCollider3D — const @experimental```BuiltinComponentDef<SphereCollider3DData>diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex dd4d1f149..7de099af7 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.node<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 114 public · 96 beta · 1673 experimental · 3 deprecated+Symbols: 114 public · 96 beta · 1676 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -8034,6 +8034,23 @@ rolloff: numberOmit<PrefabOverride, 'prefabEntityId'> & { prefabEntityId?: string }```+## Speculation — const @experimental+```+ResourceDef<SpeculationInstance>+```++## SpeculationInstance — class @experimental+```+run: (body: (commands: CommandsInstance) => SpeculationOutcome) => SpeculationOutcome+static new (world: World, resources: ResourceStorage, events: EventRegistry | null): SpeculationInstance+static prototype: SpeculationInstance+```++## SpeculationOutcome — type @experimental+```+'commit' | 'abandon'+```+## SphereCollider3D — const @experimental```BuiltinComponentDef<SphereCollider3DData>diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 9d01f8e12..5e416a0cf 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -1,7 +1,7 @@# API surface — esengine/minigame<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 114 public · 94 beta · 1695 experimental · 3 deprecated+Symbols: 114 public · 94 beta · 1698 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -8282,6 +8282,23 @@ rolloff: numberOmit<PrefabOverride, 'prefabEntityId'> & { prefabEntityId?: string }```+## Speculation — const @experimental+```+ResourceDef<SpeculationInstance>+```++## SpeculationInstance — class @experimental+```+run: (body: (commands: CommandsInstance) => SpeculationOutcome) => SpeculationOutcome+static new (world: World, resources: ResourceStorage, events: EventRegistry | null): SpeculationInstance+static prototype: SpeculationInstance+```++## SpeculationOutcome — type @experimental+```+'commit' | 'abandon'+```+## SphereCollider3D — const @experimental```BuiltinComponentDef<SphereCollider3DData>diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 1d7d689a1..ad564150f 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -1,7 +1,7 @@# API surface — esengine/wechat<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 114 public · 94 beta · 1685 experimental · 3 deprecated+Symbols: 114 public · 94 beta · 1688 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -8041,6 +8041,23 @@ rolloff: numberOmit<PrefabOverride, 'prefabEntityId'> & { prefabEntityId?: string }```+## Speculation — const @experimental+```+ResourceDef<SpeculationInstance>+```++## SpeculationInstance — class @experimental+```+run: (body: (commands: CommandsInstance) => SpeculationOutcome) => SpeculationOutcome+static new (world: World, resources: ResourceStorage, events: EventRegistry | null): SpeculationInstance+static prototype: SpeculationInstance+```++## SpeculationOutcome — type @experimental+```+'commit' | 'abandon'+```+## SphereCollider3D — const @experimental```BuiltinComponentDef<SphereCollider3DData>diff --git a/sdk/src/app/app.ts b/sdk/src/app/app.tsindex 4996f1bc1..d8b0401d3 100644--- a/sdk/src/app/app.ts+++ b/sdk/src/app/app.ts@@ -8,6 +8,7 @@import { World } from '../ecs/world';import { Schedule, SystemDef, SystemRunner, SystemSet, mergeOrderingEdges, rescopeSystem, type RunCondition } from '../ecs/system';import { builtinResource, declaredResource, ResourceStorage, Time, TimeData, type ResourceDef } from '../ecs/resource';+import { Speculation, SpeculationInstance } from '../ecs/speculation';import { installAot, prepareAot, type AotHost } from '../ecs/aot/installAot';import { installNativeAot, nativeAotBindings } from '../ecs/aot/installNativeAot';import { createNativeHeap } from '../ecs/bridge/nativeHeap';@@ -1155,9 +1156,15 @@ export class App {* such thing and it runs BEFORE the first frame: a twin declaring `Res(Time)`* is refused outright if this App cannot yet say what Time's fields are.*/+ private ensureSpeculation_(): void {+ if (this.resources_.has(Speculation)) return;+ this.resources_.insert(Speculation, new SpeculationInstance(this.world, this.resources_, this.eventRegistry_));+ }+private ensureTime_(): void {if (this.resources_.has(Time)) return;this.resources_.insert(Time, { delta: 0, elapsed: 0, frameCount: 0, fixedDelta: this.fixedTimestep_, fixedAlpha: 0, fixedTick: 0, scale: 1, unscaledDelta: 0 });+ this.ensureSpeculation_();}/** Once per app, on the way into the first frame: the clock every systemdiff --git a/sdk/src/core-runtime.ts b/sdk/src/core-runtime.tsindex 4671ab637..aebf5646b 100644--- a/sdk/src/core-runtime.ts+++ b/sdk/src/core-runtime.ts@@ -399,6 +399,16 @@ export {type CommandsDescriptor,} from './ecs/commands';+// =============================================================================+// Speculation (a gameplay step that can be taken back)+// =============================================================================++export {+ Speculation,+ SpeculationInstance,+ type SpeculationOutcome,+} from './ecs/speculation';+// =============================================================================// Transactions (editor undo/redo)// =============================================================================diff --git a/sdk/src/ecs/speculation.ts b/sdk/src/ecs/speculation.tsindex 3a2baa78a..a8528bd40 100644--- a/sdk/src/ecs/speculation.ts+++ b/sdk/src/ecs/speculation.ts@@ -21,7 +21,7 @@ import { Entity } from '../types';import { AnyComponentDef } from './component';import { CommandsInstance } from './commands';import { EventRegistry } from './event';-import { ResourceStorage } from './resource';+import { defineResource, ResourceStorage } from './resource';import { deepClone } from '../util/deepClone';import type { World } from './world';@@ -136,3 +136,42 @@ export function speculate(if (marks && events) events.rewindWrites(marks);return 'abandon';}++// =============================================================================+// As a service a system asks for+// =============================================================================++/**+ * The scope a system was handed. `run` is one step: the body mutates, then says+ * whether it happened.+ *+ * @experimental+ */+export class SpeculationInstance {+ private readonly world_: World;+ private readonly resources_: ResourceStorage;+ private readonly events_: EventRegistry | null;++ constructor(world: World, resources: ResourceStorage, events: EventRegistry | null) {+ this.world_ = world;+ this.resources_ = resources;+ this.events_ = events;+ }++ run(body: (commands: CommandsInstance) => SpeculationOutcome): SpeculationOutcome {+ return speculate(+ { world: this.world_, resources: this.resources_, events: this.events_ ?? undefined },+ body,+ );+ }+}++/**+ * `Res(Speculation)` — the engine's existing way for a system to be handed a+ * service, which is what this is. The parameter vocabulary is a frozen public+ * type: a capability that grows it breaks that promise for every reader of+ * `SystemParam`, and a service does not need to.+ *+ * @experimental+ */+export const Speculation = defineResource<SpeculationInstance>(null!, 'Speculation');diff --git a/sdk/tests/speculation.test.ts b/sdk/tests/speculation.test.tsindex cd1d155d2..97b00ed99 100644--- a/sdk/tests/speculation.test.ts+++ b/sdk/tests/speculation.test.ts@@ -17,6 +17,10 @@ import { defineEvent, EventRegistry } from '../src/ecs/event';import { ResourceStorage } from '../src/ecs/resource';import { speculate } from '../src/ecs/speculation';import { App } from '../src/app/app';+import { Schedule } from '../src/ecs/system';+import { defineSystem } from '../src/ecs/system';+import { Speculation, type SpeculationInstance } from '../src/ecs/speculation';+import { Res } from '../src/ecs/resource';import { Transform } from '../src/ecs/component';import type { ESEngineModule, CppRegistry } from '../src/wasm';import { loadWasmModule, HAS_WASM } from './helpers/loadWasm';@@ -147,3 +151,34 @@ describe.skipIf(!HAS_WASM)('a speculated step, over engine components', () => {}});});++// The capability as a system actually receives it. Everything above drives the+// pieces by hand, which is not where a game meets them: the scheduler is what+// hands out a scope, and a step taken inside one is what has to leave nothing.+describe('a speculation a system asked for', () => {+ it('runs inside the schedule and takes its step back', async () => {+ const app = App.new();+ const world = app.world;+ const victim = world.spawn();+ world.insert(victim, Health, { hp: 100 });++ let outcome: string | null = null;+ app.addSystemToSchedule(Schedule.Update, defineSystem(+ [Res(Speculation)],+ (speculation: SpeculationInstance) => {+ outcome = speculation.run((commands) => {+ const hp = world.get(victim, Health);+ world.set(victim, Health, { ...hp, hp: 0 });+ commands.spawn().insert(Effect, { kind: 'death' });+ return 'abandon';+ });+ },+ ));++ await app.tick(1 / 60);++ expect(outcome).toBe('abandon');+ expect(world.get(victim, Health).hp).toBe(100);+ expect(world.getEntitiesWithComponents([Effect]).length).toBe(0);+ });+});