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(sequencer): user component fields are keyframeable (animatableFields)

esenginea8fc1dd5205b
diff --git a/desktop/electron/extractSchemas.ts b/desktop/electron/extractSchemas.ts
index df47a8e61..461733136 100644
--- a/desktop/electron/extractSchemas.ts
+++ b/desktop/electron/extractSchemas.ts
@@ -55,6 +55,8 @@ export interface ComponentSchema {
spineFields?: unknown;
/** Field keys that hold an Entity handle. */
entityFields: string[];
+ /** Keyframeable field paths (Sequencer tracks). */
+ animatableFields: string[];
/** Per-field editor metadata (enum + numeric range/unit), keyed by field name. */
fields?: Record<string, SerializedFieldMeta>;
}
@@ -200,6 +202,7 @@ interface UserComponentDef {
assetFields?: readonly unknown[];
spineFields?: unknown;
entityFields?: readonly string[];
+ animatableFields?: readonly string[];
fieldMeta?: Record<string, SerializedFieldMeta & { advanced?: boolean; category?: string; flags?: Array<{ label: string; value: number }> }>;
}
@@ -242,6 +245,7 @@ function toSchema(def: unknown): ComponentSchema {
colorKeys: [...(d.colorKeys ?? [])],
assetFields: [...(d.assetFields ?? [])],
entityFields: [...(d.entityFields ?? [])],
+ animatableFields: [...(d.animatableFields ?? [])],
};
if (d.spineFields) schema.spineFields = d.spineFields;
const fields = pickFieldMeta(d.fieldMeta);
diff --git a/desktop/src/engine/schema.ts b/desktop/src/engine/schema.ts
index 1b3a71f03..f61a15337 100644
--- a/desktop/src/engine/schema.ts
+++ b/desktop/src/engine/schema.ts
@@ -181,6 +181,8 @@ export interface UserComponentSchema {
colorKeys: string[];
/** Asset-ref fields (e.g. `[{field:'texture', type:'texture'}]`). */
assetFields?: Array<{ field: string; type: string }>;
+ /** Keyframeable field paths (Sequencer tracks). */
+ animatableFields?: string[];
/** Per-field editor metadata (enum + numeric range/unit), keyed by field name. */
fields?: Record<string, UserFieldMeta>;
}
@@ -256,6 +258,14 @@ export function assetFieldType(compType: string, key: string): string | null {
return null;
}
+/** Keyframeable field paths of a component — builtin via the engine registry, user
+ * components via their serialized schema (so both are first-class Sequencer tracks). */
+export function animatableFieldsFor(compType: string): readonly string[] {
+ const builtin = getComponent(compType);
+ if (builtin) return builtin.animatableFields ?? [];
+ return userSchema(compType)?.animatableFields ?? [];
+}
+
// — Field presentation metadata (the SDK's UPROPERTY analog) —
//
// A component declares per-field editor policy (enum options, numeric range,
diff --git a/desktop/src/panels/Sequencer.tsx b/desktop/src/panels/Sequencer.tsx
index 2e82a1c59..33758190c 100644
--- a/desktop/src/panels/Sequencer.tsx
+++ b/desktop/src/panels/Sequencer.tsx
@@ -17,7 +17,8 @@ import {
Circle, ChevronFirst, ChevronLast, ChevronLeft, ChevronRight,
Play, Pause, Repeat, Magnet, Plus, ChevronDown, Eye, EyeOff, Diamond, Film, Link2, Save, Trash2, Settings2,
} from 'lucide-react';
-import { evaluateChannel, getComponent, InterpType, WrapMode } from 'esengine';
+import { evaluateChannel, InterpType, WrapMode } from 'esengine';
+import { animatableFieldsFor } from '@/engine/schema';
import { TimelineDocument } from '@/timeline/TimelineDocument';
import { TimelineCommands } from '@/timeline/TimelineCommands';
import { useSequencerStore } from '@/store/sequencerStore';
@@ -69,7 +70,7 @@ function buildAddTrackItems(asset: { tracks: unknown } | null, rootSourceId: num
if (!entity) return [];
const items: AddTrackItem[] = [];
for (const comp of entity.components) {
- const fields = getComponent(comp.type)?.animatableFields ?? [];
+ const fields = animatableFieldsFor(comp.type);
for (const property of fields) {
const ref: ChannelRef = { childPath: '', component: comp.type, property };
if (findChannel(asset as never, ref)) continue;
diff --git a/desktop/tests/extract-schemas.test.ts b/desktop/tests/extract-schemas.test.ts
index 1a9181991..9bb84d342 100644
--- a/desktop/tests/extract-schemas.test.ts
+++ b/desktop/tests/extract-schemas.test.ts
@@ -63,6 +63,15 @@ describe('extractProjectSchemas (P2)', () => {
expect(marker!.default).toEqual({});
});
+ it('auto-derives keyframeable (animatable) fields for user components — numeric scalars + nested channels', async () => {
+ const res = await extractProjectSchemas(root);
+ const wave = byName(res.schemas, 'Wave')!;
+ // amplitude/speed are top-level numbers; tint is a {r,g,b,a} color → channel paths.
+ expect(wave.animatableFields).toContain('amplitude');
+ expect(wave.animatableFields).toContain('speed');
+ expect(wave.animatableFields).toContain('tint.r');
+ });
+
it('serializes user-component field metadata — range/tooltip/DisplayName/category (first-class, like builtins)', async () => {
const res = await extractProjectSchemas(root);
const wave = byName(res.schemas, 'Wave')!;
diff --git a/sdk/src/component.ts b/sdk/src/component.ts
index d791ecd4f..977efb269 100644
--- a/sdk/src/component.ts
+++ b/sdk/src/component.ts
@@ -75,6 +75,8 @@ export interface ComponentMetadata {
entityFields?: string[];
/** Per-field editor presentation policy, keyed by field name. */
fields?: Record<string, FieldMeta>;
+ /** Keyframeable fields (Sequencer tracks); auto-derived from numeric fields if omitted. */
+ animatableFields?: string[];
discoverAssets?: (data: Record<string, unknown>) => AssetRef[];
/**
* Runtime-only state that must never persist: a transient component is
@@ -180,7 +182,7 @@ function createComponentDef<T extends object>(
spineFields: metadata?.spineFields,
entityFields: metadata?.entityFields ?? [],
colorKeys: detectColorKeys(defaults),
- animatableFields: [],
+ animatableFields: metadata?.animatableFields ?? numericAnimatableFields(defaults),
fieldMeta: metadata?.fields ?? {},
discoverAssets: metadata?.discoverAssets,
transient: metadata?.transient ?? false,
@@ -351,6 +353,24 @@ function detectColorKeys(defaults: unknown): readonly string[] {
return keys;
}
+// Keyframeable fields for a user component (the Sequencer animates one number per
+// track): top-level numbers plus one level of nested numbers (vec / color channels
+// as dot-paths). So defineComponent('Patrol', { speed: 60 }) is animatable with no
+// boilerplate; metadata.animatableFields overrides this.
+function numericAnimatableFields(defaults: unknown): string[] {
+ if (defaults === null || typeof defaults !== 'object') return [];
+ const out: string[] = [];
+ for (const [key, val] of Object.entries(defaults as Record<string, unknown>)) {
+ if (typeof val === 'number') out.push(key);
+ else if (val !== null && typeof val === 'object' && !Array.isArray(val)) {
+ for (const [sub, sval] of Object.entries(val as Record<string, unknown>)) {
+ if (typeof sval === 'number') out.push(`${key}.${sub}`);
+ }
+ }
+ }
+ return out;
+}
+
export function defineBuiltin<T>(name: string, defaults: T, metadata?: ComponentMetadata): BuiltinComponentDef<T> {
const existing = builtinRegistry.get(name) ?? userComponents().get(name);
if (existing) {