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(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.tsindex 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: numberreturn 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-banddiff --git a/desktop/src/flipbook/createAnimatedSprite.ts b/desktop/src/flipbook/createAnimatedSprite.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsxindex 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.tsxindex 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/entitySoimport { 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.mdindex 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): numberdiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 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): numberdiff --git a/sdk/src/animation/AnimClipLoader.ts b/sdk/src/animation/AnimClipLoader.tsindex 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.tsindex 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.tsindex 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,