A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @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 { Time, type TimeData } from '../ecs/resource';
import type { Entity } from '../types';
import type { CppRegistry } from '../wasm';
import { engineApi } from '../ecs/bridge/engineApi';
import { log } from '../util/logger';
import type { AnimCore } from './Tween';
import { Tween, TweenAPI } from './Tween';
import { SpriteAnimation, SpriteAnimationAPI, type SpriteAnimClip } from './SpriteAnimator';
import { appRegistryAsset } from '../asset/registryLookup';
import { playModeOnly } from '../ecs/env';
import { installCoverFade } from '../render/coverFade';
import { installRainShelter } from '../render/rainShelter';
import { installSight } from '../render/sight';
import { installFogOfWar } from '../render/fogOfWar';
import { installSwayPush } from '../render/swayPush';
import { installFootsteps } from '../render/footsteps';
import { SystemLabel } from '../ecs/systemLabels';
export class AnimationPlugin implements Plugin {
name = 'animation';
private readonly despawnCleanups_ = new WeakMap<App, () => void>();
private latestDespawnCleanup_: (() => void) | null = null;
build(app: App): void {
this.cleanup(app);
// Whichever core is present (see ecs/engineApi.ts). Sprite animation and the
// animator graph are pure TypeScript, but tweens live in the engine, so a core
// that compiles no tween system gets the rest of the plugin and says so.
const engine = engineApi(app);
const registry = app.world.getCppRegistry() as CppRegistry;
if (engine && typeof engine.anim_createTween !== 'function') {
log.warn('animation', 'this engine core has no tween system — Tween.to() will not animate');
}
const tween = new TweenAPI(engine ?? {}, registry);
app.insertResource(Tween, tween);
const anim = new SpriteAnimationAPI();
app.insertResource(SpriteAnimation, anim);
const world = app.world;
const offDespawn = world.onDespawn((entity: Entity) => {
tween.cancelAll(entity);
anim.removeEntityListeners(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);
const offRainShelter = installRainShelter(app);
const offSight = installSight(app);
// After the sight system, whose walls it casts rays against.
const offFog = installFogOfWar(app);
const offSwayPush = installSwayPush(app);
const offFootsteps = installFootsteps(app);
const release = (): void => { offDespawn(); offCoverFade(); offRainShelter(); offSight(); offFog(); offSwayPush(); offFootsteps(); };
this.despawnCleanups_.set(app, release);
this.latestDespawnCleanup_ = release;
app.addSystemToSchedule(Schedule.Update, defineSystem(
[Res(Time), Res(Tween)],
(time: TimeData, tweenAPI: TweenAPI) => {
tweenAPI.update(time.delta);
},
{ name: 'TweenSystem' }
), { runIf: playModeOnly });
// 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));
app.addSystemToSchedule(Schedule.Update, defineSystem(
[Res(Time), Res(SpriteAnimation)],
(time: TimeData, animApi: SpriteAnimationAPI) => {
animApi.update(world, time.delta);
},
{ name: 'SpriteAnimatorSystem' }
), { runAfter: [SystemLabel.Tween, SystemLabel.Animator], runIf: playModeOnly });
}
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 animationPlugin = new AnimationPlugin();