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): inspector asset control + drag-assign (REARCH_ASSETS A3)
esengine7d324b38b9e4
diff --git a/desktop/src/engine/schema.ts b/desktop/src/engine/schema.tsindex 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.tsxindex 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.tsxindex 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.tsindex 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.cssindex 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.tsindex 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.tsindex 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);+ });});