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(editor): spine skeleton/atlas become first-class asset slots
yhhfe97c4fe25ba
diff --git a/desktop/src/engine/EngineHost.ts b/desktop/src/engine/EngineHost.tsindex 8d7160b7e..9819d9c13 100644--- a/desktop/src/engine/EngineHost.ts+++ b/desktop/src/engine/EngineHost.ts@@ -17,6 +17,7 @@ import {} from 'esengine';import type { App, ESEngineModule, ResourceDef, SubsystemStatus, SceneData } from 'esengine';import { SpinePlugin } from 'esengine/spine';+import type { SpineManager } from 'esengine/spine';import { SceneLoader } from './SceneLoader';import { useSettings } from '@/store/settingsStore';import { loadEditorSpine } from './spineLoad';@@ -102,6 +103,10 @@ class EngineHostImpl {this.targetFps_ = fps;this.app_?.setTargetFrameRate(fps);}+ /** The viewport's SpineManager (per-entity spine bindings); null until booted. */+ get spineManager(): SpineManager | null {+ return this.app_?.getPlugin(SpinePlugin)?.spineManager ?? null;+ }/** Animation names of a spine entity's loaded skeleton (for the inspector dropdown); empty if none. */spineAnimations(runtimeId: number): string[] {return this.app_?.getPlugin(SpinePlugin)?.spineManager?.getAnimations(runtimeId as never) ?? [];@@ -342,8 +347,9 @@ class EngineHostImpl {sceneData: SceneData,entityMap: Map<number, number>,toUrl: (ref: string) => string,+ resolvePath?: (ref: string) => string,): Promise<void> {- if (this.app_) await loadEditorSpine(this.app_, sceneData, entityMap, toUrl);+ if (this.app_) await loadEditorSpine(this.app_, sceneData, entityMap, toUrl, resolvePath);}private resize() {diff --git a/desktop/src/engine/Reconciler.ts b/desktop/src/engine/Reconciler.tsindex a39985396..85d6d0c23 100644--- a/desktop/src/engine/Reconciler.ts+++ b/desktop/src/engine/Reconciler.ts@@ -6,7 +6,7 @@ import type { EntityId } from '@/types';import { EngineHost } from './EngineHost';import { PerfMonitor } from './PerfMonitor';import { SceneModel, SceneModelImpl, type ModelEvent } from './SceneModel';-import { assetFieldType, componentByName, componentDefaults, isRenderComponent, componentEnable, type AnyComp, type WorldT } from './schema';+import { assetFieldType, spineSlotType, componentByName, componentDefaults, isRenderComponent, componentEnable, type AnyComp, type WorldT } from './schema';/*** Projects the model into the World.@@ -70,9 +70,14 @@ function foldHidden(c: SceneComp): SceneComp {type AssetResolver = (ref: string) => number;const UNRESOLVED: AssetResolver = () => 0;+/** Asset ref (`@uuid:<id>`) → project-relative path, null when unknown. */+type RefPathResolver = (ref: string) => string | null;+const UNRESOLVED_PATH: RefPathResolver = () => null;+export class ReconcilerImpl {private unsubscribe: (() => void) | null = null;private resolveAsset: AssetResolver = UNRESOLVED;+ private resolveRefPath: RefPathResolver = UNRESOLVED_PATH;constructor(private readonly model: SceneModelImpl) {}@@ -98,6 +103,16 @@ export class ReconcilerImpl {this.resolveAsset = fn ?? UNRESOLVED;}+ /**+ * Install the `@uuid:` → project-path resolver for PATH-VALUED asset slots+ * (spine skeleton/atlas). Those fields stay strings in the World — the spine+ * loaders fetch the pair themselves — so their refs resolve to a path, never+ * a handle. Installed alongside {@link setAssetResolver} by ProjectStore.+ */+ setRefPathResolver(fn: RefPathResolver | null): void {+ this.resolveRefPath = fn ?? UNRESOLVED_PATH;+ }+/*** Bulk path (boot / project load / play-stop): build the World from a resolved* scene and adopt the raw scene as the model. `resetWorldTo` returns source-id@@ -107,7 +122,10 @@ export class ReconcilerImpl {adopt(rawData: SceneData, resolvedData: SceneData): void {const world = EngineHost.mutableWorld();if (!world) return;- const map = resetWorldTo(world, worldProjection(resolvedData) as never) as Map<number, EntityId>;+ // The SDK scene resolver leaves the compound spine pair alone (it loads+ // through the SpineManager, not a typed handle loader) — resolveSceneRefs+ // turns those `@uuid:` refs into project paths for the World here.+ const map = resetWorldTo(world, worldProjection(this.resolveSceneRefs(resolvedData)) as never) as Map<number, EntityId>;this.model.adopt(rawData, map);}@@ -122,8 +140,7 @@ export class ReconcilerImpl {const data = this.model.current;if (!world || !data) return;PerfMonitor.measure('world.rebuild', () => {- const resolved = this.resolveRefs(data) as SceneData;- this.resolveAssetFields(resolved);+ const resolved = this.resolveSceneRefs(data);const map = resetWorldTo(world, worldProjection(resolved) as never) as Map<number, EntityId>;this.model.adopt(data, map);});@@ -266,23 +283,46 @@ export class ReconcilerImpl {out[key] = defaults[key];continue;}- const v = data[key];- out[key] = typeof v === 'string' && assetFieldType(type, key) ? this.resolveAsset(v) : this.resolveRefs(v);+ out[key] = this.resolveFieldValue(type, key, data[key]);}return out;}- /** Resolve plain-path asset-field refs left after the `@uuid:` pass (rebuild path). */- private resolveAssetFields(data: SceneData): void {- for (const e of data.entities) {- for (const c of e.components ?? []) {- const d = c.data as Record<string, unknown> | undefined;- if (!d) continue;- for (const [k, v] of Object.entries(d)) {- if (typeof v === 'string' && assetFieldType(c.type, k)) d[k] = this.resolveAsset(v);- }- }+ /**+ * Resolve one component field for the World, by what the field IS: asset+ * slots → live handles (`@uuid:` or a plain path), spine slots → project+ * paths (they stay strings — the spine loaders fetch the pair themselves),+ * anything else deep-resolves stray `@uuid:` strings to handles.+ */+ private resolveFieldValue(type: string, key: string, v: unknown): unknown {+ if (typeof v === 'string') {+ if (spineSlotType(type, key)) return this.resolveSpineRef(v);+ if (assetFieldType(type, key)) return this.resolveAsset(v);}+ return this.resolveRefs(v);+ }++ private resolveSpineRef(ref: string): string {+ if (!ref.startsWith(UUID_PREFIX)) return ref;+ return this.resolveRefPath(ref) ?? ref;+ }++ /** Clone the scene with every component field resolved via {@link resolveFieldValue}+ * (both bulk paths — adopt and rebuild — project through this). */+ private resolveSceneRefs(data: SceneData): SceneData {+ return {+ ...data,+ entities: (data.entities ?? []).map((e) => ({+ ...e,+ components: (e.components ?? []).map((c) => {+ const d = c.data as Record<string, unknown> | undefined;+ if (!d) return c;+ const out: Record<string, unknown> = {};+ for (const [k, v] of Object.entries(d)) out[k] = this.resolveFieldValue(c.type, k, v);+ return { ...c, data: out };+ }),+ })),+ } as SceneData;}/** Recursively replace `@uuid:<id>` strings with resolved asset handles. */diff --git a/desktop/src/engine/SceneStore.ts b/desktop/src/engine/SceneStore.tsindex c82feff50..9ee1dff27 100644--- a/desktop/src/engine/SceneStore.ts+++ b/desktop/src/engine/SceneStore.ts@@ -44,6 +44,11 @@ export class SceneStoreImpl {subscribe = (fn: () => void): (() => void) => this.store.subscribe(fn);getRevision = (): number => this.store.getState().revision;getStructureRevision = (): number => this.store.getState().structureRevision;++ /** Derived-from-runtime state changed without a model event (e.g. a spine+ * skeleton finished loading, so the inspector's animation/skin options+ * exist now) — bump the data revision so panels re-read. */+ poke = (): void => this.bump(false);}/** A change affects the tree (shape / name / kind / add-menu), not just a field value. */diff --git a/desktop/src/engine/schema.ts b/desktop/src/engine/schema.tsindex f57e1af4d..774577570 100644--- a/desktop/src/engine/schema.ts+++ b/desktop/src/engine/schema.ts@@ -1,6 +1,6 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team-import { getAllRegisteredComponents, getUserComponents, getComponent, getComponentAssetFieldDescriptors, getComponentFieldMeta, Light2DType } from 'esengine';+import { getAllRegisteredComponents, getUserComponents, getComponent, getComponentAssetFieldDescriptors, getComponentSpineFieldDescriptor, getComponentFieldMeta, Light2DType } from 'esengine';import type { App, SceneData } from 'esengine';import type { NodeKind, InspectorField, EnumOption, GradientValue, CurveValue } from '@/types';@@ -265,6 +265,23 @@ export function assetFieldType(compType: string, key: string): string | null {return null;}+/**+ * The spine slot a component field holds, or null. Spine skeleton/atlas are+ * PATH-VALUED asset refs: the component def carries them as a compound spine+ * descriptor (the pair loads together through the SpineManager), not as+ * handle-valued assetFields — so the World keeps the string and the Reconciler+ * must never handle-resolve them. The slot names match the SDK's+ * EditorAssetType spellings, which is what the asset picker filters on.+ */+export type SpineSlotType = 'spine-skeleton' | 'spine-atlas';+export function spineSlotType(compType: string, key: string): SpineSlotType | null {+ const d = getComponentSpineFieldDescriptor(compType);+ if (!d) return null;+ if (key === d.skeletonField) return 'spine-skeleton';+ if (key === d.atlasField) return 'spine-atlas';+ 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[] {@@ -371,7 +388,7 @@ function fieldFor(isColor: boolean,): InspectorField | null {const meta = fieldMetaFor(compType, key);- const at = assetFieldType(compType, key);+ const at = assetFieldType(compType, key) ?? spineSlotType(compType, key);let field: InspectorField | null;if (at) {field = { key, label: prettyLabel(key), type: 'asset', value: typeof value === 'string' ? value : 0, assetType: at };diff --git a/desktop/src/engine/spineLoad.ts b/desktop/src/engine/spineLoad.tsindex 9158ebcec..7b3447e82 100644--- a/desktop/src/engine/spineLoad.ts+++ b/desktop/src/engine/spineLoad.ts@@ -9,15 +9,21 @@ import { decodeImagePixels, type App, type SceneData } from 'esengine';* fetch as text/bytes; the atlas PNG is decoded to RGBA via the shared* `decodeImagePixels` (the same path the play realm uses — robust across the* editor's http/app:// origins). `toUrl` maps an asset ref to a fetchable URL,- * applied uniformly on fetch (so `resolveRef` stays identity).+ * applied uniformly on fetch. `resolvePath` maps a `@uuid:` ref to its project+ * path — the loader derives the atlas's page-texture paths from it (a raw uuid+ * ref has no directory), the same job the runtime Catalog does in play.*/-function editorSpineSource(toUrl: (ref: string) => string): RuntimeAssetSource {+function editorSpineSource(+ toUrl: (ref: string) => string,+ resolvePath: (ref: string) => string,+): RuntimeAssetSource {const fetchOk = async (ref: string, kind: string): Promise<Response> => {const r = await fetch(toUrl(ref));if (!r.ok) throw new Error(`spine ${kind} ${r.status}: ${ref}`);return r;};return {+ resolveRef: (ref) => resolvePath(ref),backend: {resolveUrl: (ref) => toUrl(ref),fetchText: async (ref) => (await fetchOk(ref, 'asset')).text(),@@ -40,6 +46,7 @@ export async function loadEditorSpine(sceneData: SceneData,entityMap: Map<number, number>,toUrl: (ref: string) => string,+ resolvePath: (ref: string) => string = (ref) => ref,): Promise<void> {const spineManager = app.getPlugin(SpinePlugin)?.spineManager;const module = app.wasmModule;@@ -49,7 +56,7 @@ export async function loadEditorSpine(try {await loadSpineSceneEntities({module,- source: editorSpineSource(toUrl),+ source: editorSpineSource(toUrl, resolvePath),spineManager,sceneData,entityMap: entityMap as Map<number, number>,diff --git a/desktop/src/engine/spineSync.ts b/desktop/src/engine/spineSync.tsnew file mode 100644index 000000000..ed5e63eb4--- /dev/null+++ b/desktop/src/engine/spineSync.ts@@ -0,0 +1,184 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file spineSync.ts+ * @brief Keeps the viewport's spine bindings a live projection of the model,+ * the same way the Reconciler keeps the World one. Spine instances live+ * OUTSIDE the World (per-entity bindings in the SpineManager, loaded+ * through the shared runtime loader), so World projection alone can't+ * keep them true. This module subscribes to the SceneModel and:+ *+ * - on `reset` (scene open / play-stop rebuild) re-binds every spine+ * entity — the rebuild despawned the old runtime entities, which+ * dropped their instances;+ * - on a skeleton/atlas ref edit reloads that entity's binding through+ * the SAME shared loader the scene load uses;+ * - on skin/animation/props edits applies them in place (live preview+ * without restarting the animation on unrelated field scrubs).+ *+ * ProjectStore installs it with the project's ref→URL transport; without+ * an install every event is a no-op (dev/automation scene loads bind+ * spine themselves, once).+ */+import { getComponentSpineFieldDescriptor } from 'esengine';+import type { SceneData } from 'esengine';+import { SceneModel, type ModelEvent } from './SceneModel';+import { SceneStore } from './SceneStore';+import { EngineHost } from './EngineHost';++type SceneEntity = SceneData['entities'][number];++/** What an entity's binding was loaded/applied from, for change detection. */+interface BoundState {+ skel: string;+ atlas: string;+ skin: string;+ animation: string;+ loop: boolean;+}++/** The project transport spine assets load over: ref → fetchable URL, and+ * `@uuid:` ref → project path (page-texture paths derive from the atlas dir). */+export interface SpineTransport {+ toUrl: (ref: string) => string;+ resolvePath: (ref: string) => string;+}++let transport: SpineTransport | null = null;+let subscribed = false;+const bound = new Map<number, BoundState>();+// Spine (re)loads are async (fetch + decode + side-module init); serialize them+// so two rapid ref edits can't finish out of order and leave the older skeleton.+let chain: Promise<void> = Promise.resolve();++/**+ * Install (or re-target) the sync for the open project's transport. Call+ * BEFORE the scene adopt so the model's `reset` performs the initial bind.+ */+export function installSpineSync(t: SpineTransport): void {+ transport = t;+ bound.clear();+ if (!subscribed) {+ subscribed = true;+ SceneModel.subscribe(onEvent);+ }+}++function onEvent(ev: ModelEvent): void {+ if (!transport) return;+ switch (ev.kind) {+ case 'reset':+ rebindAll();+ return;+ case 'entityAdded': // duplicate / paste / undo-of-delete+ syncEntity(ev.sourceId);+ return;+ case 'componentAdded':+ case 'componentChanged':+ if (getComponentSpineFieldDescriptor(ev.type)) syncEntity(ev.sourceId);+ return;+ case 'componentRemoved':+ if (getComponentSpineFieldDescriptor(ev.type)) unbind(ev.sourceId);+ return;+ case 'entityRemoved':+ bound.delete(ev.sourceId); // the World despawn already dropped the instance+ return;+ }+}++/** The entity's spine component (any component with a spine field descriptor). */+function spineComp(entity: SceneEntity): { type: string; d: Record<string, unknown> } | null {+ for (const c of entity.components ?? []) {+ if (getComponentSpineFieldDescriptor(c.type) && c.data) {+ return { type: c.type, d: c.data as Record<string, unknown> };+ }+ }+ return null;+}++function stateOf(type: string, d: Record<string, unknown>): BoundState {+ const desc = getComponentSpineFieldDescriptor(type)!;+ const str = (v: unknown): string => (typeof v === 'string' ? v : '');+ return {+ skel: str(d[desc.skeletonField]),+ atlas: str(d[desc.atlasField]),+ skin: str(d.skin),+ animation: str(d.animation),+ loop: d.loop !== false,+ };+}++/** Re-bind every spine entity from the current model (scene open / play-stop). */+function rebindAll(): void {+ bound.clear();+ const data = SceneModel.current;+ if (!data) return;+ const entityMap = new Map<number, number>();+ const entities: SceneEntity[] = [];+ for (const e of data.entities) {+ const sc = spineComp(e);+ if (!sc) continue;+ const rt = SceneModel.runtimeFor(e.id);+ if (rt === undefined) continue;+ const next = stateOf(sc.type, sc.d);+ if (!next.skel || !next.atlas) continue;+ bound.set(e.id, next);+ entityMap.set(e.id, rt as number);+ entities.push(e);+ }+ if (entities.length === 0) return;+ load({ ...data, entities }, entityMap);+}++/** Project one entity's spine component: ref change → reload, else apply in place. */+function syncEntity(sourceId: number): void {+ const entity = SceneModel.entityBySource(sourceId);+ const rt = SceneModel.runtimeFor(sourceId);+ const spine = EngineHost.spineManager;+ if (!entity || rt === undefined || !spine) return;+ const sc = spineComp(entity);+ if (!sc) return;++ const next = stateOf(sc.type, sc.d);+ const prev = bound.get(sourceId);+ bound.set(sourceId, next);++ if (!prev || prev.skel !== next.skel || prev.atlas !== next.atlas) {+ spine.removeEntity(rt as never);+ if (!next.skel || !next.atlas) return;+ const data = SceneModel.current;+ if (!data) return;+ load({ ...data, entities: [entity] }, new Map([[sourceId, rt as number]]));+ return;+ }++ // Same binding — apply the editable spine state in place. Props are+ // idempotent; skin/animation only on change so scrubbing an unrelated+ // field never restarts the animation.+ spine.setEntityProps(rt as never, {+ skeletonScale: typeof sc.d.skeletonScale === 'number' ? sc.d.skeletonScale : 1,+ flipX: sc.d.flipX === true,+ flipY: sc.d.flipY === true,+ layer: typeof sc.d.layer === 'number' ? sc.d.layer : 0,+ });+ if (prev.skin !== next.skin && next.skin) spine.setSkin(rt as never, next.skin);+ if (prev.animation !== next.animation || prev.loop !== next.loop) {+ if (next.animation) spine.setAnimation(rt as never, next.animation, next.loop);+ }+}++function unbind(sourceId: number): void {+ bound.delete(sourceId);+ const rt = SceneModel.runtimeFor(sourceId);+ if (rt !== undefined) EngineHost.spineManager?.removeEntity(rt as never);+}++/** Queue a load through the shared loader; poke panels when it lands so the+ * animation/skin dropdowns pick up the fresh skeleton's options. */+function load(sceneData: SceneData, entityMap: Map<number, number>): void {+ const t = transport!;+ chain = chain+ .then(() => EngineHost.loadSpine(sceneData, entityMap, t.toUrl, t.resolvePath))+ .then(() => SceneStore.poke())+ .catch((err) => console.warn('[spine] viewport binding load failed', err));+}diff --git a/desktop/src/panels/Details.tsx b/desktop/src/panels/Details.tsxindex a0a532efc..0f849533e 100644--- a/desktop/src/panels/Details.tsx+++ b/desktop/src/panels/Details.tsx@@ -675,6 +675,9 @@ export function AssetControl({const pop = usePopover();const [q, setQ] = useState('');const info = ProjectStore.assetInfo(value);+ // Handle-valued slots clear to 0; path-valued slots (spine skeleton/atlas)+ // are string component fields, so "no asset" is the empty string.+ const empty = assetType === 'spine-skeleton' || assetType === 'spine-atlas' ? '' : 0;const setRefFromPath = (path: string) => {onBegin?.();@@ -747,7 +750,7 @@ export function AssetControl({title="Clear"onClick={() => {onBegin?.();- onChange(0);+ onChange(empty);onEnd?.();}}>@@ -758,7 +761,7 @@ export function AssetControl({<Popover anchor={pop.anchor} width={Math.max(pop.anchor.width, 240)} onClose={close}><SearchField flush className="dd-search" iconSize={12} autoFocus placeholder="Search assets" value={q} onChange={setQ} /><div className="asset-grid">- <button type="button" className={`asset-opt${value === 0 || !info ? ' on' : ''}`} onClick={() => pick(0)}>+ <button type="button" className={`asset-opt${!info ? ' on' : ''}`} onClick={() => pick(empty)}><span className="th"><X size={13} strokeWidth={2} /></span>diff --git a/desktop/src/project/ProjectStore.ts b/desktop/src/project/ProjectStore.tsindex 6b4357878..069f93921 100644--- a/desktop/src/project/ProjectStore.ts+++ b/desktop/src/project/ProjectStore.ts@@ -1,7 +1,7 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Teamimport { createStore } from 'zustand/vanilla';-import { getComponent, Assets, migratePrefabData, extractPrefab, diffAgainstSource, applyOverridesToSource, setTextureParams, TextureFilter, TextureWrap, Renderer } from 'esengine';+import { getComponent, getEditorType, Assets, migratePrefabData, extractPrefab, diffAgainstSource, applyOverridesToSource, setTextureParams, TextureFilter, TextureWrap, Renderer } from 'esengine';import { readTextureImportSettings } from './assetImporter';import type { SceneData, PrefabData, ExtractEntity, ProcessedEntity, PhysicsPluginConfig } from 'esengine';import { EngineHost } from '@/engine/EngineHost';@@ -13,6 +13,7 @@ import { expandScenePrefabs, collapseScenePrefabs } from '@/engine/PrefabInstancimport { SceneCommands } from '@/engine/SceneCommands';import { setPrefabBaseResolver } from '@/engine/SceneQuery';import { setUserSchemas, userSchema, setBitmaskSource, setEnumSource, type UserComponentSchema } from '@/engine/schema';+import { installSpineSync, type SpineTransport } from '@/engine/spineSync';import { useSelection } from '@/store/selectionStore';import { Toasts } from '@/store/Toasts';import { confirmDiscard } from './discardGuard';@@ -31,10 +32,14 @@ function normalizeLayerMasks(masks?: number[]): number[] {}/** Whether an asset of the editor `type` is a valid pick for a `fieldType` slot. */-function assetMatchesSlot(type: AssetType, fieldType?: string): boolean {+function assetMatchesSlot(type: AssetType, path: string, fieldType?: string): boolean {if (!fieldType) return true;// A 'texture' slot accepts any image (texture or sprite); others match by name.if (fieldType === 'texture') return type === 'texture' || type === 'sprite';+ // Spine slots discriminate the shared 'spine' Content-Browser type by+ // extension, through the SDK's own classification (.skel vs .atlas) — the+ // same vocabulary the cook's dep scan uses.+ if (fieldType === 'spine-skeleton' || fieldType === 'spine-atlas') return getEditorType(path) === fieldType;return type === fieldType;}@@ -315,30 +320,18 @@ class ProjectStoreImpl {EditorHistory.clear();useSelection.getState().select(null);// Incremental recreate (duplicate / undo / play-stop) re-resolves @uuid:→handle- // from the same preload result — for all types, not just textures.+ // from the same preload result — for all types, not just textures. Spine+ // slots resolve to project paths instead (they stay strings in the World).Reconciler.setAssetResolver((ref) => this.handleForRef(ref));+ Reconciler.setRefPathResolver((ref) => this.resolveRef(ref));+ // Spine bindings (skeleton/atlas/pages → SpineManager) are a live projection+ // of the model, driven by model events: adopt's `reset` performs the initial+ // bind, and later ref/field edits keep the viewport true (see spineSync).+ installSpineSync(this.spineTransport());Reconciler.adopt(expandedRaw, resolved);// Re-apply prefab-instance tags (adopt cleared them) so save can collapse.for (const { id, tag } of tags) SceneModel.setPrefabTag(id, tag);- // Bind spine entities' skeletons/atlas/textures into the SpineManager so spine- // renders in the viewport (the World holds the SpineAnimation components, but- // spine assets load separately from Assets via side modules). The- // entityMap is the Reconciler's source→runtime binding; refs resolve through- // the project's estella:// transport.- const spineMap = new Map<number, number>();- for (const e of expandedRaw.entities) {- const id = (e as { id?: number }).id;- if (id === undefined) continue;- const rt = SceneModel.runtimeFor(id);- if (rt !== undefined) spineMap.set(id, rt as number);- }- await EngineHost.loadSpine(expandedRaw, spineMap, (ref) =>- ref.startsWith('@uuid:')- ? `estella://project/${this.resolveRef(ref) ?? ''}`- : `estella://project/${ref.replace(/^\//, '')}`,- );-EngineHost.syncEditorViewToScene();this.store.setState({ project: { ...st, currentScene: rel } });this.knownSceneText = text;@@ -380,6 +373,8 @@ class ProjectStoreImpl {EditorHistory.clear();useSelection.getState().select(null);Reconciler.setAssetResolver((ref) => this.handleForRef(ref));+ Reconciler.setRefPathResolver((ref) => this.resolveRef(ref));+ installSpineSync(this.spineTransport());Reconciler.adopt(blank, blank); // no @uuid: refs → resolved === rawEngineHost.syncEditorViewToScene();this.store.setState({ project: { ...st, currentScene: null } });@@ -469,6 +464,18 @@ class ProjectStoreImpl {return this.uuidToPath.get(uuid) ?? null;}+ /** The project transport spine assets load over: ref → `estella://` URL for+ * fetches, `@uuid:` ref → project path for atlas-dir derivation. */+ private spineTransport(): SpineTransport {+ return {+ toUrl: (ref) =>+ ref.startsWith(UUID_PREFIX)+ ? `estella://project/${this.resolveRef(ref) ?? ''}`+ : `estella://project/${ref.replace(/^\//, '')}`,+ resolvePath: (ref) => this.resolveRef(ref) ?? ref,+ };+ }+/** The live GL handle for a uuid. Textures read the engine's live cache (so a* just-assigned texture resolves); material/font fall back to the scene preload. */private handleForRef(ref: string): number {@@ -924,7 +931,7 @@ class ProjectStoreImpl {for (const [uuid, path] of this.uuidToPath) {const name = path.split('/').pop() ?? path;const type = assetTypeOf(name);- if (!assetMatchesSlot(type, fieldType)) continue;+ if (!assetMatchesSlot(type, path, fieldType)) continue;out.push({ ref: UUID_PREFIX + uuid, path, name, type });}return out.sort((a, b) => a.name.localeCompare(b.name));@@ -941,6 +948,9 @@ class ProjectStoreImpl {const uuid = this.pathToUuid.get(path);if (!uuid) return null;const ref = UUID_PREFIX + uuid;+ // Spine slots are path-valued: nothing to preload here — the spine binding+ // (skeleton + atlas + pages) loads as a pair when the component syncs.+ if (assetType === 'spine-skeleton' || assetType === 'spine-atlas') return ref;const assets = EngineHost.getResource(Assets);if (assets) {try {diff --git a/desktop/tests/schema.test.ts b/desktop/tests/schema.test.tsindex 2a115ccd1..55aa6305d 100644--- a/desktop/tests/schema.test.ts+++ b/desktop/tests/schema.test.ts@@ -6,7 +6,7 @@* the JSON-first rewrite (REARCH_SERIALIZATION.md) will lean on.*/import { describe, it, expect } from 'vitest';-import { prettyLabel, hexToRgba, angleZToQuat, inferField } from '@/engine/schema';+import { prettyLabel, hexToRgba, angleZToQuat, inferField, assetFieldType, spineSlotType } from '@/engine/schema';describe('prettyLabel', () => {it('splits camelCase and capitalizes', () => {@@ -72,3 +72,19 @@ describe('inferField', () => {expect(inferField('weird', { foo: 1 }, false)).toBeNull();});});++describe('spineSlotType', () => {+ it('maps the component def\'s compound spine descriptor to skeleton/atlas slots', () => {+ expect(spineSlotType('SpineAnimation', 'skeletonPath')).toBe('spine-skeleton');+ expect(spineSlotType('SpineAnimation', 'atlasPath')).toBe('spine-atlas');+ });+ it('is null for non-spine fields and non-spine components', () => {+ expect(spineSlotType('SpineAnimation', 'animation')).toBeNull();+ expect(spineSlotType('Sprite', 'texture')).toBeNull();+ });+ it('stays disjoint from assetFieldType — spine slots are path-valued, never handle-resolved', () => {+ expect(assetFieldType('SpineAnimation', 'skeletonPath')).toBeNull();+ expect(assetFieldType('SpineAnimation', 'atlasPath')).toBeNull();+ expect(assetFieldType('SpineAnimation', 'material')).toBe('material');+ });+});