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(animation): an animator state can play at the speed of a float parameter (speedParameter), and the Cocos animation graph is converted to an animator controller
yhhfc333ba01ef9
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 051aadc03..adcada9c0 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -20,6 +20,7 @@ published separately; it ships inside the editor.- **Scroll areas can be pulled past an end and spring back.** A scroll area whose movement is Elastic now does what the setting always said: a drag past an end is stiffer the further out it goes, letting go returns the content, and a flick that reaches an end bounces off it. It is opt-in per area (`ScrollMovement.Elastic`; Clamped, the default, behaves as before), and the gesture model (`ScrollMotion`, with `ScrollContainer.dragTo` and `getOverscroll`) is exported for scrolling anything else the same way.- **More easing curves.** Sine, quart, quint, expo and circ (each in, out and in-out), bounce in and in-out, and smoothstep and smootherstep join the quad, cubic, back, elastic and out-bounce curves. They are new `EasingType` members after the existing ones, so a saved tween keeps its curve, and they ease the same in a C++ tween and a script value tween.- **World content has a rectangle: `ContentRect`.** A size and the pivot the entity's transform sits on, which the `Sprite` and `Text` on the entity follow and which a `UIMask` on it clips to — no `UINode` needed, so a clipping region or a scroll viewport can stand in the world. `contentRectContains` tests a world point against it.+- **An animator state can play at the speed of a parameter.** `speedParameter` on an `AnimatorState` names a float parameter; the state's clock advances by `dt` times its value, so a run clip follows a character's speed and a value of 0 holds the pose. It applies to every kind of motion, since it is the state's own clock that is scaled.- **Particles can carry an added velocity and be held to a speed limit.** `ParticleEmitter.addedVelocityMin` and `addedVelocityMax` give each particle a velocity on top of its own, chosen between the two when it is born and untouched by gravity, damping and noise. `speedLimit` pulls a faster particle back toward the limit, by `limitDampen` of the excess every 1/60 s so the braking does not depend on the frame rate. Both are run by the CPU simulation.- **An emitter can start late.** `ParticleEmitter.startDelay` holds back emission for that many seconds after the emitter starts playing; the duration of a non-looping emitter is counted from the end of the delay. Zero, the default, is the behaviour before.- **Particles can be stretched along their velocity.** `ParticleEmitter.renderMode` is `Billboard` (as before) or `Stretched`, which turns each particle's quad so its Y axis runs along the particle's velocity and makes it `size * lengthScale + speed * velocityScale` long: sparks, rain and streaks. A particle at rest keeps its own rotation. It is drawn by the CPU simulation; an emitter simulated on the GPU still draws as a billboard.diff --git a/docs/astro/src/content/docs/animation/overview.mdx b/docs/astro/src/content/docs/animation/overview.mdxindex 3492b6ffe..0c273617d 100644--- a/docs/astro/src/content/docs/animation/overview.mdx+++ b/docs/astro/src/content/docs/animation/overview.mdx@@ -613,6 +613,25 @@ What the animator promises:The animator calls into no particle system, no audio and no gameplay: it statesthe event, and whoever owns those things answers it.+### State speed that follows a parameter++A state's playback speed can follow a float parameter, so a run clip keeps pace+with a character's speed:++```json+{+ "name": "Run",+ "motion": { "kind": "timeline", "clip": "run.estimeline", "loop": true },+ "speedParameter": "MoveSpeed",+ "transitions": []+}+```++The state's clock advances by `dt × MoveSpeed`: 2 plays twice as fast, 0 holds the+pose. It scales whatever the motion is, a sprite clip, a timeline or a blend,+because it is the state's clock that is scaled. A parameter that is not there plays+at the normal rate.+### Root motionA clip that animates the entity it is played **on** is not posing a skeleton —diff --git a/docs/astro/src/content/docs/zh-cn/animation/overview.mdx b/docs/astro/src/content/docs/zh-cn/animation/overview.mdxindex db7ea2d0d..6ad14d71a 100644--- a/docs/astro/src/content/docs/zh-cn/animation/overview.mdx+++ b/docs/astro/src/content/docs/zh-cn/animation/overview.mdx@@ -566,6 +566,21 @@ const footsteps = defineSystem(动画器不调用任何粒子、音频或玩法代码:它只陈述事件,由拥有这些东西的系统来回应。+### 状态速度跟随参数++状态的播放速度可以跟随一个浮点参数,这样奔跑片段就能跟上角色的移动速度:++```json+{+ "name": "Run",+ "motion": { "kind": "timeline", "clip": "run.estimeline", "loop": true },+ "speedParameter": "MoveSpeed",+ "transitions": []+}+```++状态的时钟每帧前进 `dt × MoveSpeed`:2 就是两倍速,0 就停在当前姿势。它缩放的是状态的时钟,所以不论动作是精灵片段、时间线还是混合都生效。参数不存在时按正常速度播放。+### 根运动一段动画如果动的是它被播放在其上的那个实体,它就不是在摆骨架的姿势——它是在说角色diff --git a/pipeline/src/import/cocos/animationGraph.ts b/pipeline/src/import/cocos/animationGraph.tsnew file mode 100644index 000000000..8ffabff76--- /dev/null+++ b/pipeline/src/import/cocos/animationGraph.ts@@ -0,0 +1,194 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file A Cocos `.animgraph` as an engine `.esanimator`.+ *+ * A graph is layers of state machines. A state plays a motion (one clip, or clips blended along a number), and transitions between states wait on+ * conditions over named variables, optionally for the clip to end. The engine's Animator is the same model: parameters (numbers, flags,+ * triggers), states with motions of any registered kind, transitions with conditions, an any-state, layers. So the conversion is a rename, and+ * what the Animator cannot state is counted: a mask on a layer, `<=` and `>=` (the Animator has only+ * `<` and `>`).+ */+type Raw = Record<string, unknown>;+const isObj = (v: unknown): v is Raw => typeof v === 'object' && v !== null && !Array.isArray(v);+const num = (v: unknown, d: number): number => (typeof v === 'number' && Number.isFinite(v) ? v : d);+const typeOf = (o: unknown): string => (isObj(o) && typeof o.__type__ === 'string' ? o.__type__.replace('cc.animation.', '') : '');++export interface GraphContext {+ /** The timeline a clip uuid plays as on the node the controller is put on, or null when it cannot be found there. */+ clip(clipUuid: string): string | null;+ /** Called with a short code for something the Animator cannot state. */+ note(code: string): void;+}++interface Condition { param: string; op: string; value?: number }+interface Transition { to: string; conditions: Condition[]; duration?: number; hasExitTime?: boolean }+interface State { name: string; motion?: Raw; speed?: number; speedParameter?: string; transitions: Transition[] }+interface Scope { states: State[]; initialState: string; anyStateTransitions: Transition[] }++export interface ConvertedGraph {+ document: Raw;+ /** Clip uuids the graph plays, found or not. */+ clips: string[];+}++export function convertAnimationGraph(objects: unknown, ctx: GraphContext): ConvertedGraph {+ const d = Array.isArray(objects) ? objects : [objects];+ const at = (v: unknown): unknown => (isObj(v) && typeof v.__id__ === 'number' ? d[v.__id__] : v);+ const root = d[0];+ const clips: string[] = [];++ // ---- parameters --------------------------------------------------------------------------------------------------------------------+ const parameters: Raw[] = [];+ const variables = isObj(root) && isObj(root._variables) ? root._variables : {};+ for (const [name, ref] of Object.entries(variables)) {+ const v = at(ref);+ const kind = typeOf(v);+ if (kind === 'TriggerVariable') parameters.push({ name, type: 'trigger' });+ else if (isObj(v) && num(v._type, 0) === 2) parameters.push({ name, type: 'bool', default: v._value === true });+ else parameters.push({ name, type: 'float', default: isObj(v) ? num(v._value, 0) : 0 });+ }+ const boolean = new Set(parameters.filter((p) => p.type === 'bool').map((p) => p.name as string));++ // ---- motions -----------------------------------------------------------------------------------------------------------------------+ const clipMotion = (ref: unknown): Raw | null => {+ const motion = at(ref);+ if (typeOf(motion) === 'ClipMotion' && isObj(motion)) {+ const uuid = isObj(motion.clip) && typeof motion.clip.__uuid__ === 'string' ? motion.clip.__uuid__ : '';+ if (!uuid) return null;+ clips.push(uuid);+ const timeline = ctx.clip(uuid);+ if (!timeline) { ctx.note('graph-clip-not-found'); return null; }+ return { kind: 'timeline', clip: timeline };+ }+ if (typeOf(motion) === 'AnimationBlend1D' && isObj(motion)) {+ const param = at(motion.param);+ const parameter = isObj(param) && typeof param.variable === 'string' ? param.variable : '';+ const thresholds = (Array.isArray(motion._items) ? motion._items : []).flatMap((item) => {+ const it = at(item);+ const inner = isObj(it) ? clipMotion(it.motion) : null;+ return inner && isObj(it) ? [{ value: num(it.threshold, 0), motion: inner }] : [];+ });+ if (!parameter || thresholds.length === 0) { ctx.note('graph-blend-empty'); return null; }+ return { kind: 'blend1d', parameter, thresholds };+ }+ if (motion !== undefined && motion !== null) ctx.note(`graph-motion-${typeOf(motion) || 'unknown'}`);+ return null;+ };++ // ---- one state machine as a scope ----------------------------------------------------------------------------------------------+ const scope = (machineRef: unknown): Scope => {+ const machine = at(machineRef);+ const m: Raw = isObj(machine) ? machine : {};+ const names = new Map<unknown, string>();+ const used = new Set<string>();+ const unique = (name: string): string => {+ let n = name || 'state';+ for (let i = 2; used.has(n); i++) n = `${name || 'state'}_${i}`;+ used.add(n);+ return n;+ };+ const stateRefs = Array.isArray(m._states) ? (m._states as unknown[]) : [];+ const entry = at(m._entryState), exit = at(m._exitState), any = at(m._anyState);+ const states: State[] = [];+ for (const ref of stateRefs) {+ const s = at(ref);+ if (s === entry || s === exit || s === any || !isObj(s)) continue;+ const name = unique(typeof s.name === 'string' ? s.name : '');+ names.set(s, name);+ const state: State = { name, transitions: [] };+ if (typeOf(s) === 'Motion') {+ const motion = clipMotion(s.motion);+ if (motion) state.motion = motion;+ state.speed = num(s.speed, 1);+ // the variable scales the state's clock; it has to be a number the graph declares+ if (s.speedMultiplierEnabled === true && typeof s.speedMultiplier === 'string' && s.speedMultiplier !== '') {+ if (parameters.some((p) => p.name === s.speedMultiplier && p.type === 'float')) state.speedParameter = s.speedMultiplier;+ else ctx.note('graph-speed-variable-missing');+ }+ } else {+ ctx.note(`graph-state-${typeOf(s) || 'unknown'}`);+ }+ states.push(state);+ }+ const conditionOf = (ref: unknown): Condition | null => {+ const c = at(ref);+ const kind = typeOf(c);+ if (kind === 'TriggerCondition' && isObj(c)) return typeof c.trigger === 'string' ? { param: c.trigger, op: 'trigger' } : null;+ if (kind === 'UnaryCondition' && isObj(c)) {+ const operand = at(c.operand);+ const param = isObj(operand) && typeof operand.variable === 'string' ? operand.variable : '';+ if (!param) { ctx.note('graph-condition-constant'); return null; }+ return { param, op: num(c.operator, 0) === 0 ? 'true' : 'false' };+ }+ if (kind === 'BinaryCondition' && isObj(c)) {+ const lhs = at(c.lhs), rhs = at(c.rhs);+ const param = isObj(lhs) && typeof lhs.variable === 'string' ? lhs.variable : '';+ const value = isObj(rhs) ? num(rhs.value, 0) : 0;+ if (!param) { ctx.note('graph-condition-constant'); return null; }+ const operator = num(c.operator, 0);+ if (operator === 3 || operator === 5) ctx.note('graph-condition-inclusive');+ if (boolean.has(param)) return { param, op: value !== 0 && operator !== 1 ? 'true' : 'false' };+ return { param, op: ['eq', 'neq', 'lt', 'lt', 'gt', 'gt'][operator] ?? 'eq', value };+ }+ ctx.note(`graph-condition-${kind || 'unknown'}`);+ return null;+ };+ let initialState = '';+ const transitions = Array.isArray(m._transitions) ? (m._transitions as unknown[]) : [];+ const anyStateTransitions: Transition[] = [];+ for (const ref of transitions) {+ const t = at(ref);+ if (!isObj(t)) continue;+ const from = at(t.from), to = at(t.to);+ if (from === entry) {+ const target = names.get(to);+ if (target && initialState === '') initialState = target;+ continue;+ }+ const target = names.get(to);+ if (to === exit || target === undefined) { ctx.note('graph-transition-to-exit'); continue; }+ const kind = typeOf(t);+ const conditions = (Array.isArray(t.conditions) ? t.conditions : []).map(conditionOf).filter((c): c is Condition => c !== null);+ const out: Transition = { to: target, conditions };+ if (kind === 'AnimationTransition') {+ const duration = num(t.duration, 0);+ if (duration > 0) out.duration = duration;+ if (t.relativeDuration === true && duration > 0) ctx.note('graph-duration-relative');+ if (t.exitConditionEnabled === true) out.hasExitTime = true;+ }+ if (from === any) anyStateTransitions.push(out);+ else {+ const owner = states.find((s) => names.get(from) === s.name);+ if (owner) owner.transitions.push(out);+ }+ }+ return { states, initialState: initialState || states[0]?.name || '', anyStateTransitions };+ };++ const layers = isObj(root) && Array.isArray(root._layers) ? (root._layers as unknown[]) : [];+ const built = layers.map((ref) => {+ const layer = at(ref);+ return { layer: isObj(layer) ? layer : ({} as Raw), scope: scope(isObj(layer) ? layer._stateMachine : undefined) };+ });+ const base = built[0]?.scope ?? { states: [], initialState: '', anyStateTransitions: [] };+ const toState = (s: State): Raw => ({+ name: s.name,+ ...(s.motion ? { motion: s.motion } : {}),+ ...(s.speed !== undefined && s.speed !== 1 ? { speed: s.speed } : {}),+ ...(s.speedParameter ? { speedParameter: s.speedParameter } : {}),+ transitions: s.transitions,+ });+ const scopeDoc = (s: Scope): Raw => ({+ states: s.states.map(toState), initialState: s.initialState,+ ...(s.anyStateTransitions.length > 0 ? { anyStateTransitions: s.anyStateTransitions } : {}),+ });+ const extra = built.slice(1).map(({ layer, scope: s }) => {+ if (layer.mask) ctx.note('graph-layer-mask');+ return { name: typeof layer.name === 'string' && layer.name ? layer.name : 'layer', weight: num(layer.weight, 1), blend: 'override', ...scopeDoc(s) };+ });+ return {+ document: { version: 2, parameters, ...scopeDoc(base), ...(extra.length > 0 ? { layers: extra } : {}) },+ clips,+ };+}diff --git a/pipeline/src/import/cocos/components.ts b/pipeline/src/import/cocos/components.tsindex ab9455be9..8a491e2aa 100644--- a/pipeline/src/import/cocos/components.ts+++ b/pipeline/src/import/cocos/components.ts@@ -65,6 +65,13 @@ export interface ComponentContext {* the part was picked because the model draws only one.*/modelMesh?(uuid: string): { components: Record<string, unknown>[]; exact: boolean } | null;+ /** The engine prefab of a model a uuid names (the whole model, or its scene), or null when the uuid is not a model that was brought in. */+ modelInstance?(uuid: string): { prefab: string; rootId: string; name: string; paths: Map<string, string> } | null;+ /**+ * The `.esanimator` a Cocos animation graph is converted to for a node whose bones stand at @p paths, or null when the graph is not one of the+ * project's. A graph that plays clips of a model is written once for each skeleton it is put on.+ */+ animatorController?(graphUuid: string, paths: Map<string, string>, where: string): { ref: string; complete: boolean } | null;/** The timeline a Cocos `.anim` clip is converted to (project-relative), or null when the clip is not one of the project's. */animationClip?(clipUuid: string, where: string): string | null;/** The joints, by name, a skinned part of a model is bound to, in the order its vertices index them. */@@ -454,12 +461,15 @@ function directionalLight(c: CocosComponent, ctx: ComponentContext, where: strin}/** Where each node under @p node stands, by name, as a path from it: what a clip addresses a node by. The first node of a name wins. */-function namePaths(node: CocosNode): Map<string, string> {+function namePaths(node: CocosNode, ctx: ComponentContext): Map<string, string> {const paths = new Map<string, string>();const walk = (n: CocosNode, prefix: string): void => {for (const child of n.children) {const here = prefix ? `${prefix}/${child.name}` : child.name;if (!paths.has(child.name)) paths.set(child.name, here);+ // a model put in under this node brings its own bones, which stand below the instance+ const model = child.instance ? ctx.modelInstance?.(child.instance.asset) : null;+ if (model) for (const [name, below] of model.paths) if (!paths.has(name)) paths.set(name, `${here}/${below}`);walk(child, here);}};@@ -508,18 +518,27 @@ function animation(c: CocosComponent, node: CocosNode, ctx: ComponentContext, whconst clips = (Array.isArray(c.data._clips) ? c.data._clips : []).map(uuidOf).filter(Boolean);const wanted = uuidOf(c.data._defaultClip) || clips[0] || '';// a clip of the project's own, or one that lives in a model file and animates the bones below this node- const ref = wanted ? ctx.animationClip?.(wanted, where) ?? ctx.clipOn?.(wanted, namePaths(node), where) : null;+ const ref = wanted ? ctx.animationClip?.(wanted, where) ?? ctx.clipOn?.(wanted, namePaths(node, ctx), where) : null;if (!ref) return null;if (clips.length > 1) ctx.report.note('animation-several-clips', where);ctx.report.component('cc.Animation', clips.length > 1 ? 'partial' : 'mapped');return { type: 'TimelinePlayer', data: { timeline: ref, playing: c.data.playOnLoad === true, speed: 1, wrapMode: '' } };}+/** `cc.animation.AnimationController`: the graph as the engine's Animator, with its clips on this node's own bones. */+function animationController(c: CocosComponent, node: CocosNode, ctx: ComponentContext, where: string): ComponentData | null {+ const graph = uuidOf(c.data._graph) || uuidOf(c.data.graph);+ const made = graph ? ctx.animatorController?.(graph, namePaths(node, ctx), where) : null;+ if (!made) return null;+ ctx.report.component('cc.animation.AnimationController', made.complete ? 'mapped' : 'partial');+ return { type: 'Animator', data: { controller: made.ref, enabled: c.enabled } };+}+/** `cc.SkeletalAnimation`: the clip it plays by default, copied onto this node's own bones, played from the start if the node asks. */function skeletalAnimation(c: CocosComponent, node: CocosNode, ctx: ComponentContext, where: string): ComponentData | null {const clips = (Array.isArray(c.data._clips) ? c.data._clips : []).map(uuidOf).filter(Boolean);const wanted = uuidOf(c.data._defaultClip) || clips[0] || '';- const ref = wanted ? ctx.clipOn?.(wanted, namePaths(node), where) : null;+ const ref = wanted ? ctx.clipOn?.(wanted, namePaths(node, ctx), where) : null;if (!ref) return null;if (clips.length > 1) ctx.report.note('animation-several-clips', where);ctx.report.component('cc.SkeletalAnimation', clips.length > 1 ? 'partial' : 'mapped');@@ -725,6 +744,9 @@ export function convertNode(node: CocosNode, ctx: ComponentContext, where: strinif (skinned) extra.push(...skinned.extra);break;}+ case 'cc.animation.AnimationController':+ out = animationController(c, node, ctx, where);+ break;case 'cc.Animation':out = animation(c, node, ctx, where);break;diff --git a/pipeline/src/import/cocos/convert.ts b/pipeline/src/import/cocos/convert.tsindex 808de1ffb..30bad8a62 100644--- a/pipeline/src/import/cocos/convert.ts+++ b/pipeline/src/import/cocos/convert.ts@@ -78,8 +78,6 @@ export interface ConvertContext extends ComponentContext {loadPrefab(uuid: string): CocosDocument | null;/** The project-relative path the converted prefab of a uuid is written to. */prefabRef(uuid: string): string | null;- /** The engine prefab of a model a uuid names (the whole model, or its scene), or null when the uuid is not a model that was brought in. */- modelInstance?(uuid: string): { prefab: string; rootId: string; name: string; paths: Map<string, string> } | null;/** Where the document being converted lives, for notes. */where: string;}diff --git a/pipeline/src/import/cocos/importProject.ts b/pipeline/src/import/cocos/importProject.tsindex ca5eff23d..d65bd2a53 100644--- a/pipeline/src/import/cocos/importProject.ts+++ b/pipeline/src/import/cocos/importProject.ts@@ -20,6 +20,7 @@ import { parseCocosDocument, type CocosDocument } from './document';import { ImportReport, type ImportReportData } from './report';import { CocosModels, clipOf, clipPlayOf, mintSidecar, retargetClip } from './models';import { convertAnimationClip } from './animationClip';+import { convertAnimationGraph } from './animationGraph';import type { MaterialInfo } from './components';export interface CocosImportOptions {@@ -194,6 +195,36 @@ export async function importCocosProject(opts: CocosImportOptions): Promise<Impoclips.set(entry.file, ref);return ref;},+ animatorController(graphUuid, paths, where) {+ const entry = index.byUuid.get(graphUuid.split('@')[0]!);+ if (!entry || !entry.rel.endsWith('.animgraph')) return null;+ let ref: string | null = null;+ let complete = true;+ try {+ let onModel = false;+ const converted = convertAnimationGraph(JSON.parse(readFileSync(entry.file, 'utf8')), {+ clip: (uuid) => {+ const own = ctx.animationClip?.(uuid, where);+ if (own) return own;+ onModel = true;+ return ctx.clipOn?.(uuid, paths, where) ?? null;+ },+ note: (code) => {+ report.note(code, `${where}: ${entry.rel}`);+ if (code !== 'graph-transition-to-exit') complete = false;+ },+ });+ // a graph that plays a model's clips is written for the skeleton it is put on+ const key = createHash('sha1').update(JSON.stringify([...paths].sort())).digest('hex').slice(0, 8);+ const rel = outRef(esRel(entry.rel, onModel ? `__${key}.esanimator` : '.esanimator'));+ write(rel, converted.document);+ if (!opts.dryRun) mintSidecar(path.join(out, rel));+ ref = rel;+ } catch (err) {+ report.note('animation-graph-unreadable', `${where}: ${entry.rel}: ${(err as Error).message}`);+ }+ return ref ? { ref, complete } : null;+ },clipOn(clipUuid, paths, where) {const clip = models.use(clipUuid);if (!clip) return null;diff --git a/pipeline/src/import/cocos/models.ts b/pipeline/src/import/cocos/models.tsindex 4877d8d4f..45ba0557b 100644--- a/pipeline/src/import/cocos/models.ts+++ b/pipeline/src/import/cocos/models.ts@@ -39,6 +39,7 @@ export const isModelEntry = (entry: CocosAssetEntry | undefined): entry is Cocosexport class CocosModels {private readonly uses = new Map<string, ModelUse | null>();private readonly scanned = new Map<string, string[]>();+ private readonly scanning = new Set<string>();readonly failures: Array<{ file: string; error: string }> = [];readonly warnings: Array<{ file: string; warning: string }> = [];@@ -67,6 +68,11 @@ export class CocosModels {for (const u of uuids) {const entry = this.index.byUuid.get(u);if (isModelEntry(entry) && !found.includes(entry)) found.push(entry);+ // an animation graph names the clips it plays, which live in model files the document itself never mentions+ else if (entry && entry.rel.endsWith('.animgraph') && !this.scanning.has(entry.file)) {+ this.scanning.add(entry.file);+ for (const nested of this.modelsIn(entry.file)) if (!found.includes(nested)) found.push(nested);+ }}return found;}diff --git a/pipeline/tests/cocos-animation-graph.test.ts b/pipeline/tests/cocos-animation-graph.test.tsnew file mode 100644index 000000000..1c8facc8c--- /dev/null+++ b/pipeline/tests/cocos-animation-graph.test.ts@@ -0,0 +1,121 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file A Cocos animation graph as the engine's animator controller: states, transitions, conditions and blends map one to one, and what the+ * Animator cannot state is counted.+ */+import { describe, expect, it } from 'vitest';+import path from 'node:path';+import { convertAnimationGraph } from '../src/import/cocos/animationGraph';++/** A graph: attack/move/idle on one layer, driven by a trigger, a number and a flag. Ids are positions in the list. */+function graph(over: { motionSpeedFollows?: boolean; inclusive?: boolean } = {}): unknown[] {+ const o: unknown[] = [];+ const add = (x: unknown): { __id__: number } => { o.push(x); return { __id__: o.length - 1 }; };+ const root: Record<string, unknown> = { __type__: 'cc.animation.AnimationGraph', _layers: [], _variables: {} };+ add(root);+ const layer: Record<string, unknown> = { __type__: 'cc.animation.Layer', name: '', weight: 1, mask: null };+ root._layers = [add(layer)];+ const machine: Record<string, unknown> = { __type__: 'cc.animation.StateMachine', _states: [], _transitions: [] };+ layer._stateMachine = add(machine);+ const entry = add({ __type__: 'cc.animation.State', name: 'Entry' });+ const exit = add({ __type__: 'cc.animation.State', name: 'Exit' });+ const any = add({ __type__: 'cc.animation.State', name: 'Any State' });+ const clip = (uuid: string) => add({ __type__: 'cc.animation.ClipMotion', clip: { __uuid__: uuid } });+ const idle = add({ __type__: 'cc.animation.Motion', name: 'idle', motion: clip('idle-clip'), speed: 1 });+ const blend = add({+ __type__: 'cc.animation.AnimationBlend1D', name: 'move', param: add({ __type__: 'cc.animation.BindableNumber', variable: 'MoveSpeed', value: 0 }),+ _items: [+ add({ __type__: 'cc.animation.AnimationBlend1DItem', motion: clip('walk-clip'), threshold: 0 }),+ add({ __type__: 'cc.animation.AnimationBlend1DItem', motion: clip('run-clip'), threshold: 1 }),+ ],+ });+ const move = add({ __type__: 'cc.animation.Motion', name: 'move', motion: blend, speed: 2, speedMultiplierEnabled: over.motionSpeedFollows === true, speedMultiplier: 'MoveSpeed' });+ const attack = add({ __type__: 'cc.animation.Motion', name: 'attack', motion: clip('attack-clip'), speed: 1 });+ machine._states = [entry, exit, any, idle, move, attack];+ machine._entryState = entry; machine._exitState = exit; machine._anyState = any;+ root._variables = {+ MoveSpeed: add({ __type__: 'cc.animation.PlainVariable', _type: 0, _value: 0 }),+ Grounded: add({ __type__: 'cc.animation.PlainVariable', _type: 2, _value: true }),+ hit: add({ __type__: 'cc.animation.TriggerVariable', _flags: 0 }),+ };+ const trig = (name: string) => add({ __type__: 'cc.animation.TriggerCondition', trigger: name });+ const flag = (name: string, operator: number) => add({ __type__: 'cc.animation.UnaryCondition', operator, operand: add({ __type__: 'cc.animation.BindableBoolean', variable: name, value: false }) });+ const faster = add({+ __type__: 'cc.animation.BinaryCondition', operator: over.inclusive ? 5 : 4,+ lhs: add({ __type__: 'cc.animation.BindableNumber', variable: 'MoveSpeed', value: 0 }), rhs: add({ __type__: 'cc.animation.BindableNumber', variable: '', value: 0.5 }),+ });+ machine._transitions = [+ add({ __type__: 'cc.animation.Transition', from: entry, to: idle, conditions: [] }),+ add({ __type__: 'cc.animation.AnimationTransition', from: idle, to: move, conditions: [faster, flag('Grounded', 0)], duration: 0.2, exitConditionEnabled: false }),+ add({ __type__: 'cc.animation.AnimationTransition', from: any, to: attack, conditions: [trig('hit')], duration: 0 }),+ add({ __type__: 'cc.animation.AnimationTransition', from: attack, to: idle, conditions: [], duration: 0.1, exitConditionEnabled: true }),+ add({ __type__: 'cc.animation.AnimationTransition', from: move, to: exit, conditions: [] }),+ ];+ return o;+}++const convert = (objects: unknown[]) => {+ const notes: string[] = [];+ const result = convertAnimationGraph(objects, { clip: (uuid) => (uuid === 'run-clip' ? null : `clips/${uuid}.estimeline`), note: (c) => notes.push(c) });+ return { ...result, notes, doc: result.document as any };+};++describe('a Cocos animation graph', () => {+ it('keeps its parameters: numbers, flags and triggers', () => {+ const { doc } = convert(graph());+ expect(doc.parameters).toEqual([+ { name: 'MoveSpeed', type: 'float', default: 0 }, { name: 'Grounded', type: 'bool', default: true }, { name: 'hit', type: 'trigger' },+ ]);+ });++ it('starts where the entry state leads and names the states it plays', () => {+ const { doc } = convert(graph());+ expect(doc.initialState).toBe('idle');+ expect(doc.states.map((s: any) => s.name)).toEqual(['idle', 'move', 'attack']);+ expect(doc.states[0].motion).toEqual({ kind: 'timeline', clip: 'clips/idle-clip.estimeline' });+ expect(doc.states[1].speed).toBe(2);+ });++ it('turns a 1D blend into a blend over its clips, and drops a clip the node has no bones for', () => {+ const { doc, notes } = convert(graph());+ const blend = doc.states[1].motion;+ expect(blend.kind).toBe('blend1d');+ expect(blend.parameter).toBe('MoveSpeed');+ expect(blend.thresholds).toEqual([{ value: 0, motion: { kind: 'timeline', clip: 'clips/walk-clip.estimeline' } }]);+ expect(notes).toContain('graph-clip-not-found');+ });++ it('carries transitions with their conditions, blend time and wait for the clip to end', () => {+ const { doc } = convert(graph());+ expect(doc.states[0].transitions).toEqual([{+ to: 'move', duration: 0.2,+ conditions: [{ param: 'MoveSpeed', op: 'gt', value: 0.5 }, { param: 'Grounded', op: 'true' }],+ }]);+ expect(doc.states[2].transitions).toEqual([{ to: 'idle', duration: 0.1, hasExitTime: true, conditions: [] }]);+ });++ it('puts what leaves the any-state in the any-state transitions, and says what leaves for the exit state', () => {+ const { doc, notes } = convert(graph());+ expect(doc.anyStateTransitions).toEqual([{ to: 'attack', conditions: [{ param: 'hit', op: 'trigger' }] }]);+ expect(notes).toContain('graph-transition-to-exit');+ });++ it('makes a state\'s speed follow the variable Cocos names, and counts one it cannot find', () => {+ const { doc, notes } = convert(graph({ motionSpeedFollows: true }));+ expect(doc.states[1].speedParameter).toBe('MoveSpeed');+ expect(notes).not.toContain('graph-speed-variable-missing');+ expect(convert(graph()).doc.states[1].speedParameter).toBeUndefined();+ });++ it('counts a comparison the Animator has only in strict form', () => {+ expect(convert(graph({ inclusive: true })).notes).toContain('graph-condition-inclusive');+ });++ it('is a controller the engine accepts', async () => {+ const { migrateAnimatorController } = await import(/* @vite-ignore */ path.resolve(__dirname, '../../sdk/src/animation/animatorMigrate.ts'));+ const migrated = migrateAnimatorController(convert(graph()).document);+ expect(migrated.def.states.map((s: any) => s.name)).toEqual(['idle', 'move', 'attack']);+ expect(migrated.def.initialState).toBe('idle');+ });+});diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex af092d4de..6292e0710 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -692,6 +692,7 @@ motion: AnimatorMotion | undefinedname: stringrootMotion: boolean | undefinedspeed: number | undefined+speedParameter: string | undefinedspine: AnimatorSpineMotion | undefinedstateMachine: AnimatorSubMachine | undefinedtransitions: AnimatorTransition[]@@ -16235,7 +16236,7 @@ ServicesPlugin## setAnimatorStateProps — function @experimental```-(def: AnimatorControllerDef, name: string, patch: { speed?: number; loop?: boolean; rootMotion?: boolean; }, layer?: number): AnimatorControllerDef+(def: AnimatorControllerDef, name: string, patch: { speed?: number; loop?: boolean; rootMotion?: boolean; speedParameter?: string; }, layer?: number): AnimatorControllerDef```## setBlobShadowGround — function @experimentaldiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex e91e9fb1e..840de784d 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -692,6 +692,7 @@ motion: AnimatorMotion | undefinedname: stringrootMotion: boolean | undefinedspeed: number | undefined+speedParameter: string | undefinedspine: AnimatorSpineMotion | undefinedstateMachine: AnimatorSubMachine | undefinedtransitions: AnimatorTransition[]@@ -16498,7 +16499,7 @@ ServicesPlugin## setAnimatorStateProps — function @experimental```-(def: AnimatorControllerDef, name: string, patch: { speed?: number; loop?: boolean; rootMotion?: boolean; }, layer?: number): AnimatorControllerDef+(def: AnimatorControllerDef, name: string, patch: { speed?: number; loop?: boolean; rootMotion?: boolean; speedParameter?: string; }, layer?: number): AnimatorControllerDef```## setBlobShadowGround — function @experimentaldiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex ea22c5204..373af80c8 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -687,6 +687,7 @@ motion: AnimatorMotion | undefinedname: stringrootMotion: boolean | undefinedspeed: number | undefined+speedParameter: string | undefinedspine: AnimatorSpineMotion | undefinedstateMachine: AnimatorSubMachine | undefinedtransitions: AnimatorTransition[]@@ -16240,7 +16241,7 @@ ServicesPlugin## setAnimatorStateProps — function @experimental```-(def: AnimatorControllerDef, name: string, patch: { speed?: number; loop?: boolean; rootMotion?: boolean; }, layer?: number): AnimatorControllerDef+(def: AnimatorControllerDef, name: string, patch: { speed?: number; loop?: boolean; rootMotion?: boolean; speedParameter?: string; }, layer?: number): AnimatorControllerDef```## setBlobShadowGround — function @experimentaldiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex e8dc8d612..64673f518 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -687,6 +687,7 @@ motion: AnimatorMotion | undefinedname: stringrootMotion: boolean | undefinedspeed: number | undefined+speedParameter: string | undefinedspine: AnimatorSpineMotion | undefinedstateMachine: AnimatorSubMachine | undefinedtransitions: AnimatorTransition[]@@ -16546,7 +16547,7 @@ ServicesPlugin## setAnimatorStateProps — function @experimental```-(def: AnimatorControllerDef, name: string, patch: { speed?: number; loop?: boolean; rootMotion?: boolean; }, layer?: number): AnimatorControllerDef+(def: AnimatorControllerDef, name: string, patch: { speed?: number; loop?: boolean; rootMotion?: boolean; speedParameter?: string; }, layer?: number): AnimatorControllerDef```## setBlobShadowGround — function @experimentaldiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 2515d25c6..d2efb26c0 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -687,6 +687,7 @@ motion: AnimatorMotion | undefinedname: stringrootMotion: boolean | undefinedspeed: number | undefined+speedParameter: string | undefinedspine: AnimatorSpineMotion | undefinedstateMachine: AnimatorSubMachine | undefinedtransitions: AnimatorTransition[]@@ -16272,7 +16273,7 @@ ServicesPlugin## setAnimatorStateProps — function @experimental```-(def: AnimatorControllerDef, name: string, patch: { speed?: number; loop?: boolean; rootMotion?: boolean; }, layer?: number): AnimatorControllerDef+(def: AnimatorControllerDef, name: string, patch: { speed?: number; loop?: boolean; rootMotion?: boolean; speedParameter?: string; }, layer?: number): AnimatorControllerDef```## setBlobShadowGround — function @experimentaldiff --git a/sdk/src/animation/Animator.ts b/sdk/src/animation/Animator.tsindex b6e4ad732..5f29a91a3 100644--- a/sdk/src/animation/Animator.ts+++ b/sdk/src/animation/Animator.ts@@ -153,6 +153,12 @@ export interface AnimatorState {*/rootMotion?: boolean;speed?: number;+ /**+ * A float parameter that multiplies how fast this state plays: its clock advances by `dt * parameter`, so a run clip follows a character's+ * speed and a parameter of 0 holds the pose. Whatever the motion's kind, because it is the state's clock that is scaled. A missing or+ * negative parameter plays at the normal rate or stops, never backwards.+ */+ speedParameter?: string;loop?: boolean;transitions: AnimatorTransition[];/** Editor-only canvas position; the interpreter ignores it. */@@ -455,6 +461,13 @@ export const SPINE_MOTION = 'spine';*/const migratedMotions = new WeakMap<AnimatorState, AnimatorMotion | null>();+/** How much faster than the clock a state's own clock runs: its speed parameter's value, or 1 for a state that names none. */+export function stateTimeScale(state: AnimatorState, params: Readonly<Record<string, number | boolean>>): number {+ if (!state.speedParameter) return 1;+ const value = params[state.speedParameter];+ return typeof value === 'number' && value > 0 ? value : typeof value === 'number' ? 0 : 1;+}+/** A legacy 1D blend over sprite clips, as the equivalent blend over motions.* A stop's own speed/loop wins over the state's, which is what it did before. */function spriteBlendMotion(st: AnimatorState, blend: AnimatorBlend1D): AnimatorBlend1DMotion {@@ -830,7 +843,7 @@ export class AnimatorControllerAPI {// Advance BEFORE asking whether the motion ran out: judging the clip// on the previous frame's clock holds every exit-time transition one// frame past the clip it was waiting for.- this.advance(lrt, dt);+ this.advance(lrt, dt * stateTimeScale(leaf, params));const leafMotion = motionOf(leaf);const clipFinished = leafMotion !== null && this.motionEnded(ctx, leafMotion, lrt.time);diff --git a/sdk/src/animation/animatorGraph.ts b/sdk/src/animation/animatorGraph.tsindex 34f61b772..ffd5d78fc 100644--- a/sdk/src/animation/animatorGraph.ts+++ b/sdk/src/animation/animatorGraph.ts@@ -163,7 +163,7 @@ export function setStateMotion(export function setStateProps(def: AnimatorControllerDef, name: string,- patch: { speed?: number; loop?: boolean; rootMotion?: boolean }, layer = 0,+ patch: { speed?: number; loop?: boolean; rootMotion?: boolean; speedParameter?: string }, layer = 0,): AnimatorControllerDef {return withLayer(def, layer, {states: scopeAt(def, layer).states.map((s) => (s.name === name ? { ...s, ...patch } : s)),diff --git a/sdk/tests/animatorLayers.test.ts b/sdk/tests/animatorLayers.test.tsindex 6829efb31..81a57013d 100644--- a/sdk/tests/animatorLayers.test.ts+++ b/sdk/tests/animatorLayers.test.ts@@ -601,3 +601,54 @@ describe('a layer playing something that cannot be sampled', () => {expect(clipOf(world)).toBe('base_clip');});});++describe('a state whose speed follows a parameter', () => {+ const ramped = (state: Record<string, unknown> = {}, params: AnimatorControllerDef['parameters'] = [{ name: 'Speed', type: 'float', default: 1 }]) => {+ const world = seedWorld();+ const timeline = new TimelineAPI();+ timeline.registerAsset('ramp.estimeline', ramp('lift', 0, 100));+ const ctrl = new AnimatorControllerAPI();+ ctrl.registerMotionDriver(TIMELINE_MOTION, createTimelineMotionDriver(timeline));+ ctrl.registerController('rig', {+ parameters: params,+ states: [{ name: 'Run', motion: { kind: TIMELINE_MOTION, clip: 'ramp.estimeline', loop: true }, transitions: [], ...state }],+ initialState: 'Run',+ });+ attach(world);+ return { world, ctrl };+ };++ it('plays at the clock\'s rate while the parameter is 1, and at twice it while the parameter is 2', () => {+ const slow = ramped({ speedParameter: 'Speed' });+ slow.ctrl.update(slow.world, 0);+ slow.ctrl.update(slow.world, 1);+ const normal = read(slow.world).lift;++ const fast = ramped({ speedParameter: 'Speed' });+ fast.ctrl.setFloat(E, 'Speed', 2);+ fast.ctrl.update(fast.world, 0);+ fast.ctrl.update(fast.world, 1);+ expect(read(fast.world).lift).toBeCloseTo(normal * 2, 3);+ });++ it('holds the pose while the parameter is 0', () => {+ const held = ramped({ speedParameter: 'Speed' });+ held.ctrl.setFloat(E, 'Speed', 0);+ held.ctrl.update(held.world, 0);+ held.ctrl.update(held.world, 1);+ expect(read(held.world).lift).toBeCloseTo(0, 5);+ });++ it('ignores a state that names no parameter, and a parameter nobody declared', () => {+ const plain = ramped({});+ plain.ctrl.setFloat(E, 'Speed', 5);+ plain.ctrl.update(plain.world, 0);+ plain.ctrl.update(plain.world, 1);+ const base = read(plain.world).lift;++ const unknown = ramped({ speedParameter: 'Nope' });+ unknown.ctrl.update(unknown.world, 0);+ unknown.ctrl.update(unknown.world, 1);+ expect(read(unknown.world).lift).toBeCloseTo(base, 3);+ });+});diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex 046bd35a6..856e01f08 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -28,6 +28,8 @@ export const NOTES_FLOOR = 'v0.65.0';* the reader recognises anyway.*/export const NOTED = {+ 'feat(animation): an animator state can play at the speed of a float parameter (speedParameter), and the Cocos animation graph is converted to an animator controller':+ {"note":"An animator state can play at the speed of a parameter."},'feat(cocos): the importer converts Animation clips (.anim) to timelines: position, scale, rotation, sprite and label colour, opacity and active tracks, and plays model-file clips on the node':{"internal":"The Cocos Creator compatibility layer and importer have not shipped; nothing a creator reaches without opting in."},'feat(cocos): a MeshRenderer wears the Cocos material it was given (image, tint, blending, culling, lighting), and a mesh is found by its place in the model when its name is not readable':