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(sequencer): user component fields are keyframeable (animatableFields)
esenginea8fc1dd5205b
diff --git a/desktop/electron/extractSchemas.ts b/desktop/electron/extractSchemas.tsindex 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.tsindex 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.tsxindex 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: numif (!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.tsindex 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.tsindex 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) {