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): a frame draws at its own size, so one clip can hold different pictures
esenginec9262bcc8beb
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.jsonindex 13bb698fd..7ce216cf3 100644--- a/docs/astro/src/data/apiStability.generated.json+++ b/docs/astro/src/data/apiStability.generated.json@@ -3,10 +3,10 @@"counts": {"public": 113,"beta": 91,- "experimental": 1673,+ "experimental": 1678,"deprecated": 3},- "total": 1877,+ "total": 1882,"subsystems": [{"id": "ecs",diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 49ef20b12..7b0a5fcc5 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: 113 public · 84 beta · 1509 experimental · 3 deprecated+Symbols: 113 public · 84 beta · 1514 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -15,7 +15,7 @@ readonly AnchorAxis[]## ANIM_CLIP_FORMAT_VERSION — const @experimental```-"1.4"+"1.5"```## ASSET_GROUP_MODES — const @experimental@@ -315,6 +315,7 @@ v: AnchorAxis```events: AnimClipEventData[] | undefinedfps: number | undefined+frameSizing: AnimClipSizing | undefinedframes: AnimClipFrameData[]loop: boolean | undefinedpivot: AnimClipPivotData | undefined@@ -335,7 +336,9 @@ name: stringatlasFrame: { x: number; y: number; width: number; height: number; pageWidth: number; pageHeight: number; } | undefinedcell: number | undefinedduration: number | undefined+offset: AnimClipVec2 | undefinedpivot: AnimClipPivotData | undefined+size: AnimClipVec2 | undefinedtexture: string | undefined```@@ -356,6 +359,17 @@ spacing: numbertexture: string```+## AnimClipSizing — type @experimental+```+'entity' | 'frame'+```++## AnimClipVec2 — interface @experimental+```+x: number+y: number+```+## AnimFramesTrack — interface @experimental```childPath: string@@ -7510,6 +7524,7 @@ name: string```duration: number | undefinedpivot: { x: number; y: number; } | undefined+size: { x: number; y: number; } | undefinedtexture: numberuvOffset: { x: number; y: number; } | undefineduvScale: { x: number; y: number; } | undefined@@ -9653,9 +9668,19 @@ AiRegistry<AiContext>(data: AnimClipAssetData): boolean```+## animClipDrivesSize — function @experimental+```+(data: AnimClipAssetData): boolean+```+## animClipFramePivot — function @experimental```-(data: AnimClipAssetData, frame: AnimClipFrameData): AnimClipPivotData | null+(data: AnimClipAssetData, frame: AnimClipFrameData, size?: AnimClipVec2 | null): AnimClipPivotData | null+```++## animClipFrameSize — function @experimental+```+(data: AnimClipAssetData, frame: AnimClipFrameData, natural?: AnimClipVec2 | null): AnimClipVec2 | null```## animClipSheetCols — function @experimental@@ -10083,6 +10108,11 @@ Plugin(texture: string, cellWidth: number, cellHeight: number, pageWidth: number, pageHeight: number): AnimClipAssetData```+## createAnimClipFromTextures — function @experimental+```+(textures: string[]): AnimClipAssetData+```+## createBtRunState — function @experimental```(): BtRunState@@ -11355,7 +11385,7 @@ NavPlugin## parseAnimClipData — function @experimental```-(clipPath: string, data: AnimClipAssetData, textureHandles: Map<string, number>): SpriteAnimClip+(clipPath: string, data: AnimClipAssetData, textureHandles: Map<string, number>, textureSizes?: Map<string, AnimClipVec2>): SpriteAnimClip```## parseAnimationClip — function @experimentaldiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 48e6e87c3..28b5da880 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.native<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 113 public · 89 beta · 1528 experimental · 3 deprecated+Symbols: 113 public · 89 beta · 1533 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -15,7 +15,7 @@ readonly AnchorAxis[]## ANIM_CLIP_FORMAT_VERSION — const @experimental```-"1.4"+"1.5"```## ASSET_GROUP_MODES — const @experimental@@ -315,6 +315,7 @@ v: AnchorAxis```events: AnimClipEventData[] | undefinedfps: number | undefined+frameSizing: AnimClipSizing | undefinedframes: AnimClipFrameData[]loop: boolean | undefinedpivot: AnimClipPivotData | undefined@@ -335,7 +336,9 @@ name: stringatlasFrame: { x: number; y: number; width: number; height: number; pageWidth: number; pageHeight: number; } | undefinedcell: number | undefinedduration: number | undefined+offset: AnimClipVec2 | undefinedpivot: AnimClipPivotData | undefined+size: AnimClipVec2 | undefinedtexture: string | undefined```@@ -356,6 +359,17 @@ spacing: numbertexture: string```+## AnimClipSizing — type @experimental+```+'entity' | 'frame'+```++## AnimClipVec2 — interface @experimental+```+x: number+y: number+```+## AnimFramesTrack — interface @experimental```childPath: string@@ -7703,6 +7717,7 @@ name: string```duration: number | undefinedpivot: { x: number; y: number; } | undefined+size: { x: number; y: number; } | undefinedtexture: numberuvOffset: { x: number; y: number; } | undefineduvScale: { x: number; y: number; } | undefined@@ -9846,9 +9861,19 @@ AiRegistry<AiContext>(data: AnimClipAssetData): boolean```+## animClipDrivesSize — function @experimental+```+(data: AnimClipAssetData): boolean+```+## animClipFramePivot — function @experimental```-(data: AnimClipAssetData, frame: AnimClipFrameData): AnimClipPivotData | null+(data: AnimClipAssetData, frame: AnimClipFrameData, size?: AnimClipVec2 | null): AnimClipPivotData | null+```++## animClipFrameSize — function @experimental+```+(data: AnimClipAssetData, frame: AnimClipFrameData, natural?: AnimClipVec2 | null): AnimClipVec2 | null```## animClipSheetCols — function @experimental@@ -10291,6 +10316,11 @@ Plugin(texture: string, cellWidth: number, cellHeight: number, pageWidth: number, pageHeight: number): AnimClipAssetData```+## createAnimClipFromTextures — function @experimental+```+(textures: string[]): AnimClipAssetData+```+## createBtRunState — function @experimental```(): BtRunState@@ -11598,7 +11628,7 @@ NavPlugin## parseAnimClipData — function @experimental```-(clipPath: string, data: AnimClipAssetData, textureHandles: Map<string, number>): SpriteAnimClip+(clipPath: string, data: AnimClipAssetData, textureHandles: Map<string, number>, textureSizes?: Map<string, AnimClipVec2>): SpriteAnimClip```## parseAnimationClip — function @experimentaldiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 37c85f0d1..5d134b20b 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: 113 public · 86 beta · 1508 experimental · 3 deprecated+Symbols: 113 public · 86 beta · 1513 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -10,7 +10,7 @@ readonly AnchorAxis[]## ANIM_CLIP_FORMAT_VERSION — const @experimental```-"1.4"+"1.5"```## ASSET_GROUP_MODES — const @experimental@@ -310,6 +310,7 @@ v: AnchorAxis```events: AnimClipEventData[] | undefinedfps: number | undefined+frameSizing: AnimClipSizing | undefinedframes: AnimClipFrameData[]loop: boolean | undefinedpivot: AnimClipPivotData | undefined@@ -330,7 +331,9 @@ name: stringatlasFrame: { x: number; y: number; width: number; height: number; pageWidth: number; pageHeight: number; } | undefinedcell: number | undefinedduration: number | undefined+offset: AnimClipVec2 | undefinedpivot: AnimClipPivotData | undefined+size: AnimClipVec2 | undefinedtexture: string | undefined```@@ -351,6 +354,17 @@ spacing: numbertexture: string```+## AnimClipSizing — type @experimental+```+'entity' | 'frame'+```++## AnimClipVec2 — interface @experimental+```+x: number+y: number+```+## AnimFramesTrack — interface @experimental```childPath: string@@ -7505,6 +7519,7 @@ name: string```duration: number | undefinedpivot: { x: number; y: number; } | undefined+size: { x: number; y: number; } | undefinedtexture: numberuvOffset: { x: number; y: number; } | undefineduvScale: { x: number; y: number; } | undefined@@ -9648,9 +9663,19 @@ AiRegistry<AiContext>(data: AnimClipAssetData): boolean```+## animClipDrivesSize — function @experimental+```+(data: AnimClipAssetData): boolean+```+## animClipFramePivot — function @experimental```-(data: AnimClipAssetData, frame: AnimClipFrameData): AnimClipPivotData | null+(data: AnimClipAssetData, frame: AnimClipFrameData, size?: AnimClipVec2 | null): AnimClipPivotData | null+```++## animClipFrameSize — function @experimental+```+(data: AnimClipAssetData, frame: AnimClipFrameData, natural?: AnimClipVec2 | null): AnimClipVec2 | null```## animClipSheetCols — function @experimental@@ -10078,6 +10103,11 @@ Plugin(texture: string, cellWidth: number, cellHeight: number, pageWidth: number, pageHeight: number): AnimClipAssetData```+## createAnimClipFromTextures — function @experimental+```+(textures: string[]): AnimClipAssetData+```+## createBtRunState — function @experimental```(): BtRunState@@ -11360,7 +11390,7 @@ NodePlatformAdapter## parseAnimClipData — function @experimental```-(clipPath: string, data: AnimClipAssetData, textureHandles: Map<string, number>): SpriteAnimClip+(clipPath: string, data: AnimClipAssetData, textureHandles: Map<string, number>, textureSizes?: Map<string, AnimClipVec2>): SpriteAnimClip```## parseAnimationClip — function @experimentaldiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex fb88f8568..b5b06570e 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -1,7 +1,7 @@# API surface — esengine/minigame<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 113 public · 84 beta · 1530 experimental · 3 deprecated+Symbols: 113 public · 84 beta · 1535 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -10,7 +10,7 @@ readonly AnchorAxis[]## ANIM_CLIP_FORMAT_VERSION — const @experimental```-"1.4"+"1.5"```## ASSET_GROUP_MODES — const @experimental@@ -310,6 +310,7 @@ v: AnchorAxis```events: AnimClipEventData[] | undefinedfps: number | undefined+frameSizing: AnimClipSizing | undefinedframes: AnimClipFrameData[]loop: boolean | undefinedpivot: AnimClipPivotData | undefined@@ -330,7 +331,9 @@ name: stringatlasFrame: { x: number; y: number; width: number; height: number; pageWidth: number; pageHeight: number; } | undefinedcell: number | undefinedduration: number | undefined+offset: AnimClipVec2 | undefinedpivot: AnimClipPivotData | undefined+size: AnimClipVec2 | undefinedtexture: string | undefined```@@ -351,6 +354,17 @@ spacing: numbertexture: string```+## AnimClipSizing — type @experimental+```+'entity' | 'frame'+```++## AnimClipVec2 — interface @experimental+```+x: number+y: number+```+## AnimFramesTrack — interface @experimental```childPath: string@@ -7751,6 +7765,7 @@ name: string```duration: number | undefinedpivot: { x: number; y: number; } | undefined+size: { x: number; y: number; } | undefinedtexture: numberuvOffset: { x: number; y: number; } | undefineduvScale: { x: number; y: number; } | undefined@@ -9900,9 +9915,19 @@ AiRegistry<AiContext>(data: AnimClipAssetData): boolean```+## animClipDrivesSize — function @experimental+```+(data: AnimClipAssetData): boolean+```+## animClipFramePivot — function @experimental```-(data: AnimClipAssetData, frame: AnimClipFrameData): AnimClipPivotData | null+(data: AnimClipAssetData, frame: AnimClipFrameData, size?: AnimClipVec2 | null): AnimClipPivotData | null+```++## animClipFrameSize — function @experimental+```+(data: AnimClipAssetData, frame: AnimClipFrameData, natural?: AnimClipVec2 | null): AnimClipVec2 | null```## animClipSheetCols — function @experimental@@ -10330,6 +10355,11 @@ Plugin(texture: string, cellWidth: number, cellHeight: number, pageWidth: number, pageHeight: number): AnimClipAssetData```+## createAnimClipFromTextures — function @experimental+```+(textures: string[]): AnimClipAssetData+```+## createBtRunState — function @experimental```(): BtRunState@@ -11617,7 +11647,7 @@ NavPlugin## parseAnimClipData — function @experimental```-(clipPath: string, data: AnimClipAssetData, textureHandles: Map<string, number>): SpriteAnimClip+(clipPath: string, data: AnimClipAssetData, textureHandles: Map<string, number>, textureSizes?: Map<string, AnimClipVec2>): SpriteAnimClip```## parseAnimationClip — function @experimentaldiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 9ada6b076..e0afd3b2e 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: 113 public · 84 beta · 1520 experimental · 3 deprecated+Symbols: 113 public · 84 beta · 1525 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -10,7 +10,7 @@ readonly AnchorAxis[]## ANIM_CLIP_FORMAT_VERSION — const @experimental```-"1.4"+"1.5"```## ASSET_GROUP_MODES — const @experimental@@ -310,6 +310,7 @@ v: AnchorAxis```events: AnimClipEventData[] | undefinedfps: number | undefined+frameSizing: AnimClipSizing | undefinedframes: AnimClipFrameData[]loop: boolean | undefinedpivot: AnimClipPivotData | undefined@@ -330,7 +331,9 @@ name: stringatlasFrame: { x: number; y: number; width: number; height: number; pageWidth: number; pageHeight: number; } | undefinedcell: number | undefinedduration: number | undefined+offset: AnimClipVec2 | undefinedpivot: AnimClipPivotData | undefined+size: AnimClipVec2 | undefinedtexture: string | undefined```@@ -351,6 +354,17 @@ spacing: numbertexture: string```+## AnimClipSizing — type @experimental+```+'entity' | 'frame'+```++## AnimClipVec2 — interface @experimental+```+x: number+y: number+```+## AnimFramesTrack — interface @experimental```childPath: string@@ -7512,6 +7526,7 @@ name: string```duration: number | undefinedpivot: { x: number; y: number; } | undefined+size: { x: number; y: number; } | undefinedtexture: numberuvOffset: { x: number; y: number; } | undefineduvScale: { x: number; y: number; } | undefined@@ -9676,9 +9691,19 @@ AiRegistry<AiContext>(data: AnimClipAssetData): boolean```+## animClipDrivesSize — function @experimental+```+(data: AnimClipAssetData): boolean+```+## animClipFramePivot — function @experimental```-(data: AnimClipAssetData, frame: AnimClipFrameData): AnimClipPivotData | null+(data: AnimClipAssetData, frame: AnimClipFrameData, size?: AnimClipVec2 | null): AnimClipPivotData | null+```++## animClipFrameSize — function @experimental+```+(data: AnimClipAssetData, frame: AnimClipFrameData, natural?: AnimClipVec2 | null): AnimClipVec2 | null```## animClipSheetCols — function @experimental@@ -10106,6 +10131,11 @@ Plugin(texture: string, cellWidth: number, cellHeight: number, pageWidth: number, pageHeight: number): AnimClipAssetData```+## createAnimClipFromTextures — function @experimental+```+(textures: string[]): AnimClipAssetData+```+## createBtRunState — function @experimental```(): BtRunState@@ -11383,7 +11413,7 @@ NavPlugin## parseAnimClipData — function @experimental```-(clipPath: string, data: AnimClipAssetData, textureHandles: Map<string, number>): SpriteAnimClip+(clipPath: string, data: AnimClipAssetData, textureHandles: Map<string, number>, textureSizes?: Map<string, AnimClipVec2>): SpriteAnimClip```## parseAnimationClip — function @experimentaldiff --git a/sdk/src/animation/AnimClipLoader.ts b/sdk/src/animation/AnimClipLoader.tsindex 7adc491c7..96fd28988 100644--- a/sdk/src/animation/AnimClipLoader.ts+++ b/sdk/src/animation/AnimClipLoader.ts@@ -13,7 +13,7 @@ import { log } from '../util/logger';// .esanim File Format// =============================================================================-export const ANIM_CLIP_FORMAT_VERSION = '1.4';+export const ANIM_CLIP_FORMAT_VERSION = '1.5';/*** A frame's anchor, normalized inside the frame's own rect — EXACTLY the space@@ -30,6 +30,21 @@ export interface AnimClipPivotData {/** The anchor a clip that authors pivots falls back to — the `Sprite.pivot` default. */export const DEFAULT_ANIM_CLIP_PIVOT: AnimClipPivotData = { x: 0.5, y: 0.5 };+/** A pair in the clip's own units — world units, which the engine authors at 1 = 1+ * design pixel. Frame sizes and offsets are both in it. */+export interface AnimClipVec2 {+ x: number;+ y: number;+}++/**+ * Who owns `Sprite.size` while the clip plays. `'entity'` — the default, and what+ * every clip written before format 1.5 does — leaves the entity's size alone, so+ * every frame draws at that one size. `'frame'` hands size to the clip and each+ * frame draws at its own, which is what lets frames of DIFFERENT sizes share a clip.+ */+export type AnimClipSizing = 'entity' | 'frame';+/*** Sprite-sheet slicing grid. When present, frames may reference grid cells* instead of per-frame textures; all cell frames share `texture`.@@ -58,6 +73,18 @@ export interface AnimClipFrameData {* inside the cell from frame to frame.*/pivot?: AnimClipPivotData;+ /**+ * What this frame draws at. Absent = its own natural size (its sheet cell, or+ * its texture's pixels), which is what an author almost always means.+ */+ size?: AnimClipVec2;+ /**+ * Shifts this frame's artwork away from the clip's anchor, in {@link size}'s+ * units, and folded into the frame's pivot at load. Units rather than a+ * normalized pivot because the same offset is the same visual shift on frames+ * of any size — a pivot is not.+ */+ offset?: AnimClipVec2;atlasFrame?: {x: number;y: number;@@ -91,6 +118,8 @@ export interface AnimClipAssetData {* exactly as the entity authored it.*/pivot?: AnimClipPivotData;+ /** Who owns `Sprite.size` — see {@link AnimClipSizing}. Absent = `'entity'`. */+ frameSizing?: AnimClipSizing;sheet?: AnimClipSheetData;frames: AnimClipFrameData[];events?: AnimClipEventData[];@@ -149,7 +178,7 @@ export function animClipCellUv(}// =============================================================================-// Frame anchors+// Frame geometry — size and anchor// =============================================================================/**@@ -157,9 +186,38 @@ export function animClipCellUv(* frame declares one. All-or-nothing on purpose: a clip that anchored only some* frames would leave the last override standing on the plain ones — the same* staleness the UV window has to reset away.+ *+ * An offset counts: it IS an anchor, written in units instead of fractions.*/export function animClipDrivesPivot(data: AnimClipAssetData): boolean {- return data.pivot !== undefined || data.frames.some(f => f.pivot !== undefined);+ return data.pivot !== undefined+ || data.frames.some(f => f.pivot !== undefined || f.offset !== undefined);+}++/**+ * Does this clip own `Sprite.size`? The mode says so outright, an authored frame+ * size says so by existing — and so does an offset, which needs the size it is a+ * fraction of. Left to the entity, one clip on two entities would shift by two+ * different amounts, the very drift offsets exist to remove.+ */+export function animClipDrivesSize(data: AnimClipAssetData): boolean {+ return data.frameSizing === 'frame'+ || data.frames.some(f => f.size !== undefined || f.offset !== undefined);+}++/**+ * The size a frame renders at: its own override, else its natural size (the+ * caller's — a sheet cell, or the texture's pixels) — or `null` when the clip+ * does not own size, which leaves `Sprite.size` as the entity authored it.+ */+export function animClipFrameSize(+ data: AnimClipAssetData,+ frame: AnimClipFrameData,+ natural?: AnimClipVec2 | null,+): AnimClipVec2 | null {+ if (frame.size) return { x: frame.size.x, y: frame.size.y };+ if (!animClipDrivesSize(data)) return null;+ return natural ? { x: natural.x, y: natural.y } : null;}/**@@ -173,11 +231,17 @@ export function animClipDrivesPivot(data: AnimClipAssetData): boolean {export function animClipFramePivot(data: AnimClipAssetData,frame: AnimClipFrameData,+ size?: AnimClipVec2 | null,): AnimClipPivotData | null {- if (frame.pivot) return { x: frame.pivot.x, y: frame.pivot.y };- if (!animClipDrivesPivot(data)) return null;- const p = data.pivot ?? DEFAULT_ANIM_CLIP_PIVOT;- return { x: p.x, y: p.y };+ const base = frame.pivot+ ?? (animClipDrivesPivot(data) ? (data.pivot ?? DEFAULT_ANIM_CLIP_PIVOT) : null);+ if (!frame.offset) return base ? { x: base.x, y: base.y } : null;+ // Moving the artwork one way is the anchor moving the other. With no size to+ // divide by the shift is dropped rather than guessed; animClipDrivesSize is+ // what keeps that from happening on a clip that authors offsets.+ if (!size || size.x <= 0 || size.y <= 0) return base ? { x: base.x, y: base.y } : null;+ const b = base ?? DEFAULT_ANIM_CLIP_PIVOT;+ return { x: b.x - frame.offset.x / size.x, y: b.y - frame.offset.y / size.y };}// =============================================================================@@ -203,6 +267,16 @@ function pivotOf(v: unknown): AnimClipPivotData | undefined {return { x: p.x, y: p.y };}+/** A `{x,y}` in clip units, or undefined. `positive` rejects a zero/negative size,+ * which would divide an offset by nothing and blank the sprite. */+function vec2Of(v: unknown, positive: boolean): AnimClipVec2 | undefined {+ const p = v as { x?: unknown; y?: unknown } | null | undefined;+ if (!p || typeof p.x !== 'number' || typeof p.y !== 'number') return undefined;+ if (!Number.isFinite(p.x) || !Number.isFinite(p.y)) return undefined;+ if (positive && (p.x <= 0 || p.y <= 0)) return undefined;+ return { x: p.x, y: p.y };+}+/** Parse arbitrary JSON into a normalized {@link AnimClipAssetData} (tolerant of missing fields). */export function parseAnimClipAsset(rawJson: unknown): AnimClipAssetData {const raw = rawJson as Record<string, any> | null | undefined;@@ -224,16 +298,22 @@ export function parseAnimClipAsset(rawJson: unknown): AnimClipAssetData {if (!f) continue;const duration = typeof f.duration === 'number' && f.duration > 0 ? f.duration : undefined;const framePivot = pivotOf(f.pivot);+ const frameSize = vec2Of(f.size, true);+ const frameOffset = vec2Of(f.offset, false);if (sheet && typeof f.cell === 'number' && Number.isInteger(f.cell) && f.cell >= 0) {frames.push({cell: f.cell,...(duration !== undefined ? { duration } : {}),...(framePivot ? { pivot: framePivot } : {}),+ ...(frameSize ? { size: frameSize } : {}),+ ...(frameOffset ? { offset: frameOffset } : {}),});} else if (typeof f.texture === 'string' && f.texture) {const frame: AnimClipFrameData = { texture: f.texture };if (duration !== undefined) frame.duration = duration;if (framePivot) frame.pivot = framePivot;+ if (frameSize) frame.size = frameSize;+ if (frameOffset) frame.offset = frameOffset;const af = f.atlasFrame;if (af && [af.x, af.y, af.width, af.height, af.pageWidth, af.pageHeight].every((n: unknown) => typeof n === 'number' && Number.isFinite(n))) {@@ -253,12 +333,15 @@ export function parseAnimClipAsset(rawJson: unknown): AnimClipAssetData {}}const clipPivot = pivotOf(raw?.pivot);+ const sizing: AnimClipSizing | undefined = raw?.frameSizing === 'frame' ? 'frame'+ : raw?.frameSizing === 'entity' ? 'entity' : undefined;return {version: typeof raw?.version === 'string' ? raw.version : ANIM_CLIP_FORMAT_VERSION,type: 'animation-clip',fps: posInt(raw?.fps, DEFAULT_FPS),loop: typeof raw?.loop === 'boolean' ? raw.loop : true,...(clipPivot ? { pivot: clipPivot } : {}),+ ...(sizing ? { frameSizing: sizing } : {}),...(sheet ? { sheet } : {}),frames,...(events.length ? { events } : {}),@@ -278,8 +361,14 @@ export function serializeAnimClip(asset: AnimClipAssetData): Record<string, unknfps: asset.fps ?? DEFAULT_FPS,loop: asset.loop ?? true,...(asset.pivot ? { pivot: { ...asset.pivot } } : {}),+ ...(asset.frameSizing ? { frameSizing: asset.frameSizing } : {}),...(asset.sheet ? { sheet: { ...asset.sheet } } : {}),- frames: asset.frames.map(f => ({ ...f, ...(f.pivot ? { pivot: { ...f.pivot } } : {}) })),+ frames: asset.frames.map(f => ({+ ...f,+ ...(f.pivot ? { pivot: { ...f.pivot } } : {}),+ ...(f.size ? { size: { ...f.size } } : {}),+ ...(f.offset ? { offset: { ...f.offset } } : {}),+ })),...(asset.events && asset.events.length ? { events: asset.events.map(e => ({ ...e })) } : {}),};}@@ -302,6 +391,22 @@ export function createAnimClip(};}+/**+ * A fresh clip over a sequence of per-frame textures — the shape a flipbook of+ * separate images is. Owns size from the start: images drawn at one shared size+ * is the thing an image sequence is authored to avoid.+ */+export function createAnimClipFromTextures(textures: string[]): AnimClipAssetData {+ return {+ version: ANIM_CLIP_FORMAT_VERSION,+ type: 'animation-clip',+ fps: DEFAULT_FPS,+ loop: true,+ frameSizing: 'frame',+ frames: textures.filter(t => !!t).map(texture => ({ texture })),+ };+}+// =============================================================================// Runtime clip resolution// =============================================================================@@ -336,22 +441,36 @@ function uvFromRect(};}+/**+ * Bake a parsed clip into what the runtime plays. @p textureSizes carries each+ * frame texture's pixel size, which is the natural size of a per-texture frame —+ * without it a clip that owns size has nothing to fall back to and says so.+ */export function parseAnimClipData(clipPath: string,data: AnimClipAssetData,textureHandles: Map<string, number>,+ textureSizes?: Map<string, AnimClipVec2>,): SpriteAnimClip {const sheet = data.sheet;const cellCount = sheet ? animClipSheetCols(sheet) * animClipSheetRows(sheet) : 0;- return {+ const drivesSize = animClipDrivesSize(data);+ let missingNatural = 0;+ const clip: SpriteAnimClip = {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 => {- // Resolved once at load: at runtime a frame either carries the anchor it- // renders with, or the clip authors none and playback leaves pivot alone.- const pivot = animClipFramePivot(data, f);+ // Resolved once at load: at runtime a frame either carries the size and+ // anchor it renders with, or the clip authors none and playback leaves+ // the entity's own standing.+ const natural = sheet && f.cell !== undefined+ ? { x: sheet.cellWidth, y: sheet.cellHeight }+ : textureSizes?.get(f.texture ?? '');+ const size = animClipFrameSize(data, f, natural);+ if (drivesSize && !size) missingNatural++;+ const pivot = animClipFramePivot(data, f, size);if (sheet && f.cell !== undefined) {if (f.cell >= cellCount) {log.warn('asset', `${clipPath}: frame cell ${f.cell} outside the ${cellCount}-cell sheet grid; clamped`);@@ -360,6 +479,7 @@ export function parseAnimClipData(texture: textureHandles.get(sheet.texture) ?? 0,duration: f.duration,...(pivot ? { pivot } : {}),+ ...(size ? { size } : {}),...animClipCellUv(sheet, f.cell),};return frame;@@ -368,6 +488,7 @@ export function parseAnimClipData(texture: textureHandles.get(f.texture ?? '') ?? 0,duration: f.duration,...(pivot ? { pivot } : {}),+ ...(size ? { size } : {}),};if (f.atlasFrame) {const af = f.atlasFrame;@@ -376,4 +497,8 @@ export function parseAnimClipData(return frame;}),};+ if (missingNatural > 0) {+ log.warn('asset', `${clipPath}: ${missingNatural} frame(s) own their size but no natural size was available; they draw at the entity's`);+ }+ return clip;}diff --git a/sdk/src/animation/SpriteAnimator.ts b/sdk/src/animation/SpriteAnimator.tsindex e570c2f4d..344a67a04 100644--- a/sdk/src/animation/SpriteAnimator.ts+++ b/sdk/src/animation/SpriteAnimator.ts@@ -27,6 +27,13 @@ export interface SpriteAnimFrame {* touching a pivot the entity owns.*/pivot?: { x: number; y: number };+ /**+ * The size this frame renders at, in world units — resolved at load time from+ * the clip's sizing mode and the frame's natural size. Absent on EVERY frame of+ * a clip that does not own size, which is what keeps playback from resizing a+ * sprite the entity sized itself.+ */+ size?: { x: number; y: number };}export interface SpriteAnimEvent {@@ -236,9 +243,12 @@ export class SpriteAnimationAPI {sprite.uvOffset = { x: 0, y: 0 };sprite.uvScale = { x: 1, y: 1 };}- // No reset branch: the loader gives EVERY frame of an anchor-authoring- // clip a pivot, so absent here means the clip authors none at all and- // the entity's own pivot stands.+ // No reset branch on either: the loader gives EVERY frame of an+ // owning clip both, so absent here means the clip owns neither and+ // what the entity authored stands.+ if (frame.size) {+ sprite.size = { x: frame.size.x, y: frame.size.y };+ }if (frame.pivot) {sprite.pivot = { x: frame.pivot.x, y: frame.pivot.y };}diff --git a/sdk/src/animation/index.ts b/sdk/src/animation/index.tsindex 0e1ce9f1b..08f2c17e6 100644--- a/sdk/src/animation/index.ts+++ b/sdk/src/animation/index.ts@@ -110,13 +110,16 @@ export {parseAnimClipAsset,serializeAnimClip,createAnimClip,+ createAnimClipFromTextures,extractAnimClipTexturePaths,animClipSheetCols,animClipSheetRows,animClipCellRect,animClipCellUv,animClipDrivesPivot,+ animClipDrivesSize,animClipFramePivot,+ animClipFrameSize,ANIM_CLIP_FORMAT_VERSION,DEFAULT_ANIM_CLIP_PIVOT,type AnimClipAssetData,@@ -124,4 +127,6 @@ export {type AnimClipSheetData,type AnimClipEventData,type AnimClipPivotData,+ type AnimClipVec2,+ type AnimClipSizing,} from './AnimClipLoader';diff --git a/sdk/src/asset/loaders/AnimClipAssetLoader.ts b/sdk/src/asset/loaders/AnimClipAssetLoader.tsindex 5105372c5..8be4e9be7 100644--- a/sdk/src/asset/loaders/AnimClipAssetLoader.ts+++ b/sdk/src/asset/loaders/AnimClipAssetLoader.ts@@ -23,18 +23,24 @@ export class AnimClipAssetLoader implements AssetLoader<AnimClipResult> {const text = await ctx.loadText(ctx.catalog.getBuildPath(path));const data = parseAnimClipAsset(JSON.parse(text));const textureHandles = new Map<string, number>();+ // Pixel size travels with the handle: it is the natural size of a+ // per-texture frame, and the only place it is free to know.+ const textureSizes = new Map<string, { x: number; y: number }>();for (const texPath of extractAnimClipTexturePaths(data)) {try {const lease = await ctx.acquireTexture(texPath, true);textureHandles.set(texPath, lease.value.handle);+ if (lease.value.width > 0 && lease.value.height > 0) {+ textureSizes.set(texPath, { x: lease.value.width, y: lease.value.height });+ }} catch (e) {log.warn('asset', `Failed to load texture: ${texPath}`, e);textureHandles.set(texPath, 0);}}return {- published: parseAnimClipData(path, data, textureHandles),+ published: parseAnimClipData(path, data, textureHandles, textureSizes),value: { clipId: path },};},diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.tsindex 1c4b10875..25f719c03 100644--- a/sdk/src/core-content.ts+++ b/sdk/src/core-content.ts@@ -409,13 +409,16 @@ export {parseAnimClipAsset,serializeAnimClip,createAnimClip,+ createAnimClipFromTextures,extractAnimClipTexturePaths,animClipSheetCols,animClipSheetRows,animClipCellRect,animClipCellUv,animClipDrivesPivot,+ animClipDrivesSize,animClipFramePivot,+ animClipFrameSize,ANIM_CLIP_FORMAT_VERSION,DEFAULT_ANIM_CLIP_PIVOT,type AnimClipAssetData,@@ -423,6 +426,8 @@ export {type AnimClipSheetData,type AnimClipEventData,type AnimClipPivotData,+ type AnimClipVec2,+ type AnimClipSizing,TweenGroup,TweenSequence,type Completable,diff --git a/sdk/tests/anim-clip-asset.test.ts b/sdk/tests/anim-clip-asset.test.tsindex fa6e47dfd..b55e1d7ea 100644--- a/sdk/tests/anim-clip-asset.test.ts+++ b/sdk/tests/anim-clip-asset.test.ts@@ -16,7 +16,10 @@ import {animClipSheetRows,animClipCellRect,animClipDrivesPivot,+ animClipDrivesSize,animClipFramePivot,+ animClipFrameSize,+ createAnimClipFromTextures,ANIM_CLIP_FORMAT_VERSION,DEFAULT_ANIM_CLIP_PIVOT,type AnimClipAssetData,@@ -424,4 +427,130 @@ describe('parseAnimClipAsset (tolerant parse)', () => {margin: 0, spacing: 0, pageWidth: 1, pageHeight: 1,});});++ // =========================================================================+ // Frame size + offset (format 1.5)+ // =========================================================================++ it('round-trips per-frame size, offset and the sizing mode', () => {+ const parsed = parseAnimClipAsset({+ version: '1.5', frameSizing: 'frame',+ frames: [+ { texture: 'a.png', size: { x: 96, y: 64 }, offset: { x: 12, y: -5 } },+ { texture: 'b.png' },+ ],+ });+ expect(parsed.frameSizing).toBe('frame');+ expect(parsed.frames[0].size).toEqual({ x: 96, y: 64 });+ expect(parsed.frames[0].offset).toEqual({ x: 12, y: -5 });+ expect(parsed.frames[1].size).toBeUndefined();++ const round = parseAnimClipAsset(serializeAnimClip(parsed));+ expect(round.frameSizing).toBe('frame');+ expect(round.frames[0].size).toEqual({ x: 96, y: 64 });+ expect(round.frames[0].offset).toEqual({ x: 12, y: -5 });+ });++ it('carries size and offset on sheet-cell frames too', () => {+ const parsed = parseAnimClipAsset({+ sheet: { texture: 't.png', cellWidth: 32, cellHeight: 32, pageWidth: 64, pageHeight: 64 },+ frames: [{ cell: 1, size: { x: 48, y: 24 }, offset: { x: 4, y: 2 } }],+ });+ expect(parsed.frames[0].size).toEqual({ x: 48, y: 24 });+ expect(parsed.frames[0].offset).toEqual({ x: 4, y: 2 });+ });++ it('rejects a non-positive size but keeps a negative offset', () => {+ // A zero size would divide an offset by nothing; a negative offset is just+ // a shift the other way.+ const parsed = parseAnimClipAsset({+ frames: [+ { texture: 'a.png', size: { x: 0, y: 10 } },+ { texture: 'b.png', size: { x: -8, y: 10 } },+ { texture: 'c.png', offset: { x: -12, y: -5 } },+ { texture: 'd.png', offset: { x: NaN, y: 0 } },+ ],+ });+ expect(parsed.frames[0].size).toBeUndefined();+ expect(parsed.frames[1].size).toBeUndefined();+ expect(parsed.frames[2].offset).toEqual({ x: -12, y: -5 });+ expect(parsed.frames[3].offset).toBeUndefined();+ });++ it('does not own size for a clip written before 1.5', () => {+ const parsed = parseAnimClipAsset({ version: '1.4', frames: [{ texture: 'a.png' }] });+ expect(animClipDrivesSize(parsed)).toBe(false);+ expect(animClipFrameSize(parsed, parsed.frames[0], { x: 96, y: 64 })).toBeNull();+ });++ it('owns size as soon as ANY frame authors a size or an offset', () => {+ const sized = parseAnimClipAsset({ frames: [{ texture: 'a.png', size: { x: 8, y: 8 } }, { texture: 'b.png' }] });+ expect(animClipDrivesSize(sized)).toBe(true);+ // The plain frame follows: an offset needs a size to be a fraction of, and a+ // clip that sized only some frames would leave the last one standing.+ expect(animClipFrameSize(sized, sized.frames[1], { x: 96, y: 64 })).toEqual({ x: 96, y: 64 });++ const shifted = parseAnimClipAsset({ frames: [{ texture: 'a.png', offset: { x: 3, y: 0 } }] });+ expect(animClipDrivesSize(shifted)).toBe(true);+ expect(animClipDrivesPivot(shifted)).toBe(true);+ });++ it('prefers an authored size over the natural one', () => {+ const parsed = parseAnimClipAsset({+ frameSizing: 'frame',+ frames: [{ texture: 'a.png', size: { x: 20, y: 10 } }],+ });+ expect(animClipFrameSize(parsed, parsed.frames[0], { x: 96, y: 64 })).toEqual({ x: 20, y: 10 });+ });++ it('folds an offset into the anchor, in the frame’s own size', () => {+ const parsed = parseAnimClipAsset({+ frameSizing: 'frame',+ pivot: { x: 0.5, y: 0 },+ frames: [{ texture: 'a.png', offset: { x: 12, y: -5 } }],+ });+ const size = animClipFrameSize(parsed, parsed.frames[0], { x: 96, y: 64 })!;+ expect(animClipFramePivot(parsed, parsed.frames[0], size)).toEqual({+ x: 0.5 - 12 / 96,+ y: 0 - -5 / 64,+ });+ });++ it('drops an offset it has no size to divide by, rather than guessing', () => {+ const parsed = parseAnimClipAsset({+ frames: [{ texture: 'a.png', pivot: { x: 0.25, y: 0.75 }, offset: { x: 12, y: -5 } }],+ });+ expect(animClipFramePivot(parsed, parsed.frames[0], null)).toEqual({ x: 0.25, y: 0.75 });+ });++ it('bakes each frame size into the runtime clip from the texture sizes', () => {+ const parsed = parseAnimClipAsset({+ frameSizing: 'frame',+ frames: [{ texture: 'a.png' }, { texture: 'b.png' }],+ });+ const clip = parseAnimClipData('seq.esanim', parsed,+ new Map([['a.png', 1], ['b.png', 2]]),+ new Map([['a.png', { x: 96, y: 64 }], ['b.png', { x: 48, y: 80 }]]));+ expect(clip.frames[0].size).toEqual({ x: 96, y: 64 });+ expect(clip.frames[1].size).toEqual({ x: 48, y: 80 });+ });++ it('bakes a sheet cell frame at the cell size', () => {+ const parsed = parseAnimClipAsset({+ frameSizing: 'frame',+ sheet: { texture: 't.png', cellWidth: 32, cellHeight: 24, pageWidth: 64, pageHeight: 48 },+ frames: [{ cell: 0 }],+ });+ const clip = parseAnimClipData('sheet.esanim', parsed, new Map([['t.png', 7]]));+ expect(clip.frames[0].size).toEqual({ x: 32, y: 24 });+ });++ it('creates an image-sequence clip that owns size', () => {+ const clip = createAnimClipFromTextures(['a.png', 'b.png']);+ expect(clip.version).toBe(ANIM_CLIP_FORMAT_VERSION);+ expect(clip.frameSizing).toBe('frame');+ expect(clip.frames).toEqual([{ texture: 'a.png' }, { texture: 'b.png' }]);+ expect(clip.sheet).toBeUndefined();+ expect(animClipDrivesSize(clip)).toBe(true);+ });});diff --git a/sdk/tests/sprite-animator.test.ts b/sdk/tests/sprite-animator.test.tsindex 39ceec0db..ea233048b 100644--- a/sdk/tests/sprite-animator.test.ts+++ b/sdk/tests/sprite-animator.test.ts@@ -358,20 +358,6 @@ describe('SpriteAnimator', () => {expect((world.get(entity, Sprite) as SpriteData).pivot).toEqual({ x: 0.5, y: 0 });});- it('copies the anchor instead of aliasing the clip frame', () => {- const frame = { texture: 1, pivot: { x: 0.5, y: 0 } };- anim.registerClip({ name: 'shared', fps: 10, loop: true, frames: [frame] });- const entity = world.spawn();- world.insert(entity, Sprite, { texture: 0 });- world.insert(entity, SpriteAnimator, { clip: 'shared' });-- anim.update(world, 0.001);- const sprite = world.get(entity, Sprite) as SpriteData;- sprite.pivot.x = 0.9;-- expect(frame.pivot.x).toBe(0.5);- });-it('carries an anchor from .esanim TEXT all the way onto the Sprite', () => {// The whole production path in one go: file text → tolerant parse → runtime// bake → animator apply, which is what a shipped clip actually travels.@@ -406,4 +392,86 @@ describe('SpriteAnimator', () => {expect(sprite.pivot).toEqual({ x: 0.25, y: 0.75 }); // frame override});});++ // =========================================================================+ // Per-frame size and offset+ // =========================================================================++ describe('per-frame size', () => {+ it('draws each frame at its own texture size', () => {+ const data = parseAnimClipAsset({+ version: '1.5', type: 'animation-clip', fps: 10, loop: true,+ frameSizing: 'frame',+ frames: [{ texture: 'wide.png' }, { texture: 'tall.png' }],+ });+ anim.registerClip(parseAnimClipData('seq.esanim', data,+ new Map([['wide.png', 11], ['tall.png', 22]]),+ new Map([['wide.png', { x: 96, y: 64 }], ['tall.png', { x: 48, y: 80 }]])));++ const entity = world.spawn();+ world.insert(entity, Sprite, { texture: 0, size: { x: 100, y: 100 } });+ world.insert(entity, SpriteAnimator, { clip: 'seq.esanim' });++ anim.update(world, 0.001);+ expect((world.get(entity, Sprite) as SpriteData).size).toEqual({ x: 96, y: 64 });++ anim.update(world, 0.1);+ expect((world.get(entity, Sprite) as SpriteData).size).toEqual({ x: 48, y: 80 });+ });++ it('leaves the entity size alone for a clip that does not own size', () => {+ const data = parseAnimClipAsset({+ version: '1.4', type: 'animation-clip', fps: 10, loop: true,+ frames: [{ texture: 'a.png' }, { texture: 'b.png' }],+ });+ anim.registerClip(parseAnimClipData('plain.esanim', data,+ new Map([['a.png', 11], ['b.png', 22]]),+ new Map([['a.png', { x: 96, y: 64 }], ['b.png', { x: 48, y: 80 }]])));++ const entity = world.spawn();+ world.insert(entity, Sprite, { texture: 0, size: { x: 100, y: 100 } });+ world.insert(entity, SpriteAnimator, { clip: 'plain.esanim' });++ anim.update(world, 0.001);+ anim.update(world, 0.1);++ expect((world.get(entity, Sprite) as SpriteData).size).toEqual({ x: 100, y: 100 });+ });++ it('shifts differently-sized frames by the SAME world distance', () => {+ // The reason offsets exist. A normalized pivot cannot do this: the same+ // fraction on a 96-wide and a 48-wide frame are different shifts.+ const data = parseAnimClipAsset({+ version: '1.5', type: 'animation-clip', fps: 10, loop: true,+ frames: [+ { texture: 'big.png', offset: { x: 12, y: -5 } },+ { texture: 'small.png', offset: { x: 12, y: -5 } },+ ],+ });+ anim.registerClip(parseAnimClipData('shift.esanim', data,+ new Map([['big.png', 11], ['small.png', 22]]),+ new Map([['big.png', { x: 96, y: 64 }], ['small.png', { x: 48, y: 32 }]])));++ const entity = world.spawn();+ world.insert(entity, Sprite, { texture: 0 });+ world.insert(entity, SpriteAnimator, { clip: 'shift.esanim' });++ // How far the artwork sits from the anchor, in world units: the centre of+ // the frame is (0.5 - pivot) of its size away from it.+ const shiftOf = (s: SpriteData) => ({+ x: (0.5 - s.pivot.x) * s.size.x,+ y: (0.5 - s.pivot.y) * s.size.y,+ });++ anim.update(world, 0.001);+ const big = shiftOf(world.get(entity, Sprite) as SpriteData);+ expect(big.x).toBeCloseTo(12, 10);+ expect(big.y).toBeCloseTo(-5, 10);++ anim.update(world, 0.1);+ const small = shiftOf(world.get(entity, Sprite) as SpriteData);+ expect(small.x).toBeCloseTo(12, 10);+ expect(small.y).toBeCloseTo(-5, 10);+ });+ });});