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
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
//
// Locks the .esanimator graph ops after they were refactored onto the shared
// `stateGraph` core — the structural algorithms are shared with fsmGraph, but
// the animator keeps required transition lists, `{to, conditions}` payloads,
// parameters, and any-state transition rewiring on rename.
import { describe, it, expect } from 'vitest';
import {
emptyAnimatorController, animatorEdges,
addState, removeState, moveState, renameState, setInitial,
addTransition, removeTransition, updateTransition, setConditions,
addParam, removeParam, updateParam,
addLayer as addAnimatorLayer, removeLayer as removeAnimatorLayer,
updateLayer as updateAnimatorLayer, moveLayer as moveAnimatorLayer,
addIK as addAnimatorIK, removeIK as removeAnimatorIK, updateIK as updateAnimatorIK,
} from '../src/animation/animatorGraph';
import { animatorLayerCount, ANIMATOR_FORMAT_VERSION } from '../src/animation/Animator';
import type { AnimatorControllerDef } from '../src/animation/Animator';
describe('animatorGraph', () => {
it('creates a blank controller with one initial state and no params', () => {
const def = emptyAnimatorController();
expect(def.initialState).toBe('Idle');
expect(def.states).toEqual([{ name: 'Idle', x: 80, y: 80, transitions: [] }]);
expect(def.parameters).toEqual([]);
});
it('adds states immutably; first state of an empty graph becomes initial', () => {
const empty: AnimatorControllerDef = { parameters: [], states: [], initialState: '' };
const one = addState(empty, 'Run', 10, 20);
expect(one).not.toBe(empty);
expect(one.initialState).toBe('Run');
expect(one.states[0]).toEqual({ name: 'Run', x: 10, y: 20, transitions: [] });
// duplicate is ignored
expect(addState(one, 'Run')).toBe(one);
});
it('removes a state and prunes transitions that target it, reassigning initial', () => {
let def = emptyAnimatorController();
def = addState(def, 'Run');
def = addTransition(def, 'Run', 'Idle');
def = removeState(def, 'Idle');
expect(def.states.map(s => s.name)).toEqual(['Run']);
expect(def.states[0].transitions).toEqual([]);
expect(def.initialState).toBe('Run');
});
it('creates transitions with an empty condition list and updates them', () => {
let def = emptyAnimatorController();
def = addState(def, 'Run');
def = addTransition(def, 'Idle', 'Run');
expect(def.states[0].transitions).toEqual([{ to: 'Run', conditions: [] }]);
def = setConditions(def, 'Idle', 0, [{ param: 'Speed', op: 'gt', value: 0.1 }]);
expect(def.states[0].transitions[0].conditions).toHaveLength(1);
def = updateTransition(def, 'Idle', 0, { hasExitTime: true });
expect(def.states[0].transitions[0].hasExitTime).toBe(true);
def = removeTransition(def, 'Idle', 0);
expect(def.states[0].transitions).toEqual([]);
});
it('renames a state, rewiring initial, state transitions AND any-state transitions', () => {
let def = emptyAnimatorController();
def = addState(def, 'Run');
def = addTransition(def, 'Run', 'Idle');
def = { ...def, anyStateTransitions: [{ to: 'Idle', conditions: [] }] };
def = renameState(def, 'Idle', 'Base');
expect(def.initialState).toBe('Base');
expect(def.states.find(s => s.name === 'Run')!.transitions[0].to).toBe('Base');
expect(def.anyStateTransitions![0].to).toBe('Base');
});
it('moves a state and sets initial only to an existing state', () => {
let def = addState(emptyAnimatorController(), 'Run', 0, 0);
def = moveState(def, 'Run', 40, 50);
expect(def.states.find(s => s.name === 'Run')).toMatchObject({ x: 40, y: 50 });
expect(setInitial(def, 'Nope')).toBe(def);
expect(setInitial(def, 'Run').initialState).toBe('Run');
});
it('manages parameters', () => {
let def = emptyAnimatorController();
def = addParam(def, 'Speed', 'float');
expect(def.parameters).toEqual([{ name: 'Speed', type: 'float' }]);
expect(addParam(def, 'Speed', 'int')).toBe(def); // duplicate ignored
def = updateParam(def, 'Speed', { type: 'int' });
expect(def.parameters[0].type).toBe('int');
def = removeParam(def, 'Speed');
expect(def.parameters).toEqual([]);
});
it('flattens transitions into addressable edges', () => {
let def = emptyAnimatorController();
def = addState(def, 'Run');
def = addTransition(def, 'Idle', 'Run');
const edges = animatorEdges(def);
expect(edges).toHaveLength(1);
expect(edges[0]).toMatchObject({ id: 'Idle->Run#0', from: 'Idle', to: 'Run', index: 0 });
});
});
// ---------------------------------------------------------------------------
// Layers
// ---------------------------------------------------------------------------
describe('editing a controller with layers', () => {
const base = (): AnimatorControllerDef => ({
version: ANIMATOR_FORMAT_VERSION,
parameters: [],
states: [{ name: 'Idle', transitions: [] }],
initialState: 'Idle',
});
it('adds a layer with a machine of its own', () => {
const def = addAnimatorLayer(base(), 'arms');
expect(animatorLayerCount(def)).toBe(2);
expect(def.layers![0]!.states).toHaveLength(1);
expect(def.layers![0]!.initialState).toBe('Idle');
});
it('refuses a second layer by the same name', () => {
const once = addAnimatorLayer(base(), 'arms');
expect(addAnimatorLayer(once, 'arms')).toBe(once);
});
it('edits the layer the op was given and no other', () => {
// The base and the layer both hold a state called Idle. An op that
// reached the wrong one would still "work", which is why this asserts on
// both sides rather than on the one it edited.
let def = addAnimatorLayer(base(), 'arms');
def = addState(def, 'Wave', 0, 0, 1);
expect(def.layers![0]!.states.map(s => s.name)).toEqual(['Idle', 'Wave']);
expect(def.states.map(s => s.name)).toEqual(['Idle']);
def = addState(def, 'Run', 0, 0);
expect(def.states.map(s => s.name)).toEqual(['Idle', 'Run']);
expect(def.layers![0]!.states.map(s => s.name)).toEqual(['Idle', 'Wave']);
});
it('renames within one layer, rewiring that layer’s any-state edges', () => {
let def = addAnimatorLayer(base(), 'arms');
def = updateAnimatorLayer(def, 1, {});
def = { ...def, layers: [{ ...def.layers![0]!, anyStateTransitions: [{ to: 'Idle', conditions: [] }] }] };
def = renameState(def, 'Idle', 'Calm', 1);
expect(def.layers![0]!.initialState).toBe('Calm');
expect(def.layers![0]!.anyStateTransitions![0]!.to).toBe('Calm');
expect(def.initialState).toBe('Idle');
});
it('sets what a layer IS, and refuses to on the base', () => {
let def = addAnimatorLayer(base(), 'arms');
def = updateAnimatorLayer(def, 1, { weight: 0.4, blend: 'additive', mask: { paths: ['chest'] } });
expect(def.layers![0]!.weight).toBe(0.4);
expect(def.layers![0]!.blend).toBe('additive');
expect(def.layers![0]!.mask!.paths).toEqual(['chest']);
// The base layer has no weight to set — it is what the others modify.
expect(updateAnimatorLayer(def, 0, { weight: 0.5 })).toBe(def);
expect(removeAnimatorLayer(def, 0)).toBe(def);
});
it('reorders layers, order being what a stack means', () => {
let def = addAnimatorLayer(addAnimatorLayer(base(), 'arms'), 'aim');
expect(def.layers!.map(l => l.name)).toEqual(['arms', 'aim']);
def = moveAnimatorLayer(def, 2, 1);
expect(def.layers!.map(l => l.name)).toEqual(['aim', 'arms']);
});
it('removes a layer without disturbing the base', () => {
let def = addAnimatorLayer(base(), 'arms');
def = removeAnimatorLayer(def, 1);
expect(animatorLayerCount(def)).toBe(1);
expect(def.states.map(s => s.name)).toEqual(['Idle']);
});
});
describe('editing a controller’s constraints', () => {
const base = (): AnimatorControllerDef => ({
version: ANIMATOR_FORMAT_VERSION, parameters: [],
states: [{ name: 'Idle', transitions: [] }], initialState: 'Idle',
});
it('adds one that reaches for nothing until an author says what', () => {
const def = addAnimatorIK(base(), 'two-bone');
expect(def.ik).toHaveLength(1);
expect(def.ik![0]).toEqual({ kind: 'two-bone', tip: '', target: '' });
});
it('drops the field the other kind owns when the kind changes', () => {
// A pole on a look-at is a field nothing reads; leaving it writes a file
// that answers a question it was not asked.
let def = addAnimatorIK(base(), 'two-bone');
def = updateAnimatorIK(def, 0, { tip: 'Hand', target: 'Goal', pole: 'Elbow' });
expect(def.ik![0]!.pole).toBe('Elbow');
def = updateAnimatorIK(def, 0, { kind: 'look-at', axis: 'x' });
expect(def.ik![0]!.pole).toBeUndefined();
expect(def.ik![0]!.axis).toBe('x');
expect(def.ik![0]!.tip).toBe('Hand');
def = updateAnimatorIK(def, 0, { kind: 'two-bone' });
expect(def.ik![0]!.axis).toBeUndefined();
});
it('removes one, and refuses an index it has not got', () => {
const def = addAnimatorIK(base(), 'look-at');
expect(removeAnimatorIK(def, 0).ik).toEqual([]);
expect(removeAnimatorIK(def, 7)).toBe(def);
expect(updateAnimatorIK(def, 7, { tip: 'x' })).toBe(def);
});
});