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
feat(anim): .esanim v1.3 persists frame events
esengineca48515e3406
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 804340a0d..0d9b2aea6 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1,7 +1,7 @@# API surface — esengine/index<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 1265 stable · 17 beta · 0 deprecated+Symbols: 1266 stable · 17 beta · 0 deprecated## ABI_LAYOUT_HASH — const```@@ -15,7 +15,7 @@ readonly AnchorAxis[]## ANIM_CLIP_FORMAT_VERSION — const```-"1.2"+"1.3"```## ActionDef — interface@@ -190,6 +190,7 @@ v: AnchorAxis## AnimClipAssetData — interface```+events: AnimClipEventData[] | undefinedfps: number | undefinedframes: AnimClipFrameData[]loop: boolean | undefined@@ -198,6 +199,13 @@ type: "animation-clip"version: string```+## AnimClipEventData — interface+```+data: unknown+frame: number+name: string+```+## AnimClipFrameData — interface```atlasFrame: { x: number; y: number; width: number; height: number; pageWidth: number; pageHeight: number; } | undefineddiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex d99fc0065..42fb24275 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.node<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 1264 stable · 19 beta · 0 deprecated+Symbols: 1265 stable · 19 beta · 0 deprecated## ANCHOR_AXES — const```@@ -10,7 +10,7 @@ readonly AnchorAxis[]## ANIM_CLIP_FORMAT_VERSION — const```-"1.2"+"1.3"```## ActionDef — interface@@ -185,6 +185,7 @@ v: AnchorAxis## AnimClipAssetData — interface```+events: AnimClipEventData[] | undefinedfps: number | undefinedframes: AnimClipFrameData[]loop: boolean | undefined@@ -193,6 +194,13 @@ type: "animation-clip"version: string```+## AnimClipEventData — interface+```+data: unknown+frame: number+name: string+```+## AnimClipFrameData — interface```atlasFrame: { x: number; y: number; width: number; height: number; pageWidth: number; pageHeight: number; } | undefineddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 6d3e1af17..63779ea4c 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -1,7 +1,7 @@# API surface — esengine/wechat<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 1275 stable · 17 beta · 0 deprecated+Symbols: 1276 stable · 17 beta · 0 deprecated## ANCHOR_AXES — const```@@ -10,7 +10,7 @@ readonly AnchorAxis[]## ANIM_CLIP_FORMAT_VERSION — const```-"1.2"+"1.3"```## ActionDef — interface@@ -185,6 +185,7 @@ v: AnchorAxis## AnimClipAssetData — interface```+events: AnimClipEventData[] | undefinedfps: number | undefinedframes: AnimClipFrameData[]loop: boolean | undefined@@ -193,6 +194,13 @@ type: "animation-clip"version: string```+## AnimClipEventData — interface+```+data: unknown+frame: number+name: string+```+## AnimClipFrameData — interface```atlasFrame: { x: number; y: number; width: number; height: number; pageWidth: number; pageHeight: number; } | undefineddiff --git a/sdk/src/animation/AnimClipLoader.ts b/sdk/src/animation/AnimClipLoader.tsindex ed9c23f28..75796ce40 100644--- a/sdk/src/animation/AnimClipLoader.ts+++ b/sdk/src/animation/AnimClipLoader.ts@@ -12,7 +12,7 @@ import { log } from '../logger';// .esanim File Format// =============================================================================-export const ANIM_CLIP_FORMAT_VERSION = '1.2';+export const ANIM_CLIP_FORMAT_VERSION = '1.3';/*** Sprite-sheet slicing grid. When present, frames may reference grid cells@@ -46,6 +46,17 @@ export interface AnimClipFrameData {};}+/**+ * A frame event: as the playhead crosses `frame`, the runtime fires `name`+ * (with optional `data`) to any listener. Added in format 1.3; the runtime+ * (SpriteAnimator) always supported events, only the format/editor did not.+ */+export interface AnimClipEventData {+ frame: number;+ name: string;+ data?: unknown;+}+export interface AnimClipAssetData {version: string;type: 'animation-clip';@@ -53,6 +64,7 @@ export interface AnimClipAssetData {loop?: boolean;sheet?: AnimClipSheetData;frames: AnimClipFrameData[];+ events?: AnimClipEventData[];}// =============================================================================@@ -157,6 +169,13 @@ export function parseAnimClipAsset(rawJson: unknown): AnimClipAssetData {frames.push(frame);}}+ const events: AnimClipEventData[] = [];+ for (const e of Array.isArray(raw?.events) ? raw.events : []) {+ if (e && typeof e.name === 'string' && e.name+ && typeof e.frame === 'number' && Number.isInteger(e.frame) && e.frame >= 0) {+ events.push({ frame: e.frame, name: e.name, ...(e.data !== undefined ? { data: e.data } : {}) });+ }+ }return {version: typeof raw?.version === 'string' ? raw.version : ANIM_CLIP_FORMAT_VERSION,type: 'animation-clip',@@ -164,6 +183,7 @@ export function parseAnimClipAsset(rawJson: unknown): AnimClipAssetData {loop: typeof raw?.loop === 'boolean' ? raw.loop : true,...(sheet ? { sheet } : {}),frames,+ ...(events.length ? { events } : {}),};}@@ -176,6 +196,7 @@ export function serializeAnimClip(asset: AnimClipAssetData): Record<string, unknloop: asset.loop ?? true,...(asset.sheet ? { sheet: { ...asset.sheet } } : {}),frames: asset.frames.map(f => ({ ...f })),+ ...(asset.events && asset.events.length ? { events: asset.events.map(e => ({ ...e })) } : {}),};}@@ -242,6 +263,7 @@ export function parseAnimClipData(name: clipPath,fps: data.fps ?? DEFAULT_FPS,loop: data.loop ?? true,+ ...(data.events?.length ? { events: data.events.map(e => ({ frame: e.frame, name: e.name, data: e.data })) } : {}),frames: data.frames.map(f => {if (sheet && f.cell !== undefined) {if (f.cell >= cellCount) {diff --git a/sdk/src/animation/index.ts b/sdk/src/animation/index.tsindex 5b68df1c5..30cdbf835 100644--- a/sdk/src/animation/index.ts+++ b/sdk/src/animation/index.ts@@ -96,4 +96,5 @@ export {type AnimClipAssetData,type AnimClipFrameData,type AnimClipSheetData,+ type AnimClipEventData,} from './AnimClipLoader';diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.tsindex 760ce84c9..9b5f4a563 100644--- a/sdk/src/core-content.ts+++ b/sdk/src/core-content.ts@@ -283,6 +283,7 @@ export {type AnimClipAssetData,type AnimClipFrameData,type AnimClipSheetData,+ type AnimClipEventData,TweenGroup,TweenSequence,type Completable,