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 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.estimelinenew file mode 100644index 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.metanew file mode 100644index 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.esanimatorindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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);+ }+ });+});