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): keyframe properties in the shared Inspector via override channel

esengine248757a0df57
diff --git a/desktop/src/i18n/messages/sequencer.ts b/desktop/src/i18n/messages/sequencer.ts
index ee1cc58dc..219598c1c 100644
--- a/desktop/src/i18n/messages/sequencer.ts
+++ b/desktop/src/i18n/messages/sequencer.ts
@@ -64,6 +64,9 @@ export const sequencerMessages = defineMessages({
'seq.durationS': { en: 'Duration (s)', zh: '时长(秒)' },
'seq.frameRateFps': { en: 'Frame rate (fps)', zh: '帧率(fps)' },
'seq.insp.timeline': { en: 'Timeline', zh: '时间轴' },
+ 'seq.insp.keyframe': { en: 'Keyframe', zh: '关键帧' },
+ 'seq.field.value': { en: 'Value', zh: '值' },
+ 'seq.field.interp': { en: 'Interpolation', zh: '插值' },
'seq.timelineClip': { en: 'Timeline', zh: '时间轴' },
'seq.field.duration': { en: 'Duration', zh: '持续时间' },
'seq.field.fps': { en: 'FPS', zh: '帧率' },
diff --git a/desktop/src/panels/Details.tsx b/desktop/src/panels/Details.tsx
index 4b2b91f35..0ba73c555 100644
--- a/desktop/src/panels/Details.tsx
+++ b/desktop/src/panels/Details.tsx
@@ -2833,6 +2833,11 @@ function EditorDetails() {
return out;
}, [components, query]);
+ // An explicit sub-object inspection source (a keyframe, a track…) overrides the
+ // entity/asset inspector; a non-override source is the fallback further below.
+ if (inspectSource?.override) {
+ return <SourceInspector source={inspectSource} />;
+ }
// Unified inspector: an asset selection (mutually exclusive with entities)
// renders the asset view in this same panel.
if (selectedAsset) {
diff --git a/desktop/src/panels/Sequencer.tsx b/desktop/src/panels/Sequencer.tsx
index 89d596f8f..47d4966b7 100644
--- a/desktop/src/panels/Sequencer.tsx
+++ b/desktop/src/panels/Sequencer.tsx
@@ -23,6 +23,7 @@ import { TimelineDocument } from '@/timeline/TimelineDocument';
import { createAnimationClip } from '@/timeline/openClip';
import { TimelineCommands } from '@/timeline/TimelineCommands';
import { buildTimelineComponents, makeTimelineWrite } from '@/timeline/timelineInspectorModel';
+import { buildKeyframeComponents, makeKeyframeWrite, keyframeExists } from '@/timeline/keyframeInspectorModel';
import { useSequencerStore } from '@/store/sequencerStore';
import { useSelection } from '@/store/selectionStore';
import { SceneModel } from '@/engine/SceneModel';
@@ -109,15 +110,27 @@ export function Sequencer() {
// Re-read the document on every revision bump (open / edit / close).
useSyncExternalStore(TimelineDocument.subscribe, TimelineDocument.getRevision);
const asset = TimelineDocument.asset;
+ const selectedKey = useSequencerStore((s) => s.selectedKey);
- // Push the open timeline's clip settings (duration / fps / wrap) into the ONE
- // shared Details inspector via the generic inspection-source channel — a
- // fallback, so an entity/asset selection still wins. Cleared on close/unmount.
+ // Feed the shared Details inspector via the generic inspection-source channel:
+ // a SELECTED KEYFRAME (value/interp) overrides the entity inspector; otherwise
+ // the open timeline's clip settings (duration/fps/wrap) show as a fallback (so
+ // an entity/asset selection still wins). Cleared on close / unmount.
const timelineOpen = !!asset;
const timelinePath = TimelineDocument.meta.filePath;
+ const keyframeSel = timelineOpen && selectedKey && keyframeExists(asset, selectedKey) ? selectedKey : null;
useEffect(() => {
const sel = useSelection.getState();
- if (timelineOpen) {
+ if (keyframeSel) {
+ sel.setInspectSource({
+ title: t('seq.insp.keyframe'),
+ override: true,
+ subscribe: TimelineDocument.subscribe,
+ getRevision: TimelineDocument.getRevision,
+ build: () => buildKeyframeComponents(TimelineDocument.asset!, keyframeSel),
+ write: makeKeyframeWrite(keyframeSel),
+ });
+ } else if (timelineOpen) {
sel.setInspectSource({
title: timelinePath?.split('/').pop() ?? t('seq.timelineClip'),
subscribe: TimelineDocument.subscribe,
@@ -129,7 +142,7 @@ export function Sequencer() {
sel.setInspectSource(null);
}
return () => { useSelection.getState().setInspectSource(null); };
- }, [timelineOpen, timelinePath]);
+ }, [timelineOpen, timelinePath, keyframeSel]);
if (!asset) return <div className="seq"><EmptyState /></div>;
diff --git a/desktop/src/timeline/keyframeInspectorModel.ts b/desktop/src/timeline/keyframeInspectorModel.ts
new file mode 100644
index 000000000..181c93d16
--- /dev/null
+++ b/desktop/src/timeline/keyframeInspectorModel.ts
@@ -0,0 +1,78 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file keyframeInspectorModel.ts
+ * @brief The Sequencer's selected keyframe (value + interpolation) as shared-
+ * inspector components, pushed through the generic inspection-source
+ * channel as an OVERRIDE — so clicking a keyframe shows its properties
+ * in the one Details panel, replacing the bespoke interp popover. Time
+ * is edited by dragging the key in the timeline (not here), so the
+ * selection key stays valid across edits. Writes route through
+ * TimelineCommands (one undo step each).
+ */
+import { InterpType, type TimelineAsset } from 'esengine';
+import type { InspectorComponent, InspectorFieldType, GradientValue, CurveValue, DimensionValue } from '@/types';
+import { buildTimelineRows, findChannel, type ChannelRef } from './timelineView';
+import { TimelineCommands } from './TimelineCommands';
+import { TimelineDocument } from './TimelineDocument';
+import { t } from '@/i18n';
+
+// InterpType is a STRING enum; the shared `enum` field takes int options, so map
+// it to an index (label ← friendly i18n, value ← position) and back on write.
+const INTERP_ORDER = [InterpType.Hermite, InterpType.Linear, InterpType.Step, InterpType.EaseInOut];
+const INTERP_OPTIONS = [
+ { label: t('seq.interp.auto'), value: 0 },
+ { label: t('seq.interp.linear'), value: 1 },
+ { label: t('seq.interp.step'), value: 2 },
+ { label: t('seq.interp.easeInOut'), value: 3 },
+];
+
+/** Resolve `${rowId}@${time}` to its channel ref + live keyframe (or null). */
+function resolve(asset: TimelineAsset, selectedKey: string): { ref: ChannelRef; time: number; value: number; interp: InterpType } | null {
+ const at = selectedKey.lastIndexOf('@');
+ if (at < 0) return null;
+ const rowId = selectedKey.slice(0, at);
+ const time = parseFloat(selectedKey.slice(at + 1));
+ const row = buildTimelineRows(asset).find((r) => r.id === rowId);
+ if (!row?.ref) return null;
+ const kf = findChannel(asset, row.ref)?.keyframes.find((k) => Math.abs(k.time - time) < 1e-4);
+ if (!kf) return null;
+ return { ref: row.ref, time: kf.time, value: kf.value, interp: kf.interpolation ?? InterpType.Hermite };
+}
+
+/** True when `selectedKey` addresses a live keyframe in `asset`. */
+export function keyframeExists(asset: TimelineAsset | null, selectedKey: string | null): boolean {
+ return !!asset && !!selectedKey && resolve(asset, selectedKey) != null;
+}
+
+export function buildKeyframeComponents(asset: TimelineAsset, selectedKey: string): InspectorComponent[] {
+ const r = resolve(asset, selectedKey);
+ if (!r) return [];
+ return [
+ {
+ name: 'Keyframe',
+ label: t('seq.insp.keyframe'),
+ fields: [
+ { key: 'value', label: t('seq.field.value'), type: 'number', value: r.value, step: 0.1 },
+ { key: 'interpolation', label: t('seq.field.interp'), type: 'enum', value: Math.max(0, INTERP_ORDER.findIndex((x) => x === r.interp)), options: INTERP_OPTIONS },
+ ],
+ },
+ ];
+}
+
+export function makeKeyframeWrite(selectedKey: string) {
+ return (key: string, _type: InspectorFieldType, value: number | boolean | string | number[] | GradientValue | CurveValue | DimensionValue): void => {
+ const asset = TimelineDocument.asset;
+ if (!asset) return;
+ const r = resolve(asset, selectedKey);
+ if (!r) return;
+ switch (key) {
+ case 'value':
+ TimelineCommands.setKeyValue(r.ref, r.time, value as number);
+ break;
+ case 'interpolation':
+ TimelineCommands.setKeyInterp(r.ref, r.time, INTERP_ORDER[value as number] ?? InterpType.Hermite);
+ break;
+ }
+ };
+}
diff --git a/desktop/src/types.ts b/desktop/src/types.ts
index 74cdb3ef2..7077092e0 100644
--- a/desktop/src/types.ts
+++ b/desktop/src/types.ts
@@ -163,6 +163,12 @@ export interface InspectSource {
getRevision: () => number;
build: () => InspectorComponent[];
write: (key: string, type: InspectorFieldType, value: number | boolean | string | number[] | GradientValue | CurveValue | DimensionValue) => void;
+ /**
+ * When true this is an explicit sub-object selection (a keyframe, a track) and
+ * OVERRIDES the entity/asset inspector. Default (false) is a fallback — shown
+ * only when nothing else is selected (an open document's clip-level settings).
+ */
+ override?: boolean;
}
export type AssetType =