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.

feat(anim): .esanim v1.3 persists frame events

esengineca48515e3406
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 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[] | undefined
fps: number | undefined
frames: 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; } | undefined
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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[] | undefined
fps: number | undefined
frames: 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; } | undefined
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 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[] | undefined
fps: number | undefined
frames: 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; } | undefined
diff --git a/sdk/src/animation/AnimClipLoader.ts b/sdk/src/animation/AnimClipLoader.ts
index 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, unkn
loop: 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.ts
index 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.ts
index 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,