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(gameplay): a game can state what its own run has reached

esengine20f1bb13a503
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index 526196719..e9dd89b2b 100644
--- a/docs/astro/src/data/apiStability.generated.json
+++ b/docs/astro/src/data/apiStability.generated.json
@@ -3,10 +3,10 @@
"counts": {
"public": 113,
"beta": 91,
- "experimental": 1790,
+ "experimental": 1793,
"deprecated": 3
},
- "total": 1994,
+ "total": 1997,
"subsystems": [
{
"id": "ecs",
diff --git a/pipeline/src/runtime/gameHost.ts b/pipeline/src/runtime/gameHost.ts
index 2105864c1..11c87d11d 100644
--- a/pipeline/src/runtime/gameHost.ts
+++ b/pipeline/src/runtime/gameHost.ts
@@ -18,7 +18,7 @@ import {
packagedAppOptions, packagedRuntimeInit, Transform, SceneManager, Nav, UINode,
acquireWebGPUDevice, ThirdPersonCamera, CharacterController3D, AnimatorController,
Animator, TPC_SPEED, TPC_GROUNDED, Particle, MeleeAttack, Health,
- Hunter, NavAgent, Perception, AnimatorRootMotion,
+ Hunter, NavAgent, Perception, AnimatorRootMotion, Playthrough,
worldResidencyReport,
} from 'esengine';
import type {
@@ -400,6 +400,15 @@ async function boot(): Promise<void> {
setPaused(paused: boolean): void {
app.setPaused(paused);
},
+ /**
+ * What the GAME says about its own run. The rest of this seam reports the
+ * engine's side of a frame, and a checkpoint or a victory lives only in
+ * the game's own state. A copy: this observes a run, it never drives one.
+ */
+ facts(): Record<string, string | number | boolean> {
+ if (!app.hasResource(Playthrough)) return {};
+ return { ...app.getResource(Playthrough).facts };
+ },
/**
* A way from one named entity to another, over the same navigation grid
* the game's own enemies walk. A driver that steers straight at its goal
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 60c92f3c7..e36b831c7 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: 113 public · 84 beta · 1626 experimental · 3 deprecated
+Symbols: 113 public · 84 beta · 1629 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -6163,6 +6163,21 @@ inclusiveStart: boolean
to: number
```
+## Playthrough — const @experimental
+```
+ResourceDef<PlaythroughData>
+```
+
+## PlaythroughData — interface @experimental
+```
+facts: Record<string, PlaythroughValue>
+```
+
+## PlaythroughValue — type @experimental
+```
+string | number | boolean
+```
+
## Plugin — interface @experimental
```
after: string[] | undefined
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 9f4fe8aec..5dd2c6a82 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: 113 public · 89 beta · 1645 experimental · 3 deprecated
+Symbols: 113 public · 89 beta · 1648 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -6346,6 +6346,21 @@ inclusiveStart: boolean
to: number
```
+## Playthrough — const @experimental
+```
+ResourceDef<PlaythroughData>
+```
+
+## PlaythroughData — interface @experimental
+```
+facts: Record<string, PlaythroughValue>
+```
+
+## PlaythroughValue — type @experimental
+```
+string | number | boolean
+```
+
## Plugin — interface @experimental
```
after: string[] | undefined
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 2ca5fe5e8..bd2671975 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: 113 public · 86 beta · 1625 experimental · 3 deprecated
+Symbols: 113 public · 86 beta · 1628 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -6158,6 +6158,21 @@ inclusiveStart: boolean
to: number
```
+## Playthrough — const @experimental
+```
+ResourceDef<PlaythroughData>
+```
+
+## PlaythroughData — interface @experimental
+```
+facts: Record<string, PlaythroughValue>
+```
+
+## PlaythroughValue — type @experimental
+```
+string | number | boolean
+```
+
## Plugin — interface @experimental
```
after: string[] | undefined
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index ea120fe0a..650dc65dc 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: 113 public · 84 beta · 1647 experimental · 3 deprecated
+Symbols: 113 public · 84 beta · 1650 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -6404,6 +6404,21 @@ inclusiveStart: boolean
to: number
```
+## Playthrough — const @experimental
+```
+ResourceDef<PlaythroughData>
+```
+
+## PlaythroughData — interface @experimental
+```
+facts: Record<string, PlaythroughValue>
+```
+
+## PlaythroughValue — type @experimental
+```
+string | number | boolean
+```
+
## Plugin — interface @experimental
```
after: string[] | undefined
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 65a17ae9e..52b4354bf 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: 113 public · 84 beta · 1637 experimental · 3 deprecated
+Symbols: 113 public · 84 beta · 1640 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -6165,6 +6165,21 @@ inclusiveStart: boolean
to: number
```
+## Playthrough — const @experimental
+```
+ResourceDef<PlaythroughData>
+```
+
+## PlaythroughData — interface @experimental
+```
+facts: Record<string, PlaythroughValue>
+```
+
+## PlaythroughValue — type @experimental
+```
+string | number | boolean
+```
+
## Plugin — interface @experimental
```
after: string[] | undefined
diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.ts
index cb2f43e1f..dce0b373a 100644
--- a/sdk/src/core-content.ts
+++ b/sdk/src/core-content.ts
@@ -949,6 +949,9 @@ export {
type ThirdPersonControllerData,
type ThirdPersonCameraData,
type MoveBasis,
+ Playthrough,
+ type PlaythroughData,
+ type PlaythroughValue,
} from './gameplay';
// =============================================================================
diff --git a/sdk/src/gameplay/GameplayPlugin.ts b/sdk/src/gameplay/GameplayPlugin.ts
index 87d51ac56..30a226117 100644
--- a/sdk/src/gameplay/GameplayPlugin.ts
+++ b/sdk/src/gameplay/GameplayPlugin.ts
@@ -32,6 +32,7 @@ import { huntTargets } from './Hunter';
import { q } from '../math/quat';
import type { World } from '../ecs/world';
import type { Entity } from '../types';
+import { Playthrough } from './Playthrough';
import {
ThirdPersonController, type ThirdPersonControllerData,
desiredDirection, approachVelocity, facingYaw, turnToward, rootMotionVelocity,
@@ -272,6 +273,9 @@ export class GameplayPlugin implements Plugin {
build(app: App): void {
const world = app.world;
+ // Always present, empty until a game states something. Absent, a driver
+ // cannot tell "this game publishes nothing" from "the seam is broken".
+ app.insertResource(Playthrough, { facts: {} });
const attacks = this.attacks_;
this.offDespawn_ = world.onDespawn((entity: Entity) => {
lastPointer.delete(entity);
diff --git a/sdk/src/gameplay/Playthrough.ts b/sdk/src/gameplay/Playthrough.ts
new file mode 100644
index 000000000..426c95a35
--- /dev/null
+++ b/sdk/src/gameplay/Playthrough.ts
@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Playthrough.ts
+ * @brief What a game says about its own progress, for automation that must
+ * prove a run can be finished.
+ *
+ * @details The observation seam a packaged game already had could see the
+ * ENGINE's side of a run — where a character stands, what an animator
+ * plays, whether a swing landed. It could not see the game's: a
+ * checkpoint armed, three cores taken, a gate opened, a victory. So no
+ * level's completion could be confirmed from outside, and a playthrough
+ * driver had to infer one from an entity going missing.
+ *
+ * Published, not read. The engine does not reach into a game's
+ * resources and guess which field means "won" — the game states it, in
+ * its own words, and that statement is the contract. Read-only from
+ * outside: this is how a run is OBSERVED, never how it is driven.
+ */
+import { defineResource } from '../ecs/resource';
+
+/** What a fact may be. Enough for a count, a flag, or a named place. */
+export type PlaythroughValue = string | number | boolean;
+
+/**
+ * The facts a game publishes about itself, by its own names. Open rather than a
+ * fixed set: `cores` and `gate` belong to one game, and an engine that named
+ * them would be designing every other game's progression.
+ */
+export interface PlaythroughData {
+ facts: Record<string, PlaythroughValue>;
+}
+
+export const Playthrough = defineResource<PlaythroughData>({ facts: {} }, 'Playthrough');
diff --git a/sdk/src/gameplay/index.ts b/sdk/src/gameplay/index.ts
index 66531063a..8513fbe39 100644
--- a/sdk/src/gameplay/index.ts
+++ b/sdk/src/gameplay/index.ts
@@ -66,3 +66,9 @@ export {
observeMotion,
updateCameras,
} from './GameplayPlugin';
+
+export {
+ Playthrough,
+ type PlaythroughData,
+ type PlaythroughValue,
+} from './Playthrough';
diff --git a/tools/launchers/launch-export.mjs b/tools/launchers/launch-export.mjs
index 56ebb8bec..80b5480cb 100644
--- a/tools/launchers/launch-export.mjs
+++ b/tools/launchers/launch-export.mjs
@@ -37,6 +37,7 @@
* doing, and what the world let it do
* --render after settling, print the renderer counters of the last
* frame — draws, culls and LOD levels, which no pixel shows
+ * --facts after settling, print what the GAME says about its run
* --gameplay p[,c] after settling, print what the third-person character
* IS: where it stands, what the physics step gave it, and
* what its animator was told
@@ -153,6 +154,7 @@ async function main() {
return;
}
const PROBE = flag('probe', '');
+const FACTS = has('facts');
const GAMEPLAY = flag('gameplay', '');
const PARTICLES = flag('particles', '');
const COMBAT = flag('combat', '');
@@ -162,7 +164,7 @@ const RENDER = has('render');
const SCENE = flag('scene', '');
const server = await serve(DIR, flag('safe-area', ''));
const query = new URLSearchParams();
- if (PROBE || GAMEPLAY || PARTICLES || COMBAT || AI || RENDER) query.set('headless', '');
+ if (PROBE || GAMEPLAY || PARTICLES || COMBAT || AI || RENDER || FACTS) query.set('headless', '');
if (SCENE) query.set('scene', SCENE);
const search = query.toString() ? `?${query.toString().replace(/=$/, '').replace(/=&/g, '&')}` : '';
const base = `http://127.0.0.1:${server.address().port}/${search}`;
@@ -216,6 +218,12 @@ const SCENE = flag('scene', '');
console.log(` input: ${ran} source(s) over ${Number(spec.frames ?? 40)} frames`);
}
+ if (FACTS) {
+ const seen = await win.webContents.executeJavaScript(
+ 'window.__estellaCooked?.facts() ?? null',
+ ).catch((e) => ({ error: String(e) }));
+ console.log(` facts: ${JSON.stringify(seen)}`);
+ }
if (PROBE) {
const names = PROBE.split(',').map((n) => n.trim()).filter(Boolean);
const seen = await win.webContents.executeJavaScript(
diff --git a/tools/launchers/play-through.mjs b/tools/launchers/play-through.mjs
index 0860c6e4e..00d80d2ed 100644
--- a/tools/launchers/play-through.mjs
+++ b/tools/launchers/play-through.mjs
@@ -168,7 +168,7 @@ async function main() {
await win.loadURL(base);
// Where the wall time goes, by what was asked of the page: a route that
// takes 40 minutes on a runner is a driver question before it is an engine one.
- const spentOn = { probe: [0, 0], step: [0, 0], path: [0, 0], other: [0, 0] };
+ const spentOn = { probe: [0, 0], step: [0, 0], path: [0, 0], facts: [0, 0], other: [0, 0] };
const exec = (js, kind = 'other') => {
const t = performance.now();
return win.webContents.executeJavaScript(js).finally(() => {
@@ -184,8 +184,10 @@ async function main() {
ready = await exec(`(() => {
const c = window.__estellaCooked;
if (!c || !c.probe) return false;
- const s = c.probe(['Lyra_Player']);
- return !!(s.scene && s.at.Lyra_Player);
+ // A scene, not a named character: which entity a game's player IS belongs
+ // to that game, and a driver that waits for one name waits forever in
+ // every other one.
+ return !!c.probe([]).scene;
})()`).catch(() => false);
if (!ready) await new Promise((r) => setTimeout(r, 100));
}
@@ -213,11 +215,24 @@ async function main() {
// driver holds the clock. Waiting for requestAnimationFrame first cost a
// second per read in a hidden window — 407 s of a 412 s walk whose steps took 3.
const probe = (names) => exec(`window.__estellaCooked.probe(${JSON.stringify(names)})`, 'probe');
+ // What the GAME says about itself. A leg may be judged on this instead of on
+ // an entity going missing — the only evidence a level's own progression ever
+ // had, and one that cannot see a checkpoint, a core or a victory.
+ const facts = () => exec('window.__estellaCooked.facts?.() ?? {}', 'facts');
+
+ /** Whether every `until` clause the leg names is satisfied by the game's facts. */
+ const untilMet = (want, got) =>
+ Object.entries(want).every(([k, v]) => (typeof v === 'object' && v !== null
+ ? (v.atLeast !== undefined && Number(got[k]) >= Number(v.atLeast))
+ || (v.atMost !== undefined && Number(got[k]) <= Number(v.atMost))
+ : got[k] === v));
const pathTo = (goal) => exec(`window.__estellaCooked.pathBetween("Lyra_Player", ${JSON.stringify(goal)})`, 'path');
// Every goal the route names, before a step is taken: a leg whose goal never
// existed would otherwise report as "already done" and the run would fail
// later, somewhere else, for a reason that is not the reason.
- const goals = [...new Set(route.legs.map((l) => l.goal))];
+ // Only the legs that name one: a leg the game judges has no goal to find, and
+ // counting its absence as a missing entity fails the route before it starts.
+ const goals = [...new Set(route.legs.map((l) => l.goal).filter(Boolean))];
const opening = await probe(goals);
const missing = goals.filter((g) => !(g in opening.at));
console.log(` route names ${goals.length} goal(s); ${goals.length - missing.length} are in ${opening.scene}`
@@ -233,7 +248,7 @@ async function main() {
let failure = null;
for (const leg of route.legs) {
- const label = `${leg.area}:${leg.goal}`;
+ const label = leg.until ? `${leg.area}:${JSON.stringify(leg.until)}` : `${leg.area}:${leg.goal}`;
const timeout = Number(leg.timeout ?? 1800);
// Only when the route asks for it: "gone" is the game's own answer, a distance
// is this driver guessing at one. A default of 90 outran a PICKUP_RADIUS of
@@ -256,6 +271,21 @@ async function main() {
let waited = 0;
const WAIT_CAP = 1800;
+ // A leg the GAME judges. Nothing here reads an entity: what "arrived" means
+ // is the fact the level publishes, so a re-authored level moves under it
+ // without moving the claim.
+ if (leg.until) {
+ while (spent < timeout && frames < BUDGET) {
+ const got = await facts();
+ if (untilMet(leg.until, got)) { arrived = true; break; }
+ await exec(stepScript(leg.keys ?? [], STEP, leg.tap ?? null), 'step');
+ spent += STEP; frames += STEP;
+ }
+ if (arrived) { console.log(` ${label} — the game says so`); done.push(label); }
+ else { failure = `${label} never became true (last: ${JSON.stringify(await facts())})`; break; }
+ continue;
+ }
+
// Something picked up on the way to somewhere else is still picked up. A
// leg whose goal is already gone before it starts is a leg already walked —
// and a goal that is merely misspelled fails the legs that depend on it.