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: enhance timeline with interpolation presets, marker/event tracks, and grid snap

esengine3b577aa27fbf
diff --git a/editor/src/panels/timeline/TimelineAddTrackWizard.ts b/editor/src/panels/timeline/TimelineAddTrackWizard.ts
index f6056789a..176af174b 100644
--- a/editor/src/panels/timeline/TimelineAddTrackWizard.ts
+++ b/editor/src/panels/timeline/TimelineAddTrackWizard.ts
@@ -36,6 +36,8 @@ const TRACK_TYPE_OPTIONS: { type: TrackType; label: string; icon: (s: number) =>
{ type: 'spriteAnim', label: 'Sprite Anim', icon: icons.film, needsEntity: true, componentFilter: 'SpriteAnimator' },
{ type: 'audio', label: 'Audio', icon: icons.volume, needsEntity: false },
{ type: 'activation', label: 'Activation', icon: icons.eye, needsEntity: true },
+ { type: 'marker', label: 'Marker', icon: icons.tag, needsEntity: false },
+ { type: 'customEvent', label: 'Custom Event', icon: icons.zap, needsEntity: false },
];
const SKIP_COMPONENTS = new Set(['Name', 'Parent', 'Children', 'UIInteraction']);
@@ -126,7 +128,7 @@ export class TimelineAddTrackWizard {
this.selectedType_ = opt.type;
if (!opt.needsEntity) {
- this.complete(this.buildAudioTrack());
+ this.complete(this.buildSimpleTrack(opt.type));
return;
}
@@ -289,12 +291,17 @@ export class TimelineAddTrackWizard {
};
}
- private buildAudioTrack(): TimelineTrackData {
- return {
- type: 'audio',
- name: 'Audio Events',
- events: [],
- };
+ private buildSimpleTrack(type: TrackType): TimelineTrackData {
+ switch (type) {
+ case 'audio':
+ return { type: 'audio', name: 'Audio Events', events: [] };
+ case 'marker':
+ return { type: 'marker', name: 'Markers', markers: [] };
+ case 'customEvent':
+ return { type: 'customEvent', name: 'Custom Events', customEvents: [] };
+ default:
+ return { type, name: type };
+ }
}
private buildTrack(): TimelineTrackData {
diff --git a/editor/src/panels/timeline/TimelineCommands.ts b/editor/src/panels/timeline/TimelineCommands.ts
index 77974b761..9d698a817 100644
--- a/editor/src/panels/timeline/TimelineCommands.ts
+++ b/editor/src/panels/timeline/TimelineCommands.ts
@@ -9,6 +9,7 @@ interface KeyframeData {
value: number;
inTangent?: number;
outTangent?: number;
+ interpolation?: string;
}
interface ChannelData {
@@ -463,6 +464,49 @@ export class RenameTrackCommand extends BaseCommand {
}
}
+export class ChangeInterpolationCommand extends BaseCommand {
+ readonly type = 'timeline_change_interpolation';
+ readonly description = 'Change interpolation';
+
+ constructor(
+ private data_: TimelineAssetData,
+ private trackIndex_: number,
+ private channelIndex_: number,
+ private keyframeIndex_: number,
+ private oldInterp_: string | undefined,
+ private newInterp_: string,
+ private oldInTangent_: number,
+ private oldOutTangent_: number,
+ private newInTangent_: number,
+ private newOutTangent_: number,
+ private onChanged_: () => void,
+ ) {
+ super();
+ }
+
+ execute(): void {
+ const channel = getPropertyChannel(this.data_, this.trackIndex_, this.channelIndex_);
+ if (!channel) return;
+ const kf = channel.keyframes[this.keyframeIndex_];
+ if (!kf) return;
+ kf.interpolation = this.newInterp_;
+ kf.inTangent = this.newInTangent_;
+ kf.outTangent = this.newOutTangent_;
+ this.onChanged_();
+ }
+
+ undo(): void {
+ const channel = getPropertyChannel(this.data_, this.trackIndex_, this.channelIndex_);
+ if (!channel) return;
+ const kf = channel.keyframes[this.keyframeIndex_];
+ if (!kf) return;
+ kf.interpolation = this.oldInterp_;
+ kf.inTangent = this.oldInTangent_;
+ kf.outTangent = this.oldOutTangent_;
+ this.onChanged_();
+ }
+}
+
export class PasteKeyframesCommand extends BaseCommand {
readonly type = 'timeline_paste_keyframes';
readonly description = 'Paste keyframes';
diff --git a/editor/src/panels/timeline/TimelineCurveEditor.ts b/editor/src/panels/timeline/TimelineCurveEditor.ts
index bbcd7b1be..d7cf1de33 100644
--- a/editor/src/panels/timeline/TimelineCurveEditor.ts
+++ b/editor/src/panels/timeline/TimelineCurveEditor.ts
@@ -1,6 +1,6 @@
import type { TimelineState } from './TimelineState';
import type { TimelineAssetData, TimelinePanelHost } from './TimelineKeyframeArea';
-import { ChangeTangentCommand } from './TimelineCommands';
+import { ChangeTangentCommand, ChangeInterpolationCommand } from './TimelineCommands';
const CURVE_BG = '#1a1a1a';
const CURVE_GRID = '#2a2a2a';
@@ -11,8 +11,6 @@ const PADDING = 20;
const KF_RADIUS = 4;
const HANDLE_RADIUS = 3;
const TANGENT_LENGTH_PX = 40;
-const STEP_TANGENT_VALUE = 1e6;
-
const CHANNEL_COLORS = ['#e06c75', '#98c379', '#61afef', '#d19a66', '#c678dd', '#56b6c2'];
interface CurveKeyframe {
@@ -20,6 +18,7 @@ interface CurveKeyframe {
value: number;
inTangent?: number;
outTangent?: number;
+ interpolation?: string;
}
interface TangentHit {
@@ -312,15 +311,35 @@ export class TimelineCurveEditor {
if (dt <= 0) return k0.value;
const t = (time - k0.time) / dt;
- const m0 = (k0.outTangent ?? 0) * dt;
- const m1 = (k1.inTangent ?? 0) * dt;
-
- const t2 = t * t;
- const t3 = t2 * t;
- return (2 * t3 - 3 * t2 + 1) * k0.value
- + (t3 - 2 * t2 + t) * m0
- + (-2 * t3 + 3 * t2) * k1.value
- + (t3 - t2) * m1;
+ const interp = k0.interpolation ?? 'hermite';
+
+ switch (interp) {
+ case 'linear':
+ return k0.value + (k1.value - k0.value) * t;
+ case 'step':
+ return k0.value;
+ case 'easeIn':
+ return k0.value + (k1.value - k0.value) * (t * t);
+ case 'easeOut': {
+ const inv = 1 - t;
+ return k0.value + (k1.value - k0.value) * (1 - inv * inv);
+ }
+ case 'easeInOut': {
+ const e = t < 0.5 ? 2 * t * t : 1 - 2 * (1 - t) * (1 - t);
+ return k0.value + (k1.value - k0.value) * e;
+ }
+ case 'hermite':
+ default: {
+ const m0 = (k0.outTangent ?? 0) * dt;
+ const m1 = (k1.inTangent ?? 0) * dt;
+ const t2 = t * t;
+ const t3 = t2 * t;
+ return (2 * t3 - 3 * t2 + 1) * k0.value
+ + (t3 - 2 * t2 + t) * m0
+ + (-2 * t3 + 3 * t2) * k1.value
+ + (t3 - t2) * m1;
+ }
+ }
}
}
@@ -348,6 +367,9 @@ export class TimelineCurveEditor {
}
private drawTangentHandles(ctx: CanvasRenderingContext2D, kf: CurveKeyframe, x: number, y: number): void {
+ const interp = kf.interpolation ?? 'hermite';
+ if (interp !== 'hermite') return;
+
const inTan = kf.inTangent ?? 0;
const outTan = kf.outTangent ?? 0;
@@ -387,6 +409,8 @@ export class TimelineCurveEditor {
if (this.selectedKfIndex_ < 0 || this.selectedKfIndex_ >= kfs.length) return null;
const kf = kfs[this.selectedKfIndex_];
+ const interp = kf.interpolation ?? 'hermite';
+ if (interp !== 'hermite') return null;
const kx = this.timeToX(kf.time);
const ky = this.valueToY(kf.value);
@@ -492,25 +516,26 @@ export class TimelineCurveEditor {
menu.style.left = `${e.clientX}px`;
menu.style.top = `${e.clientY}px`;
- const linearIn = this.calcLinearTangent(kfs, kfIdx, 'in');
- const linearOut = this.calcLinearTangent(kfs, kfIdx, 'out');
-
- const presets: { label: string; inT: number; outT: number }[] = [
- { label: 'Flat (Smooth)', inT: 0, outT: 0 },
- { label: 'Linear', inT: linearIn, outT: linearOut },
- { label: 'Ease In', inT: 0, outT: 2 },
- { label: 'Ease Out', inT: 2, outT: 0 },
- { label: 'Ease In-Out', inT: linearIn * 0.5, outT: linearOut * 0.5 },
- { label: 'Step (Constant)', inT: 0, outT: STEP_TANGENT_VALUE },
+ const presets: { label: string; interp: string; inT: number; outT: number }[] = [
+ { label: 'Hermite (Smooth)', interp: 'hermite', inT: 0, outT: 0 },
+ { label: 'Linear', interp: 'linear', inT: 0, outT: 0 },
+ { label: 'Step (Constant)', interp: 'step', inT: 0, outT: 0 },
+ { label: 'Ease In', interp: 'easeIn', inT: 0, outT: 0 },
+ { label: 'Ease Out', interp: 'easeOut', inT: 0, outT: 0 },
+ { label: 'Ease In-Out', interp: 'easeInOut', inT: 0, outT: 0 },
];
for (const preset of presets) {
const item = document.createElement('div');
item.className = 'es-timeline-dropdown-item';
+ const current = kf.interpolation ?? 'hermite';
+ if (current === preset.interp) {
+ item.style.fontWeight = 'bold';
+ }
item.textContent = preset.label;
item.addEventListener('click', () => {
menu.remove();
- this.applyTangentPreset(kfIdx, kf, preset.inT, preset.outT);
+ this.applyInterpolationPreset(kfIdx, kf, preset.interp, preset.inT, preset.outT);
});
menu.appendChild(item);
}
@@ -525,52 +550,27 @@ export class TimelineCurveEditor {
setTimeout(() => document.addEventListener('mousedown', dismiss, true), 0);
}
- private applyTangentPreset(kfIdx: number, kf: CurveKeyframe, newIn: number, newOut: number): void {
- const oldIn = kf.inTangent ?? 0;
- const oldOut = kf.outTangent ?? 0;
-
+ private applyInterpolationPreset(
+ kfIdx: number, kf: CurveKeyframe,
+ interp: string, newIn: number, newOut: number,
+ ): void {
if (this.host_ && this.assetData_) {
- if (newIn !== oldIn) {
- const cmdIn = new ChangeTangentCommand(
- this.assetData_, this.trackIndex_, this.channelIndex_,
- kfIdx, 'in', oldIn, newIn,
- () => this.host_!.onAssetDataChanged(),
- );
- this.host_.executeCommand(cmdIn);
- }
- if (newOut !== oldOut) {
- const cmdOut = new ChangeTangentCommand(
- this.assetData_, this.trackIndex_, this.channelIndex_,
- kfIdx, 'out', oldOut, newOut,
- () => this.host_!.onAssetDataChanged(),
- );
- this.host_.executeCommand(cmdOut);
- }
+ const cmd = new ChangeInterpolationCommand(
+ this.assetData_, this.trackIndex_, this.channelIndex_,
+ kfIdx, kf.interpolation, interp,
+ kf.inTangent ?? 0, kf.outTangent ?? 0,
+ newIn, newOut,
+ () => this.host_!.onAssetDataChanged(),
+ );
+ this.host_.executeCommand(cmd);
} else {
+ (kf as any).interpolation = interp;
(kf as any).inTangent = newIn;
(kf as any).outTangent = newOut;
this.draw();
}
}
- private calcLinearTangent(
- kfs: CurveKeyframe[], index: number, direction: 'in' | 'out',
- ): number {
- if (direction === 'in' && index > 0) {
- const prev = kfs[index - 1];
- const curr = kfs[index];
- const dt = curr.time - prev.time;
- return dt > 0 ? (curr.value - prev.value) / dt : 0;
- }
- if (direction === 'out' && index < kfs.length - 1) {
- const curr = kfs[index];
- const next = kfs[index + 1];
- const dt = next.time - curr.time;
- return dt > 0 ? (next.value - curr.value) / dt : 0;
- }
- return 0;
- }
-
private startTangentDrag(_e: MouseEvent, rect: DOMRect, hit: TangentHit): void {
const kfs = this.getKeyframes();
const kf = kfs[hit.keyframeIndex];
diff --git a/editor/src/panels/timeline/TimelineKeyframeArea.ts b/editor/src/panels/timeline/TimelineKeyframeArea.ts
index 805df5017..8842ffe51 100644
--- a/editor/src/panels/timeline/TimelineKeyframeArea.ts
+++ b/editor/src/panels/timeline/TimelineKeyframeArea.ts
@@ -25,6 +25,13 @@ import {
MoveActivationRangeCommand,
ResizeActivationRangeCommand,
DeleteActivationRangeCommand,
+ AddMarkerCommand,
+ MoveMarkerCommand,
+ DeleteMarkerCommand,
+ AddCustomEventCommand,
+ MoveCustomEventCommand,
+ DeleteCustomEventCommand,
+ MoveSpriteAnimStartCommand,
} from './TimelineTrackCommands';
const RULER_BG = '#1e1e1e';
@@ -47,6 +54,10 @@ const EDGE_RESIZE_ZONE = 8;
const FRAME_STEP = 1 / 60;
const RUBBERBAND_COLOR = 'rgba(97, 175, 239, 0.2)';
const RUBBERBAND_BORDER = 'rgba(97, 175, 239, 0.6)';
+const MARKER_COLOR = '#c678dd';
+const CUSTOM_EVENT_COLOR = '#56b6c2';
+const SPRITE_ANIM_COLOR = 'rgba(229, 192, 123, 0.3)';
+const SPRITE_ANIM_BORDER = '#e5c07b';
const DURATION_LINE_COLOR = '#e5c07b';
const BEYOND_DURATION_COLOR = 'rgba(0, 0, 0, 0.2)';
@@ -67,6 +78,20 @@ interface ActivationRangeHit {
zone: 'body' | 'left' | 'right';
}
+interface MarkerHit {
+ trackIndex: number;
+ markerIndex: number;
+}
+
+interface CustomEventHit {
+ trackIndex: number;
+ eventIndex: number;
+}
+
+interface SpriteAnimHit {
+ trackIndex: number;
+}
+
export interface TimelineAssetData {
tracks: TimelineTrackData[];
duration: number;
@@ -77,10 +102,12 @@ export interface TimelineTrackData {
name: string;
childPath?: string;
component?: string;
- channels?: { property: string; keyframes: { time: number; value: number; inTangent?: number; outTangent?: number }[] }[];
+ channels?: { property: string; keyframes: { time: number; value: number; inTangent?: number; outTangent?: number; interpolation?: string }[] }[];
clips?: { start: number; duration: number; animation: string }[];
events?: { time: number; clip: string }[];
ranges?: { start: number; end: number }[];
+ markers?: { time: number; name: string }[];
+ customEvents?: { time: number; name: string; payload: Record<string, unknown> }[];
clip?: string;
startTime?: number;
}
@@ -418,7 +445,7 @@ export class TimelineKeyframeArea {
case 'spriteAnim':
if (assetTrack.startTime != null) {
- this.drawSpriteAnimMarker(ctx, assetTrack.startTime, y);
+ this.drawSpriteAnimClip(ctx, assetTrack.startTime, assetTrack.clip ?? '', y, width);
}
break;
@@ -429,6 +456,59 @@ export class TimelineKeyframeArea {
case 'activation':
this.drawActivationRanges(ctx, assetTrack.ranges ?? [], y, width);
break;
+
+ case 'marker':
+ this.drawMarkers(ctx, assetTrack.markers ?? [], y);
+ break;
+
+ case 'customEvent':
+ this.drawCustomEvents(ctx, assetTrack.customEvents ?? [], y);
+ break;
+ }
+ }
+
+ private drawCustomEvents(
+ ctx: CanvasRenderingContext2D,
+ events: { time: number; name: string }[],
+ y: number,
+ ): void {
+ for (const event of events) {
+ const x = this.state_.timeToX(event.time);
+ ctx.fillStyle = CUSTOM_EVENT_COLOR;
+ ctx.fillRect(x - 1, y + 2, 3, TRACK_HEIGHT - 4);
+
+ ctx.beginPath();
+ ctx.arc(x, y + 6, 4, 0, Math.PI * 2);
+ ctx.fill();
+
+ ctx.fillStyle = '#cccccc';
+ ctx.font = '9px monospace';
+ ctx.textAlign = 'left';
+ ctx.fillText(event.name, x + 6, y + TRACK_HEIGHT / 2 + 3);
+ }
+ }
+
+ private drawMarkers(
+ ctx: CanvasRenderingContext2D,
+ markers: { time: number; name: string }[],
+ y: number,
+ ): void {
+ for (const marker of markers) {
+ const x = this.state_.timeToX(marker.time);
+ ctx.fillStyle = MARKER_COLOR;
+ ctx.fillRect(x - 1, y + 2, 3, TRACK_HEIGHT - 4);
+
+ ctx.beginPath();
+ ctx.moveTo(x - 5, y + 2);
+ ctx.lineTo(x + 5, y + 2);
+ ctx.lineTo(x, y + 8);
+ ctx.closePath();
+ ctx.fill();
+
+ ctx.fillStyle = '#cccccc';
+ ctx.font = '9px monospace';
+ ctx.textAlign = 'left';
+ ctx.fillText(marker.name, x + 6, y + TRACK_HEIGHT / 2 + 3);
}
}
@@ -494,14 +574,43 @@ export class TimelineKeyframeArea {
}
}
- private drawSpriteAnimMarker(
+ private drawSpriteAnimClip(
ctx: CanvasRenderingContext2D,
startTime: number,
+ clipName: string,
y: number,
+ width: number,
): void {
- const x = this.state_.timeToX(startTime);
- ctx.fillStyle = KEYFRAME_COLOR;
- ctx.fillRect(x - 1, y + 2, 3, TRACK_HEIGHT - 4);
+ const x1 = this.state_.timeToX(startTime);
+ const x2 = Math.min(this.state_.timeToX(this.state_.duration), width);
+ const clipY = y + 3;
+ const clipH = TRACK_HEIGHT - 6;
+
+ if (x2 > x1) {
+ ctx.fillStyle = SPRITE_ANIM_COLOR;
+ ctx.fillRect(x1, clipY, x2 - x1, clipH);
+ ctx.strokeStyle = SPRITE_ANIM_BORDER;
+ ctx.lineWidth = 1;
+ ctx.strokeRect(x1 + 0.5, clipY + 0.5, x2 - x1 - 1, clipH - 1);
+ }
+
+ ctx.fillStyle = SPRITE_ANIM_BORDER;
+ ctx.fillRect(x1 - 1, y + 2, 3, TRACK_HEIGHT - 4);
+
+ if (clipName) {
+ ctx.fillStyle = '#cccccc';
+ ctx.font = '10px monospace';
+ ctx.textAlign = 'left';
+ const textX = Math.max(x1 + 6, 6);
+ ctx.save();
+ if (x2 > x1) {
+ ctx.beginPath();
+ ctx.rect(x1, clipY, x2 - x1, clipH);
+ ctx.clip();
+ }
+ ctx.fillText(clipName, textX, clipY + clipH / 2 + 3);
+ ctx.restore();
+ }
}
private drawAudioEvents(
@@ -726,7 +835,47 @@ export class TimelineKeyframeArea {
return null;
}
- private hitTestNonPropertyTrack(x: number, y: number): { type: string; hit: SpineClipHit | AudioEventHit | ActivationRangeHit } | null {
+ private hitTestMarker(x: number, trackIndex: number): MarkerHit | null {
+ if (!this.assetData_) return null;
+ const track = this.assetData_.tracks[trackIndex];
+ if (!track || track.type !== 'marker' || !track.markers) return null;
+
+ for (let i = 0; i < track.markers.length; i++) {
+ const mx = this.state_.timeToX(track.markers[i].time);
+ if (Math.abs(x - mx) <= KEYFRAME_HIT_RADIUS) {
+ return { trackIndex, markerIndex: i };
+ }
+ }
+ return null;
+ }
+
+ private hitTestCustomEvent(x: number, trackIndex: number): CustomEventHit | null {
+ if (!this.assetData_) return null;
+ const track = this.assetData_.tracks[trackIndex];
+ if (!track || track.type !== 'customEvent' || !track.customEvents) return null;
+
+ for (let i = 0; i < track.customEvents.length; i++) {
+ const ex = this.state_.timeToX(track.customEvents[i].time);
+ if (Math.abs(x - ex) <= KEYFRAME_HIT_RADIUS) {
+ return { trackIndex, eventIndex: i };
+ }
+ }
+ return null;
+ }
+
+ private hitTestSpriteAnim(x: number, trackIndex: number): SpriteAnimHit | null {
+ if (!this.assetData_) return null;
+ const track = this.assetData_.tracks[trackIndex];
+ if (!track || track.type !== 'spriteAnim' || track.startTime == null) return null;
+
+ const sx = this.state_.timeToX(track.startTime);
+ if (Math.abs(x - sx) <= KEYFRAME_HIT_RADIUS) {
+ return { trackIndex };
+ }
+ return null;
+ }
+
+ private hitTestNonPropertyTrack(x: number, y: number): { type: string; hit: SpineClipHit | AudioEventHit | ActivationRangeHit | MarkerHit | CustomEventHit | SpriteAnimHit } | null {
if (!this.assetData_) return null;
const tracks = this.state_.tracks;
@@ -746,6 +895,15 @@ export class TimelineKeyframeArea {
} else if (assetTrack.type === 'activation') {
const hit = this.hitTestActivationRange(x, y, track.index, rowY);
if (hit) return { type: 'activation', hit };
+ } else if (assetTrack.type === 'marker') {
+ const hit = this.hitTestMarker(x, track.index);
+ if (hit) return { type: 'marker', hit };
+ } else if (assetTrack.type === 'customEvent') {
+ const hit = this.hitTestCustomEvent(x, track.index);
+ if (hit) return { type: 'customEvent', hit };
+ } else if (assetTrack.type === 'spriteAnim') {
+ const hit = this.hitTestSpriteAnim(x, track.index);
+ if (hit) return { type: 'spriteAnim', hit };
}
}
rowY += TRACK_HEIGHT;
@@ -891,6 +1049,12 @@ export class TimelineKeyframeArea {
this.startAudioEventDrag(e, rect, npHit.hit as AudioEventHit);
} else if (npHit.type === 'activation') {
this.startActivationRangeDrag(e, rect, npHit.hit as ActivationRangeHit);
+ } else if (npHit.type === 'marker') {
+ this.startMarkerDrag(e, rect, npHit.hit as MarkerHit);
+ } else if (npHit.type === 'customEvent') {
+ this.startCustomEventDrag(e, rect, npHit.hit as CustomEventHit);
+ } else if (npHit.type === 'spriteAnim') {
+ this.startSpriteAnimDrag(e, rect, npHit.hit as SpriteAnimHit);
}
return;
}
@@ -920,7 +1084,7 @@ export class TimelineKeyframeArea {
const oldDuration = clip.duration;
const onMove = (ev: MouseEvent) => {
const mx = ev.clientX - rect.left;
- const endTime = Math.max(clip.start + 0.05, this.state_.xToTime(mx));
+ const endTime = Math.max(clip.start + 0.05, this.state_.snapTime(this.state_.xToTime(mx)));
const newDuration = endTime - clip.start;
const cmd = new ResizeSpineClipCommand(
this.assetData_!, hit.trackIndex, hit.clipIndex,
@@ -940,7 +1104,7 @@ export class TimelineKeyframeArea {
const offsetX = _e.clientX - rect.left - this.state_.timeToX(clip.start);
const onMove = (ev: MouseEvent) => {
const mx = ev.clientX - rect.left - offsetX;
- const newStart = Math.max(0, this.state_.xToTime(mx));
+ const newStart = this.state_.snapTime(Math.max(0, this.state_.xToTime(mx)));
const cmd = new MoveSpineClipCommand(
this.assetData_!, hit.trackIndex, hit.clipIndex,
oldStart, newStart,
@@ -967,7 +1131,7 @@ export class TimelineKeyframeArea {
const oldTime = event.time;
const onMove = (ev: MouseEvent) => {
const mx = ev.clientX - rect.left;
- const newTime = Math.max(0, this.state_.xToTime(mx));
+ const newTime = this.state_.snapTime(Math.max(0, this.state_.xToTime(mx)));
const cmd = new MoveAudioEventCommand(
this.assetData_!, hit.trackIndex, hit.eventIndex,
oldTime, newTime,
@@ -996,7 +1160,7 @@ export class TimelineKeyframeArea {
if (hit.zone === 'left') {
const onMove = (ev: MouseEvent) => {
const mx = ev.clientX - rect.left;
- const newStart = Math.max(0, Math.min(this.state_.xToTime(mx), oldEnd - 0.05));
+ const newStart = Math.max(0, Math.min(this.state_.snapTime(this.state_.xToTime(mx)), oldEnd - 0.05));
const cmd = new ResizeActivationRangeCommand(
this.assetData_!, hit.trackIndex, hit.rangeIndex,
oldStart, oldEnd, newStart, oldEnd,
@@ -1013,7 +1177,7 @@ export class TimelineKeyframeArea {
} else if (hit.zone === 'right') {
const onMove = (ev: MouseEvent) => {
const mx = ev.clientX - rect.left;
- const newEnd = Math.max(oldStart + 0.05, this.state_.xToTime(mx));
+ const newEnd = Math.max(oldStart + 0.05, this.state_.snapTime(this.state_.xToTime(mx)));
const cmd = new ResizeActivationRangeCommand(
this.assetData_!, hit.trackIndex, hit.rangeIndex,
oldStart, oldEnd, oldStart, newEnd,
@@ -1032,7 +1196,7 @@ export class TimelineKeyframeArea {
const offsetX = _e.clientX - rect.left - this.state_.timeToX(oldStart);
const onMove = (ev: MouseEvent) => {
const mx = ev.clientX - rect.left - offsetX;
- const newStart = Math.max(0, this.state_.xToTime(mx));
+ const newStart = this.state_.snapTime(Math.max(0, this.state_.xToTime(mx)));
const newEnd = newStart + duration;
const cmd = new MoveActivationRangeCommand(
this.assetData_!, hit.trackIndex, hit.rangeIndex,
@@ -1050,6 +1214,82 @@ export class TimelineKeyframeArea {
}
}
+ private startSpriteAnimDrag(_e: MouseEvent, rect: DOMRect, hit: SpriteAnimHit): void {
+ if (!this.assetData_ || !this.host_) return;
+ const track = this.assetData_.tracks[hit.trackIndex];
+ if (!track || track.startTime == null) return;
+
+ const oldTime = track.startTime;
+ const onMove = (ev: MouseEvent) => {
+ const mx = ev.clientX - rect.left;
+ const newTime = this.state_.snapTime(Math.max(0, this.state_.xToTime(mx)));
+ const cmd = new MoveSpriteAnimStartCommand(
+ this.assetData_!, hit.trackIndex,
+ oldTime, newTime,
+ () => this.host_!.onAssetDataChanged(),
+ );
+ this.host_!.executeCommand(cmd);
+ };
+ const onUp = () => {
+ document.removeEventListener('mousemove', onMove);
+ document.removeEventListener('mouseup', onUp);
+ };
+ document.addEventListener('mousemove', onMove);
+ document.addEventListener('mouseup', onUp);
+ }
+
+ private startCustomEventDrag(_e: MouseEvent, rect: DOMRect, hit: CustomEventHit): void {
+ if (!this.assetData_ || !this.host_) return;
+ const track = this.assetData_.tracks[hit.trackIndex];
+ if (!track?.customEvents) return;
+ const event = track.customEvents[hit.eventIndex];
+ if (!event) return;
+
+ const oldTime = event.time;
+ const onMove = (ev: MouseEvent) => {
+ const mx = ev.clientX - rect.left;
+ const newTime = this.state_.snapTime(Math.max(0, this.state_.xToTime(mx)));
+ const cmd = new MoveCustomEventCommand(
+ this.assetData_!, hit.trackIndex, hit.eventIndex,
+ oldTime, newTime,
+ () => this.host_!.onAssetDataChanged(),
+ );
+ this.host_!.executeCommand(cmd);
+ };
+ const onUp = () => {
+ document.removeEventListener('mousemove', onMove);
+ document.removeEventListener('mouseup', onUp);
+ };
+ document.addEventListener('mousemove', onMove);
+ document.addEventListener('mouseup', onUp);
+ }
+
+ private startMarkerDrag(_e: MouseEvent, rect: DOMRect, hit: MarkerHit): void {
+ if (!this.assetData_ || !this.host_) return;
+ const track = this.assetData_.tracks[hit.trackIndex];
+ if (!track?.markers) return;
+ const marker = track.markers[hit.markerIndex];
+ if (!marker) return;
+
+ const oldTime = marker.time;
+ const onMove = (ev: MouseEvent) => {
+ const mx = ev.clientX - rect.left;
+ const newTime = this.state_.snapTime(Math.max(0, this.state_.xToTime(mx)));
+ const cmd = new MoveMarkerCommand(
+ this.assetData_!, hit.trackIndex, hit.markerIndex,
+ oldTime, newTime,
+ () => this.host_!.onAssetDataChanged(),
+ );
+ this.host_!.executeCommand(cmd);
+ };
+ const onUp = () => {
+ document.removeEventListener('mousemove', onMove);
+ document.removeEventListener('mouseup', onUp);
+ };
+ document.addEventListener('mousemove', onMove);
+ document.addEventListener('mouseup', onUp);
+ }
+
private startRubberBand(e: MouseEvent, rect: DOMRect): void {
const startX = e.clientX - rect.left;
const startY = e.clientY - rect.top;
@@ -1112,7 +1352,7 @@ export class TimelineKeyframeArea {
const assetTrack = this.assetData_.tracks[trackInfo.trackIndex];
if (!assetTrack) return;
- const time = Math.max(0, this.state_.xToTime(x));
+ const time = this.state_.snapTime(Math.max(0, this.state_.xToTime(x)));
switch (assetTrack.type) {
case 'property': {
@@ -1154,6 +1394,24 @@ export class TimelineKeyframeArea {
this.host_.executeCommand(cmd);
break;
}
+ case 'marker': {
+ const cmd = new AddMarkerCommand(
+ this.assetData_, trackInfo.trackIndex,
+ { time, name: 'marker' },
+ () => this.host_!.onAssetDataChanged(),
+ );
+ this.host_.executeCommand(cmd);
+ break;
+ }
+ case 'customEvent': {
+ const cmd = new AddCustomEventCommand(
+ this.assetData_, trackInfo.trackIndex,
+ { time, name: 'event', payload: {} },
+ () => this.host_!.onAssetDataChanged(),
+ );
+ this.host_.executeCommand(cmd);
+ break;
+ }
}
}
@@ -1179,7 +1437,9 @@ export class TimelineKeyframeArea {
const onMove = (ev: MouseEvent) => {
const currentX = ev.clientX - rect.left;
const currentTime = this.state_.xToTime(currentX);
- const timeDelta = currentTime - startTime;
+ const rawDelta = currentTime - startTime;
+ const snappedFirst = this.state_.snapTime(oldTimes[0] + rawDelta);
+ const timeDelta = snappedFirst - oldTimes[0];
if (timeDelta === lastDelta) return;
lastDelta = timeDelta;
@@ -1493,7 +1753,7 @@ export class TimelineKeyframeArea {
private buildNonPropertyContextMenu(
menu: HTMLElement,
- npHit: { type: string; hit: SpineClipHit | AudioEventHit | ActivationRangeHit },
+ npHit: { type: string; hit: SpineClipHit | AudioEventHit | ActivationRangeHit | MarkerHit | CustomEventHit | SpriteAnimHit },
): void {
if (!this.assetData_ || !this.host_) return;
@@ -1539,6 +1799,34 @@ export class TimelineKeyframeArea {
this.host_!.executeCommand(cmd);
});
menu.appendChild(item);
+ } else if (npHit.type === 'marker') {
+ const hit = npHit.hit as MarkerHit;
+ const item = document.createElement('div');
+ item.className = 'es-timeline-dropdown-item';
+ item.textContent = 'Delete Marker';
+ item.addEventListener('click', () => {
+ menu.remove();
+ const cmd = new DeleteMarkerCommand(
+ this.assetData_!, hit.trackIndex, hit.markerIndex,
+ () => this.host_!.onAssetDataChanged(),
+ );
+ this.host_!.executeCommand(cmd);
+ });
+ menu.appendChild(item);
+ } else if (npHit.type === 'customEvent') {
+ const hit = npHit.hit as CustomEventHit;
+ const item = document.createElement('div');
+ item.className = 'es-timeline-dropdown-item';
+ item.textContent = 'Delete Event';
+ item.addEventListener('click', () => {
+ menu.remove();
+ const cmd = new DeleteCustomEventCommand(
+ this.assetData_!, hit.trackIndex, hit.eventIndex,
+ () => this.host_!.onAssetDataChanged(),
+ );
+ this.host_!.executeCommand(cmd);
+ });
+ menu.appendChild(item);
}
}
diff --git a/editor/src/panels/timeline/TimelinePanel.ts b/editor/src/panels/timeline/TimelinePanel.ts
index 58ee85d4e..11112f65c 100644
--- a/editor/src/panels/timeline/TimelinePanel.ts
+++ b/editor/src/panels/timeline/TimelinePanel.ts
@@ -431,7 +431,7 @@ export class TimelinePanel implements PanelInstance {
}
private evaluateChannelAtTime(
- keyframes: { time: number; value: number; inTangent?: number; outTangent?: number }[],
+ keyframes: { time: number; value: number; inTangent?: number; outTangent?: number; interpolation?: string }[],
time: number,
): number | null {
if (keyframes.length === 0) return null;
@@ -448,15 +448,35 @@ export class TimelinePanel implements PanelInstance {
if (dt <= 0) return k0.value;
const t = (time - k0.time) / dt;
- const m0 = (k0.outTangent ?? 0) * dt;
- const m1 = (k1.inTangent ?? 0) * dt;
- const t2 = t * t;
- const t3 = t2 * t;
-
- return (2 * t3 - 3 * t2 + 1) * k0.value
- + (t3 - 2 * t2 + t) * m0
- + (-2 * t3 + 3 * t2) * k1.value
- + (t3 - t2) * m1;
+ const interp = k0.interpolation ?? 'hermite';
+
+ switch (interp) {
+ case 'linear':
+ return k0.value + (k1.value - k0.value) * t;
+ case 'step':
+ return k0.value;
+ case 'easeIn':
+ return k0.value + (k1.value - k0.value) * (t * t);
+ case 'easeOut': {
+ const inv = 1 - t;
+ return k0.value + (k1.value - k0.value) * (1 - inv * inv);
+ }
+ case 'easeInOut': {
+ const e = t < 0.5 ? 2 * t * t : 1 - 2 * (1 - t) * (1 - t);
+ return k0.value + (k1.value - k0.value) * e;
+ }
+ case 'hermite':
+ default: {
+ const m0 = (k0.outTangent ?? 0) * dt;
+ const m1 = (k1.inTangent ?? 0) * dt;
+ const t2 = t * t;
+ const t3 = t2 * t;
+ return (2 * t3 - 3 * t2 + 1) * k0.value
+ + (t3 - 2 * t2 + t) * m0
+ + (-2 * t3 + 3 * t2) * k1.value
+ + (t3 - t2) * m1;
+ }
+ }
}
private setNestedValue(obj: Record<string, unknown>, path: string, value: number): void {
diff --git a/editor/src/panels/timeline/TimelineState.ts b/editor/src/panels/timeline/TimelineState.ts
index e5e8b6d57..85f3e8856 100644
--- a/editor/src/panels/timeline/TimelineState.ts
+++ b/editor/src/panels/timeline/TimelineState.ts
@@ -9,7 +9,7 @@ export const KEYFRAME_SIZE = 8;
export const SNAP_THRESHOLD = 5;
export const DEFAULT_DURATION = 5;
-export type TrackType = 'property' | 'spine' | 'spriteAnim' | 'audio' | 'activation';
+export type TrackType = 'property' | 'spine' | 'spriteAnim' | 'audio' | 'activation' | 'marker' | 'customEvent';
export interface TimelineTrackState {
index: number;
@@ -21,6 +21,8 @@ export interface TimelineTrackState {
export type WrapMode = 'once' | 'loop' | 'pingPong';
+export const FRAME_RATE = 60;
+
export class TimelineState {
pixelsPerSecond = DEFAULT_PIXELS_PER_SECOND;
scrollX = 0;
@@ -31,6 +33,7 @@ export class TimelineState {
recording = false;
playbackSpeed = 1;
wrapMode: WrapMode = 'once';
+ snapEnabled = true;
selectedTrackIndex = -1;
selectedKeyframes: Set<string> = new Set();
tracks: TimelineTrackState[] = [];
@@ -88,6 +91,12 @@ export class TimelineState {
return y - this.scrollY;
}
+ snapTime(time: number): number {
+ if (!this.snapEnabled) return time;
+ const step = 1 / FRAME_RATE;
+ return Math.round(time / step) * step;
+ }
+
getTotalTracksHeight(): number {
let h = 0;
for (const track of this.tracks) {
diff --git a/editor/src/panels/timeline/TimelineToolbar.ts b/editor/src/panels/timeline/TimelineToolbar.ts
index 243f1ab88..662aee99a 100644
--- a/editor/src/panels/timeline/TimelineToolbar.ts
+++ b/editor/src/panels/timeline/TimelineToolbar.ts
@@ -23,6 +23,7 @@ export class TimelineToolbar {
private recordBtn_: HTMLElement | null = null;
private wrapBtn_: HTMLElement | null = null;
private speedBtn_: HTMLElement | null = null;
+ private snapBtn_: HTMLElement | null = null;
private valueGroup_: HTMLElement | null = null;
private valueInput_: HTMLInputElement | null = null;
private unsub_: (() => void) | null = null;
@@ -97,6 +98,7 @@ export class TimelineToolbar {
<div class="es-timeline-toolbar-right">
<button class="es-btn es-btn-sm es-timeline-speed-btn" data-action="speed" title="Playback Speed">1x</button>
<button class="es-btn es-btn-icon es-timeline-wrap-btn" data-action="wrap" title="Wrap Mode: Once">${icons.repeat(12)}</button>
+ <button class="es-btn es-btn-icon es-timeline-snap-btn es-active" data-action="snap" title="Snap to Grid">${icons.grid(12)}</button>
<button class="es-btn es-btn-icon" data-action="add-track" title="Add Track">${icons.plus(12)}</button>
</div>
</div>
@@ -107,6 +109,7 @@ export class TimelineToolbar {
this.recordBtn_ = this.el_.querySelector('[data-action="record"]');
this.wrapBtn_ = this.el_.querySelector('[data-action="wrap"]');
this.speedBtn_ = this.el_.querySelector('[data-action="speed"]');
+ this.snapBtn_ = this.el_.querySelector('[data-action="snap"]');
this.valueGroup_ = this.el_.querySelector('.es-timeline-value-group');
this.valueInput_ = this.el_.querySelector('.es-timeline-value-input');
@@ -148,6 +151,11 @@ export class TimelineToolbar {
this.cycleWrapMode();
});
+ this.el_.querySelector('[data-action="snap"]')?.addEventListener('click', () => {
+ this.state_.snapEnabled = !this.state_.snapEnabled;
+ this.snapBtn_?.classList.toggle('es-active', this.state_.snapEnabled);
+ });
+
this.el_.querySelector('[data-action="add-track"]')?.addEventListener('click', (e) => {
e.stopPropagation();
this.showWizard(e.target as HTMLElement);
diff --git a/editor/src/panels/timeline/TimelineTrackCommands.ts b/editor/src/panels/timeline/TimelineTrackCommands.ts
index d36748870..386e99354 100644
--- a/editor/src/panels/timeline/TimelineTrackCommands.ts
+++ b/editor/src/panels/timeline/TimelineTrackCommands.ts
@@ -41,6 +41,31 @@ function getActivationRanges(data: TimelineAssetData, trackIndex: number): Activ
return track.ranges;
}
+interface MarkerData {
+ time: number;
+ name: string;
+}
+
+function getMarkers(data: TimelineAssetData, trackIndex: number): MarkerData[] | null {
+ const track = data.tracks[trackIndex];
+ if (!track || track.type !== 'marker') return null;
+ if (!track.markers) track.markers = [];
+ return track.markers as MarkerData[];
+}
+
+interface CustomEventData {
+ time: number;
+ name: string;
+ payload: Record<string, unknown>;
+}
+
+function getCustomEvents(data: TimelineAssetData, trackIndex: number): CustomEventData[] | null {
+ const track = data.tracks[trackIndex];
+ if (!track || track.type !== 'customEvent') return null;
+ if (!track.customEvents) track.customEvents = [];
+ return track.customEvents as CustomEventData[];
+}
+
// =============================================================================
// Spine Clip Commands
// =============================================================================
@@ -516,3 +541,296 @@ export class DeleteActivationRangeCommand extends BaseCommand {
this.onChanged_();
}
}
+
+// =============================================================================
+// Marker Commands
+// =============================================================================
+
+export class AddMarkerCommand extends BaseCommand {
+ readonly type = 'timeline_add_marker';
+ readonly description = 'Add marker';
+ private insertedIndex_ = -1;
+
+ constructor(
+ private data_: TimelineAssetData,
+ private trackIndex_: number,
+ private marker_: MarkerData,
+ private onChanged_: () => void,
+ ) {
+ super();
+ }
+
+ execute(): void {
+ const markers = getMarkers(this.data_, this.trackIndex_);
+ if (!markers) return;
+ let idx = markers.findIndex(m => m.time > this.marker_.time);
+ if (idx === -1) idx = markers.length;
+ markers.splice(idx, 0, { ...this.marker_ });
+ this.insertedIndex_ = idx;
+ this.onChanged_();
+ }
+
+ undo(): void {
+ const markers = getMarkers(this.data_, this.trackIndex_);
+ if (!markers || this.insertedIndex_ < 0) return;
+ markers.splice(this.insertedIndex_, 1);
+ this.insertedIndex_ = -1;
+ this.onChanged_();
+ }
+}
+
+export class MoveMarkerCommand extends BaseCommand {
+ readonly type = 'timeline_move_marker';
+ readonly description = 'Move marker';
+ readonly newTime: number;
+
+ constructor(
+ private data_: TimelineAssetData,
+ private trackIndex_: number,
+ private markerIndex_: number,
+ private oldTime_: number,
+ newTime: number,
+ private onChanged_: () => void,
+ ) {
+ super();
+ this.newTime = newTime;
+ }
+
+ execute(): void {
+ const markers = getMarkers(this.data_, this.trackIndex_);
+ if (!markers) return;
+ const m = markers[this.markerIndex_];
+ if (m) {
+ m.time = this.newTime;
+ markers.sort((a, b) => a.time - b.time);
+ }
+ this.onChanged_();
+ }
+
+ undo(): void {
+ const markers = getMarkers(this.data_, this.trackIndex_);
+ if (!markers) return;
+ const m = markers.find(mk => mk.time === this.newTime);
+ if (m) {
+ m.time = this.oldTime_;
+ markers.sort((a, b) => a.time - b.time);
+ }
+ this.onChanged_();
+ }
+
+ override canMerge(other: Command): boolean {
+ if (!(other instanceof MoveMarkerCommand)) return false;
+ if (other.trackIndex_ !== this.trackIndex_) return false;
+ if (other.markerIndex_ !== this.markerIndex_) return false;
+ return other.timestamp - this.timestamp < MERGE_THRESHOLD_MS;
+ }
+
+ override merge(other: Command): Command {
+ if (!(other instanceof MoveMarkerCommand)) return this;
+ return new MoveMarkerCommand(
+ this.data_, this.trackIndex_, this.markerIndex_,
+ this.oldTime_, other.newTime, this.onChanged_,
+ );
+ }
+}
+
+export class DeleteMarkerCommand extends BaseCommand {
+ readonly type = 'timeline_delete_marker';
+ readonly description = 'Delete marker';
+ private deleted_: MarkerData | null = null;
+
+ constructor(
+ private data_: TimelineAssetData,
+ private trackIndex_: number,
+ private markerIndex_: number,
+ private onChanged_: () => void,
+ ) {
+ super();
+ }
+
+ execute(): void {
+ const markers = getMarkers(this.data_, this.trackIndex_);
+ if (!markers) return;
+ this.deleted_ = markers.splice(this.markerIndex_, 1)[0] ?? null;
+ this.onChanged_();
+ }
+
+ undo(): void {
+ const markers = getMarkers(this.data_, this.trackIndex_);
+ if (!markers || !this.deleted_) return;
+ markers.splice(this.markerIndex_, 0, this.deleted_);
+ this.deleted_ = null;
+ this.onChanged_();
+ }
+}
+
+// =============================================================================
+// Custom Event Commands
+// =============================================================================
+
+export class AddCustomEventCommand extends BaseCommand {
+ readonly type = 'timeline_add_custom_event';
+ readonly description = 'Add custom event';
+ private insertedIndex_ = -1;
+
+ constructor(
+ private data_: TimelineAssetData,
+ private trackIndex_: number,
+ private event_: CustomEventData,
+ private onChanged_: () => void,
+ ) {
+ super();
+ }
+
+ execute(): void {
+ const events = getCustomEvents(this.data_, this.trackIndex_);
+ if (!events) return;
+ let idx = events.findIndex(e => e.time > this.event_.time);
+ if (idx === -1) idx = events.length;
+ events.splice(idx, 0, { ...this.event_ });
+ this.insertedIndex_ = idx;
+ this.onChanged_();
+ }
+
+ undo(): void {
+ const events = getCustomEvents(this.data_, this.trackIndex_);
+ if (!events || this.insertedIndex_ < 0) return;
+ events.splice(this.insertedIndex_, 1);
+ this.insertedIndex_ = -1;
+ this.onChanged_();
+ }
+}
+
+export class MoveCustomEventCommand extends BaseCommand {
+ readonly type = 'timeline_move_custom_event';
+ readonly description = 'Move custom event';
+ readonly newTime: number;
+
+ constructor(
+ private data_: TimelineAssetData,
+ private trackIndex_: number,
+ private eventIndex_: number,
+ private oldTime_: number,
+ newTime: number,
+ private onChanged_: () => void,
+ ) {
+ super();
+ this.newTime = newTime;
+ }
+
+ execute(): void {
+ const events = getCustomEvents(this.data_, this.trackIndex_);
+ if (!events) return;
+ const ev = events[this.eventIndex_];
+ if (ev) {
+ ev.time = this.newTime;
+ events.sort((a, b) => a.time - b.time);
+ }
+ this.onChanged_();
+ }
+
+ undo(): void {
+ const events = getCustomEvents(this.data_, this.trackIndex_);
+ if (!events) return;
+ const ev = events.find(e => e.time === this.newTime);
+ if (ev) {
+ ev.time = this.oldTime_;
+ events.sort((a, b) => a.time - b.time);
+ }
+ this.onChanged_();
+ }
+
+ override canMerge(other: Command): boolean {
+ if (!(other instanceof MoveCustomEventCommand)) return false;
+ if (other.trackIndex_ !== this.trackIndex_) return false;
+ if (other.eventIndex_ !== this.eventIndex_) return false;
+ return other.timestamp - this.timestamp < MERGE_THRESHOLD_MS;
+ }
+
+ override merge(other: Command): Command {
+ if (!(other instanceof MoveCustomEventCommand)) return this;
+ return new MoveCustomEventCommand(
+ this.data_, this.trackIndex_, this.eventIndex_,
+ this.oldTime_, other.newTime, this.onChanged_,
+ );
+ }
+}
+
+export class DeleteCustomEventCommand extends BaseCommand {
+ readonly type = 'timeline_delete_custom_event';
+ readonly description = 'Delete custom event';
+ private deleted_: CustomEventData | null = null;
+
+ constructor(
+ private data_: TimelineAssetData,
+ private trackIndex_: number,
+ private eventIndex_: number,
+ private onChanged_: () => void,
+ ) {
+ super();
+ }
+
+ execute(): void {
+ const events = getCustomEvents(this.data_, this.trackIndex_);
+ if (!events) return;
+ this.deleted_ = events.splice(this.eventIndex_, 1)[0] ?? null;
+ this.onChanged_();
+ }
+
+ undo(): void {
+ const events = getCustomEvents(this.data_, this.trackIndex_);
+ if (!events || !this.deleted_) return;
+ events.splice(this.eventIndex_, 0, this.deleted_);
+ this.deleted_ = null;
+ this.onChanged_();
+ }
+}
+
+// =============================================================================
+// SpriteAnim Commands
+// =============================================================================
+
+export class MoveSpriteAnimStartCommand extends BaseCommand {
+ readonly type = 'timeline_move_sprite_anim_start';
+ readonly description = 'Move sprite anim start';
+ readonly newTime: number;
+
+ constructor(
+ private data_: TimelineAssetData,
+ private trackIndex_: number,
+ private oldTime_: number,
+ newTime: number,
+ private onChanged_: () => void,
+ ) {
+ super();
+ this.newTime = newTime;
+ }
+
+ execute(): void {
+ const track = this.data_.tracks[this.trackIndex_];
+ if (!track || track.type !== 'spriteAnim') return;
+ track.startTime = this.newTime;
+ this.onChanged_();
+ }
+
+ undo(): void {
+ const track = this.data_.tracks[this.trackIndex_];
+ if (!track || track.type !== 'spriteAnim') return;
+ track.startTime = this.oldTime_;
+ this.onChanged_();
+ }
+
+ override canMerge(other: Command): boolean {
+ if (!(other instanceof MoveSpriteAnimStartCommand)) return false;
+ if (other.trackIndex_ !== this.trackIndex_) return false;
+ return other.timestamp - this.timestamp < MERGE_THRESHOLD_MS;
+ }
+
+ override merge(other: Command): Command {
+ if (!(other instanceof MoveSpriteAnimStartCommand)) return this;
+ return new MoveSpriteAnimStartCommand(
+ this.data_, this.trackIndex_,
+ this.oldTime_, other.newTime, this.onChanged_,
+ );
+ }
+}
diff --git a/sdk/src/timeline/TimelineLoader.ts b/sdk/src/timeline/TimelineLoader.ts
index 40ec0a0ee..be45b6762 100644
--- a/sdk/src/timeline/TimelineLoader.ts
+++ b/sdk/src/timeline/TimelineLoader.ts
@@ -8,8 +8,47 @@ import {
type SpriteAnimTrack,
type AudioTrack,
type ActivationTrack,
+ type MarkerTrack,
+ type CustomEventTrack,
} from './TimelineTypes';
+const CURRENT_VERSION = '1.1';
+
+const STEP_TANGENT_THRESHOLD = 1e5;
+
+type MigrationFn = (raw: any) => void;
+
+const MIGRATIONS: [string, string, MigrationFn][] = [
+ ['1.0', '1.1', (raw: any) => {
+ for (const track of raw.tracks ?? []) {
+ if (track.type === TrackType.Property) {
+ for (const ch of track.channels ?? []) {
+ for (const kf of ch.keyframes ?? []) {
+ if (kf.interpolation) continue;
+ if (Math.abs(kf.outTangent) >= STEP_TANGENT_THRESHOLD) {
+ kf.interpolation = 'step';
+ kf.outTangent = 0;
+ }
+ }
+ }
+ }
+ }
+ }],
+];
+
+function migrateAsset(raw: any): void {
+ let version = raw.version ?? '1.0';
+
+ for (const [from, to, fn] of MIGRATIONS) {
+ if (version === from) {
+ fn(raw);
+ version = to;
+ }
+ }
+
+ raw.version = CURRENT_VERSION;
+}
+
const WRAP_MODE_MAP: Record<string, WrapMode> = {
once: WrapMode.Once,
loop: WrapMode.Loop,
@@ -69,18 +108,39 @@ function parseTrack(raw: any): Track {
ranges: raw.ranges ?? [],
} as ActivationTrack;
+ case TrackType.Marker:
+ return {
+ ...base,
+ type: TrackType.Marker,
+ markers: raw.markers ?? [],
+ } as MarkerTrack;
+
+ case TrackType.CustomEvent:
+ return {
+ ...base,
+ type: TrackType.CustomEvent,
+ events: (raw.events ?? []).map((e: any) => ({
+ time: e.time ?? 0,
+ name: e.name ?? '',
+ payload: e.payload ?? {},
+ })),
+ } as CustomEventTrack;
+
default:
- throw new Error(`Unknown track type: ${raw.type}`);
+ console.warn(`[Timeline] Unknown track type: ${raw.type}, skipping`);
+ return null as any;
}
}
export function parseTimelineAsset(raw: any): TimelineAsset {
+ migrateAsset(raw);
+
return {
- version: raw.version ?? '1.0',
+ version: CURRENT_VERSION,
type: 'timeline',
duration: raw.duration ?? 0,
wrapMode: parseWrapMode(raw.wrapMode),
- tracks: (raw.tracks ?? []).map(parseTrack),
+ tracks: (raw.tracks ?? []).map(parseTrack).filter((t: Track | null) => t !== null),
};
}
diff --git a/sdk/src/timeline/TimelineTypes.ts b/sdk/src/timeline/TimelineTypes.ts
index 5be8b857c..cb7f466f8 100644
--- a/sdk/src/timeline/TimelineTypes.ts
+++ b/sdk/src/timeline/TimelineTypes.ts
@@ -12,15 +12,29 @@ export const TrackType = {
SpriteAnim: 'spriteAnim',
Audio: 'audio',
Activation: 'activation',
+ Marker: 'marker',
+ CustomEvent: 'customEvent',
} as const;
export type TrackType = (typeof TrackType)[keyof typeof TrackType];
+export const InterpType = {
+ Hermite: 'hermite',
+ Linear: 'linear',
+ Step: 'step',
+ EaseIn: 'easeIn',
+ EaseOut: 'easeOut',
+ EaseInOut: 'easeInOut',
+} as const;
+
+export type InterpType = (typeof InterpType)[keyof typeof InterpType];
+
export interface Keyframe {
time: number;
value: number;
inTangent: number;
outTangent: number;
+ interpolation?: InterpType;
}
export interface PropertyChannel {
@@ -81,7 +95,28 @@ export interface ActivationTrack extends TrackBase {
ranges: ActivationRange[];
}
-export type Track = PropertyTrack | SpineTrack | SpriteAnimTrack | AudioTrack | ActivationTrack;
+export interface Marker {
+ time: number;
+ name: string;
+}
+
+export interface MarkerTrack extends TrackBase {
+ type: typeof TrackType.Marker;
+ markers: Marker[];
+}
+
+export interface CustomEvent {
+ time: number;
+ name: string;
+ payload: Record<string, unknown>;
+}
+
+export interface CustomEventTrack extends TrackBase {
+ type: typeof TrackType.CustomEvent;
+ events: CustomEvent[];
+}
+
+export type Track = PropertyTrack | SpineTrack | SpriteAnimTrack | AudioTrack | ActivationTrack | MarkerTrack | CustomEventTrack;
export interface TimelineAsset {
version: string;
diff --git a/sdk/src/timeline/TimelineUploader.ts b/sdk/src/timeline/TimelineUploader.ts
index 58ad10770..6bc7af084 100644
--- a/sdk/src/timeline/TimelineUploader.ts
+++ b/sdk/src/timeline/TimelineUploader.ts
@@ -1,6 +1,6 @@
import type { ESEngineModule } from '../wasm';
import type { TimelineAsset, PropertyTrack, Track } from './TimelineTypes';
-import { TrackType } from './TimelineTypes';
+import { TrackType, InterpType } from './TimelineTypes';
export enum AnimTargetField {
PositionX = 0, PositionY, PositionZ,
@@ -69,6 +69,20 @@ const COMPONENT_MAP: Record<string, AnimTargetComponent> = {
Camera: AnimTargetComponent.Camera,
};
+const INTERP_TYPE_MAP: Record<string, number> = {
+ [InterpType.Hermite]: 0,
+ [InterpType.Linear]: 1,
+ [InterpType.Step]: 2,
+ [InterpType.EaseIn]: 3,
+ [InterpType.EaseOut]: 4,
+ [InterpType.EaseInOut]: 5,
+};
+
+function interpTypeToNum(interp?: InterpType): number {
+ if (!interp) return 0;
+ return INTERP_TYPE_MAP[interp] ?? 0;
+}
+
function resolveField(component: string, property: string): AnimTargetField {
return FIELD_MAP[component]?.[property] ?? AnimTargetField.CustomField;
}
@@ -168,8 +182,8 @@ function uploadPropertyTrack(module: ESEngineModule, handle: number, track: Prop
const countsPtr = mod._malloc(channelCount * 4);
new Int32Array(mod.HEAPU8.buffer, countsPtr, channelCount).set(counts);
- const dataPtr = mod._malloc(totalKeyframes * 4 * 4);
- const dataArr = new Float32Array(mod.HEAPU8.buffer, dataPtr, totalKeyframes * 4);
+ const dataPtr = mod._malloc(totalKeyframes * 5 * 4);
+ const dataArr = new Float32Array(mod.HEAPU8.buffer, dataPtr, totalKeyframes * 5);
let offset = 0;
for (const ch of track.channels) {
for (const kf of ch.keyframes) {
@@ -177,6 +191,7 @@ function uploadPropertyTrack(module: ESEngineModule, handle: number, track: Prop
dataArr[offset++] = kf.value;
dataArr[offset++] = kf.inTangent;
dataArr[offset++] = kf.outTangent;
+ dataArr[offset++] = interpTypeToNum(kf.interpolation);
}
}
@@ -220,8 +235,8 @@ function uploadCustomPropertyTrack(module: ESEngineModule, handle: number, track
const countsPtr = mod._malloc(channelCount * 4);
new Int32Array(mod.HEAPU8.buffer, countsPtr, channelCount).set(counts);
- const dataPtr = mod._malloc(totalKeyframes * 4 * 4);
- const dataArr = new Float32Array(mod.HEAPU8.buffer, dataPtr, totalKeyframes * 4);
+ const dataPtr = mod._malloc(totalKeyframes * 5 * 4);
+ const dataArr = new Float32Array(mod.HEAPU8.buffer, dataPtr, totalKeyframes * 5);
let dOffset = 0;
for (const ch of track.channels) {
for (const kf of ch.keyframes) {
@@ -229,6 +244,7 @@ function uploadCustomPropertyTrack(module: ESEngineModule, handle: number, track
dataArr[dOffset++] = kf.value;
dataArr[dOffset++] = kf.inTangent;
dataArr[dOffset++] = kf.outTangent;
+ dataArr[dOffset++] = interpTypeToNum(kf.interpolation);
}
}
diff --git a/sdk/src/timeline/index.ts b/sdk/src/timeline/index.ts
index 569600cf5..20c20eea2 100644
--- a/sdk/src/timeline/index.ts
+++ b/sdk/src/timeline/index.ts
@@ -1,6 +1,7 @@
export {
WrapMode,
TrackType,
+ InterpType,
type Keyframe,
type PropertyChannel,
type PropertyTrack,
@@ -11,6 +12,10 @@ export {
type AudioTrack,
type ActivationRange,
type ActivationTrack,
+ type Marker,
+ type MarkerTrack,
+ type CustomEvent,
+ type CustomEventTrack,
type Track,
type TimelineAsset,
} from './TimelineTypes';
diff --git a/src/esengine/animation/TimelineData.hpp b/src/esengine/animation/TimelineData.hpp
index 18da223ac..54d8381c1 100644
--- a/src/esengine/animation/TimelineData.hpp
+++ b/src/esengine/animation/TimelineData.hpp
@@ -13,11 +13,21 @@ enum class TimelineWrapMode : u8 {
PingPong,
};
+enum class InterpType : u8 {
+ Hermite = 0,
+ Linear,
+ Step,
+ EaseIn,
+ EaseOut,
+ EaseInOut,
+};
+
struct TimelineKeyframe {
f32 time;
f32 value;
f32 inTangent;
f32 outTangent;
+ InterpType interpolation{InterpType::Hermite};
};
struct TimelineChannel {
diff --git a/src/esengine/animation/TimelineSystem.cpp b/src/esengine/animation/TimelineSystem.cpp
index 338193151..a24710da6 100644
--- a/src/esengine/animation/TimelineSystem.cpp
+++ b/src/esengine/animation/TimelineSystem.cpp
@@ -105,6 +105,18 @@ f32 TimelineSystem::hermiteInterpolate(f32 p0, f32 p1, f32 m0, f32 m1, f32 t) {
return h00 * p0 + h10 * m0 + h01 * p1 + h11 * m1;
}
+f32 TimelineSystem::easeIn(f32 t) {
+ return t * t;
+}
+
+f32 TimelineSystem::easeOut(f32 t) {
+ return 1.0f - (1.0f - t) * (1.0f - t);
+}
+
+f32 TimelineSystem::easeInOut(f32 t) {
+ return t < 0.5f ? 2.0f * t * t : 1.0f - 2.0f * (1.0f - t) * (1.0f - t);
+}
+
f32 TimelineSystem::evaluateChannel(const TimelineChannel& channel, f32 time) {
const auto& kfs = channel.keyframes;
if (kfs.empty()) return 0.0f;
@@ -124,7 +136,22 @@ f32 TimelineSystem::evaluateChannel(const TimelineChannel& channel, f32 time) {
if (dt <= 0.0f) return k0.value;
f32 t = (time - k0.time) / dt;
- return hermiteInterpolate(k0.value, k1.value, k0.outTangent * dt, k1.inTangent * dt, t);
+
+ switch (k0.interpolation) {
+ case InterpType::Linear:
+ return k0.value + (k1.value - k0.value) * t;
+ case InterpType::Step:
+ return k0.value;
+ case InterpType::EaseIn:
+ return k0.value + (k1.value - k0.value) * easeIn(t);
+ case InterpType::EaseOut:
+ return k0.value + (k1.value - k0.value) * easeOut(t);
+ case InterpType::EaseInOut:
+ return k0.value + (k1.value - k0.value) * easeInOut(t);
+ case InterpType::Hermite:
+ default:
+ return hermiteInterpolate(k0.value, k1.value, k0.outTangent * dt, k1.inTangent * dt, t);
+ }
}
f32 TimelineSystem::applyWrapMode(f32 time, f32 duration, TimelineWrapMode mode, bool& stopped) {
diff --git a/src/esengine/animation/TimelineSystem.hpp b/src/esengine/animation/TimelineSystem.hpp
index 2133ed6a8..416477fb0 100644
--- a/src/esengine/animation/TimelineSystem.hpp
+++ b/src/esengine/animation/TimelineSystem.hpp
@@ -76,6 +76,9 @@ private:
};
static f32 hermiteInterpolate(f32 p0, f32 p1, f32 m0, f32 m1, f32 t);
+ static f32 easeIn(f32 t);
+ static f32 easeOut(f32 t);
+ static f32 easeInOut(f32 t);
static f32 evaluateChannel(const TimelineChannel& channel, f32 time);
static f32 applyWrapMode(f32 time, f32 duration, TimelineWrapMode mode, bool& stopped);
diff --git a/src/esengine/bindings/TimelineBindings.cpp b/src/esengine/bindings/TimelineBindings.cpp
index a58379c64..39e9a4fd0 100644
--- a/src/esengine/bindings/TimelineBindings.cpp
+++ b/src/esengine/bindings/TimelineBindings.cpp
@@ -62,9 +62,10 @@ void tl_addPropertyTrack(u32 handle, uintptr_t childPathPtr, i32 childPathLen,
for (i32 ki = 0; ki < count; ki++) {
channel.keyframes[ki] = {
kfData[dataOffset], kfData[dataOffset + 1],
- kfData[dataOffset + 2], kfData[dataOffset + 3]
+ kfData[dataOffset + 2], kfData[dataOffset + 3],
+ static_cast<animation::InterpType>(static_cast<u8>(kfData[dataOffset + 4]))
};
- dataOffset += 4;
+ dataOffset += 5;
}
track.channels.push_back(std::move(channel));
}
@@ -112,9 +113,10 @@ void tl_addCustomPropertyTrack(u32 handle, uintptr_t childPathPtr, i32 childPath
for (i32 ki = 0; ki < count; ki++) {
channel.keyframes[ki] = {
kfData[dataOffset], kfData[dataOffset + 1],
- kfData[dataOffset + 2], kfData[dataOffset + 3]
+ kfData[dataOffset + 2], kfData[dataOffset + 3],
+ static_cast<animation::InterpType>(static_cast<u8>(kfData[dataOffset + 4]))
};
- dataOffset += 4;
+ dataOffset += 5;
}
track.channels.push_back(std::move(channel));
}