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.

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.estimeline
new file mode 100644
index 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.meta
new file mode 100644
index 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.esanimator
index 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.estimeline
index 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.esscene
index 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 file
diff --git a/examples/third-person-3d/assets/scenes/main.esscene b/examples/third-person-3d/assets/scenes/main.esscene
index 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.ts
index 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.ts
index 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 components
diff --git a/tools/launchers/launch-export.mjs b/tools/launchers/launch-export.mjs
index 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.mjs
index 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.');