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(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.md
index 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.mdx
index 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 states
the 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 motion
A 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.mdx
index 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.ts
new file mode 100644
index 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.ts
index 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, wh
const 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: strin
if (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.ts
index 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.ts
index 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<Impo
clips.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.ts
index 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 Cocos
export 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.ts
new file mode 100644
index 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.md
index af092d4de..6292e0710 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -692,6 +692,7 @@ motion: AnimatorMotion | undefined
name: string
rootMotion: boolean | undefined
speed: number | undefined
+speedParameter: string | undefined
spine: AnimatorSpineMotion | undefined
stateMachine: AnimatorSubMachine | undefined
transitions: 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 @experimental
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index e91e9fb1e..840de784d 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -692,6 +692,7 @@ motion: AnimatorMotion | undefined
name: string
rootMotion: boolean | undefined
speed: number | undefined
+speedParameter: string | undefined
spine: AnimatorSpineMotion | undefined
stateMachine: AnimatorSubMachine | undefined
transitions: 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 @experimental
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index ea22c5204..373af80c8 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -687,6 +687,7 @@ motion: AnimatorMotion | undefined
name: string
rootMotion: boolean | undefined
speed: number | undefined
+speedParameter: string | undefined
spine: AnimatorSpineMotion | undefined
stateMachine: AnimatorSubMachine | undefined
transitions: 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 @experimental
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index e8dc8d612..64673f518 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -687,6 +687,7 @@ motion: AnimatorMotion | undefined
name: string
rootMotion: boolean | undefined
speed: number | undefined
+speedParameter: string | undefined
spine: AnimatorSpineMotion | undefined
stateMachine: AnimatorSubMachine | undefined
transitions: 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 @experimental
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 2515d25c6..d2efb26c0 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -687,6 +687,7 @@ motion: AnimatorMotion | undefined
name: string
rootMotion: boolean | undefined
speed: number | undefined
+speedParameter: string | undefined
spine: AnimatorSpineMotion | undefined
stateMachine: AnimatorSubMachine | undefined
transitions: 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 @experimental
diff --git a/sdk/src/animation/Animator.ts b/sdk/src/animation/Animator.ts
index 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.ts
index 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.ts
index 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.mjs
index 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':