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
test(gameplay): a footstep and a dodge, claimed in the packaged game
esengine77e5cb39f08d
diff --git a/examples/third-person-3d/assets/models/dodge.estimeline b/examples/third-person-3d/assets/models/dodge.estimelinenew file mode 100644index 000000000..83c3ef4c8--- /dev/null+++ b/examples/third-person-3d/assets/models/dodge.estimeline@@ -0,0 +1,152 @@+{+ "version": "1.2",+ "type": "timeline",+ "duration": 0.5,+ "wrapMode": "once",+ "tracks": [+ {+ "type": "property",+ "name": "Root",+ "childPath": "",+ "component": "Transform",+ "channels": [+ {+ "property": "position.z",+ "keyframes": [+ {+ "time": 0,+ "value": 0,+ "inTangent": 0,+ "outTangent": 0,+ "interpolation": "linear"+ },+ {+ "time": 0.35,+ "value": -260,+ "inTangent": 0,+ "outTangent": 0,+ "interpolation": "linear"+ },+ {+ "time": 0.5,+ "value": -280,+ "inTangent": 0,+ "outTangent": 0,+ "interpolation": "linear"+ }+ ]+ }+ ]+ },+ {+ "type": "property",+ "name": "Bone1",+ "childPath": "Bone1",+ "component": "Transform",+ "channels": [+ {+ "property": "rotation.x",+ "keyframes": [+ {+ "time": 0,+ "value": 0,+ "inTangent": 0,+ "outTangent": 0,+ "interpolation": "linear"+ },+ {+ "time": 0.5,+ "value": 0,+ "inTangent": 0,+ "outTangent": 0,+ "interpolation": "linear"+ }+ ]+ },+ {+ "property": "rotation.y",+ "keyframes": [+ {+ "time": 0,+ "value": 0,+ "inTangent": 0,+ "outTangent": 0,+ "interpolation": "linear"+ },+ {+ "time": 0.5,+ "value": 0,+ "inTangent": 0,+ "outTangent": 0,+ "interpolation": "linear"+ }+ ]+ },+ {+ "property": "rotation.z",+ "keyframes": [+ {+ "time": 0,+ "value": 0,+ "inTangent": 0,+ "outTangent": 0,+ "interpolation": "linear"+ },+ {+ "time": 0.25,+ "value": -0.5,+ "inTangent": 0,+ "outTangent": 0,+ "interpolation": "linear"+ },+ {+ "time": 0.5,+ "value": 0,+ "inTangent": 0,+ "outTangent": 0,+ "interpolation": "linear"+ }+ ]+ },+ {+ "property": "rotation.w",+ "keyframes": [+ {+ "time": 0,+ "value": 1,+ "inTangent": 0,+ "outTangent": 0,+ "interpolation": "linear"+ },+ {+ "time": 0.25,+ "value": 0.866,+ "inTangent": 0,+ "outTangent": 0,+ "interpolation": "linear"+ },+ {+ "time": 0.5,+ "value": 1,+ "inTangent": 0,+ "outTangent": 0,+ "interpolation": "linear"+ }+ ]+ }+ ]+ },+ {+ "type": "customEvent",+ "name": "Beats",+ "childPath": "",+ "events": [+ {+ "time": 0,+ "name": "dodge-start",+ "payload": {}+ }+ ]+ }+ ]+}diff --git a/examples/third-person-3d/assets/models/dodge.estimeline.meta b/examples/third-person-3d/assets/models/dodge.estimeline.metanew file mode 100644index 000000000..127256536--- /dev/null+++ b/examples/third-person-3d/assets/models/dodge.estimeline.meta@@ -0,0 +1,6 @@+{+ "uuid": "67269bec-b2a7-4f4b-9a52-207986bf34f2",+ "version": "2.0",+ "type": "animation",+ "importer": {}+}diff --git a/examples/third-person-3d/assets/models/locomotion.esanimator b/examples/third-person-3d/assets/models/locomotion.esanimatorindex 32f2e42ab..bfeee94df 100644--- a/examples/third-person-3d/assets/models/locomotion.esanimator+++ b/examples/third-person-3d/assets/models/locomotion.esanimator@@ -9,6 +9,10 @@"name": "grounded","type": "bool","default": true+ },+ {+ "name": "dodge",+ "type": "trigger"}],"initialState": "Idle",@@ -71,6 +75,35 @@"duration": 0.25}]+ },+ {+ "name": "Dodge",+ "motion": {+ "kind": "timeline",+ "clip": "dodge.estimeline",+ "loop": false+ },+ "rootMotion": true,+ "transitions": [+ {+ "to": "Idle",+ "conditions": [],+ "hasExitTime": true,+ "duration": 0.12+ }+ ]+ }+ ],+ "anyStateTransitions": [+ {+ "to": "Dodge",+ "conditions": [+ {+ "param": "dodge",+ "op": "trigger"+ }+ ],+ "duration": 0.08}]-}\ No newline at end of file+}diff --git a/examples/third-person-3d/assets/models/skinned-fade_Bent.estimeline b/examples/third-person-3d/assets/models/skinned-fade_Bent.estimelineindex 8888436fb..350e89e1c 100644--- a/examples/third-person-3d/assets/models/skinned-fade_Bent.estimeline+++ b/examples/third-person-3d/assets/models/skinned-fade_Bent.estimeline@@ -87,6 +87,27 @@]}]+ },+ {+ "type": "customEvent",+ "name": "Steps",+ "childPath": "",+ "events": [+ {+ "time": 0.25,+ "name": "footstep",+ "payload": {+ "text": "left"+ }+ },+ {+ "time": 0.75,+ "name": "footstep",+ "payload": {+ "text": "right"+ }+ }+ ]}]}diff --git a/examples/third-person-3d/assets/scenes/gym.esscene b/examples/third-person-3d/assets/scenes/gym.essceneindex 7f807a1fa..b67be31fd 100644--- a/examples/third-person-3d/assets/scenes/gym.esscene+++ b/examples/third-person-3d/assets/scenes/gym.esscene@@ -297,7 +297,8 @@"children": [6,7,- 8+ 8,+ 13],"visible": true,"components": [@@ -336,6 +337,12 @@"currentState": "","enabled": true}+ },+ {+ "type": "AnimatorRootMotion",+ "data": {+ "enabled": true+ }}]},@@ -602,6 +609,69 @@}}]+ },+ {+ "id": 13,+ "name": "FootDust",+ "parent": 5,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": -78,+ "z": 0+ }+ }+ },+ {+ "type": "ParticleEmitter",+ "data": {+ "rate": 0,+ "burstCount": 12,+ "burstInterval": 0,+ "duration": 0.05,+ "looping": false,+ "playOnStart": false,+ "maxParticles": 64,+ "lifetimeMin": 0.6,+ "lifetimeMax": 1.0,+ "shape": 5,+ "shapeRadius": 18,+ "speedMin": 18,+ "speedMax": 42,+ "startSizeMin": 10,+ "startSizeMax": 16,+ "endSizeMin": 22,+ "endSizeMax": 30,+ "sizeEasing": 2,+ "startColor": {+ "r": 0.74,+ "g": 0.68,+ "b": 0.56,+ "a": 0.35+ },+ "endColor": {+ "r": 0.66,+ "g": 0.62,+ "b": 0.54,+ "a": 0.0+ },+ "gravity": {+ "x": 0,+ "y": 26,+ "z": 0+ },+ "damping": 1.6,+ "blendMode": 0,+ "layer": 0,+ "simulationSpace": 0+ }+ }+ ]}]}\ No newline at end of filediff --git a/examples/third-person-3d/assets/scenes/main.esscene b/examples/third-person-3d/assets/scenes/main.essceneindex febad6ec2..69d185255 100644--- a/examples/third-person-3d/assets/scenes/main.esscene+++ b/examples/third-person-3d/assets/scenes/main.esscene@@ -337,6 +337,12 @@"currentState": "","enabled": true}+ },+ {+ "type": "AnimatorRootMotion",+ "data": {+ "enabled": true+ }}]},@@ -624,10 +630,15 @@{"type": "ParticleEmitter","data": {- "rate": 14,- "maxParticles": 48,- "lifetimeMin": 0.35,- "lifetimeMax": 0.6,+ "rate": 0,+ "burstCount": 12,+ "burstInterval": 0,+ "duration": 0.05,+ "looping": false,+ "playOnStart": false,+ "maxParticles": 64,+ "lifetimeMin": 0.6,+ "lifetimeMax": 1.0,"shape": 5,"shapeRadius": 18,"speedMin": 18,@@ -641,7 +652,7 @@"r": 0.74,"g": 0.68,"b": 0.56,- "a": 0.22+ "a": 0.35},"endColor": {"r": 0.66,diff --git a/examples/third-person-3d/src/main.ts b/examples/third-person-3d/src/main.tsindex d29b54595..d31b6377c 100644--- a/examples/third-person-3d/src/main.ts+++ b/examples/third-person-3d/src/main.ts@@ -1,4 +1,26 @@-// No gameplay script: ThirdPersonController and ThirdPersonCamera are components-// the scene declares, and the engine's systems run them. Reading WASD, moving-// the character and following it with the camera is what those components are.-export {};+// Movement is declared, not scripted: ThirdPersonController and+// ThirdPersonCamera are components the scene carries. What a game DOES own is+// what an animation means — here, that a footstep throws up dust.+import {+ addSystemToSchedule, Schedule, defineSystem, EventReader, GetWorld, Res,+ AnimatorEvent, Particle, resolveChildEntity,+} from 'esengine';++/**+ * Dust on a footstep. The animator says WHEN a foot lands — it is a moment the+ * walk clip declares, not a guess from speed — and the effect under that+ * character is what answers. Nothing here reads a clip or a clock.+ */+const footstepDustSystem = defineSystem(+ [EventReader(AnimatorEvent), GetWorld(), Res(Particle)],+ (events, world, particles) => {+ for (const event of events) {+ if (event.name !== 'footstep') continue;+ const dust = resolveChildEntity(world, event.entity, 'FootDust');+ if (dust !== null) particles.play(dust);+ }+ },+ { name: 'FootstepDustSystem' },+);++addSystemToSchedule(Schedule.Update, footstepDustSystem);diff --git a/pipeline/src/runtime/gameHost.ts b/pipeline/src/runtime/gameHost.tsindex 12006b1c5..e28195657 100644--- a/pipeline/src/runtime/gameHost.ts+++ b/pipeline/src/runtime/gameHost.ts@@ -17,7 +17,7 @@ import {HttpBackend, fetchDecodePixels, registerPackagedSideModules,packagedAppOptions, packagedRuntimeInit, Transform, SceneManager, Nav, UINode,acquireWebGPUDevice, ThirdPersonCamera, CharacterController3D, AnimatorController,- Animator, TPC_SPEED, TPC_GROUNDED,+ Animator, TPC_SPEED, TPC_GROUNDED, Particle,} from 'esengine';import type { SceneData, AddressableManifest, PackagedGameConfig, RenderSurfaceSource } from 'esengine';import type { ESEngineModule } from 'esengine/wasm';@@ -191,6 +191,23 @@ async function boot(): Promise<void> {// "the thing I was walking to is gone", which is a lie with a cost.return { scene: scenes?.getActive() ?? null, transitioning: scenes?.isTransitioning() ?? false, at };},+ /**+ * How many particles a named emitter is running. The far END of a chain+ * that starts in a clip: nothing else can say a moment the animation+ * declared reached the effect a project chose to answer it with, since a+ * position cannot and a unit test stops at the event being posted.+ */+ particles(names: string[] = []): Record<string, number> {+ const out: Record<string, number> = {};+ if (!app.hasResource(Particle)) return out;+ const api = app.getResource(Particle);+ for (const name of names) {+ const entity = app.world.findEntityByName(name);+ if (entity === null) continue;+ out[name] = api.getAliveCount(entity);+ }+ return out;+ },/*** What a third-person character IS: where it stands, what the physics step* gave it, what its animator was told. Read-only, off the same componentsdiff --git a/tools/launchers/launch-export.mjs b/tools/launchers/launch-export.mjsindex b1e927e3f..85761206a 100644--- a/tools/launchers/launch-export.mjs+++ b/tools/launchers/launch-export.mjs@@ -29,6 +29,8 @@* CSS variables the web platform reads* --probe a,b,c after settling, print where those named entities are* (opens the package with ?headless)+ * --particles a[,b] after settling, print how many particles named emitters+ * are running — the far end of an effect chain* --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@@ -146,11 +148,12 @@ async function main() {}const PROBE = flag('probe', '');const GAMEPLAY = flag('gameplay', '');+const PARTICLES = flag('particles', '');/** Boot a named scene from the package instead of its entry. */const SCENE = flag('scene', '');const server = await serve(DIR, flag('safe-area', ''));const query = new URLSearchParams();- if (PROBE || GAMEPLAY) query.set('headless', '');+ if (PROBE || GAMEPLAY || PARTICLES) 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}`;@@ -221,6 +224,14 @@ const SCENE = flag('scene', '');console.log(` gameplay: ${JSON.stringify(seen)}`);}+ if (PARTICLES) {+ const names = PARTICLES.split(',').map((n) => n.trim()).filter(Boolean);+ const seen = await win.webContents.executeJavaScript(+ `window.__estellaCooked?.particles(${JSON.stringify(names)}) ?? null`,+ ).catch((e) => ({ error: String(e) }));+ console.log(` particles: ${JSON.stringify(seen)}`);+ }+const image = await win.webContents.capturePage();if (OUT) await writeFile(OUT, image.toPNG());stop();diff --git a/tools/verify-third-person.mjs b/tools/verify-third-person.mjsindex 3d6fabbd6..c13e0c336 100644--- a/tools/verify-third-person.mjs+++ b/tools/verify-third-person.mjs@@ -11,8 +11,8 @@* CharacterController3D, real Animator over TimelineMotion, real skin.** Input goes in as key and mouse events on the page, and the only thing read- * back is `__estellaCooked.gameplay` — an observation seam, not a second way to- * play. Lanes run in -Z, so a run strafes to one and then walks it.+ * back is `__estellaCooked` — an observation seam, not a second way to play.+ * Lanes run in -Z, so a run strafes to one and then walks it.** The scene is `gym`, and it is a FIXTURE: its coordinates, sizes and materials* answer to these claims and to nothing else. The project's entry scene is a@@ -52,23 +52,34 @@ function packageGame() {return out;}+/** The JSON a launcher printed after `label:`, or null when it printed none. */+function reading(stdout, label) {+ const line = (stdout || '').split('\n').find((l) => l.includes(`${label}:`));+ if (!line) return null;+ try {+ return JSON.parse(line.slice(line.indexOf('{')));+ } catch {+ return null;+ }+}+/** Drive the package with one gesture and read what the character became. */function run(dir, input) {const r = runElectron([LAUNCHER, '--dir', dir, '--w', String(W), '--h', String(H),'--settle', '30', '--timeout', '60000', '--scene', 'gym','--input', JSON.stringify(input), '--gameplay', 'Player,Camera',+ '--particles', 'FootDust','--out', path.join(WORK, 'frame.png'),], { encoding: 'utf8', cwd: ROOT });- const line = (r.stdout || '').split('\n').find((l) => l.includes('gameplay:'));- if (!line) {+ const seen = reading(r.stdout, 'gameplay');+ if (!seen) {return { error: `no reading — ${(r.stdout || r.stderr || '').trim().slice(-200)}` };}- try {- return JSON.parse(line.slice(line.indexOf('{')));- } catch (e) {- return { error: `unreadable reading: ${e.message}` };- }+ // The far end of the effect chain, beside what the character became: the+ // reading is one launch, so asking twice would be two different games.+ seen.particles = reading(r.stdout, 'particles') ?? {};+ return seen;}/**@@ -240,6 +251,59 @@ const START = { y: 60, z: 120 };`distance ${against.cameraDistance?.toFixed(0)} vs ${open.cameraDistance?.toFixed(0)}`);}+// 9. The footstep the WALK CLIP declares, reaching the effect that answers it.+// The emitter starts nothing itself, so a live particle means clip → animator →+// event → the project's system. Standing still is the other half of the pair.+{+ const still = run(dir, { frames: 60 });+ check('standing still throws up no dust',+ (still.particles?.FootDust ?? -1) === 0,+ `alive ${still.particles?.FootDust}`);++ const running = run(dir, { keys: ['KeyW'], frames: 90 });+ check('a footstep the clip declares reaches the effect that answers it',+ (running.particles?.FootDust ?? 0) > 0,+ `alive ${running.particles?.FootDust}, state ${running.animator?.state}`);+}++// 10. A dodge: an action whose MOVEMENT is the animation's. The stick is never+// touched, so anything that happens is the clip's doing — and the wall says the+// difference between what it asked for and what it got.+{+ const dodgeFrom = (holds, frames) => run(dir, { holds, frames });+ const DODGE = (at) => ({ key: 'ShiftLeft', from: at, to: at + 3 });++ const still = run(dir, { frames: 45 });+ const dodged = dodgeFrom([DODGE(5)], 45);+ const stillZ = still.position?.z ?? 0;+ const travelled = stillZ - (dodged.position?.z ?? stillZ);+ check('a dodge moves the character with no stick at all',+ travelled > 200,+ `travelled ${travelled.toFixed(0)} against a standing ${stillZ.toFixed(0)}`);++ const during = dodgeFrom([DODGE(5)], 20);+ const asked = Math.hypot(during.askedVelocity?.x ?? 0, during.askedVelocity?.z ?? 0);+ const real = Math.hypot(during.realVelocity?.x ?? 0, during.realVelocity?.z ?? 0);+ check('and while it runs, the animation is what the controller was asked for',+ during.animator?.state === 'Dodge' && asked > 400 && real > 200,+ `state ${during.animator?.state}, asked ${asked.toFixed(0)}, real ${real.toFixed(0)}`);++ // The same gesture against the wall the walk cannot pass. The request is the+ // clip's either way; only the world's answer differs.+ const held = dodgeFrom([+ { key: 'KeyD', from: 0, to: TO_LANE.wall },+ { key: 'KeyW', from: TO_LANE.wall, to: TO_LANE.wall + 160 },+ DODGE(TO_LANE.wall + 145),+ ], TO_LANE.wall + 160);+ const wallAsked = Math.hypot(held.askedVelocity?.x ?? 0, held.askedVelocity?.z ?? 0);+ const wallReal = Math.hypot(held.realVelocity?.x ?? 0, held.realVelocity?.z ?? 0);+ check('a dodge into a wall asks for the whole distance and is given none',+ held.animator?.state === 'Dodge' && wallAsked > 400+ && wallReal < 60 && (held.position?.z ?? -999) > -520,+ `state ${held.animator?.state}, asked ${wallAsked.toFixed(0)},`+ + ` real ${wallReal.toFixed(0)}, z ${held.position?.z?.toFixed(0)}`);+}+const failed = results.filter((r) => !r.ok);console.log(`\nverify-third-person: ${results.length - failed.length}/${results.length}`+ ' behaviour(s) hold up in the packaged game.');