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 character off the ground stops looking like one standing on it

esengine7668f868c02b
diff --git a/examples/third-person-3d/assets/models/airborne.estimeline b/examples/third-person-3d/assets/models/airborne.estimeline
new file mode 100644
index 000000000..4e0dd666a
--- /dev/null
+++ b/examples/third-person-3d/assets/models/airborne.estimeline
@@ -0,0 +1,120 @@
+{
+ "version": "1.2",
+ "type": "timeline",
+ "duration": 1,
+ "wrapMode": "loop",
+ "tracks": [
+ {
+ "type": "property",
+ "name": "Bone1",
+ "childPath": "Bone1",
+ "component": "Transform",
+ "channels": [
+ {
+ "property": "rotation.x",
+ "keyframes": [
+ {
+ "time": 0.0,
+ "value": -0.5736,
+ "inTangent": 0,
+ "outTangent": 0,
+ "interpolation": "linear"
+ },
+ {
+ "time": 0.5,
+ "value": -0.6428,
+ "inTangent": 0,
+ "outTangent": 0,
+ "interpolation": "linear"
+ },
+ {
+ "time": 1.0,
+ "value": -0.5736,
+ "inTangent": 0,
+ "outTangent": 0,
+ "interpolation": "linear"
+ }
+ ]
+ },
+ {
+ "property": "rotation.y",
+ "keyframes": [
+ {
+ "time": 0.0,
+ "value": 0,
+ "inTangent": 0,
+ "outTangent": 0,
+ "interpolation": "linear"
+ },
+ {
+ "time": 0.5,
+ "value": 0,
+ "inTangent": 0,
+ "outTangent": 0,
+ "interpolation": "linear"
+ },
+ {
+ "time": 1.0,
+ "value": 0,
+ "inTangent": 0,
+ "outTangent": 0,
+ "interpolation": "linear"
+ }
+ ]
+ },
+ {
+ "property": "rotation.z",
+ "keyframes": [
+ {
+ "time": 0.0,
+ "value": 0,
+ "inTangent": 0,
+ "outTangent": 0,
+ "interpolation": "linear"
+ },
+ {
+ "time": 0.5,
+ "value": 0,
+ "inTangent": 0,
+ "outTangent": 0,
+ "interpolation": "linear"
+ },
+ {
+ "time": 1.0,
+ "value": 0,
+ "inTangent": 0,
+ "outTangent": 0,
+ "interpolation": "linear"
+ }
+ ]
+ },
+ {
+ "property": "rotation.w",
+ "keyframes": [
+ {
+ "time": 0.0,
+ "value": 0.8192,
+ "inTangent": 0,
+ "outTangent": 0,
+ "interpolation": "linear"
+ },
+ {
+ "time": 0.5,
+ "value": 0.766,
+ "inTangent": 0,
+ "outTangent": 0,
+ "interpolation": "linear"
+ },
+ {
+ "time": 1.0,
+ "value": 0.8192,
+ "inTangent": 0,
+ "outTangent": 0,
+ "interpolation": "linear"
+ }
+ ]
+ }
+ ]
+ }
+ ]
+}
diff --git a/examples/third-person-3d/assets/models/airborne.estimeline.meta b/examples/third-person-3d/assets/models/airborne.estimeline.meta
new file mode 100644
index 000000000..356227426
--- /dev/null
+++ b/examples/third-person-3d/assets/models/airborne.estimeline.meta
@@ -0,0 +1,6 @@
+{
+ "uuid": "93493690-4828-46a2-adcd-cc9d3cb4a869",
+ "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 d3d140974..272aea2ce 100644
--- a/examples/third-person-3d/assets/models/locomotion.esanimator
+++ b/examples/third-person-3d/assets/models/locomotion.esanimator
@@ -17,6 +17,10 @@
{
"name": "attack",
"type": "trigger"
+ },
+ {
+ "name": "jump",
+ "type": "trigger"
}
],
"initialState": "Idle",
@@ -113,6 +117,49 @@
"duration": 0.15
}
]
+ },
+ {
+ "name": "Airborne",
+ "motion": {
+ "kind": "timeline",
+ "clip": "airborne.estimeline",
+ "loop": true
+ },
+ "rootMotion": false,
+ "transitions": [
+ {
+ "to": "Locomotion",
+ "conditions": [
+ {
+ "param": "grounded",
+ "op": "true"
+ },
+ {
+ "param": "speed",
+ "op": "gt",
+ "value": 8
+ }
+ ],
+ "duration": 0.12
+ },
+ {
+ "to": "Idle",
+ "conditions": [
+ {
+ "param": "grounded",
+ "op": "true"
+ },
+ {
+ "param": "speed",
+ "op": "lt",
+ "value": 8
+ }
+ ],
+ "duration": 0.12
+ }
+ ],
+ "x": 520,
+ "y": 80
}
],
"anyStateTransitions": [
@@ -135,6 +182,26 @@
}
],
"duration": 0.08
+ },
+ {
+ "to": "Airborne",
+ "conditions": [
+ {
+ "param": "jump",
+ "op": "trigger"
+ }
+ ],
+ "duration": 0.06
+ },
+ {
+ "to": "Airborne",
+ "conditions": [
+ {
+ "param": "grounded",
+ "op": "false"
+ }
+ ],
+ "duration": 0.12
}
]
}
diff --git a/sdk/src/gameplay/GameplayPlugin.ts b/sdk/src/gameplay/GameplayPlugin.ts
index 4b6ca2aa7..87d51ac56 100644
--- a/sdk/src/gameplay/GameplayPlugin.ts
+++ b/sdk/src/gameplay/GameplayPlugin.ts
@@ -36,7 +36,7 @@ import {
ThirdPersonController, type ThirdPersonControllerData,
desiredDirection, approachVelocity, facingYaw, turnToward, rootMotionVelocity,
yawQuaternion, yawOfQuaternion, WORLD_BASIS, DODGE_KEY, ATTACK_KEY,
- TPC_SPEED, TPC_GROUNDED, TPC_DODGE, TPC_ATTACK, type MoveBasis,
+ TPC_SPEED, TPC_GROUNDED, TPC_DODGE, TPC_ATTACK, TPC_JUMP, type MoveBasis,
} from './ThirdPersonController';
import {
ThirdPersonCamera, type ThirdPersonCameraData,
@@ -125,6 +125,13 @@ export function requestMotion(
c.velocity.z = next.z;
c.velocity.y = jumping ? data.jumpSpeed : 0;
});
+
+ // The jump that was APPLIED, not the key that asked for one. An edge
+ // rather than a level: this runs on the fixed clock and the animator on
+ // the frame's, so a whole arc can pass between two of its samples.
+ if (jumping && animator && world.has(entity, Animator)) {
+ animator.setTrigger(entity, TPC_JUMP);
+ }
}
}
diff --git a/sdk/src/gameplay/ThirdPersonController.ts b/sdk/src/gameplay/ThirdPersonController.ts
index 77cce1a41..6855fe6b8 100644
--- a/sdk/src/gameplay/ThirdPersonController.ts
+++ b/sdk/src/gameplay/ThirdPersonController.ts
@@ -27,6 +27,8 @@ import type { Vec3 } from '../types';
*/
export const TPC_SPEED = 'speed';
export const TPC_GROUNDED = 'grounded';
+/** Set the frame a jump was ACCEPTED, not the frame one was asked for. */
+export const TPC_JUMP = 'jump';
export const TPC_DODGE = 'dodge';
export const TPC_ATTACK = 'attack';
diff --git a/sdk/src/gameplay/index.ts b/sdk/src/gameplay/index.ts
index 30631f1e6..66531063a 100644
--- a/sdk/src/gameplay/index.ts
+++ b/sdk/src/gameplay/index.ts
@@ -10,6 +10,7 @@ export {
rootMotionVelocity,
TPC_SPEED,
TPC_GROUNDED,
+ TPC_JUMP,
TPC_DODGE,
TPC_ATTACK,
yawQuaternion,
diff --git a/sdk/tests/airborne.test.ts b/sdk/tests/airborne.test.ts
new file mode 100644
index 000000000..bedc36816
--- /dev/null
+++ b/sdk/tests/airborne.test.ts
@@ -0,0 +1,259 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * The claim: a character off the ground stops looking like one standing on it.
+ * Through the SHIPPED graph and clip — a fixture pair proves nothing about them.
+ */
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import {
+ ThirdPersonController, requestMotion, observeMotion,
+ TPC_SPEED, TPC_GROUNDED, TPC_JUMP,
+ type ThirdPersonControllerData,
+} from '../src/gameplay';
+import { CharacterController3D, type CharacterController3DData } from '../src/physics3d/Physics3DComponents';
+import {
+ Animator, AnimatorControllerAPI,
+ type AnimatorData, type AnimatorControllerDef,
+} from '../src/animation';
+import { createTimelineMotionDriver, TIMELINE_MOTION, parseTimelineAsset } from '../src/timeline';
+import { TimelineAPI } from '../src/timeline/TimelineControl';
+import { Transform, Children, Name, type TransformData } from '../src/ecs/component';
+
+const PLAYER = 1;
+const BONE1 = 2;
+const MODELS = path.resolve(__dirname, '../../examples/third-person-3d/assets/models');
+
+const asset = (name: string) =>
+ parseTimelineAsset(JSON.parse(readFileSync(path.join(MODELS, name), 'utf8')));
+const GRAPH: AnimatorControllerDef =
+ JSON.parse(readFileSync(path.join(MODELS, 'locomotion.esanimator'), 'utf8'));
+
+function makeWorld() {
+ const store = new Map<unknown, Map<number, unknown>>();
+ const children = new Map<number, Record<string, number>>();
+ const mapOf = (c: unknown) => {
+ let m = store.get(c);
+ if (!m) { m = new Map(); store.set(c, m); }
+ return m;
+ };
+ return {
+ childOf: children,
+ insert(e: number, c: unknown, d: unknown) { mapOf(c).set(e, d); },
+ get(e: number, c: unknown) { return mapOf(c).get(e); },
+ has(e: number, c: unknown) { return mapOf(c).has(e); },
+ set(e: number, c: unknown, d: unknown) { mapOf(c).set(e, d); },
+ tryGet(e: number, c: unknown) { return mapOf(c).get(e) ?? null; },
+ valid() { return true; },
+ ensureTransformsComposed() { /* nothing is parented in this harness */ },
+ update(e: number, c: unknown, edit: (d: any) => void) {
+ const d = mapOf(c).get(e);
+ if (d === undefined) throw new Error('update: entity does not carry it');
+ edit(d); mapOf(c).set(e, d);
+ },
+ getEntitiesWithComponents(comps: unknown[]) {
+ const [first, ...rest] = comps;
+ return [...mapOf(first).keys()].filter((e) => rest.every((c) => mapOf(c).has(e)));
+ },
+ findEntityByName(name: string) { return name === 'Bone1' ? BONE1 : null; },
+ } as any;
+}
+
+const character = (over: Partial<CharacterController3DData> = {}): CharacterController3DData => ({
+ velocity: { x: 0, y: 0, z: 0 },
+ radius: 30, halfHeight: 30, maxSlope: 0.87, layer: 0,
+ stepHeight: 40, snapDown: 50, mass: 70, pushForce: 5000, enabled: true,
+ isOnFloor: true, floorNormal: { x: 0, y: 1, z: 0 },
+ realVelocity: { x: 0, y: 0, z: 0 },
+ ...over,
+} as CharacterController3DData);
+
+const controller = (over: Partial<ThirdPersonControllerData> = {}): ThirdPersonControllerData => ({
+ moveSpeed: 320, acceleration: 2400, deceleration: 3200, rotationSpeed: 720,
+ jumpSpeed: 520, airControl: 0.3, cameraRelative: false, camera: 0 as never,
+ idleThreshold: 8, enabled: true, ...over,
+});
+
+const transform = (): TransformData => ({
+ position: { x: 0, y: 0, z: 0 },
+ rotation: { w: 1, x: 0, y: 0, z: 0 },
+ scale: { x: 1, y: 1, z: 1 },
+} as TransformData);
+
+/** Keys the controller reads, as the input resource it expects. */
+const keys = (down: string[] = [], pressed: string[] = []) => ({
+ isKeyDown: (k: string) => down.includes(k),
+ isKeyPressed: (k: string) => pressed.includes(k),
+ getMousePosition: () => ({ x: 0, y: 0 }),
+ isMouseButtonDown: () => false,
+}) as any;
+
+function rig() {
+ const world = makeWorld();
+ world.insert(PLAYER, Transform, transform());
+ world.insert(PLAYER, CharacterController3D, character());
+ world.insert(PLAYER, ThirdPersonController, controller());
+ world.insert(PLAYER, Animator,
+ { controller: 'loco', currentState: '', enabled: true } as AnimatorData);
+ // The joint the clips pose, reached the way the sampler reaches it: a
+ // `childPath` is walked through Children and Name, so a harness that only
+ // holds a Transform is one the clip writes nothing into.
+ world.insert(PLAYER, Children, { entities: [BONE1] } as any);
+ world.insert(BONE1, Name, { value: 'Bone1' } as any);
+ world.insert(BONE1, Transform, transform());
+
+ const timeline = new TimelineAPI();
+ for (const name of ['skinned-fade_Flat', 'skinned-fade_Bent', 'airborne', 'dodge', 'attack']) {
+ timeline.registerAsset(`${name}.estimeline`, asset(`${name}.estimeline`));
+ }
+ const ctrl = new AnimatorControllerAPI();
+ ctrl.registerMotionDriver(TIMELINE_MOTION, createTimelineMotionDriver(timeline));
+ ctrl.registerController('loco', GRAPH);
+ return { world, ctrl };
+}
+
+/** The clip the SHIPPED graph's Airborne state actually plays. Read from the
+ * graph, not named here: a pose claim that hard-codes the file it wants stays
+ * green when the state is repointed at a ground clip. */
+const AIRBORNE_CLIP =
+ (GRAPH.states.find((s) => s.name === 'Airborne')?.motion as any)?.clip as string;
+
+const stateOf = (world: any) => (world.get(PLAYER, Animator) as AnimatorData).currentState;
+
+/** One frame: ask, let the world answer, observe, then pose. */
+function frame(
+ world: any, ctrl: AnimatorControllerAPI,
+ { down = [], pressed = [], onFloor, moved = { x: 0, z: 0 } }:
+ { down?: string[]; pressed?: string[]; onFloor: boolean; moved?: { x: number; z: number } },
+) {
+ const dt = 1 / 60;
+ requestMotion(world, keys(down, pressed), dt, ctrl);
+ world.update(PLAYER, CharacterController3D, (c: CharacterController3DData) => {
+ c.isOnFloor = onFloor;
+ c.realVelocity.x = moved.x; c.realVelocity.z = moved.z;
+ });
+ observeMotion(world, ctrl, dt);
+ ctrl.update(world, dt);
+}
+
+describe('the shipped graph answers leaving the ground', () => {
+ it('declares an Airborne state over its own clip', () => {
+ const airborne = GRAPH.states.find((s) => s.name === 'Airborne');
+ expect(airborne, 'the shipped graph has no Airborne state').toBeDefined();
+ expect((airborne!.motion as any).clip).toBe('airborne.estimeline');
+ // The character controller owns the vertical; a clip that also moved it
+ // would be a second author of the same number.
+ expect(airborne!.rootMotion).toBe(false);
+ });
+
+ it('its clip states a pose and no placement', () => {
+ // The flag above is half of it: with rootMotion off a root track lands
+ // in the character's Transform, which the controller owns and discards
+ // silently — a clip that moves the character, and no frame that shows it.
+ const clip = JSON.parse(readFileSync(path.join(MODELS, AIRBORNE_CLIP), 'utf8'));
+ const placement = clip.tracks.flatMap((t: any) => (t.channels ?? [])
+ .filter((c: any) => /^position\./.test(c.property))
+ .map((c: any) => `${t.name}.${c.property}`));
+ expect(placement, 'the airborne clip places the character').toEqual([]);
+ });
+
+ it('stands in a ground state while it is on the floor', () => {
+ const { world, ctrl } = rig();
+ for (let i = 0; i < 6; i++) frame(world, ctrl, { onFloor: true });
+ expect(stateOf(world)).toBe('Idle');
+ });
+
+ it('an accepted jump reaches Airborne', () => {
+ const { world, ctrl } = rig();
+ frame(world, ctrl, { onFloor: true });
+ frame(world, ctrl, { pressed: ['Space'], onFloor: true });
+ expect(stateOf(world)).toBe('Airborne');
+ });
+
+ it('stays Airborne while it is off the floor', () => {
+ const { world, ctrl } = rig();
+ frame(world, ctrl, { pressed: ['Space'], onFloor: true });
+ for (let i = 0; i < 20; i++) frame(world, ctrl, { onFloor: false });
+ expect(stateOf(world)).toBe('Airborne');
+ });
+
+ it('walking off a ledge is airborne too, with no jump to announce it', () => {
+ const { world, ctrl } = rig();
+ const seen: string[] = [];
+ const spy = new Proxy(ctrl, {
+ get(t: any, k) {
+ if (k === 'setTrigger') {
+ return (e: number, n: string) => { seen.push(n); return t.setTrigger(e, n); };
+ }
+ const v = t[k];
+ return typeof v === 'function' ? v.bind(t) : v;
+ },
+ }) as AnimatorControllerAPI;
+ for (let i = 0; i < 3; i++) frame(world, spy, { onFloor: true });
+ for (let i = 0; i < 6; i++) frame(world, spy, { onFloor: false });
+ expect(seen).not.toContain(TPC_JUMP);
+ expect(ctrl.getBool(PLAYER, TPC_GROUNDED)).toBe(false);
+ expect(stateOf(world)).toBe('Airborne');
+ });
+
+ it('landing still returns to Idle', () => {
+ const { world, ctrl } = rig();
+ frame(world, ctrl, { pressed: ['Space'], onFloor: true });
+ for (let i = 0; i < 6; i++) frame(world, ctrl, { onFloor: false });
+ for (let i = 0; i < 6; i++) frame(world, ctrl, { onFloor: true });
+ expect(stateOf(world)).toBe('Idle');
+ });
+
+ it('landing at speed returns to Locomotion', () => {
+ const { world, ctrl } = rig();
+ frame(world, ctrl, { pressed: ['Space'], onFloor: true });
+ for (let i = 0; i < 6; i++) frame(world, ctrl, { onFloor: false });
+ for (let i = 0; i < 6; i++) {
+ frame(world, ctrl, { down: ['KeyW'], onFloor: true, moved: { x: 0, z: -300 } });
+ }
+ expect(ctrl.getFloat(PLAYER, TPC_SPEED)).toBeGreaterThan(8);
+ expect(stateOf(world)).toBe('Locomotion');
+ });
+});
+
+describe('the airborne pose is one a grounded pose cannot be mistaken for', () => {
+ /** What the shipped clip writes into the joint at `t`, as the sampler sees it. */
+ function poseAt(clip: string, t: number) {
+ const { world, ctrl } = rig();
+ const timeline = new TimelineAPI();
+ timeline.registerAsset(clip, asset(clip));
+ const driver = createTimelineMotionDriver(timeline);
+ const solo = new AnimatorControllerAPI();
+ solo.registerMotionDriver(TIMELINE_MOTION, driver);
+ solo.registerController('one', {
+ parameters: [], initialState: 'S',
+ states: [{ name: 'S', motion: { kind: TIMELINE_MOTION, clip, loop: true }, transitions: [] }],
+ });
+ world.update(PLAYER, Animator, (a: AnimatorData) => { a.controller = 'one'; a.currentState = ''; });
+ solo.update(world, 0);
+ solo.update(world, t);
+ return { ...(world.get(BONE1, Transform) as TransformData).rotation };
+ }
+
+ it('tilts about X, which every ground clip leaves alone', () => {
+ const air = poseAt(AIRBORNE_CLIP, 0.5);
+ expect(Math.abs(air.x)).toBeGreaterThan(0.4);
+ for (const ground of ['skinned-fade_Flat.estimeline', 'skinned-fade_Bent.estimeline']) {
+ expect(Math.abs(poseAt(ground, 0.5).x)).toBeLessThan(0.05);
+ }
+ });
+
+ it('is far enough from every other shipped pose to be told apart', () => {
+ const air = poseAt(AIRBORNE_CLIP, 0.5);
+ const others = ['skinned-fade_Flat.estimeline', 'skinned-fade_Bent.estimeline',
+ 'dodge.estimeline', 'attack.estimeline'].filter((n) => n !== AIRBORNE_CLIP);
+ for (const name of others) {
+ const p = poseAt(name, 0.25);
+ // Quaternion dot: 1 is the same orientation. Anything this graph can
+ // reach must be visibly apart, or a screenshot proves nothing.
+ const dot = Math.abs(air.x * p.x + air.y * p.y + air.z * p.z + air.w * p.w);
+ expect(dot, `${name} is indistinguishable from airborne`).toBeLessThan(0.95);
+ }
+ });
+});