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): author frame events in the Flipbook editor

esengined35a8a461f74
diff --git a/desktop/src/flipbook/AnimClipCommands.ts b/desktop/src/flipbook/AnimClipCommands.ts
index cbc4afe4a..be09d65c5 100644
--- a/desktop/src/flipbook/AnimClipCommands.ts
+++ b/desktop/src/flipbook/AnimClipCommands.ts
@@ -91,6 +91,37 @@ export const AnimClipCommands = {
});
},
+ /** Add a frame event at @p frame (kept sorted by frame). */
+ addEvent(frame: number, name: string): void {
+ AnimClipDocument.edit('Add Event', (a) => {
+ if (!a.events) a.events = [];
+ a.events.push({ frame: Math.max(0, Math.floor(frame)), name });
+ a.events.sort((x, y) => x.frame - y.frame);
+ });
+ },
+
+ removeEvent(index: number): void {
+ AnimClipDocument.edit('Remove Event', (a) => {
+ if (a.events && index >= 0 && index < a.events.length) a.events.splice(index, 1);
+ });
+ },
+
+ setEventFrame(index: number, frame: number): void {
+ AnimClipDocument.edit('Move Event', (a) => {
+ const e = a.events?.[index];
+ if (!e) return;
+ e.frame = Math.max(0, Math.floor(frame));
+ a.events!.sort((x, y) => x.frame - y.frame);
+ });
+ },
+
+ setEventName(index: number, name: string): void {
+ AnimClipDocument.edit('Rename Event', (a) => {
+ const e = a.events?.[index];
+ if (e && name) e.name = name;
+ });
+ },
+
/** Persist the open flipbook to its file. */
async save(): Promise<void> {
const asset = AnimClipDocument.asset;
diff --git a/desktop/src/i18n/messages/flipbook.ts b/desktop/src/i18n/messages/flipbook.ts
index aa79c7f99..1a77b27e9 100644
--- a/desktop/src/i18n/messages/flipbook.ts
+++ b/desktop/src/i18n/messages/flipbook.ts
@@ -32,6 +32,12 @@ export const flipbookMessages = defineMessages({
'fb.field.loopMode': { en: 'Loop Mode', zh: '循环模式' },
'fb.loopMode.once': { en: "Don't loop", zh: '不循环' },
'fb.loopMode.loop': { en: 'Loop', zh: '循环' },
+ 'fb.events': { en: 'Events', zh: '动画事件' },
+ 'fb.addEvent': { en: 'Add event', zh: '添加事件' },
+ 'fb.event.default': { en: 'event', zh: '事件' },
+ 'fb.event.onFrame': { en: 'Fires on this frame', zh: '在此帧触发' },
+ 'fb.event.remove': { en: 'Remove event', zh: '移除事件' },
+ 'fb.events.empty': { en: 'No events — add one at the current frame', zh: '暂无事件——在当前帧添加一个' },
'fb.onion': { en: 'Onion skin', zh: '洋葱皮' },
'fb.onionFrames': { en: 'Frames', zh: '帧数' },
'fb.onionTip': { en: 'Ghost the nearest frames behind the current one (while paused)', zh: '暂停时在当前帧后叠印相邻帧,便于对位' },
diff --git a/desktop/src/panels/FlipbookEditor.tsx b/desktop/src/panels/FlipbookEditor.tsx
index d2bc63dd8..fbb1cc9c5 100644
--- a/desktop/src/panels/FlipbookEditor.tsx
+++ b/desktop/src/panels/FlipbookEditor.tsx
@@ -13,7 +13,7 @@ import {
useEffect, useRef, useState, useSyncExternalStore,
type CSSProperties, type DragEvent,
} from 'react';
-import { Trash2, X } from 'lucide-react';
+import { Plus, Trash2, X } from 'lucide-react';
import {
animClipSheetCols, animClipSheetRows,
type AnimClipFrameData, type AnimClipSheetData,
@@ -252,6 +252,7 @@ export function FlipbookEditor() {
}}
title={invalid ? t('fb.frame.invalidTip', { cell: f.cell ?? 0 }) : undefined}
>
+ {asset.events?.some((e) => e.frame === i) && <span className="fb-frame__evt" title={t('fb.event.onFrame')} />}
<span
className="fb-thumb fb-frame__thumb" style={thumbFor(f)}
title={t('fb.frame.scrubTip')}
@@ -295,6 +296,46 @@ export function FlipbookEditor() {
)}
</div>
+ {asset.frames.length > 0 && (
+ <div className="fb-events">
+ <span className="fb-events__head">
+ <span>{t('fb.events')}</span>
+ <button
+ type="button"
+ className="fb-events__add"
+ title={t('fb.addEvent')}
+ onClick={() => AnimClipCommands.addEvent(curFrame, t('fb.event.default'))}
+ >
+ <Plus size={12} /> {t('fb.addEvent')}
+ </button>
+ </span>
+ {(asset.events ?? []).map((ev, i) => (
+ <span key={i} className="fb-event">
+ <button
+ type="button"
+ className="fb-event__frame"
+ title={t('fb.event.onFrame')}
+ onClick={() => { setPlaying(false); setFrameIdx(Math.min(ev.frame, asset.frames.length - 1)); }}
+ >
+ {ev.frame}
+ </button>
+ <input
+ key={`${i}-${ev.name}`}
+ className="fb-event__name"
+ defaultValue={ev.name}
+ spellCheck={false}
+ onBlur={(e) => AnimClipCommands.setEventName(i, e.target.value.trim())}
+ onKeyDown={(e) => { if (e.key === 'Enter') (e.target as HTMLInputElement).blur(); }}
+ />
+ <button type="button" className="fb-event__x" title={t('fb.event.remove')} onClick={() => AnimClipCommands.removeEvent(i)}>
+ <X size={10} strokeWidth={2.2} />
+ </button>
+ </span>
+ ))}
+ {(asset.events?.length ?? 0) === 0 && <span className="fb-hint">{t('fb.events.empty')}</span>}
+ </div>
+ )}
+
{sheet && (
<div className="fb-canvas" onPointerUp={commitStroke} onPointerLeave={commitStroke}>
{!texUrl ? (
diff --git a/desktop/src/theme/flipbook.css b/desktop/src/theme/flipbook.css
index 81880bfd3..7e425f689 100644
--- a/desktop/src/theme/flipbook.css
+++ b/desktop/src/theme/flipbook.css
@@ -91,6 +91,91 @@
}
.fb-frame.is-current { border-color: var(--acc-hi); }
.fb-frame__thumb { cursor: pointer; }
+.fb-frame { position: relative; }
+.fb-frame__evt {
+ position: absolute;
+ top: 2px;
+ right: 2px;
+ width: 6px;
+ height: 6px;
+ border-radius: 50%;
+ background: var(--acc-hi);
+ box-shadow: 0 0 0 1px var(--srf-2);
+ z-index: 1;
+}
+
+/* Animation events bar: chips of {frame → name}, one per frame event. */
+.fb-events {
+ display: flex;
+ align-items: center;
+ gap: 6px;
+ flex-wrap: wrap;
+ padding: 6px 10px;
+ border-bottom: 1px solid var(--line);
+ background: var(--srf-2);
+ flex: 0 0 auto;
+ min-height: 32px;
+}
+.fb-events__head { display: inline-flex; align-items: center; gap: 8px; color: var(--text-dim); font-size: var(--fs-xs); }
+.fb-events__add {
+ display: inline-flex;
+ align-items: center;
+ gap: 3px;
+ height: 22px;
+ padding: 0 7px;
+ border: 1px solid var(--line);
+ border-radius: var(--r-sm);
+ background: var(--srf-3);
+ color: var(--text-dim);
+ cursor: pointer;
+ font-size: var(--fs-xs);
+}
+.fb-events__add:hover { background: var(--raised); color: var(--text); }
+.fb-event {
+ display: inline-flex;
+ align-items: center;
+ gap: 4px;
+ background: var(--srf-3);
+ border: 1px solid var(--line);
+ border-radius: var(--r-sm);
+ padding: 2px 4px 2px 2px;
+}
+.fb-event__frame {
+ min-width: 20px;
+ height: 18px;
+ padding: 0 5px;
+ border: 0;
+ border-radius: var(--r-xs);
+ background: var(--srf-4);
+ color: var(--acc-hi);
+ font-family: var(--mono);
+ font-size: var(--fs-xs);
+ cursor: pointer;
+}
+.fb-event__frame:hover { background: var(--srf-5); }
+.fb-event__name {
+ width: 92px;
+ height: 18px;
+ background: var(--inset);
+ border: 1px solid var(--line);
+ border-radius: var(--r-xs);
+ color: var(--text);
+ font-size: var(--fs-xs);
+ padding: 0 4px;
+}
+.fb-event__x {
+ display: inline-flex;
+ align-items: center;
+ justify-content: center;
+ width: 16px;
+ height: 16px;
+ border: 0;
+ border-radius: var(--r-xs);
+ background: transparent;
+ color: var(--text-faint);
+ cursor: pointer;
+}
+.fb-event__x:hover { color: var(--error-hi); background: var(--srf-4); }
/* Transport-driven preview stage: a checkerboard view with the current frame
(onion-skin ghosts behind it) over a control bar (shared <Transport> + onion). */
diff --git a/examples/sprite-animation/assets/animations/coin.esanim b/examples/sprite-animation/assets/animations/coin.esanim
index 47626c611..05f0069af 100644
--- a/examples/sprite-animation/assets/animations/coin.esanim
+++ b/examples/sprite-animation/assets/animations/coin.esanim
@@ -1,5 +1,5 @@
{
- "version": "1.2",
+ "version": "1.3",
"type": "animation-clip",
"fps": 12,
"loop": true,
@@ -37,5 +37,10 @@
{
"cell": 7
}
+ ],
+ "events": [
+ { "frame": 0, "name": "flip" },
+ { "frame": 3, "name": "edge" },
+ { "frame": 6, "name": "chime" }
]
}