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
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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 everythingtry {- 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.tsindex 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.tsindex 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.jsonindex 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.jsindex 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.jsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.jsindex 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' },