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.

refactor(sdk): the animator graph and grip poses ship in esengine/skeletal-animation, installed only where the content uses them

yhh54c432d03465
diff --git a/pipeline/src/bundle/engineInstalls.ts b/pipeline/src/bundle/engineInstalls.ts
index e10bb2a44..60145e448 100644
--- a/pipeline/src/bundle/engineInstalls.ts
+++ b/pipeline/src/bundle/engineInstalls.ts
@@ -24,6 +24,8 @@ import { ESENGINE_SUBPATHS } from './engineSubpaths';
* scene says "script graph", the `.esgraph` it references does. */
const ASSET_SUBPATH: Readonly<Record<string, string>> = {
'.esgraph': 'esengine/logic',
+ '.esanimator': 'esengine/skeletal-animation',
+ '.esavatar': 'esengine/skeletal-animation',
'.estimeline': 'esengine/timeline',
'.esfsm': 'esengine/ai',
'.esbt': 'esengine/ai',
diff --git a/pipeline/src/bundle/engineSubpaths.ts b/pipeline/src/bundle/engineSubpaths.ts
index 8e91f3950..db091cb4f 100644
--- a/pipeline/src/bundle/engineSubpaths.ts
+++ b/pipeline/src/bundle/engineSubpaths.ts
@@ -24,6 +24,7 @@ export const ESENGINE_SUBPATHS: Readonly<Record<string, string>> = {
'esengine/voxel': 'voxel/index.js',
'esengine/rig2d': 'rig2d/index.js',
'esengine/imported-scene': 'imported-scene/index.js',
+ 'esengine/skeletal-animation': 'skeletal-animation/index.js',
'esengine/character-shaders': 'character-shaders/index.js',
'esengine/logic': 'logic/index.js',
'esengine/debug-channel': 'debug-channel/index.js',
diff --git a/pipeline/src/export/exportGame.ts b/pipeline/src/export/exportGame.ts
index 4b2deb25d..9229d6255 100644
--- a/pipeline/src/export/exportGame.ts
+++ b/pipeline/src/export/exportGame.ts
@@ -87,6 +87,7 @@ import { sizeSettingsOf } from './sizeHistory';
import { loadProjectModules, sideModuleDeclarations, stageProjectModules } from './projectModules';
import { subsystemGapWarnings, targetGaps } from '../project/targetSupport';
import { contentSubsystems } from './contentSubsystems';
+import { scriptsMentionSkeletal } from './liteEngine';
import { planSideModules, spineRefusalMessage, type SpineRuntimeDecision, sideModuleFiles, shipsSideModule, textureDecoderBytes } from '../bundle/sideModuleScan';
import { nativeSpineMismatch } from './nativeTemplates';
import { MODULES, NATIVE_MODULE_REGISTRY } from '../../../tools/nativeScriptModules.js';
@@ -1094,8 +1095,11 @@ async function produceExport(opts: ExportGameOptions): Promise<ExportGameResult>
// so the shipped game shares one SDK with the project bundle and runs
// custom systems (same shape as the play realm).
if (!nativeContent) {
+ const usedSubsystems = await contentSubsystems(opts.root, cook.includedPaths);
+ // A script can add an Animator to a world no scene mentioned, and the name is exported from `esengine` itself.
+ const needsSkeletal = !usedSubsystems.has('skeletalAnimation') && await scriptsMentionSkeletal(opts.root, opts.scriptsEntry);
plan = engineInstalls({
- subsystems: (await contentSubsystems(opts.root, cook.includedPaths)).keys(),
+ subsystems: needsSkeletal ? [...usedSubsystems.keys(), 'skeletalAnimation'] : usedSubsystems.keys(),
assetPaths: cook.includedPaths,
sideModuleIds,
scriptImports,
diff --git a/pipeline/src/export/exportMiniGame.ts b/pipeline/src/export/exportMiniGame.ts
index 6004e26ef..d0b0a7845 100644
--- a/pipeline/src/export/exportMiniGame.ts
+++ b/pipeline/src/export/exportMiniGame.ts
@@ -32,7 +32,7 @@ import type { DebugChannelConfig } from 'esengine';
import { packagedDebugChannel } from './debugChannel';
import { packagedHotUpdate } from './hotUpdateConfig';
import { loadEsbuild } from '../bundle/esbuildRuntime';
-import { liteEngineAnswer, scriptsMentionOmitted } from './liteEngine';
+import { liteEngineAnswer, scriptsMentionOmitted, scriptsMentionSkeletal } from './liteEngine';
import type { ModuleChoice, ProjectFeatures, ProjectPackaging } from '../project/format';
import {
DEFAULT_RUNTIME_CONFIG, packagedRuntimeFields, withAudioLoadTypes, type RuntimeProjectConfig,
@@ -551,8 +551,10 @@ export async function exportMiniGame(profile: MiniGameExportProfile, opts: {
// gets, from the same evidence, so a subsystem cannot be installed on one
// target and silently missing on the other.
const usedSubsystems = await contentSubsystems(opts.root, cook.includedPaths);
+ // A script can add an Animator to a world no scene mentioned, and the name is exported from `esengine` itself.
+ const needsSkeletal = !usedSubsystems.has('skeletalAnimation') && await scriptsMentionSkeletal(opts.root, opts.scriptsEntry);
const plan = engineInstalls({
- subsystems: usedSubsystems.keys(),
+ subsystems: needsSkeletal ? [...usedSubsystems.keys(), 'skeletalAnimation'] : usedSubsystems.keys(),
assetPaths: cook.includedPaths,
sideModuleIds: sideModules.map((m) => m.id),
choices: moduleChoices(opts.features, opts.modulesByPlatform?.[profile.id]),
diff --git a/pipeline/src/export/liteEngine.ts b/pipeline/src/export/liteEngine.ts
index 23c81d296..a20a7816c 100644
--- a/pipeline/src/export/liteEngine.ts
+++ b/pipeline/src/export/liteEngine.ts
@@ -24,8 +24,24 @@ const SCRIPT_EXT = /\.(?:[cm]?[jt]sx?)$/;
const SKIP_DIRS = new Set(['node_modules', '.git', '.esengine', 'dist', 'build', 'out']);
const MAX_FILES = 4000;
+/**
+ * What a script says when it uses the animator graph or a grip pose. Those names are exported from `esengine` itself, not
+ * only from the subpath that installs them, so a script that reaches one by name leaves no import to read. `SpriteAnimator`
+ * does not match: the boundary sits before `Animator`, not inside a longer name.
+ */
+const SKELETAL_MENTIONS = /\b(Animator\w*|Grip[A-Z]\w*|registerAnimatorController|getRegisteredAnimatorController|solveAnimatorIK|parseAvatar|emptyAvatar|avatarResolver|MotionRegistry|motionOf|blend[12]DMotionDriver)\b|esengine\/skeletal-animation/;
+
/** Whether any of the project's script sources mentions a subsystem the lite engine leaves out. */
-export async function scriptsMentionOmitted(root: string, scriptsEntry?: string): Promise<boolean> {
+export function scriptsMentionOmitted(root: string, scriptsEntry?: string): Promise<boolean> {
+ return scriptsMatch(root, scriptsEntry, SCRIPT_MENTIONS);
+}
+
+/** Whether any of the project's script sources names the animator graph or a grip pose. */
+export function scriptsMentionSkeletal(root: string, scriptsEntry?: string): Promise<boolean> {
+ return scriptsMatch(root, scriptsEntry, SKELETAL_MENTIONS);
+}
+
+async function scriptsMatch(root: string, scriptsEntry: string | undefined, pattern: RegExp): Promise<boolean> {
let seen = 0;
const walk = async (dir: string): Promise<boolean> => {
let entries;
@@ -37,7 +53,7 @@ export async function scriptsMentionOmitted(root: string, scriptsEntry?: string)
} else if (SCRIPT_EXT.test(e.name) && !e.name.endsWith('.d.ts')) {
if (++seen > MAX_FILES) return true; // too many to say: carry everything
try {
- if (SCRIPT_MENTIONS.test(await readFile(path.join(dir, e.name), 'utf8'))) return true;
+ if (pattern.test(await readFile(path.join(dir, e.name), 'utf8'))) return true;
} catch { return true; }
}
}
diff --git a/pipeline/src/project/targetSupport.ts b/pipeline/src/project/targetSupport.ts
index 19a3c87ae..13a32f739 100644
--- a/pipeline/src/project/targetSupport.ts
+++ b/pipeline/src/project/targetSupport.ts
@@ -27,7 +27,7 @@ import { NATIVE_PLATFORMS, type ExportPlatform } from './platforms';
/** An engine subsystem a build target may lack. */
export type Subsystem =
- | 'text' | 'tilemap' | 'terrain' | 'foliage' | 'worldgen' | 'water' | 'spline' | 'voxel' | 'rig2d' | 'importedScene' | 'characterShaders' | 'timeline' | 'fxBasic' | 'fxAtmosphere' | 'fxLighting' | 'particles' | 'postprocess' | 'physics' | 'physics3d'
+ | 'text' | 'tilemap' | 'terrain' | 'foliage' | 'worldgen' | 'water' | 'spline' | 'voxel' | 'rig2d' | 'importedScene' | 'skeletalAnimation' | 'characterShaders' | 'timeline' | 'fxBasic' | 'fxAtmosphere' | 'fxLighting' | 'particles' | 'postprocess' | 'physics' | 'physics3d'
| 'spine' | 'dragonbones' | 'video' | 'ai' | 'logic' | 'replication' | 'gameplay';
/**
@@ -52,6 +52,7 @@ export const SUBSYSTEM_COMPONENTS: Readonly<Record<Subsystem, readonly string[]>
voxel: ['VoxelTerrain'],
rig2d: ['Bone2D', 'IK2D', 'BoneConstraint2D'],
importedScene: ['NodeVisibility', 'ParticleModelUnits'],
+ skeletalAnimation: ['Animator', 'AnimatorRootMotion', 'GripPose', 'GripSurface', 'GripProfile', 'GripHolder'],
// Hair, Skin and Eye are shaders, not components: a character's materials are what name them (see SHADER_SUBSYSTEM).
characterShaders: [],
particles: ['ParticleEmitter', 'ParticleForceField', 'ParticleCollider'],
@@ -121,6 +122,7 @@ export const SUBSYSTEM_LABEL: Readonly<Record<Subsystem, string>> = {
voxel: 'Voxel terrain',
rig2d: '2D rig constraints',
importedScene: 'Imported scene (node visibility, particle units)',
+ skeletalAnimation: 'Skeletal animation (animator, grip poses)',
characterShaders: 'Character shaders (hair, skin, eye)',
particles: 'Particles',
postprocess: 'Post-processing',
@@ -158,6 +160,7 @@ export const SUBSYSTEM_INSTALL: Readonly<Record<Subsystem, string>> = {
voxel: 'esengine/voxel',
rig2d: 'esengine/rig2d',
importedScene: 'esengine/imported-scene',
+ skeletalAnimation: 'esengine/skeletal-animation',
characterShaders: 'esengine/character-shaders',
physics: 'esengine/physics',
physics3d: 'esengine/physics3d',
diff --git a/pipeline/tests/engine-installs.test.ts b/pipeline/tests/engine-installs.test.ts
index ebcf731b6..23f60e5e2 100644
--- a/pipeline/tests/engine-installs.test.ts
+++ b/pipeline/tests/engine-installs.test.ts
@@ -46,6 +46,13 @@ describe('the engine modules a package installs', () => {
expect(engineInstalls({ subsystems: ['importedScene'] }).subpaths).toEqual(['esengine/imported-scene']);
});
+ it('takes the animator graph and grip poses from an Animator or a controller asset, so a 2D game carries none', () => {
+ expect(engineInstalls({ subsystems: ['skeletalAnimation'] }).subpaths).toEqual(['esengine/skeletal-animation']);
+ expect(engineInstalls({ assetPaths: ['assets/hero.esanimator'] }).subpaths).toEqual(['esengine/skeletal-animation']);
+ expect(engineInstalls({ assetPaths: ['assets/hero.esavatar'] }).subpaths).toEqual(['esengine/skeletal-animation']);
+ expect(engineInstalls({ assetPaths: ['assets/hero.esanim'] }).subpaths).toEqual([]);
+ });
+
it('takes splines from a Spline, so a game without one carries none', () => {
expect(engineInstalls({ subsystems: ['spline'] }).subpaths).toEqual(['esengine/spline']);
});
diff --git a/sdk/package.json b/sdk/package.json
index 624b66811..7fd770f08 100644
--- a/sdk/package.json
+++ b/sdk/package.json
@@ -29,6 +29,7 @@
"./dist/voxel/index.js",
"./dist/rig2d/index.js",
"./dist/imported-scene/index.js",
+ "./dist/skeletal-animation/index.js",
"./dist/character-shaders/index.js",
"./dist/logic/index.js",
"./dist/debug-channel/index.js",
@@ -134,6 +135,10 @@
"import": "./dist/imported-scene/index.js",
"types": "./dist/imported-scene/index.d.ts"
},
+ "./skeletal-animation": {
+ "import": "./dist/skeletal-animation/index.js",
+ "types": "./dist/skeletal-animation/index.d.ts"
+ },
"./character-shaders": {
"import": "./dist/character-shaders/index.js",
"types": "./dist/character-shaders/index.d.ts"
diff --git a/sdk/rolldown.config.js b/sdk/rolldown.config.js
index 13e751f81..c26630200 100644
--- a/sdk/rolldown.config.js
+++ b/sdk/rolldown.config.js
@@ -115,6 +115,7 @@ export default defineConfig([
'voxel/index': 'src/voxel/index.ts',
'rig2d/index': 'src/rig2d/index.ts',
'imported-scene/index': 'src/imported-scene/index.ts',
+ 'skeletal-animation/index': 'src/skeletal-animation/index.ts',
'character-shaders/index': 'src/character/index.ts',
'logic/index': 'src/logic/index.ts',
'debug-channel/index': 'src/debug-channel/index.ts',
diff --git a/sdk/rollup.config.js b/sdk/rollup.config.js
index 4cb08036c..12815565f 100644
--- a/sdk/rollup.config.js
+++ b/sdk/rollup.config.js
@@ -37,6 +37,7 @@ export default [
'voxel/index': 'src/voxel/index.ts',
'rig2d/index': 'src/rig2d/index.ts',
'imported-scene/index': 'src/imported-scene/index.ts',
+ 'skeletal-animation/index': 'src/skeletal-animation/index.ts',
'character-shaders/index': 'src/character/index.ts',
'logic/index': 'src/logic/index.ts',
'debug-channel/index': 'src/debug-channel/index.ts',
diff --git a/sdk/src/animation/AnimationPlugin.ts b/sdk/src/animation/AnimationPlugin.ts
index 4d0d0b805..26f7bb648 100644
--- a/sdk/src/animation/AnimationPlugin.ts
+++ b/sdk/src/animation/AnimationPlugin.ts
@@ -3,13 +3,13 @@
/**
* @file AnimationPlugin.ts
* @brief Animation plugin registering Tween and SpriteAnimator systems
+ *
+ * The animator graph and grip poses are SkeletalAnimationPlugin's.
*/
import type { App, Plugin } from '../app/app';
import { defineSystem, Schedule } from '../ecs/system';
import { Res } from '../ecs/resource';
-import { EventWriter, type EventWriterInstance } from '../ecs/event';
-import { AnimatorEvent, type AnimatorEventPayload } from './animatorEvent';
import { Time, type TimeData } from '../ecs/resource';
import type { Entity } from '../types';
import type { CppRegistry } from '../wasm';
@@ -18,8 +18,6 @@ import { log } from '../util/logger';
import type { AnimCore } from './Tween';
import { Tween, TweenAPI } from './Tween';
import { SpriteAnimation, SpriteAnimationAPI, type SpriteAnimClip } from './SpriteAnimator';
-import { AnimatorController, AnimatorControllerAPI, type AnimatorControllerDef } from './Animator';
-import type { AnimatorAvatar } from './animatorAvatar';
import { appRegistryAsset } from '../asset/registryLookup';
import { playModeOnly } from '../ecs/env';
import { installCoverFade } from '../render/coverFade';
@@ -29,8 +27,6 @@ import { installFogOfWar } from '../render/fogOfWar';
import { installSwayPush } from '../render/swayPush';
import { installFootsteps } from '../render/footsteps';
import { SystemLabel } from '../ecs/systemLabels';
-import { installGripPose } from './gripPose';
-import { installGripHold } from './gripHold';
export class AnimationPlugin implements Plugin {
name = 'animation';
@@ -51,14 +47,11 @@ export class AnimationPlugin implements Plugin {
app.insertResource(Tween, tween);
const anim = new SpriteAnimationAPI();
app.insertResource(SpriteAnimation, anim);
- const animator = new AnimatorControllerAPI();
- app.insertResource(AnimatorController, animator);
const world = app.world;
const offDespawn = world.onDespawn((entity: Entity) => {
tween.cancelAll(entity);
anim.removeEntityListeners(entity);
- animator.removeEntity(entity);
});
// A roof or a crown with a CoverFade thins out over what stands under it; with none in the scene the system finds nothing and returns.
const offCoverFade = installCoverFade(app);
@@ -80,27 +73,10 @@ export class AnimationPlugin implements Plugin {
{ name: 'TweenSystem' }
), { runIf: playModeOnly });
- // A `.esanim` / `.esanimator` comes from THIS app's realm, whose slots
- // answer to the authored ref as well as the resolved path. A code
- // registration still wins over one.
+ // A `.esanim` comes from THIS app's realm, whose slots answer to the
+ // authored ref as well as the resolved path. A code registration still
+ // wins over one.
anim.useAssetClips((ref) => appRegistryAsset<SpriteAnimClip>(app, 'anim-clip', ref));
- animator.useAssetAvatars((ref) => appRegistryAsset<AnimatorAvatar>(app, 'avatar', ref));
- animator.useAssetControllers(
- (ref) => appRegistryAsset<AnimatorControllerDef>(app, 'animatorcontroller', ref),
- );
-
- // The state machine runs before the sprite animator so a transition's
- // clip switch applies the same frame it fires.
- app.addSystemToSchedule(Schedule.Update, defineSystem(
- [Res(Time), Res(AnimatorController), EventWriter(AnimatorEvent)],
- (
- time: TimeData, ctrl: AnimatorControllerAPI,
- events: EventWriterInstance<AnimatorEventPayload>,
- ) => {
- ctrl.update(world, time.delta, events);
- },
- { name: 'AnimatorSystem' }
- ), { runAfter: [SystemLabel.Tween], runIf: playModeOnly });
app.addSystemToSchedule(Schedule.Update, defineSystem(
[Res(Time), Res(SpriteAnimation)],
@@ -109,10 +85,6 @@ export class AnimationPlugin implements Plugin {
},
{ name: 'SpriteAnimatorSystem' }
), { runAfter: [SystemLabel.Tween, SystemLabel.Animator], runIf: playModeOnly });
-
- // The hold first: it hands the fingers it does not pose itself to the grip pose after it.
- installGripHold(app);
- installGripPose(app);
}
cleanup(app?: App): void {
diff --git a/sdk/src/animation/SkeletalAnimationPlugin.ts b/sdk/src/animation/SkeletalAnimationPlugin.ts
new file mode 100644
index 000000000..981f054a1
--- /dev/null
+++ b/sdk/src/animation/SkeletalAnimationPlugin.ts
@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file SkeletalAnimationPlugin.ts
+ * @brief The animator graph (states, blends, IK, avatars, root motion) and grip poses.
+ *
+ * Split from AnimationPlugin because a game with no skeleton to drive — a 2D one,
+ * a UI one — carried ~65KB of it all the same: tweens and sprite clips are the
+ * part every package uses, this is the part a rigged character does. It installs
+ * where the content uses it (see `skeletalAnimationSupport.ts`); the full entry
+ * installs it beside everything else.
+ *
+ * Builds right after `animation` (PLUGIN_BUILD_ORDER) because spine, 3D physics,
+ * the timeline and gameplay all look for the AnimatorController resource this
+ * inserts and degrade without it.
+ */
+
+import type { App, Plugin } from '../app/app';
+import { defineSystem, Schedule } from '../ecs/system';
+import { Res, Time, type TimeData } from '../ecs/resource';
+import { EventWriter, type EventWriterInstance } from '../ecs/event';
+import { AnimatorEvent, type AnimatorEventPayload } from './animatorEvent';
+import type { Entity } from '../types';
+import { AnimatorController, AnimatorControllerAPI, type AnimatorControllerDef } from './Animator';
+import type { AnimatorAvatar } from './animatorAvatar';
+import { appRegistryAsset } from '../asset/registryLookup';
+import { playModeOnly } from '../ecs/env';
+import { SystemLabel } from '../ecs/systemLabels';
+import { installGripPose } from './gripPose';
+import { installGripHold } from './gripHold';
+
+export class SkeletalAnimationPlugin implements Plugin {
+ name = 'skeletalAnimation';
+ private readonly despawnCleanups_ = new WeakMap<App, () => void>();
+ private latestDespawnCleanup_: (() => void) | null = null;
+
+ build(app: App): void {
+ this.cleanup(app);
+ const animator = new AnimatorControllerAPI();
+ app.insertResource(AnimatorController, animator);
+ const world = app.world;
+
+ const offDespawn = world.onDespawn((entity: Entity) => {
+ animator.removeEntity(entity);
+ });
+ this.despawnCleanups_.set(app, offDespawn);
+ this.latestDespawnCleanup_ = offDespawn;
+
+ // A `.esanimator` / `.esavatar` comes from THIS app's realm, whose slots
+ // answer to the authored ref as well as the resolved path. A code
+ // registration still wins over one.
+ animator.useAssetAvatars((ref) => appRegistryAsset<AnimatorAvatar>(app, 'avatar', ref));
+ animator.useAssetControllers(
+ (ref) => appRegistryAsset<AnimatorControllerDef>(app, 'animatorcontroller', ref),
+ );
+
+ // The state machine runs before the sprite animator so a transition's
+ // clip switch applies the same frame it fires.
+ app.addSystemToSchedule(Schedule.Update, defineSystem(
+ [Res(Time), Res(AnimatorController), EventWriter(AnimatorEvent)],
+ (
+ time: TimeData, ctrl: AnimatorControllerAPI,
+ events: EventWriterInstance<AnimatorEventPayload>,
+ ) => {
+ ctrl.update(world, time.delta, events);
+ },
+ { name: 'AnimatorSystem' }
+ ), { runAfter: [SystemLabel.Tween], runIf: playModeOnly });
+
+ // The hold first: it hands the fingers it does not pose itself to the grip pose after it.
+ installGripHold(app);
+ installGripPose(app);
+ }
+
+ cleanup(app?: App): void {
+ const release = app ? this.despawnCleanups_.get(app) : this.latestDespawnCleanup_;
+ if (!release) return;
+ if (app) this.despawnCleanups_.delete(app);
+ if (release === this.latestDespawnCleanup_) this.latestDespawnCleanup_ = null;
+ release();
+ }
+}
+
+export const skeletalAnimationPlugin = new SkeletalAnimationPlugin();
diff --git a/sdk/src/animation/skeletalAnimationSupport.ts b/sdk/src/animation/skeletalAnimationSupport.ts
new file mode 100644
index 000000000..f7fa6bbbd
--- /dev/null
+++ b/sdk/src/animation/skeletalAnimationSupport.ts
@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file skeletalAnimationSupport.ts — what a build that ships a skeleton tells the core.
+ *
+ * A call, not a file's side effect — see tilemap/tilemapSupport.ts. Both halves
+ * come from here: the plugin an app installs, and the loaders that read a
+ * `.esanimator` and a `.esavatar`. A loader names the animator's parsers, so one
+ * the asset registry constructs is one every package carries.
+ */
+import { addEntryPlugin } from '../runtime/entryPlugins';
+import { addAssetLoader } from '../asset/optionalLoaders';
+import { SkeletalAnimationPlugin } from './SkeletalAnimationPlugin';
+import { AnimatorControllerAssetLoader } from '../asset/loaders/AnimatorControllerAssetLoader';
+import { AvatarAssetLoader } from '../asset/loaders/AvatarAssetLoader';
+
+export function registerSkeletalAnimationSupport(): void {
+ addEntryPlugin('skeletalAnimation', () => new SkeletalAnimationPlugin());
+ addAssetLoader('animatorcontroller', () => new AnimatorControllerAssetLoader() as never);
+ addAssetLoader('avatar', () => new AvatarAssetLoader() as never);
+}
diff --git a/sdk/src/app/pluginSets.ts b/sdk/src/app/pluginSets.ts
index 165bafcdc..94ab018fc 100644
--- a/sdk/src/app/pluginSets.ts
+++ b/sdk/src/app/pluginSets.ts
@@ -70,7 +70,7 @@ export const presentationBasePlugins = (): Plugin[] => [
* set or from `entryPlugins()` — so the order is declared, not positional.
*/
export const PLUGIN_BUILD_ORDER: readonly string[] = [
- 'Diagnostics', 'timer', 'velocity', 'lifecycle', 'animation', 'audio', 'video',
+ 'Diagnostics', 'timer', 'velocity', 'lifecycle', 'animation', 'skeletalAnimation', 'audio', 'video',
'importedScene', 'particle', 'trail', 'springBone', 'meshRenderer', 'staticBatch', 'compositeBatch', 'impostor', 'textureStreaming', 'terrain', 'voxel', 'foliage', 'spline', 'water', 'floating', 'underwater', 'tilemap', 'postProcess', 'timeline',
'gameplay',
'perception', 'fsm', 'bt', 'scriptGraph', 'nav', 'eventBinding', 'replication',
diff --git a/sdk/src/asset/Assets.ts b/sdk/src/asset/Assets.ts
index 8d20b0937..6cf526ca6 100644
--- a/sdk/src/asset/Assets.ts
+++ b/sdk/src/asset/Assets.ts
@@ -45,8 +45,6 @@ import { FontAssetLoader } from './loaders/FontAssetLoader';
import { AudioAssetLoader } from './loaders/AudioAssetLoader';
import { AnimClipAssetLoader } from './loaders/AnimClipAssetLoader';
import { PrefabAssetLoader } from './loaders/PrefabAssetLoader';
-import { AnimatorControllerAssetLoader } from './loaders/AnimatorControllerAssetLoader';
-import { AvatarAssetLoader } from './loaders/AvatarAssetLoader';
import { preparePrefabFromSource, type PreparedPrefab } from '../prefab/preparedPrefab';
import type { PrefabOverride } from '../prefab';
import { LocaleAssetLoader } from './loaders/LocaleAssetLoader';
@@ -2705,8 +2703,6 @@ export class Assets {
load: (path, context) => this.bakePrefab_(path, context as LoadContext & { recorder: DependencyRecorder }),
unload: (prepared) => prepared.release(),
});
- this.register(new AnimatorControllerAssetLoader());
- this.register(new AvatarAssetLoader());
this.register(new LocaleAssetLoader());
this.register(new JsonAssetLoader());
this.register(new SoundEventAssetLoader());
diff --git a/sdk/src/platform/nativeModuleRegistry.ts b/sdk/src/platform/nativeModuleRegistry.ts
index b4eedea18..fc04bc8b5 100644
--- a/sdk/src/platform/nativeModuleRegistry.ts
+++ b/sdk/src/platform/nativeModuleRegistry.ts
@@ -36,6 +36,7 @@ import * as SplineModule from '../spline';
import * as VoxelModule from '../voxel';
import * as Rig2DModule from '../rig2d';
import * as ImportedSceneModule from '../imported-scene';
+import * as SkeletalAnimationModule from '../skeletal-animation';
import * as CharacterShadersModule from '../character';
import * as ScriptGraphModule from '../logic';
import * as AiModule from '../ai';
@@ -69,6 +70,7 @@ export const NATIVE_MODULE_NAMESPACES: Readonly<Record<string, unknown>> = {
'esengine/voxel': VoxelModule,
'esengine/rig2d': Rig2DModule,
'esengine/imported-scene': ImportedSceneModule,
+ 'esengine/skeletal-animation': SkeletalAnimationModule,
'esengine/character-shaders': CharacterShadersModule,
'esengine/logic': ScriptGraphModule,
'esengine/ai': AiModule,
diff --git a/sdk/src/runtime/optionalPlugins.ts b/sdk/src/runtime/optionalPlugins.ts
index ee0c93d5c..45ef375f3 100644
--- a/sdk/src/runtime/optionalPlugins.ts
+++ b/sdk/src/runtime/optionalPlugins.ts
@@ -23,6 +23,7 @@ import { registerTilemapSupport } from '../tilemap/tilemapSupport';
import { registerBasicEffectSources } from '../postprocess/sources/basic';
import { registerAtmosphereEffectSources } from '../postprocess/sources/atmosphere';
import { registerLightingEffectSources } from '../postprocess/sources/lighting';
+import { registerSkeletalAnimationSupport } from '../animation/skeletalAnimationSupport';
import { registerTimelineSupport } from '../timeline/timelineSupport';
import { registerTerrainSupport } from '../terrain/terrainSupport';
import { registerFoliageSupport } from '../foliage/foliageSupport';
@@ -45,6 +46,7 @@ export function installOptionalPlugins(): void {
registerPhysics2DSupport();
registerPhysics3DSupport();
registerTilemapSupport();
+ registerSkeletalAnimationSupport();
registerTimelineSupport();
registerBasicEffectSources();
registerAtmosphereEffectSources();
diff --git a/sdk/src/skeletal-animation/index.ts b/sdk/src/skeletal-animation/index.ts
new file mode 100644
index 000000000..5e3e159f0
--- /dev/null
+++ b/sdk/src/skeletal-animation/index.ts
@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file esengine/skeletal-animation — the animator graph and grip poses.
+ *
+ * Importing this is what installs them on a lean entry. The names are also
+ * exported from `esengine` itself, so a script that imports them from there
+ * reaches the same code; what the subpath adds is the installation.
+ */
+export {
+ Animator, AnimatorController, AnimatorControllerAPI,
+ type AnimatorData, type AnimatorControllerDef,
+} from '../animation/Animator';
+export { SkeletalAnimationPlugin, skeletalAnimationPlugin } from '../animation/SkeletalAnimationPlugin';
+export { GripPose, GripSurface, GripProfile, GripHolder } from '../animation';
+
+import { registerSkeletalAnimationSupport } from '../animation/skeletalAnimationSupport';
+
+registerSkeletalAnimationSupport();
diff --git a/sdk/tests/grip-hold-wasm.test.ts b/sdk/tests/grip-hold-wasm.test.ts
index 7dd3d40d6..718f869fa 100644
--- a/sdk/tests/grip-hold-wasm.test.ts
+++ b/sdk/tests/grip-hold-wasm.test.ts
@@ -7,6 +7,7 @@
import { afterEach, beforeAll, describe, expect, it } from 'vitest';
import { App } from '../src/app/app';
import { AnimationPlugin } from '../src/animation/AnimationPlugin';
+import { SkeletalAnimationPlugin } from '../src/animation/SkeletalAnimationPlugin';
import { GripHand, GripHolder, GripMirror, GripPlacement, GripProfile, captureFingerPose, gripHolderStatus, registerFingerPose, releaseGripHolds, slerpQuat, type GripHolderData, type GripProfileData } from '../src/animation/gripHold';
import { GripPose, gripHandJoints, gripPose, gripPoseByJoint, gripPoseFromJson, gripPoseStatus, palmFrameOf, registerGripPose } from '../src/animation/gripPose';
import { GripSurface, GripSurfaceShape, closeFinger, gripSurfaceLines, surfaceDistance, surfacesUnder } from '../src/animation/gripContact';
@@ -30,6 +31,7 @@ function scene() {
const app = App.new(); apps.push(app); app.connectCpp(new core.Registry(), core, { ownedRegistry: true });
setPlayMode(true);
app.addPlugin(new AnimationPlugin());
+ app.addPlugin(new SkeletalAnimationPlugin());
const tick = async (n = 1, dt = 1 / 60): Promise<void> => { for (let i = 0; i < n; i++) { await app.tick(dt); await Promise.resolve(); } };
return { app, world: app.world, tick };
}
diff --git a/sdk/tests/grip-pose-wasm.test.ts b/sdk/tests/grip-pose-wasm.test.ts
index 2b3d28464..f8b42aa64 100644
--- a/sdk/tests/grip-pose-wasm.test.ts
+++ b/sdk/tests/grip-pose-wasm.test.ts
@@ -8,6 +8,7 @@ import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
import { App } from '../src/app/app';
import { Animator } from '../src/animation';
import { AnimationPlugin } from '../src/animation/AnimationPlugin';
+import { SkeletalAnimationPlugin } from '../src/animation/SkeletalAnimationPlugin';
import { GripPose, gripPoseNames, gripPoseStatus, registerGripPose, type GripPoseData } from '../src/animation/gripPose';
import { Name, Transform, type TransformData } from '../src/ecs/component';
import { setEditorMode, setPlayMode } from '../src/ecs/env';
@@ -29,6 +30,7 @@ function scene() {
const app = App.new(); apps.push(app); app.connectCpp(new core.Registry(), core, { ownedRegistry: true });
setPlayMode(true);
app.addPlugin(new AnimationPlugin());
+ app.addPlugin(new SkeletalAnimationPlugin());
const tick = async (n = 1): Promise<void> => { for (let i = 0; i < n; i++) { await app.tick(1 / 60); await Promise.resolve(); } };
return { app, world: app.world, tick };
}
diff --git a/sdk/tests/realm-registry-isolation.test.ts b/sdk/tests/realm-registry-isolation.test.ts
index 9ddea8ae0..269c94800 100644
--- a/sdk/tests/realm-registry-isolation.test.ts
+++ b/sdk/tests/realm-registry-isolation.test.ts
@@ -177,6 +177,8 @@ describe('two realms in one process do not share an asset', () => {
// This round changes which realm answers, not who wins: a name the game
// registered in code is still the one an Animator gets.
const { AnimatorControllerAPI } = await import('../src/animation/Animator');
+ // The controller loader ships with the skeletal-animation module, installed where the content uses it.
+ (await import('../src/animation/skeletalAnimationSupport')).registerSkeletalAnimationSupport();
const CODE = { initialState: 'run', states: [{ name: 'run' }] };
const DISK = JSON.stringify({ initialState: 'idle', states: [{ name: 'idle' }] });
const a = realm(() => DISK);
diff --git a/tools/apiSubsystems.mjs b/tools/apiSubsystems.mjs
index f9cb9132b..9e7e962ba 100644
--- a/tools/apiSubsystems.mjs
+++ b/tools/apiSubsystems.mjs
@@ -365,6 +365,16 @@ export const SUBSYSTEMS = [
whyZh: 'glTF 场景在几何体之外带来的东西(随动画显隐的节点、按模型单位写的粒子)已经和导入器一起检查过,但目前只有导入的场景会写它们',
entry: ['NodeVisibility', 'ParticleModelUnits'],
},
+ {
+ id: 'skeletal-animation',
+ title: 'Skeletal animation',
+ titleZh: '骨骼动画',
+ source: ['skeletal-animation'],
+ tier: 'experimental',
+ why: 'the animator graph and grip poses are checked against the engine, and a lean package installs them only where its content uses them',
+ whyZh: '动画状态机和握持姿态已对引擎做过检查,精简包只在内容用到时才安装它们',
+ entry: ['Animator', 'AnimatorController', 'GripPose'],
+ },
{
id: 'water',
title: 'Water',
diff --git a/tools/check-lean-bundle.mjs b/tools/check-lean-bundle.mjs
index c916345f1..448482a57 100644
--- a/tools/check-lean-bundle.mjs
+++ b/tools/check-lean-bundle.mjs
@@ -67,7 +67,22 @@ for (const [source, bytes] of bySource) {
if (m) byDir.set(m[1], (byDir.get(m[1]) ?? 0) + bytes);
}
+/** Files that belong to an optional module inside a directory the base also uses: the animator graph is esengine/skeletal-animation, the tweens and sprite clips beside it are not. */
+const FILE_CEILING = { 'animation/Animator.ts': 0, 'animation/motion.ts': 0, 'animation/animatorIK.ts': 0, 'animation/animatorAvatar.ts': 0, 'animation/layerStack.ts': 0 };
+const byFile = new Map();
+for (const [source, bytes] of bySource) {
+ const m = /sdk\/src\/(.+)$/.exec(source.split(BS).join('/'));
+ if (m) byFile.set(m[1], (byFile.get(m[1]) ?? 0) + bytes);
+}
+
let failed = false;
+for (const [file, ceiling] of Object.entries(FILE_CEILING)) {
+ const bytes = byFile.get(file) ?? 0;
+ if (bytes > ceiling) {
+ failed = true;
+ console.error(`check-lean-bundle: ${file} left ${bytes} bytes in a blank package (ceiling ${ceiling}) — a subsystem is riding along again`);
+ }
+}
for (const [dir, ceiling] of Object.entries(CEILING)) {
const bytes = byDir.get(dir) ?? 0;
if (bytes > ceiling) {
diff --git a/tools/lib/sdkProgram.mjs b/tools/lib/sdkProgram.mjs
index 79700f4ec..dd0073b1c 100644
--- a/tools/lib/sdkProgram.mjs
+++ b/tools/lib/sdkProgram.mjs
@@ -71,6 +71,7 @@ export const ENTRIES = {
'voxel': 'src/voxel/index.ts',
'rig2d': 'src/rig2d/index.ts',
'imported-scene': 'src/imported-scene/index.ts',
+ 'skeletal-animation': 'src/skeletal-animation/index.ts',
'character-shaders': 'src/character/index.ts',
'logic': 'src/logic/index.ts',
'debug-channel': 'src/debug-channel/index.ts',
diff --git a/tools/nativeScriptModules.js b/tools/nativeScriptModules.js
index 90c9532d6..751c69060 100644
--- a/tools/nativeScriptModules.js
+++ b/tools/nativeScriptModules.js
@@ -77,6 +77,7 @@ export const MODULES = {
'esengine/voxel': { disposition: 'native-subpath' },
'esengine/rig2d': { disposition: 'native-subpath' },
'esengine/imported-scene': { disposition: 'native-subpath' },
+ 'esengine/skeletal-animation': { disposition: 'native-subpath' },
'esengine/character-shaders': { disposition: 'native-subpath' },
'esengine/logic': { disposition: 'native-subpath' },
'esengine/ai': { disposition: 'native-subpath' },