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): the physics contract gets a fixture, and the jump gets a claim

esenginea4aeadcf92fa
diff --git a/examples/third-person-3d/assets/scenes/gym.esscene b/examples/third-person-3d/assets/scenes/gym.esscene
new file mode 100644
index 000000000..7f807a1fa
--- /dev/null
+++ b/examples/third-person-3d/assets/scenes/gym.esscene
@@ -0,0 +1,607 @@
+{
+ "version": 4,
+ "name": "ThirdPersonGym",
+ "entities": [
+ {
+ "id": 0,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 200,
+ "z": 500
+ }
+ }
+ },
+ {
+ "type": "Camera",
+ "data": {
+ "projectionType": 0,
+ "fov": 55,
+ "nearPlane": 10,
+ "farPlane": 4000,
+ "isActive": true,
+ "priority": 0
+ }
+ },
+ {
+ "type": "ThirdPersonCamera",
+ "data": {
+ "target": 5,
+ "distance": 420,
+ "pitch": 18
+ }
+ },
+ {
+ "type": "PostProcessVolume",
+ "data": {
+ "isGlobal": true,
+ "priority": 0,
+ "weight": 1,
+ "effects": [
+ {
+ "type": "ssao",
+ "enabled": true,
+ "uniforms": {
+ "u_radius": 70,
+ "u_intensity": 1,
+ "u_bias": 0.12,
+ "u_power": 1.6
+ }
+ }
+ ]
+ }
+ }
+ ]
+ },
+ {
+ "id": 1,
+ "name": "Ground",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": -200,
+ "y": -20,
+ "z": -300
+ },
+ "scale": {
+ "x": 30.0,
+ "y": 0.4,
+ "z": 24.0
+ }
+ }
+ },
+ {
+ "type": "RigidBody3D",
+ "data": {
+ "bodyType": 0
+ }
+ },
+ {
+ "type": "BoxCollider3D",
+ "data": {
+ "halfExtents": {
+ "x": 1500.0,
+ "y": 20.0,
+ "z": 1200.0
+ },
+ "friction": 0.6
+ }
+ },
+ {
+ "type": "MeshRenderer",
+ "data": {
+ "mesh": "builtin:cube",
+ "lit": true,
+ "opaque": true,
+ "cullBackfaces": true,
+ "color": {
+ "r": 0.3,
+ "g": 0.34,
+ "b": 0.3,
+ "a": 1
+ }
+ }
+ }
+ ]
+ },
+ {
+ "id": 2,
+ "name": "Wall",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 420,
+ "y": 120,
+ "z": -520
+ },
+ "scale": {
+ "x": 3.0,
+ "y": 2.4,
+ "z": 0.4
+ }
+ }
+ },
+ {
+ "type": "RigidBody3D",
+ "data": {
+ "bodyType": 0
+ }
+ },
+ {
+ "type": "BoxCollider3D",
+ "data": {
+ "halfExtents": {
+ "x": 150.0,
+ "y": 120.0,
+ "z": 20.0
+ },
+ "friction": 0.6
+ }
+ },
+ {
+ "type": "MeshRenderer",
+ "data": {
+ "mesh": "builtin:cube",
+ "lit": true,
+ "opaque": true,
+ "cullBackfaces": true,
+ "color": {
+ "r": 0.45,
+ "g": 0.3,
+ "b": 0.28,
+ "a": 1
+ }
+ }
+ }
+ ]
+ },
+ {
+ "id": 3,
+ "name": "Step",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": -400,
+ "y": 15,
+ "z": -520
+ },
+ "scale": {
+ "x": 3.0,
+ "y": 0.3,
+ "z": 4.0
+ }
+ }
+ },
+ {
+ "type": "RigidBody3D",
+ "data": {
+ "bodyType": 0
+ }
+ },
+ {
+ "type": "BoxCollider3D",
+ "data": {
+ "halfExtents": {
+ "x": 150.0,
+ "y": 15.0,
+ "z": 200.0
+ },
+ "friction": 0.6
+ }
+ },
+ {
+ "type": "MeshRenderer",
+ "data": {
+ "mesh": "builtin:cube",
+ "lit": true,
+ "opaque": true,
+ "cullBackfaces": true,
+ "color": {
+ "r": 0.36,
+ "g": 0.32,
+ "b": 0.28,
+ "a": 1
+ }
+ }
+ }
+ ]
+ },
+ {
+ "id": 4,
+ "name": "Ramp",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 40,
+ "z": -520
+ },
+ "rotation": {
+ "w": 0.9945218953682733,
+ "x": 0.10452846326765347,
+ "y": 0,
+ "z": 0
+ },
+ "scale": {
+ "x": 3.0,
+ "y": 0.3,
+ "z": 8.0
+ }
+ }
+ },
+ {
+ "type": "RigidBody3D",
+ "data": {
+ "bodyType": 0
+ }
+ },
+ {
+ "type": "BoxCollider3D",
+ "data": {
+ "halfExtents": {
+ "x": 150.0,
+ "y": 15.0,
+ "z": 400.0
+ },
+ "friction": 0.6
+ }
+ },
+ {
+ "type": "MeshRenderer",
+ "data": {
+ "mesh": "builtin:cube",
+ "lit": true,
+ "opaque": true,
+ "cullBackfaces": true,
+ "color": {
+ "r": 0.33,
+ "g": 0.36,
+ "b": 0.4,
+ "a": 1
+ }
+ }
+ }
+ ]
+ },
+ {
+ "id": 5,
+ "name": "Player",
+ "parent": null,
+ "children": [
+ 6,
+ 7,
+ 8
+ ],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 80,
+ "z": 120
+ }
+ }
+ },
+ {
+ "type": "CharacterController3D",
+ "data": {
+ "radius": 30,
+ "halfHeight": 30,
+ "stepHeight": 40,
+ "snapDown": 50
+ }
+ },
+ {
+ "type": "ThirdPersonController",
+ "data": {
+ "camera": 0,
+ "moveSpeed": 320,
+ "jumpSpeed": 520,
+ "idleThreshold": 8
+ }
+ },
+ {
+ "type": "Animator",
+ "data": {
+ "controller": "assets/models/locomotion.esanimator",
+ "currentState": "",
+ "enabled": true
+ }
+ }
+ ]
+ },
+ {
+ "id": 6,
+ "name": "Bone0",
+ "parent": 5,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ }
+ }
+ }
+ ]
+ },
+ {
+ "id": 7,
+ "name": "Bone1",
+ "parent": 5,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 60,
+ "y": 0,
+ "z": 0
+ }
+ }
+ }
+ ]
+ },
+ {
+ "id": 8,
+ "name": "Body",
+ "parent": 5,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "MeshRenderer",
+ "data": {
+ "mesh": "assets/models/skinned-fade.esmesh",
+ "lit": true,
+ "opaque": true,
+ "color": {
+ "r": 0.35,
+ "g": 0.75,
+ "b": 0.45,
+ "a": 1
+ }
+ }
+ },
+ {
+ "type": "MeshSkin",
+ "data": {
+ "joints": [
+ 6,
+ 7
+ ]
+ }
+ }
+ ]
+ },
+ {
+ "id": 9,
+ "name": "Sun",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ },
+ "rotation": {
+ "w": 0.83394695,
+ "x": -0.52086316,
+ "y": 0.18230211,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Light",
+ "data": {
+ "type": 1,
+ "intensity": 1.05,
+ "enabled": true,
+ "color": {
+ "r": 1,
+ "g": 0.96,
+ "b": 0.9,
+ "a": 1
+ }
+ }
+ }
+ ]
+ },
+ {
+ "id": 10,
+ "name": "Sky",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Light",
+ "data": {
+ "type": 2,
+ "intensity": 0.42,
+ "enabled": true,
+ "color": {
+ "r": 0.55,
+ "g": 0.66,
+ "b": 0.85,
+ "a": 1
+ }
+ }
+ }
+ ]
+ },
+ {
+ "id": 11,
+ "name": "HighStep",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": -800,
+ "y": 45,
+ "z": -520
+ },
+ "scale": {
+ "x": 3.0,
+ "y": 0.9,
+ "z": 4.0
+ }
+ }
+ },
+ {
+ "type": "RigidBody3D",
+ "data": {
+ "bodyType": 0
+ }
+ },
+ {
+ "type": "BoxCollider3D",
+ "data": {
+ "halfExtents": {
+ "x": 150,
+ "y": 45,
+ "z": 200
+ },
+ "friction": 0.6
+ }
+ },
+ {
+ "type": "MeshRenderer",
+ "data": {
+ "mesh": "builtin:cube",
+ "lit": true,
+ "opaque": true,
+ "cullBackfaces": true,
+ "color": {
+ "r": 0.45,
+ "g": 0.28,
+ "b": 0.3,
+ "a": 1
+ }
+ }
+ }
+ ]
+ },
+ {
+ "id": 12,
+ "name": "BackWall",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 420,
+ "y": 120,
+ "z": 400
+ },
+ "scale": {
+ "x": 4.0,
+ "y": 2.4,
+ "z": 0.4
+ }
+ }
+ },
+ {
+ "type": "RigidBody3D",
+ "data": {
+ "bodyType": 0
+ }
+ },
+ {
+ "type": "BoxCollider3D",
+ "data": {
+ "halfExtents": {
+ "x": 200,
+ "y": 120,
+ "z": 20
+ },
+ "friction": 0.6
+ }
+ },
+ {
+ "type": "MeshRenderer",
+ "data": {
+ "mesh": "builtin:cube",
+ "lit": true,
+ "opaque": true,
+ "cullBackfaces": true,
+ "color": {
+ "r": 0.4,
+ "g": 0.34,
+ "b": 0.44,
+ "a": 1
+ }
+ }
+ }
+ ]
+ }
+ ]
+}
\ No newline at end of file
diff --git a/examples/third-person-3d/assets/scenes/gym.esscene.meta b/examples/third-person-3d/assets/scenes/gym.esscene.meta
new file mode 100644
index 000000000..3fefa0de8
--- /dev/null
+++ b/examples/third-person-3d/assets/scenes/gym.esscene.meta
@@ -0,0 +1,6 @@
+{
+ "uuid": "9e4ab0ce-a131-4540-82eb-27a783c9d371",
+ "version": "2.0",
+ "type": "scene",
+ "importer": {}
+}
diff --git a/pipeline/src/runtime/gameHost.ts b/pipeline/src/runtime/gameHost.ts
index 373dd1123..12006b1c5 100644
--- a/pipeline/src/runtime/gameHost.ts
+++ b/pipeline/src/runtime/gameHost.ts
@@ -66,7 +66,15 @@ async function boot(): Promise<void> {
const index = indexPackagedManifest(
(await (await fetch('./asset-manifest.json')).json()) as AddressableManifest,
);
- const sceneData = (await (await fetch(`./${cfg.entryScene}`)).json()) as SceneData;
+ // A named scene from the query boots instead of the entry, so a conformance
+ // harness can drive a fixture scene in the real package rather than needing a
+ // project of its own. Unknown names are refused rather than silently ignored.
+ const wanted = new URLSearchParams(location.search).get('scene');
+ const chosen = wanted
+ ? (cfg.scenes ?? []).find((s) => s.name === wanted)?.path
+ : cfg.entryScene;
+ if (!chosen) throw new Error(`[estella] no scene named "${wanted}" in this package`);
+ const sceneData = (await (await fetch(`./${chosen}`)).json()) as SceneData;
const wasmBase = new URL('./wasm/', import.meta.url).href; // relative → mount-path agnostic
const { default: createModule } = (await import(/* @vite-ignore */ `${wasmBase}esengine.js`)) as {
diff --git a/tools/launchers/launch-export.mjs b/tools/launchers/launch-export.mjs
index 9f575e937..b1e927e3f 100644
--- a/tools/launchers/launch-export.mjs
+++ b/tools/launchers/launch-export.mjs
@@ -19,6 +19,7 @@
* --w / --h surface size (default 640x360)
* --settle <n> frames to let run before capturing (default 30)
* --timeout <ms> how long to wait for the first frame (default 30000)
+ * --scene <name> boot this named scene instead of the package's entry
* --allow-flat accept a single-colour frame (a deliberately blank scene)
* --input <json> drive it: {"keys":["ArrowRight"]} or {"pointer":{"x":.5,"y":.5}}
* --touch present as a touch device (maxTouchPoints > 0), so a
@@ -145,8 +146,14 @@ async function main() {
}
const PROBE = flag('probe', '');
const GAMEPLAY = flag('gameplay', '');
+/** Boot a named scene from the package instead of its entry. */
+const SCENE = flag('scene', '');
const server = await serve(DIR, flag('safe-area', ''));
- const base = `http://127.0.0.1:${server.address().port}/${PROBE || GAMEPLAY ? '?headless' : ''}`;
+ const query = new URLSearchParams();
+ if (PROBE || GAMEPLAY) 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}`;
const win = new BrowserWindow({
// Content size, not window size: with the frame counted in, the surface came
diff --git a/tools/verify-third-person.mjs b/tools/verify-third-person.mjs
index 2d3871e5a..3d6fabbd6 100644
--- a/tools/verify-third-person.mjs
+++ b/tools/verify-third-person.mjs
@@ -13,6 +13,11 @@
* 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.
+ *
+ * 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
+ * level, and a level moves when it is being designed — a bridge widened there
+ * must not read here as a physics regression.
*/
import { spawnSync } from 'node:child_process';
import { rmSync, mkdirSync } from 'node:fs';
@@ -51,7 +56,7 @@ function packageGame() {
function run(dir, input) {
const r = runElectron([
LAUNCHER, '--dir', dir, '--w', String(W), '--h', String(H),
- '--settle', '30', '--timeout', '60000',
+ '--settle', '30', '--timeout', '60000', '--scene', 'gym',
'--input', JSON.stringify(input), '--gameplay', 'Player,Camera',
'--out', path.join(WORK, 'frame.png'),
], { encoding: 'utf8', cwd: ROOT });
@@ -154,7 +159,57 @@ const START = { y: 60, z: 120 };
`lifted ${lifted.toFixed(0)}, z ${high.position?.z?.toFixed(0)}`);
}
-// 6. Camera-relative movement, turned by a real mouse drag.
+// 6. The jump as an arc rather than an outcome: landing on the far side of
+// something is also what walking there looks like. Leaves the ground, gets high
+// enough to be worth having, comes back, and travels while it is up there.
+{
+ const APEX_MIN = 80;
+ const rising = run(dir, { holds: [{ key: 'Space', from: 0, to: 3 }], frames: 20 });
+ const airborne = (rising.position?.y ?? 0) - START.y;
+ check('a jump leaves the ground',
+ airborne > 30 && rising.grounded === false,
+ `rose ${airborne.toFixed(0)}, grounded ${rising.grounded}`);
+
+ const apex = run(dir, { holds: [{ key: 'Space', from: 0, to: 3 }], frames: 40 });
+ const height = (apex.position?.y ?? 0) - START.y;
+ check('and reaches an apex worth having',
+ height > APEX_MIN, `apex ${height.toFixed(0)} (needs > ${APEX_MIN})`);
+
+ const landed = run(dir, { holds: [{ key: 'Space', from: 0, to: 3 }], frames: 140 });
+ const settled = (landed.position?.y ?? 0) - START.y;
+ check('and comes back down to the floor it left',
+ Math.abs(settled) < 4 && landed.grounded === true,
+ `settled ${settled.toFixed(1)}, grounded ${landed.grounded}`);
+
+ // Authority in the air is partial by design (airControl), so the claim is
+ // that the run CONTINUES through the arc, not that it is unchanged.
+ const jumped = run(dir, {
+ holds: [{ key: 'KeyW', from: 0, to: 90 }, { key: 'Space', from: 20, to: 23 }],
+ frames: 90,
+ });
+ const walked = run(dir, { holds: [{ key: 'KeyW', from: 0, to: 90 }], frames: 90 });
+ const jumpedDz = START.z - (jumped.position?.z ?? START.z);
+ const walkedDz = START.z - (walked.position?.z ?? START.z);
+ check('and keeps travelling while it is off the ground',
+ jumpedDz > walkedDz * 0.5, `jumped ${jumpedDz.toFixed(0)} vs walked ${walkedDz.toFixed(0)}`);
+
+ // The step it cannot walk over, it can jump onto: the pair above says the
+ // 90-unit step stops a walk, so arriving on top of it is the jump's doing.
+ const onto = run(dir, {
+ holds: [
+ { key: 'KeyA', from: 0, to: TO_LANE.highStep },
+ { key: 'KeyW', from: TO_LANE.highStep, to: TO_LANE.highStep + 150 },
+ { key: 'Space', from: TO_LANE.highStep + 88, to: TO_LANE.highStep + 91 },
+ ],
+ frames: TO_LANE.highStep + 150,
+ });
+ const stood = (onto.position?.y ?? 0) - START.y;
+ check('a step too tall to walk over can be jumped onto',
+ stood > 40 && onto.grounded === true,
+ `stood ${stood.toFixed(0)}, grounded ${onto.grounded}`);
+}
+
+// 7. Camera-relative movement, turned by a real mouse drag.
{
const straight = run(dir, { keys: ['KeyW'], frames: 90 });
// sensitivity 0.2 deg/px over a 960-wide surface: 450 px is a quarter turn.
@@ -174,7 +229,7 @@ const START = { y: 60, z: 120 };
`dx ${turnedDx.toFixed(0)}, dz ${turnedDz.toFixed(0)}`);
}
-// 7. Camera obstruction, against the same wall the character cannot pass.
+// 8. Camera obstruction, against the same wall the character cannot pass.
{
const open = run(dir, { frames: 40 });
const against = run(dir, standIn(TO_LANE.wall, 'KeyD'));