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(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.jsonindex 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.tsindex 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 goaldiff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 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: booleanto: number```+## Playthrough — const @experimental+```+ResourceDef<PlaythroughData>+```++## PlaythroughData — interface @experimental+```+facts: Record<string, PlaythroughValue>+```++## PlaythroughValue — type @experimental+```+string | number | boolean+```+## Plugin — interface @experimental```after: string[] | undefineddiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 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: booleanto: number```+## Playthrough — const @experimental+```+ResourceDef<PlaythroughData>+```++## PlaythroughData — interface @experimental+```+facts: Record<string, PlaythroughValue>+```++## PlaythroughValue — type @experimental+```+string | number | boolean+```+## Plugin — interface @experimental```after: string[] | undefineddiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 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: booleanto: number```+## Playthrough — const @experimental+```+ResourceDef<PlaythroughData>+```++## PlaythroughData — interface @experimental+```+facts: Record<string, PlaythroughValue>+```++## PlaythroughValue — type @experimental+```+string | number | boolean+```+## Plugin — interface @experimental```after: string[] | undefineddiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 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: booleanto: number```+## Playthrough — const @experimental+```+ResourceDef<PlaythroughData>+```++## PlaythroughData — interface @experimental+```+facts: Record<string, PlaythroughValue>+```++## PlaythroughValue — type @experimental+```+string | number | boolean+```+## Plugin — interface @experimental```after: string[] | undefineddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 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: booleanto: number```+## Playthrough — const @experimental+```+ResourceDef<PlaythroughData>+```++## PlaythroughData — interface @experimental+```+facts: Record<string, PlaythroughValue>+```++## PlaythroughValue — type @experimental+```+string | number | boolean+```+## Plugin — interface @experimental```after: string[] | undefineddiff --git a/sdk/src/core-content.ts b/sdk/src/core-content.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.mjsindex 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.mjsindex 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.