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): selected flipbooks loop in the viewport without entering Play
esengine44825c0534bc
diff --git a/desktop/src/App.tsx b/desktop/src/App.tsxindex 1ee9e7970..049f0c431 100644--- a/desktop/src/App.tsx+++ b/desktop/src/App.tsx@@ -28,6 +28,7 @@ import { useSelection } from '@/store/selectionStore';import { PlayRealms } from '@/engine/PlayRealm';import { PlayInspect } from '@/engine/PlayInspect';import { TimelinePreview } from '@/engine/TimelinePreview';+import { FlipbookViewportPreview } from '@/engine/FlipbookViewportPreview';import { TimelineRecorder } from '@/timeline/TimelineRecorder';import { ProjectStore } from '@/project/ProjectStore';import { EditorHistory } from '@/engine/EditorHistory';@@ -103,10 +104,11 @@ export function App() {return () => { unsubMode(); unsubEngine(); };}, []);- // Wire the Sequencer's edit-mode live preview (timeline document → World) and- // record-mode auto-key once.+ // Wire the edit-mode live previews (timeline document → World, selected+ // flipbook → World) and record-mode auto-key once.useEffect(() => {TimelinePreview.attach();+ FlipbookViewportPreview.attach();TimelineRecorder.attach();}, []);diff --git a/desktop/src/engine/FlipbookViewportPreview.ts b/desktop/src/engine/FlipbookViewportPreview.tsnew file mode 100644index 000000000..0f0872d31--- /dev/null+++ b/desktop/src/engine/FlipbookViewportPreview.ts@@ -0,0 +1,183 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file FlipbookViewportPreview.ts+ * @brief Edit-mode viewport preview of the selected entity's sprite flipbook —+ * the clip→World projection mirroring TimelinePreview (sample, write,+ * base-pose capture/restore), for SpriteAnimator.+ *+ * When the selection carries a SpriteAnimator whose .esanim resolves, a rAF+ * clock samples the frame sequence and writes the frame's UV window onto the+ * Sprite — so the flipbook loops in the viewport without entering Play. If the+ * clip is open in the Flipbook editor, the document's live asset is sampled+ * instead of the file, so frame edits animate as you make them.+ *+ * Only sheet-cell frames preview (writing uvOffset/uvScale on the existing+ * sheet texture); legacy per-texture clips would need live handle resolution+ * and keep their panel-only preview. Restores the captured Sprite on deselect,+ * play-mode entry, or the Preview FX flag going off. The scene saves from the+ * MODEL, never the World, so these transient writes cannot leak into the file.+ */++import {+ getComponent, parseAnimClipAsset, animClipCellUv,+ type AnimClipAssetData, type AnimClipFrameData,+} from 'esengine';+import { AnimClipDocument } from '@/flipbook/AnimClipDocument';+import { useSelection } from '@/store/selectionStore';+import { useEditorStore } from '@/store/editorStore';+import { ProjectStore } from '@/project/ProjectStore';+import { EngineHost } from './EngineHost';+import { SceneModel } from './SceneModel';++const clone = <T>(v: T): T =>+ typeof structuredClone === 'function' ? structuredClone(v) : (JSON.parse(JSON.stringify(v)) as T);++/** The frame under a running clock, honoring per-frame durations and loop. */+export function flipbookFrameAt(asset: AnimClipAssetData, t: number): AnimClipFrameData | null {+ const frames = asset.frames;+ if (frames.length === 0) return null;+ const fps = asset.fps ?? 12;+ const dur = (f: AnimClipFrameData) => (f.duration !== undefined && f.duration > 0 ? f.duration : 1 / fps);+ let total = 0;+ for (const f of frames) total += dur(f);+ if (total <= 0) return frames[0];+ let tt = (asset.loop ?? true) ? t % total : Math.min(t, total);+ for (const f of frames) {+ tt -= dur(f);+ if (tt < 0) return f;+ }+ return frames[frames.length - 1];+}++interface Binding {+ entity: number;+ clipPath: string;+}++export class FlipbookViewportPreviewImpl {+ private attached = false;+ private bound: Binding | null = null;+ private asset: AnimClipAssetData | null = null;+ private baseSprite: unknown = null;+ private clock = 0;+ private lastTs: number | null = null;+ private raf = 0;+ private loadSeq = 0;++ /** Begin reacting to selection / play mode / the open flipbook document. Idempotent. */+ attach(): void {+ if (this.attached) return;+ this.attached = true;+ useSelection.subscribe(() => this.sync());+ useEditorStore.subscribe(() => this.sync());+ AnimClipDocument.subscribe(() => this.onDocumentChange());+ this.sync();+ }++ /** The (entity, clip) the preview should be driving right now, or null. */+ private desiredBinding(): Binding | null {+ const st = useEditorStore.getState();+ if (st.isPlaying || !st.previewFx) return null;+ const sourceId = useSelection.getState().selectedId;+ if (sourceId == null) return null;+ const world = EngineHost.mutableWorld();+ if (!world) return null;+ const rt = SceneModel.runtimeFor(sourceId);+ if (rt == null || !world.valid(rt)) return null;+ const SpriteAnimator = getComponent('SpriteAnimator');+ const Sprite = getComponent('Sprite');+ if (!SpriteAnimator || !Sprite) return null;+ if (!world.has(rt, SpriteAnimator) || !world.has(rt, Sprite)) return null;+ const clip = (world.get(rt, SpriteAnimator) as { clip?: string } | undefined)?.clip;+ if (!clip) return null;+ const path = ProjectStore.assetInfo(clip)?.path;+ return path ? { entity: rt as number, clipPath: path } : null;+ }++ private sync(): void {+ const want = this.desiredBinding();+ if (want?.entity === this.bound?.entity && want?.clipPath === this.bound?.clipPath) return;+ this.unbind();+ if (!want) return;+ this.bound = want;+ this.captureBase();+ void this.loadAsset(want.clipPath);+ }++ /** Live-follow the Flipbook editor when it has this very clip open. */+ private onDocumentChange(): void {+ if (!this.bound) return;+ if (AnimClipDocument.isOpen && AnimClipDocument.filePath === this.bound.clipPath) {+ this.asset = AnimClipDocument.asset;+ this.clock = 0;+ }+ }++ private async loadAsset(path: string): Promise<void> {+ if (AnimClipDocument.isOpen && AnimClipDocument.filePath === path) {+ this.asset = AnimClipDocument.asset;+ } else {+ const seq = ++this.loadSeq;+ try {+ const parsed = parseAnimClipAsset(JSON.parse(await window.estella.fs.read(path)));+ if (seq !== this.loadSeq || this.bound?.clipPath !== path) return;+ this.asset = parsed;+ } catch {+ return; // unreadable clip: no preview+ }+ }+ this.clock = 0;+ this.lastTs = null;+ this.startLoop();+ }++ private captureBase(): void {+ const world = EngineHost.mutableWorld();+ const Sprite = getComponent('Sprite');+ if (!world || !Sprite || !this.bound) return;+ this.baseSprite = clone(world.get(this.bound.entity, Sprite));+ }++ private unbind(): void {+ cancelAnimationFrame(this.raf);+ this.raf = 0;+ const world = EngineHost.mutableWorld();+ const Sprite = getComponent('Sprite');+ if (world && Sprite && this.bound && this.baseSprite != null+ && world.valid(this.bound.entity) && world.has(this.bound.entity, Sprite)) {+ world.set(this.bound.entity, Sprite, clone(this.baseSprite));+ }+ this.bound = null;+ this.asset = null;+ this.baseSprite = null;+ }++ private startLoop(): void {+ cancelAnimationFrame(this.raf);+ const tick = (ts: number) => {+ if (!this.bound || !this.asset) return;+ if (this.lastTs != null) this.clock += (ts - this.lastTs) / 1000;+ this.lastTs = ts;+ this.applyFrame();+ this.raf = requestAnimationFrame(tick);+ };+ this.raf = requestAnimationFrame(tick);+ }++ private applyFrame(): void {+ const world = EngineHost.mutableWorld();+ const Sprite = getComponent('Sprite');+ if (!world || !Sprite || !this.bound || !this.asset) return;+ const sheet = this.asset.sheet;+ const frame = flipbookFrameAt(this.asset, this.clock);+ if (!sheet || !frame || frame.cell === undefined) return;+ if (!world.valid(this.bound.entity) || !world.has(this.bound.entity, Sprite)) return;+ const uv = animClipCellUv(sheet, frame.cell);+ const sprite = world.get(this.bound.entity, Sprite) as { uvOffset: unknown; uvScale: unknown };+ world.set(this.bound.entity, Sprite, { ...sprite, uvOffset: uv.uvOffset, uvScale: uv.uvScale });+ }+}++/** The app's default-session flipbook viewport preview. */+export const FlipbookViewportPreview = new FlipbookViewportPreviewImpl();diff --git a/desktop/tests/flipbook-frame-at.test.ts b/desktop/tests/flipbook-frame-at.test.tsnew file mode 100644index 000000000..e0695debe--- /dev/null+++ b/desktop/tests/flipbook-frame-at.test.ts@@ -0,0 +1,35 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { describe, it, expect } from 'vitest';+import type { AnimClipAssetData } from 'esengine';+import { flipbookFrameAt } from '@/engine/FlipbookViewportPreview';++function clip(frames: AnimClipAssetData['frames'], fps = 10, loop = true): AnimClipAssetData {+ return { version: '1.2', type: 'animation-clip', fps, loop, frames };+}++describe('flipbookFrameAt', () => {+ it('walks fps-default frames (0.1s each at 10fps)', () => {+ const c = clip([{ cell: 0 }, { cell: 1 }, { cell: 2 }]);+ expect(flipbookFrameAt(c, 0)!.cell).toBe(0);+ expect(flipbookFrameAt(c, 0.15)!.cell).toBe(1);+ expect(flipbookFrameAt(c, 0.25)!.cell).toBe(2);+ });++ it('honors per-frame durations', () => {+ const c = clip([{ cell: 0, duration: 0.5 }, { cell: 1 }]);+ expect(flipbookFrameAt(c, 0.4)!.cell).toBe(0);+ expect(flipbookFrameAt(c, 0.55)!.cell).toBe(1);+ });++ it('loops when loop is on and clamps to the last frame when off', () => {+ const looping = clip([{ cell: 0 }, { cell: 1 }]);+ expect(flipbookFrameAt(looping, 0.25)!.cell).toBe(0); // wrapped past 0.2 total+ const once = clip([{ cell: 0 }, { cell: 1 }], 10, false);+ expect(flipbookFrameAt(once, 5)!.cell).toBe(1);+ });++ it('returns null for an empty clip', () => {+ expect(flipbookFrameAt(clip([]), 0)).toBeNull();+ });+});