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): inspector asset control + drag-assign (REARCH_ASSETS A3)

esengine7d324b38b9e4
diff --git a/desktop/src/engine/schema.ts b/desktop/src/engine/schema.ts
index 06c96eada..6ac8aae64 100644
--- a/desktop/src/engine/schema.ts
+++ b/desktop/src/engine/schema.ts
@@ -96,18 +96,6 @@ export function componentCategory(name: string, isUser = false): string {
return 'Other';
}
-/** The editable fields of one component (its live data introspected by shape). */
-export function componentFields(def: AnyComp, data: Record<string, unknown>): InspectorField[] {
- const colorKeys = new Set<string>(def.colorKeys);
- const fields: InspectorField[] = [];
- for (const key of Object.keys(def._default as Record<string, unknown>)) {
- if (DERIVED_FIELDS.has(key)) continue;
- const f = inferField(key, data[key], colorKeys.has(key));
- if (f) fields.push(f);
- }
- return fields;
-}
-
// — Field value inference (matches the JS data shape world.get/set use) —
const RAD2DEG = 180 / Math.PI;
@@ -175,6 +163,8 @@ export interface UserComponentSchema {
isTag: boolean;
default: Record<string, unknown>;
colorKeys: string[];
+ /** Asset-ref fields (e.g. `[{field:'texture', type:'texture'}]`). */
+ assetFields?: Array<{ field: string; type: string }>;
}
const userSchemas = new Map<string, UserComponentSchema>();
@@ -197,23 +187,76 @@ export function isColorKey(compType: string, key: string): boolean {
return new Set(userSchema(compType)?.colorKeys ?? []).has(key);
}
+// — Asset-ref fields (which component fields hold a texture/material/font/... ref) —
+//
+// Editor presentation policy (like COMPONENT_CATEGORY): the engine's
+// AssetFieldRegistry isn't exported from the built `esengine` types, so the
+// builtin map is mirrored here; user/script components declare their asset fields
+// in schemas.json. The inspector renders these as an asset control, not a raw
+// `@uuid:` string. Mirror of sdk AssetFieldRegistry.initBuiltinAssetFields.
+const BUILTIN_ASSET_FIELDS: Record<string, Record<string, string>> = {
+ Sprite: { texture: 'texture', material: 'material' },
+ SpineAnimation: { material: 'material' },
+ BitmapText: { font: 'font' },
+ Image: { texture: 'texture', material: 'material' },
+ UIRenderer: { texture: 'texture', material: 'material' },
+ SpriteAnimator: { clip: 'anim-clip' },
+ AudioSource: { clip: 'audio' },
+ ParticleEmitter: { texture: 'texture', material: 'material' },
+ Tilemap: { source: 'tilemap' },
+ TilemapLayer: { tileset: 'texture' },
+ TimelinePlayer: { timeline: 'timeline' },
+};
+
+/** The asset kind a component field holds (texture/material/font/...), or null. */
+export function assetFieldType(compType: string, key: string): string | null {
+ const builtin = BUILTIN_ASSET_FIELDS[compType]?.[key];
+ if (builtin) return builtin;
+ for (const f of userSchema(compType)?.assetFields ?? []) if (f.field === key) return f.type;
+ return null;
+}
+
/**
- * The editable fields of a component from the MODEL's stored data, resolving the
- * field shape from (in order): the engine registry, the user schema, or — as a
- * best-effort fallback — the data values themselves. `DERIVED_FIELDS` are skipped.
+ * Build one inspector field: an **asset control** for asset-ref fields (carrying
+ * the `@uuid:` ref or 0 for none), else a value-shape-inferred control.
+ */
+function fieldFor(
+ compType: string,
+ key: string,
+ value: unknown,
+ isColor: boolean,
+): InspectorField | null {
+ const at = assetFieldType(compType, key);
+ if (at) {
+ return {
+ key,
+ label: prettyLabel(key),
+ type: 'asset',
+ value: typeof value === 'string' ? value : 0,
+ assetType: at,
+ };
+ }
+ return inferField(key, value, isColor);
+}
+
+/**
+ * The editable fields of a component from the MODEL's stored data. Field shape
+ * comes from (in order): the engine registry, the user schema, or — as a
+ * best-effort fallback — the data values themselves; asset-ref fields become an
+ * asset control. `DERIVED_FIELDS` are skipped.
*/
export function inspectorFields(compType: string, data: Record<string, unknown>): InspectorField[] {
const def = componentByName(compType);
- if (def) return componentFields(def, data);
-
- const schema = userSchema(compType);
- const colorKeys = new Set(schema?.colorKeys ?? []);
- const keys = schema ? Object.keys(schema.default) : Object.keys(data);
+ const schema = def ? undefined : userSchema(compType);
+ const colorKeys = new Set<string>(def ? def.colorKeys : (schema?.colorKeys ?? []));
+ const defaults = def ? componentDefaults(def) : schema?.default;
+ // Field order: the registered / schema defaults; else the stored data's keys.
+ const keys = defaults ? Object.keys(defaults) : Object.keys(data);
const fields: InspectorField[] = [];
for (const key of keys) {
if (DERIVED_FIELDS.has(key)) continue;
- const v = key in data ? data[key] : schema?.default[key];
- const f = inferField(key, v, colorKeys.has(key));
+ const value = key in data ? data[key] : defaults?.[key];
+ const f = fieldFor(compType, key, value, colorKeys.has(key));
if (f) fields.push(f);
}
return fields;
diff --git a/desktop/src/panels/ContentBrowser.tsx b/desktop/src/panels/ContentBrowser.tsx
index 5a22ff51f..0c83d99ad 100644
--- a/desktop/src/panels/ContentBrowser.tsx
+++ b/desktop/src/panels/ContentBrowser.tsx
@@ -163,6 +163,14 @@ export function ContentBrowser() {
key={e.name}
type="button"
className="tile"
+ // Files are draggable onto inspector asset fields (drag-assign);
+ // the payload is the project-relative path, resolved to a @uuid: ref on drop.
+ draggable={!e.isDir}
+ onDragStart={(ev) => {
+ ev.dataTransfer.effectAllowed = 'copy';
+ ev.dataTransfer.setData('application/x-estella-asset', path);
+ ev.dataTransfer.setData('text/plain', path);
+ }}
onDoubleClick={() => e.isDir && setCwd(path)}
onContextMenu={(ev) => {
ev.preventDefault();
diff --git a/desktop/src/panels/Details.tsx b/desktop/src/panels/Details.tsx
index b90ffb9de..e2f7b2bb8 100644
--- a/desktop/src/panels/Details.tsx
+++ b/desktop/src/panels/Details.tsx
@@ -7,6 +7,7 @@ import { SceneQuery } from '@/engine/SceneQuery';
import { SceneModel } from '@/engine/SceneModel';
import { SceneCommands } from '@/engine/SceneCommands';
import { modelAddableComponentEntries } from '@/engine/schema';
+import { ProjectStore } from '@/project/ProjectStore';
import { ContextMenu } from '@/components/Menu';
import { AddComponentMenu } from '@/components/AddComponentMenu';
import type { InspectorComponent, InspectorField, EntityId } from '@/types';
@@ -191,6 +192,72 @@ function ColorControl({
);
}
+// An asset-ref field: a drop target showing the bound asset (texture thumbnail +
+// name) with a clear button. Drag-assign drops a project-relative path; clear
+// sets the ref to 0 (none). The ref itself is a portable `@uuid:` string.
+function AssetControl({
+ value,
+ assetType,
+ onBegin,
+ onEnd,
+ onChange,
+}: ControlGesture & {
+ value: string | number;
+ assetType?: string;
+ onChange: (v: string | number) => void;
+}) {
+ const [over, setOver] = useState(false);
+ const info = ProjectStore.assetInfo(value);
+
+ const onDrop = (e: React.DragEvent) => {
+ e.preventDefault();
+ setOver(false);
+ const path = e.dataTransfer.getData('application/x-estella-asset') || e.dataTransfer.getData('text/plain');
+ if (!path) return;
+ onBegin?.();
+ void ProjectStore.assetRefForPath(path, assetType).then((ref) => {
+ if (ref) onChange(ref);
+ onEnd?.();
+ });
+ };
+
+ return (
+ <div
+ className={`asset-field${over ? ' is-over' : ''}`}
+ title={info?.path}
+ onDragOver={(e) => {
+ e.preventDefault();
+ if (!over) setOver(true);
+ }}
+ onDragLeave={() => setOver(false)}
+ onDrop={onDrop}
+ >
+ <span className="asset-field__thumb">
+ {assetType === 'texture' && info ? (
+ <img src={`estella://project/${info.path}`} alt="" draggable={false} />
+ ) : (
+ <Box size={13} strokeWidth={1.6} />
+ )}
+ </span>
+ <span className="asset-field__name">{info ? info.name : 'None'}</span>
+ {info && (
+ <button
+ type="button"
+ className="asset-field__clear"
+ title="Clear"
+ onClick={() => {
+ onBegin?.();
+ onChange(0);
+ onEnd?.();
+ }}
+ >
+ ×
+ </button>
+ )}
+ </div>
+ );
+}
+
function FieldRow({
entity,
comp,
@@ -233,6 +300,17 @@ function FieldRow({
<ColorControl value={field.value as string} onBegin={begin} onEnd={end} onChange={apply} />
);
break;
+ case 'asset':
+ control = (
+ <AssetControl
+ value={field.value as string | number}
+ assetType={field.assetType}
+ onBegin={begin}
+ onEnd={end}
+ onChange={apply}
+ />
+ );
+ break;
default:
control = (
<StringControl value={String(field.value)} onBegin={begin} onEnd={end} onChange={apply} />
diff --git a/desktop/src/project/ProjectStore.ts b/desktop/src/project/ProjectStore.ts
index 60f2f9086..435957dae 100644
--- a/desktop/src/project/ProjectStore.ts
+++ b/desktop/src/project/ProjectStore.ts
@@ -60,6 +60,9 @@ class ProjectStoreImpl {
/** uuid → project-relative path, scanned from `.meta` sidecars — the editor's
* asset registry. The engine `Assets` loader resolves refs through it. */
private readonly uuidToPath = new Map<string, string>();
+ /** path → uuid (reverse), so a Content Browser drag (which carries a path) can
+ * be turned into a portable `@uuid:` ref for the model. */
+ private readonly pathToUuid = new Map<string, string>();
/** The latest scene preload result; the Reconciler resolver reads handles from
* it for entities recreated incrementally (duplicate / undo / play-stop). */
private lastAssetResult: PreloadResult | null = null;
@@ -202,10 +205,15 @@ class ProjectStoreImpl {
*/
private async buildAssetRegistry(): Promise<void> {
this.uuidToPath.clear();
+ this.pathToUuid.clear();
if (!this.state) return;
try {
const { index } = await window.estella.project.scanAssets();
- for (const e of index.entries) this.uuidToPath.set(e.uuid.toLowerCase(), e.path);
+ for (const e of index.entries) {
+ const uuid = e.uuid.toLowerCase();
+ this.uuidToPath.set(uuid, e.path);
+ this.pathToUuid.set(e.path, uuid);
+ }
} catch (err) {
console.warn('[project] asset scan failed', err);
}
@@ -224,12 +232,48 @@ class ProjectStoreImpl {
return this.uuidToPath.get(ref.slice(UUID_PREFIX.length).toLowerCase()) ?? null;
}
- /** The live GL handle for a uuid, from the latest preload result (any type). */
+ /** 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 handleForUuid(uuid: string): number {
+ const ref = UUID_PREFIX + uuid;
+ const tex = EngineHost.getResource(Assets)?.getTexture(ref);
+ if (tex) return tex.handle;
const path = this.uuidToPath.get(uuid.toLowerCase());
const r = this.lastAssetResult;
if (!path || !r) return 0;
- return r.textureHandles.get(path) ?? r.materialHandles.get(path) ?? r.fontHandles.get(path) ?? 0;
+ return r.materialHandles.get(path) ?? r.fontHandles.get(path) ?? 0;
+ }
+
+ /** Display info for an asset ref (`@uuid:`), or null (none / unresolved). For
+ * the inspector's asset control: the project-relative path + a leaf name. */
+ assetInfo(ref: unknown): { path: string; name: string } | null {
+ if (typeof ref !== 'string' || !ref.startsWith(UUID_PREFIX)) return null;
+ const path = this.uuidToPath.get(ref.slice(UUID_PREFIX.length).toLowerCase());
+ return path ? { path, name: path.split('/').pop() ?? path } : null;
+ }
+
+ /**
+ * Turn a Content-Browser drag (a project-relative path) into a portable
+ * `@uuid:` ref, preloading the asset so the Reconciler's synchronous projection
+ * finds its handle when the model field is set. Textures resolve live; other
+ * types are best-effort (resolved at scene load). Returns null if the path
+ * isn't a tracked asset.
+ */
+ async assetRefForPath(path: string, assetType?: string): Promise<string | null> {
+ const uuid = this.pathToUuid.get(path);
+ if (!uuid) return null;
+ const ref = UUID_PREFIX + uuid;
+ const assets = EngineHost.getResource(Assets);
+ if (assets) {
+ try {
+ if (assetType === 'material') await assets.loadMaterial(ref);
+ else if (assetType === 'font') await assets.loadFont(ref);
+ else await assets.loadTexture(ref);
+ } catch {
+ // non-loadable for this slot — the field still stores the ref losslessly
+ }
+ }
+ return ref;
}
/**
diff --git a/desktop/src/theme/app.css b/desktop/src/theme/app.css
index 6af61219e..5ed850561 100644
--- a/desktop/src/theme/app.css
+++ b/desktop/src/theme/app.css
@@ -1136,6 +1136,63 @@
color: var(--text-hi);
}
+/* Inspector asset-ref control: thumbnail + name + clear; a drag-assign drop target. */
+.asset-field {
+ display: flex;
+ align-items: center;
+ gap: 7px;
+ background: var(--input);
+ border: 1px solid var(--line);
+ border-radius: var(--r-sm);
+ padding: 4px 6px;
+ min-height: 28px;
+}
+.asset-field.is-over {
+ border-color: var(--star-line);
+ background: var(--star-soft, rgba(120, 160, 255, 0.1));
+}
+.asset-field__thumb {
+ display: flex;
+ align-items: center;
+ justify-content: center;
+ width: 20px;
+ height: 20px;
+ flex-shrink: 0;
+ border-radius: var(--r-xs);
+ background: rgba(0, 0, 0, 0.25);
+ color: var(--text-dim);
+ overflow: hidden;
+}
+.asset-field__thumb img {
+ width: 100%;
+ height: 100%;
+ object-fit: contain;
+}
+.asset-field__name {
+ flex: 1;
+ min-width: 0;
+ font-size: var(--fs-sm);
+ color: var(--text-hi);
+ overflow: hidden;
+ text-overflow: ellipsis;
+ white-space: nowrap;
+}
+.asset-field__clear {
+ flex-shrink: 0;
+ width: 16px;
+ height: 16px;
+ line-height: 14px;
+ border: none;
+ border-radius: var(--r-xs);
+ background: transparent;
+ color: var(--text-dim);
+ cursor: pointer;
+}
+.asset-field__clear:hover {
+ background: rgba(255, 255, 255, 0.1);
+ color: var(--text-hi);
+}
+
.text-input {
width: 100%;
background: var(--input);
diff --git a/desktop/src/types.ts b/desktop/src/types.ts
index d5c734b08..cef45a7ca 100644
--- a/desktop/src/types.ts
+++ b/desktop/src/types.ts
@@ -32,7 +32,8 @@ export type InspectorFieldType =
| 'vec2'
| 'vec3'
| 'angle' // 2D rotation: a quaternion shown/edited as Z degrees
- | 'color';
+ | 'color'
+ | 'asset'; // a texture/material/font/... ref (@uuid: string, or 0 for none)
export type InspectorFieldValue =
| number
@@ -47,6 +48,8 @@ export interface InspectorField {
label: string;
type: InspectorFieldType;
value: InspectorFieldValue;
+ /** For `type: 'asset'` — the asset kind (texture/material/font/...). */
+ assetType?: string;
}
export interface InspectorComponent {
diff --git a/desktop/tests/inspector-model.test.ts b/desktop/tests/inspector-model.test.ts
index 6726b3974..b94176207 100644
--- a/desktop/tests/inspector-model.test.ts
+++ b/desktop/tests/inspector-model.test.ts
@@ -91,4 +91,31 @@ describe('Unknown-component inspector (schemas.json consumer)', () => {
expect(wave).toBeDefined();
expect(wave!.fields.find((f) => f.key === 'amplitude')!.value).toBe(5);
});
+
+ it('renders a component asset-ref field as an asset control, not a raw uuid', () => {
+ const ref = '@uuid:44444444-4444-4444-8444-444444444444';
+ const fresh = EditorSession.create();
+ fresh.model.adopt(
+ {
+ version: '1.0',
+ name: 's',
+ entities: [
+ {
+ id: 1,
+ name: 'S',
+ parent: null,
+ children: [],
+ components: [{ type: 'Sprite', data: { texture: ref, color: { r: 1, g: 1, b: 1, a: 1 } } }],
+ },
+ ],
+ } as unknown as SceneData,
+ new Map([[1, 1]]),
+ );
+ const sprite = fresh.query.readInspector(1).find((c) => c.name === 'Sprite');
+ const tex = sprite!.fields.find((f) => f.key === 'texture');
+ // Sprite.texture is a builtin asset field → an asset control carrying the ref.
+ expect(tex!.type).toBe('asset');
+ expect(tex!.assetType).toBe('texture');
+ expect(tex!.value).toBe(ref);
+ });
});