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(editor): .esanim spawns a posed animated sprite - drop, or one right-click

esengine8ddce251dd89
diff --git a/desktop/src/engine/entitySources.ts b/desktop/src/engine/entitySources.ts
index f63999945..5a90b3aae 100644
--- a/desktop/src/engine/entitySources.ts
+++ b/desktop/src/engine/entitySources.ts
@@ -78,6 +78,36 @@ export function spritePrefab(name: string, textureRef: string, size: { x: number
return preset(name, [['Transform', {}], ['Sprite', { texture: textureRef, size: { x: size.x, y: size.y } }]]);
}
+/**
+ * A Transform + Sprite + SpriteAnimator prefab referencing a `.esanim` clip.
+ * The Sprite is seeded with the clip's static pose (sheet texture + frame-0 UV
+ * window + cell size) so the entity reads correctly in edit mode; Play hands the
+ * per-frame writes to the SpriteAnimator system.
+ */
+export function animatedSpritePrefab(
+ name: string,
+ clipRef: string,
+ seed: {
+ texture?: string;
+ size?: { x: number; y: number };
+ uv?: { uvOffset: { x: number; y: number }; uvScale: { x: number; y: number } };
+ loop?: boolean;
+ },
+): PrefabData {
+ const sprite: Record<string, unknown> = {};
+ if (seed.texture) sprite.texture = seed.texture;
+ if (seed.size) sprite.size = { x: seed.size.x, y: seed.size.y };
+ if (seed.uv) {
+ sprite.uvOffset = { ...seed.uv.uvOffset };
+ sprite.uvScale = { ...seed.uv.uvScale };
+ }
+ return preset(name, [
+ ['Transform', {}],
+ ['Sprite', sprite],
+ ['SpriteAnimator', { clip: clipRef, loop: seed.loop ?? true }],
+ ]);
+}
+
/**
* A Transform + TilemapLayer prefab whose `cellSize` (a vec2 → `{x, y}` in the model)
* is seeded from the tileset's tile size. `tilesetRef` bakes the out-of-band
diff --git a/desktop/src/flipbook/createAnimatedSprite.ts b/desktop/src/flipbook/createAnimatedSprite.ts
new file mode 100644
index 000000000..d0834ea8e
--- /dev/null
+++ b/desktop/src/flipbook/createAnimatedSprite.ts
@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file createAnimatedSprite.ts
+ * @brief Spawn a playing sprite-flipbook entity from a .esanim through the
+ * unified create pipeline (mirrors createTilemap.ts): `build` yields a
+ * Transform + Sprite + SpriteAnimator prefab seeded so the edit-mode
+ * static pose IS frame 0 (sheet texture + first cell's UV window), and
+ * Play animates with zero code.
+ */
+import { parseAnimClipAsset, animClipCellUv, type AnimClipAssetData } from 'esengine';
+import { Images } from 'lucide-react';
+import { createFromSource, animatedSpritePrefab, type EntitySource } from '@/engine/entitySources';
+import { useSelection } from '@/store/selectionStore';
+import { ProjectStore } from '@/project/ProjectStore';
+import { Toasts } from '@/store/Toasts';
+import { t } from '@/i18n';
+
+function animClipSource(clipPath: string, clipRef: string, asset: AnimClipAssetData): EntitySource {
+ const name = (clipPath.split('/').pop() ?? 'Sprite').replace(/\.[^.]+$/, '') || 'Sprite';
+ const sheet = asset.sheet;
+ const firstCell = asset.frames.find((f) => f.cell !== undefined)?.cell;
+ return {
+ id: `animclip:${clipPath}`,
+ label: name,
+ category: '2D',
+ icon: Images,
+ build: () =>
+ animatedSpritePrefab(name, clipRef, {
+ texture: sheet?.texture ?? asset.frames[0]?.texture,
+ size: sheet ? { x: sheet.cellWidth, y: sheet.cellHeight } : undefined,
+ uv: sheet && firstCell !== undefined ? animClipCellUv(sheet, firstCell) : undefined,
+ loop: asset.loop ?? true,
+ }),
+ afterCreate: (_ctx, rootId) => {
+ useSelection.getState().select(rootId);
+ },
+ };
+}
+
+/** Create a Sprite + SpriteAnimator entity referencing the given .esanim and select it. */
+export async function createAnimatedSpriteFromClip(
+ clipPath: string,
+ position?: { x: number; y: number },
+): Promise<void> {
+ const clipRef = ProjectStore.assetRef(clipPath); // .esanim → @uuid
+ if (!clipRef) {
+ Toasts.push(t('fb.toast.clipUntracked'), 'error');
+ return;
+ }
+ let asset: AnimClipAssetData;
+ try {
+ asset = parseAnimClipAsset(JSON.parse(await window.estella.fs.read(clipPath)));
+ } catch (e) {
+ Toasts.push(t('fb.toast.openFailed', { error: String(e) }), 'error');
+ return;
+ }
+ // Preload the sheet texture so the seeded frame renders immediately in edit mode.
+ const texRef = asset.sheet?.texture ?? asset.frames[0]?.texture;
+ const texPath = texRef ? ProjectStore.assetInfo(texRef)?.path : undefined;
+ if (texPath) await ProjectStore.assetRefForPath(texPath, 'texture');
+ await createFromSource(animClipSource(clipPath, clipRef, asset), { parent: null, position });
+}
diff --git a/desktop/src/i18n/messages/content.ts b/desktop/src/i18n/messages/content.ts
index bfc25982d..039c2c038 100644
--- a/desktop/src/i18n/messages/content.ts
+++ b/desktop/src/i18n/messages/content.ts
@@ -73,6 +73,7 @@ export const contentMessages = defineMessages({
'cb.menuIncludeInExport': { en: 'Include in Export', zh: '包含在导出中' },
'cb.menuExcludeFromExport': { en: 'Exclude from Export', zh: '从导出中排除' },
'cb.menuCreateSpriteAnim': { en: 'Create Sprite Animation', zh: '创建精灵动画' },
+ 'cb.menuCreateAnimatedSprite': { en: 'Create Animated Sprite', zh: '创建动画精灵' },
'cb.menuCreateTileset': { en: 'Create Tileset', zh: '创建瓦片集' },
'cb.menuCreateTilemap': { en: 'Create Tilemap', zh: '创建瓦片地图' },
'cb.menuCreateMaterialInstance': { en: 'Create Material Instance', zh: '创建材质实例' },
diff --git a/desktop/src/i18n/messages/flipbook.ts b/desktop/src/i18n/messages/flipbook.ts
index 7f30436d9..e62b3b7ba 100644
--- a/desktop/src/i18n/messages/flipbook.ts
+++ b/desktop/src/i18n/messages/flipbook.ts
@@ -51,6 +51,10 @@ export const flipbookMessages = defineMessages({
'fb.toast.openFailed': { en: 'Failed to open sprite animation: {error}', zh: '打开精灵动画失败:{error}' },
'fb.toast.createFailed': { en: 'Failed to create sprite animation: {error}', zh: '创建精灵动画失败:{error}' },
'fb.toast.created': { en: 'Created {name}', zh: '已创建 {name}' },
+ 'fb.toast.clipUntracked': {
+ en: 'This animation is not in the asset database yet (missing .meta)',
+ zh: '该动画尚未进入资产数据库(缺少 .meta)',
+ },
'fb.toast.texUntracked': {
en: 'This texture is not in the asset database yet (missing .meta)',
zh: '该纹理尚未进入资产数据库(缺少 .meta)',
diff --git a/desktop/src/panels/ContentBrowser.tsx b/desktop/src/panels/ContentBrowser.tsx
index 92f3b525a..499e65786 100644
--- a/desktop/src/panels/ContentBrowser.tsx
+++ b/desktop/src/panels/ContentBrowser.tsx
@@ -18,6 +18,7 @@ import { referencingPaths } from '@/project/assetRefs';
import { parseAssetQuery, filterAndSortAssets, type AssetSort } from '@/project/assetFilter';
import { createTilesetFromTexture } from '@/tileset/openTileset';
import { createFlipbookFromTexture } from '@/flipbook/openFlipbook';
+import { createAnimatedSpriteFromClip } from '@/flipbook/createAnimatedSprite';
import { createTilemapFromTileset } from '@/tilemap/createTilemap';
import { BUILTIN_SHADER_TEMPLATES } from 'esengine';
import { createMaterial, createMaterialInstance } from '@/material/openMaterial';
@@ -869,6 +870,7 @@ export function ContentBrowser() {
const isScene = !entry.isDir && assetType(entry.name) === 'scene';
const isTexture = !entry.isDir && (assetType(entry.name) === 'texture' || assetType(entry.name) === 'sprite');
const isTileset = !entry.isDir && assetType(entry.name) === 'tileset';
+ const isAnimClip = !entry.isDir && assetType(entry.name) === 'animclip';
const isMaterial = !entry.isDir && assetType(entry.name) === 'material';
const ref = entry.isDir ? null : ProjectStore.assetRef(path);
return [
@@ -895,6 +897,9 @@ export function ContentBrowser() {
...(isTileset
? [{ label: t('cb.menuCreateTilemap'), onClick: () => void createTilemapFromTileset(path) }]
: []),
+ ...(isAnimClip
+ ? [{ label: t('cb.menuCreateAnimatedSprite'), onClick: () => void createAnimatedSpriteFromClip(path) }]
+ : []),
...(isMaterial
? [{ label: t('cb.menuCreateMaterialInstance'), onClick: () => void createMaterialInstance(path) }]
: []),
diff --git a/desktop/src/panels/Viewport.tsx b/desktop/src/panels/Viewport.tsx
index da60e448f..51e5d88f3 100644
--- a/desktop/src/panels/Viewport.tsx
+++ b/desktop/src/panels/Viewport.tsx
@@ -26,6 +26,7 @@ import { createFromSource, sourceById, SOURCE_DND_MIME } from '@/engine/entitySo
import { resizeUINodeAxis, type ResizeSide, type AxisResizeWrites } from '@/engine/uiResize';
import { IMAGE_RE } from '@/project/assetMeta';
import { createTilemapFromTileset } from '@/tilemap/createTilemap';
+import { createAnimatedSpriteFromClip } from '@/flipbook/createAnimatedSprite';
import { SceneModel } from '@/engine/SceneModel';
import { SceneCommands } from '@/engine/SceneCommands';
import { SceneStore } from '@/engine/SceneStore';
@@ -1498,6 +1499,10 @@ export function Viewport() {
e.preventDefault();
// A tileset spawns a paintable TilemapLayer, which wires its own placement + painter.
void createTilemapFromTileset(path);
+ } else if (path.toLowerCase().endsWith('.esanim')) {
+ e.preventDefault();
+ // A flipbook spawns a Sprite + SpriteAnimator posed at frame 0.
+ void createAnimatedSpriteFromClip(path, wp ?? undefined);
}
};
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 9f0003861..ce71a0e4c 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: 1140 stable · 17 beta · 1 deprecated
+Symbols: 1141 stable · 17 beta · 1 deprecated
## ABI_LAYOUT_HASH — const
```
@@ -7079,6 +7079,11 @@ AiRegistry<AiContext>
(sheet: AnimClipSheetData, cell: number): { x: number; y: number; width: number; height: number; }
```
+## animClipCellUv — function
+```
+(sheet: AnimClipSheetData, cell: number): { uvOffset: { x: number; y: number; }; uvScale: { x: number; y: number; }; }
+```
+
## animClipSheetCols — function
```
(sheet: AnimClipSheetData): number
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index daab4de36..939e635a0 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: 1139 stable · 19 beta · 1 deprecated
+Symbols: 1140 stable · 19 beta · 1 deprecated
## ANCHOR_AXES — const
```
@@ -7074,6 +7074,11 @@ AiRegistry<AiContext>
(sheet: AnimClipSheetData, cell: number): { x: number; y: number; width: number; height: number; }
```
+## animClipCellUv — function
+```
+(sheet: AnimClipSheetData, cell: number): { uvOffset: { x: number; y: number; }; uvScale: { x: number; y: number; }; }
+```
+
## animClipSheetCols — function
```
(sheet: AnimClipSheetData): number
diff --git a/sdk/src/animation/AnimClipLoader.ts b/sdk/src/animation/AnimClipLoader.ts
index 1d307211e..4b6349d7f 100644
--- a/sdk/src/animation/AnimClipLoader.ts
+++ b/sdk/src/animation/AnimClipLoader.ts
@@ -89,6 +89,24 @@ export function animClipCellRect(
};
}
+/** UV window (flipY space) of a grid cell — what a Sprite shows for that frame. */
+export function animClipCellUv(
+ sheet: AnimClipSheetData,
+ cell: number,
+): { uvOffset: { x: number; y: number }; uvScale: { x: number; y: number } } {
+ const rect = animClipCellRect(sheet, cell);
+ return {
+ uvOffset: {
+ x: rect.x / sheet.pageWidth,
+ y: 1.0 - (rect.y + rect.height) / sheet.pageHeight,
+ },
+ uvScale: {
+ x: rect.width / sheet.pageWidth,
+ y: rect.height / sheet.pageHeight,
+ },
+ };
+}
+
// =============================================================================
// Parsing / serialization
// =============================================================================
@@ -231,7 +249,7 @@ export function parseAnimClipData(
const frame: SpriteAnimFrame = {
texture: textureHandles.get(sheet.texture) ?? 0,
duration: f.duration,
- ...uvFromRect(animClipCellRect(sheet, f.cell), sheet.pageWidth, sheet.pageHeight),
+ ...animClipCellUv(sheet, f.cell),
};
return frame;
}
diff --git a/sdk/src/animation/index.ts b/sdk/src/animation/index.ts
index 63ac88c54..43fdd1214 100644
--- a/sdk/src/animation/index.ts
+++ b/sdk/src/animation/index.ts
@@ -91,6 +91,7 @@ export {
animClipSheetCols,
animClipSheetRows,
animClipCellRect,
+ animClipCellUv,
ANIM_CLIP_FORMAT_VERSION,
type AnimClipAssetData,
type AnimClipFrameData,
diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.ts
index 793ae923a..461547e52 100644
--- a/sdk/src/core-content.ts
+++ b/sdk/src/core-content.ts
@@ -269,6 +269,7 @@ export {
animClipSheetCols,
animClipSheetRows,
animClipCellRect,
+ animClipCellUv,
ANIM_CLIP_FORMAT_VERSION,
type AnimClipAssetData,
type AnimClipFrameData,