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): spine skeleton/atlas become first-class asset slots

yhhfe97c4fe25ba
diff --git a/desktop/src/engine/EngineHost.ts b/desktop/src/engine/EngineHost.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.tsx
index 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.ts
index 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 Team
import { 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/PrefabInstanc
import { 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 === raw
EngineHost.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.ts
index 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');
+ });
+});