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): SpriteAnimator globals -> SpriteAnimationApi class (F3 B3a)
esengine9bfc3ecaed65
diff --git a/sdk/src/animation/SpriteAnimator.ts b/sdk/src/animation/SpriteAnimator.tsindex 0133b1efe..3fc6e23a6 100644--- a/sdk/src/animation/SpriteAnimator.ts+++ b/sdk/src/animation/SpriteAnimator.ts@@ -4,6 +4,7 @@*/import { defineComponent, type ComponentDef } from '../component';+import { defineResource } from '../resource';import type { Entity, TextureHandle } from '../types';import type { World } from '../world';import { Sprite, type SpriteData } from '../component';@@ -36,91 +37,180 @@ export interface SpriteAnimClip {events?: SpriteAnimEvent[];}+export function shouldFireEvent(eventFrame: number, prevFrame: number, newFrame: number, totalFrames: number, loop: boolean): boolean {+ if (prevFrame === newFrame && eventFrame === newFrame) return true;+ if (newFrame > prevFrame) {+ return eventFrame > prevFrame && eventFrame <= newFrame;+ }+ if (loop && newFrame < prevFrame) {+ return eventFrame > prevFrame || eventFrame <= newFrame;+ }+ return false;+}+// =============================================================================-// Clip Registry+// SpriteAnimation — per-App clip registry + frame-event listeners + system// =============================================================================-const clipRegistry = new Map<string, SpriteAnimClip>();+/**+ * Owns one App's sprite-animation clip registry and frame-event listeners, and+ * advances SpriteAnimator components. Published as the {@link SpriteAnimation}+ * resource (B3); a default instance backs the legacy free functions until the+ * per-App flip (B3b) routes registration/listeners through the owning App.+ */+export class SpriteAnimationApi {+ private readonly clips = new Map<string, SpriteAnimClip>();+ private readonly entityListeners = new Map<Entity, SpriteAnimEventHandler[]>();+ private readonly globalListeners: SpriteAnimEventHandler[] = [];-export function registerAnimClip(clip: SpriteAnimClip): void {- clipRegistry.set(clip.name, clip);-}+ // -- clip registry ---------------------------------------------------------export function unregisterAnimClip(name: string): void {- clipRegistry.delete(name);-}+ registerClip(clip: SpriteAnimClip): void {+ this.clips.set(clip.name, clip);+ }-export function getAnimClip(name: string): SpriteAnimClip | undefined {- return clipRegistry.get(name);-}+ unregisterClip(name: string): void {+ this.clips.delete(name);+ }-export function clearAnimClips(): void {- clipRegistry.clear();-}+ getClip(name: string): SpriteAnimClip | undefined {+ return this.clips.get(name);+ }-// =============================================================================-// Frame Event Listeners-// =============================================================================+ clearClips(): void {+ this.clips.clear();+ }-const animEventListeners = new Map<Entity, SpriteAnimEventHandler[]>();-const globalAnimEventListeners: SpriteAnimEventHandler[] = [];+ // -- frame-event listeners -------------------------------------------------export function onAnimEvent(entity: Entity, handler: SpriteAnimEventHandler): () => void {- let list = animEventListeners.get(entity);- if (!list) {- list = [];- animEventListeners.set(entity, list);- }- list.push(handler);- return () => {- const arr = animEventListeners.get(entity);- if (arr) {- const idx = arr.indexOf(handler);- if (idx >= 0) arr.splice(idx, 1);- if (arr.length === 0) animEventListeners.delete(entity);+ onEvent(entity: Entity, handler: SpriteAnimEventHandler): () => void {+ let list = this.entityListeners.get(entity);+ if (!list) {+ list = [];+ this.entityListeners.set(entity, list);}- };-}+ list.push(handler);+ return () => {+ const arr = this.entityListeners.get(entity);+ if (arr) {+ const idx = arr.indexOf(handler);+ if (idx >= 0) arr.splice(idx, 1);+ if (arr.length === 0) this.entityListeners.delete(entity);+ }+ };+ }-export function onAnimEventGlobal(handler: SpriteAnimEventHandler): () => void {- globalAnimEventListeners.push(handler);- return () => {- const idx = globalAnimEventListeners.indexOf(handler);- if (idx >= 0) globalAnimEventListeners.splice(idx, 1);- };-}+ onEventGlobal(handler: SpriteAnimEventHandler): () => void {+ this.globalListeners.push(handler);+ return () => {+ const idx = this.globalListeners.indexOf(handler);+ if (idx >= 0) this.globalListeners.splice(idx, 1);+ };+ }-export function removeAnimEventListeners(entity: Entity): void {- animEventListeners.delete(entity);-}+ removeEntityListeners(entity: Entity): void {+ this.entityListeners.delete(entity);+ }-function fireAnimEvents(entity: Entity, clip: SpriteAnimClip, prevFrame: number, newFrame: number): void {- if (!clip.events || clip.events.length === 0) return;+ private fireEvents(entity: Entity, clip: SpriteAnimClip, prevFrame: number, newFrame: number): void {+ if (!clip.events || clip.events.length === 0) return;- for (const evt of clip.events) {- if (shouldFireEvent(evt.frame, prevFrame, newFrame, clip.frames.length, clip.loop)) {- const listeners = animEventListeners.get(entity);- if (listeners) {- for (const handler of listeners) {+ for (const evt of clip.events) {+ if (shouldFireEvent(evt.frame, prevFrame, newFrame, clip.frames.length, clip.loop)) {+ const listeners = this.entityListeners.get(entity);+ if (listeners) {+ for (const handler of listeners) {+ handler(evt, entity);+ }+ }+ for (const handler of this.globalListeners) {handler(evt, entity);}}- for (const handler of globalAnimEventListeners) {- handler(evt, entity);+ }+ }++ // -- per-frame system -----------------------------------------------------++ update(world: World, deltaTime: number): void {+ const entities = world.getEntitiesWithComponents([SpriteAnimator]);++ for (const entity of entities) {+ const animator = world.get(entity, SpriteAnimator) as SpriteAnimatorData;+ if (!animator.enabled || !animator.playing || !animator.clip) continue;++ const clip = this.clips.get(animator.clip);+ if (!clip || clip.frames.length === 0) continue;++ const currentFrame = clip.frames[animator.currentFrame];+ const frameDuration = currentFrame?.duration ?? 1.0 / (clip.fps * animator.speed);++ const needsInitialApply = animator.frameTimer === 0 && animator.currentFrame === 0;+ const prevFrame = animator.currentFrame;++ animator.frameTimer += deltaTime;++ let frameChanged = needsInitialApply;+ if (animator.frameTimer >= frameDuration) {+ animator.frameTimer -= frameDuration;+ animator.currentFrame++;++ if (animator.currentFrame >= clip.frames.length) {+ if (animator.loop && clip.loop) {+ animator.currentFrame = 0;+ } else {+ animator.currentFrame = clip.frames.length - 1;+ animator.playing = false;+ }+ }++ frameChanged = true;+ }++ if (frameChanged) {+ this.fireEvents(entity, clip, prevFrame, animator.currentFrame);+ }++ if (frameChanged && world.has(entity, Sprite)) {+ const frame = clip.frames[animator.currentFrame];+ const sprite = world.get(entity, Sprite) as SpriteData;+ sprite.texture = frame.texture;+ if (frame.uvOffset) {+ sprite.uvOffset = frame.uvOffset;+ sprite.uvScale = frame.uvScale!;+ }+ world.insert(entity, Sprite, sprite);+ }++ if (frameChanged) {+ world.insert(entity, SpriteAnimator, animator);}}}}-export function shouldFireEvent(eventFrame: number, prevFrame: number, newFrame: number, totalFrames: number, loop: boolean): boolean {- if (prevFrame === newFrame && eventFrame === newFrame) return true;- if (newFrame > prevFrame) {- return eventFrame > prevFrame && eventFrame <= newFrame;- }- if (loop && newFrame < prevFrame) {- return eventFrame > prevFrame || eventFrame <= newFrame;- }- return false;+/**+ * Per-App sprite-animation resource (clip registry + frame-event listeners),+ * published by `AnimationPlugin` (B3b). Read as `app.getResource(SpriteAnimation)`.+ */+export const SpriteAnimation = defineResource<SpriteAnimationApi>(null!, 'SpriteAnimation');++// B3a: default instance backing the legacy free functions below (per-App in B3b).+const defaultAnim = new SpriteAnimationApi();++export function registerAnimClip(clip: SpriteAnimClip): void { defaultAnim.registerClip(clip); }+export function unregisterAnimClip(name: string): void { defaultAnim.unregisterClip(name); }+export function getAnimClip(name: string): SpriteAnimClip | undefined { return defaultAnim.getClip(name); }+export function clearAnimClips(): void { defaultAnim.clearClips(); }++export function onAnimEvent(entity: Entity, handler: SpriteAnimEventHandler): () => void {+ return defaultAnim.onEvent(entity, handler);+}+export function onAnimEventGlobal(handler: SpriteAnimEventHandler): () => void {+ return defaultAnim.onEventGlobal(handler);+}+export function removeAnimEventListeners(entity: Entity): void {+ defaultAnim.removeEntityListeners(entity);}// =============================================================================@@ -154,59 +244,7 @@ export const SpriteAnimator: ComponentDef<SpriteAnimatorData> = defineComponent(// =============================================================================export function spriteAnimatorSystemUpdate(world: World, deltaTime: number): void {- const entities = world.getEntitiesWithComponents([SpriteAnimator]);-- for (const entity of entities) {- const animator = world.get(entity, SpriteAnimator) as SpriteAnimatorData;- if (!animator.enabled || !animator.playing || !animator.clip) continue;-- const clip = clipRegistry.get(animator.clip);- if (!clip || clip.frames.length === 0) continue;-- const currentFrame = clip.frames[animator.currentFrame];- const frameDuration = currentFrame?.duration ?? 1.0 / (clip.fps * animator.speed);-- const needsInitialApply = animator.frameTimer === 0 && animator.currentFrame === 0;- const prevFrame = animator.currentFrame;-- animator.frameTimer += deltaTime;-- let frameChanged = needsInitialApply;- if (animator.frameTimer >= frameDuration) {- animator.frameTimer -= frameDuration;- animator.currentFrame++;-- if (animator.currentFrame >= clip.frames.length) {- if (animator.loop && clip.loop) {- animator.currentFrame = 0;- } else {- animator.currentFrame = clip.frames.length - 1;- animator.playing = false;- }- }-- frameChanged = true;- }-- if (frameChanged) {- fireAnimEvents(entity, clip, prevFrame, animator.currentFrame);- }-- if (frameChanged && world.has(entity, Sprite)) {- const frame = clip.frames[animator.currentFrame];- const sprite = world.get(entity, Sprite) as SpriteData;- sprite.texture = frame.texture;- if (frame.uvOffset) {- sprite.uvOffset = frame.uvOffset;- sprite.uvScale = frame.uvScale!;- }- world.insert(entity, Sprite, sprite);- }-- if (frameChanged) {- world.insert(entity, SpriteAnimator, animator);- }- }+ defaultAnim.update(world, deltaTime);}// =============================================================================@@ -218,7 +256,7 @@ export function spriteAnimatorGotoFrame(frameIndex: number,andPlay: boolean = true,): void {- const clip = clipRegistry.get(animator.clip);+ const clip = defaultAnim.getClip(animator.clip);if (!clip || clip.frames.length === 0) return;animator.currentFrame = Math.max(0, Math.min(frameIndex, clip.frames.length - 1));@@ -231,7 +269,7 @@ export function spriteAnimatorGotoLabel(label: string,andPlay: boolean = true,): void {- const clip = clipRegistry.get(animator.clip);+ const clip = defaultAnim.getClip(animator.clip);if (!clip || !clip.labels) return;const frameIndex = clip.labels[label];