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): 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.json
index 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.md
index 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: number
Omit<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.md
index 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: number
Omit<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.md
index 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: number
Omit<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.md
index 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: number
Omit<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.md
index 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: number
Omit<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.ts
index 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 system
diff --git a/sdk/src/core-runtime.ts b/sdk/src/core-runtime.ts
index 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.ts
index 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.ts
index 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);
+ });
+});