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(assets): an asset path written into an engine component at run time is loaded into its handle

yhhb4d02fd490bc
diff --git a/docs/astro/src/content/docs/graphics/sprites.mdx b/docs/astro/src/content/docs/graphics/sprites.mdx
index 8a1d248fc..12ed04748 100644
--- a/docs/astro/src/content/docs/graphics/sprites.mdx
+++ b/docs/astro/src/content/docs/graphics/sprites.mdx
@@ -39,7 +39,7 @@ Content Browser onto an entity, or set the Sprite's texture field in Details.
| Field | Default | Description |
|---|---|---|
-| `texture` | `0` | Texture handle from a loader (`0` = untextured, draws a white quad). |
+| `texture` | `0` | Texture handle from a loader (`0` = untextured, draws a white quad). An asset path written here at run time (`insert(Sprite, { texture: 'assets/hero.png' })`) is loaded and swapped for its handle; the field reads `0` until the load lands. |
| `color` | `{1,1,1,1}` | Tint multiplied into the texture (white = unchanged). |
| `size` | `{100,100}` | Rendered size in world units. |
| `pivot` | `{0.5,0.5}` | Anchor point the sprite rotates and scales about, as a fraction of its `size`. Values outside 0–1 sit off the sprite. |
diff --git a/docs/astro/src/content/docs/zh-cn/graphics/sprites.mdx b/docs/astro/src/content/docs/zh-cn/graphics/sprites.mdx
index fe3413a10..6dd7ebbee 100644
--- a/docs/astro/src/content/docs/zh-cn/graphics/sprites.mdx
+++ b/docs/astro/src/content/docs/zh-cn/graphics/sprites.mdx
@@ -36,7 +36,7 @@ const spawnPlayer = defineSystem([Commands(), Res(Assets)], async (cmds, assets)
| 字段 | 默认 | 说明 |
|---|---|---|
-| `texture` | `0` | 加载器给的纹理句柄(`0` = 无纹理,画白色四边形)。 |
+| `texture` | `0` | 加载器给的纹理句柄(`0` = 无纹理,画白色四边形)。运行时直接写资源路径(`insert(Sprite, { texture: 'assets/hero.png' })`)也可以:引擎会加载并换成句柄,加载完成前字段读到的是 `0`。 |
| `color` | `{1,1,1,1}` | 乘进纹理的着色(白 = 不变)。 |
| `size` | `{100,100}` | 渲染尺寸,世界单位。 |
| `pivot` | `{0.5,0.5}` | 精灵旋转/缩放所绕的轴心点,取值是相对 `size` 的比例。超出 0–1 就落在精灵外面。 |
diff --git a/sdk/src/asset/assetReferenceTracking.ts b/sdk/src/asset/assetReferenceTracking.ts
index cd54fe0ab..6aa379559 100644
--- a/sdk/src/asset/assetReferenceTracking.ts
+++ b/sdk/src/asset/assetReferenceTracking.ts
@@ -1,12 +1,26 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import type { World } from '../ecs/world';
+import type { AnyComponentDef } from '../ecs/component';
+import type { Entity } from '../types';
import type { Assets } from './Assets';
import { AssetRefCounter } from './AssetRefCounter';
+import { SCENE_FORMAT_VERSION, type SceneData } from '../scene/scene';
+import { prepareSpawnOwnership } from '../prefab/preparedAssetOwnership';
+import { log } from '../util/logger';
const subscribed = new WeakSet<World>();
-/** One World observer, resolving its current asset resource at notification time. */
+/**
+ * Bind a World to the asset layer of its App — one call on every core (web,
+ * packaged, native). Two things a world needs from it:
+ * * references are dropped when an entity goes;
+ * * an asset PATH written into an engine-backed component at run time
+ * (`cmds.spawn().insert(Sprite, { texture: 'assets/hero.png' })`) is loaded
+ * and replaced by its handle, through the same preload and resolve a scene
+ * file goes through, and held for as long as the entity is.
+ * `current` is read at notification time, so a replaced Assets is the one used.
+ */
export function bindAssetReferenceTracking(
world: World, assets: Assets, current: () => Assets | null | undefined,
): void {
@@ -14,4 +28,54 @@ export function bindAssetReferenceTracking(
if (subscribed.has(world)) return;
subscribed.add(world);
world.onDespawn(entity => current()?.getRefCounter()?.removeAllRefsForEntity(entity));
+ world.setAssetFieldResolver((entity, component, authored) => {
+ const live = current();
+ if (live) void resolveAssetFields(world, live, entity, component, authored);
+ });
+}
+
+/** The fields this component was given as paths, loaded, and written in as handles once they are. */
+async function resolveAssetFields(
+ world: World, assets: Assets, entity: Entity, component: AnyComponentDef, authored: Record<string, unknown>,
+): Promise<void> {
+ // A one-entity scene: the loader that understands every asset field, atlas
+ // frames included, is the scene's — a second one would be a second author.
+ const data = { ...authored };
+ const scene: SceneData = {
+ version: SCENE_FORMAT_VERSION,
+ name: `${component._name}@${entity}`,
+ entities: [{ id: 0, name: '', parent: null, children: [], components: [{ type: component._name, data }], visible: true }],
+ } as SceneData;
+ try {
+ const result = await assets.preloadSceneAssets(scene);
+ const ownership = prepareSpawnOwnership(scene, result, assets.entityScopes, assets.resolveRef?.bind(assets));
+ assets.resolveSceneAssetPaths(scene, result);
+ try {
+ if (!world.valid(entity) || !world.has(entity, component)) return;
+ for (const missing of result.missing) {
+ log.warn('asset', `${component._name} on entity ${entity}: could not load "${missing.ref}"`);
+ }
+ // Only the fields that were paths, plus what resolving them derived
+ // (an atlas frame's uv window); and only while each still holds the
+ // placeholder, so a write made during the load wins.
+ const now = world.get(entity, component) as Record<string, unknown>;
+ const defaults = component._default as Record<string, unknown>;
+ const patch: Record<string, unknown> = {};
+ for (const [key, value] of Object.entries(data)) {
+ const wasPath = typeof authored[key] === 'string';
+ if (wasPath) {
+ if (now[key] === (defaults[key] ?? 0)) patch[key] = value;
+ } else if (value !== authored[key]) {
+ patch[key] = value;
+ }
+ }
+ if (Object.keys(patch).length === 0) return;
+ world.set(entity, component, { ...now, ...patch } as never);
+ ownership?.().attach(world, new Map([[0, entity]]));
+ } finally {
+ result.scope.releaseAll();
+ }
+ } catch (err) {
+ log.warn('asset', `${component._name} on entity ${entity}: loading its asset paths failed`, err);
+ }
}
diff --git a/sdk/src/ecs/bridge/nativeRuntime.ts b/sdk/src/ecs/bridge/nativeRuntime.ts
index cd6046e2a..74ad6bdc9 100644
--- a/sdk/src/ecs/bridge/nativeRuntime.ts
+++ b/sdk/src/ecs/bridge/nativeRuntime.ts
@@ -10,6 +10,7 @@
// authoring runs in the JS engine, writing the native C++ ECS, which the native
// host renders. No wasm module: entity generations fall back to World's JS path.
+import { bindAssetReferenceTracking } from '../../asset/assetReferenceTracking';
import { App, setAppSurfaceSize } from '../../app/app';
import { World } from '../world';
import { inputPlugin } from '../../input/input';
@@ -304,5 +305,9 @@ function installNativeAssets(app: App, scope: Record<string, unknown>): void {
// to RGBA (bridge.loadImagePixels), then TextureLoader uploads through the
// native ResourceManager's createTextureFromBytes. `flip` is applied on upload.
assets.getTextureLoader().setPixelDecoder((path) => platformLoadImagePixels(path));
+ // The same binding the web and packaged factories make: references dropped
+ // with their entity, and asset paths written at run time loaded into handles.
+ bindAssetReferenceTracking(app.world, assets,
+ () => app.hasResource(AssetsResource) ? app.getResource(AssetsResource) : null);
app.insertResource(AssetsResource, assets);
}
diff --git a/sdk/src/ecs/world.ts b/sdk/src/ecs/world.ts
index 9ffa51b37..2d655057c 100644
--- a/sdk/src/ecs/world.ts
+++ b/sdk/src/ecs/world.ts
@@ -142,6 +142,10 @@ export function queryDepIds(
return ids;
}
+
+/** @internal Loads the asset paths an engine-backed component was handed; see World.setAssetFieldResolver. */
+export type AssetFieldResolver = (entity: Entity, component: AnyComponentDef, authored: Record<string, unknown>) => void;
+
/**
* The entity store, as `GetWorld()` hands it to a system — the escape hatch for
* work the declared parameters cannot express. Prefer `Query`/`Res`/`Commands`:
@@ -172,6 +176,7 @@ export class World {
private nextGeneration_ = 0;
private spawnCallbacks_: Array<(entity: Entity) => void> = [];
private despawnCallbacks_: Array<(entity: Entity) => void> = [];
+ private assetFieldResolver_: AssetFieldResolver | null = null;
private despawning_: Set<Entity> | null = null;
/** @internal */
@@ -827,7 +832,10 @@ export class World {
return this.insertHierarchy_(entity, component, data) as ComponentData<C>;
}
if (isBuiltinComponent(component)) {
- return this.insertBuiltin_(entity, component, data) as ComponentData<C>;
+ const refs = this.takeAssetRefs_(component, data as Record<string, unknown> | undefined);
+ const merged = this.insertBuiltin_(entity, component, (refs?.clean ?? data) as Partial<ComponentData<C>>) as ComponentData<C>;
+ if (refs) this.resolveAssetRefs_(entity, component, refs.authored);
+ return merged;
}
return this.insertScript_(entity, component as ComponentDef<any>, data) as ComponentData<C>;
}
@@ -843,6 +851,12 @@ export class World {
return;
}
if (isBuiltinComponent(component)) {
+ const refs = this.takeAssetRefs_(component, data as Record<string, unknown>);
+ if (refs) {
+ this.set(entity, component, refs.clean as ComponentData<C>);
+ this.resolveAssetRefs_(entity, component, refs.authored);
+ return;
+ }
// `set` is insert-or-replace: adding a builtin the entity LACKS must run
// the full structural bookkeeping (entity set + query dirty + recordAdded),
// or the C++ side holds it while queries / has() (entity-set fast path)
@@ -893,6 +907,48 @@ export class World {
notifyBridge('onComponentChanged', entity, component._name);
}
+ /**
+ * @internal What turns an asset path written into an engine-backed
+ * component's handle field (`Sprite.texture = 'assets/hero.png'`,
+ * `MeshRenderer.mesh = 'builtin:cube'`) into the handle. Installed by the
+ * asset layer on every core; see bindAssetReferenceTracking.
+ */
+ setAssetFieldResolver(resolver: AssetFieldResolver | null): void {
+ this.assetFieldResolver_ = resolver;
+ }
+
+ /**
+ * An engine-backed component's asset fields hold handles, and the engine
+ * cannot store a string there: written straight through, `texture` read
+ * back as the path while the engine held 0, and nothing drew. A string in
+ * one is a path to load — the same ref a scene file carries — so it leaves
+ * the data here (the field takes its default until the load lands) and goes
+ * to the resolver.
+ */
+ private takeAssetRefs_(
+ component: AnyComponentDef, data: Record<string, unknown> | undefined,
+ ): { clean: Record<string, unknown>; authored: Record<string, unknown> } | null {
+ const fields = (component as { assetFields?: readonly { field: string }[] }).assetFields;
+ if (!data || !fields || fields.length === 0) return null;
+ let clean: Record<string, unknown> | null = null;
+ for (const { field } of fields) {
+ const value = data[field];
+ if (typeof value !== 'string') continue;
+ clean ??= { ...data };
+ clean[field] = (component._default as Record<string, unknown>)[field] ?? 0;
+ }
+ return clean ? { clean, authored: data } : null;
+ }
+
+ private resolveAssetRefs_(entity: Entity, component: AnyComponentDef, authored: Record<string, unknown>): void {
+ if (this.assetFieldResolver_) {
+ this.assetFieldResolver_(entity, component, authored);
+ return;
+ }
+ log.warn('world', `${component._name} on entity ${entity} was given an asset path, but this world has no asset layer `
+ + 'to load it: the field holds no handle. Load it first (await assets.loadTexture(path)) and write the handle.');
+ }
+
/**
* Edit a component in place and report the change — the write path for
* "read it, adjust a field, keep the rest". The draft is BORROWED for the
diff --git a/sdk/tests/asset-field-paths.test.ts b/sdk/tests/asset-field-paths.test.ts
new file mode 100644
index 000000000..f123afa35
--- /dev/null
+++ b/sdk/tests/asset-field-paths.test.ts
@@ -0,0 +1,105 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * An asset path written into an engine-backed component at run time is loaded
+ * and swapped for its handle. Written straight through, `Sprite.texture` read
+ * back as the path while the engine held 0, and the sprite never drew.
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { Assets } from '../src/asset/Assets';
+import { Catalog, type CatalogData } from '../src/asset/Catalog';
+import type { Backend } from '../src/asset/Backend';
+import { bindAssetReferenceTracking } from '../src/asset/assetReferenceTracking';
+import { World } from '../src/ecs/world';
+import { Sprite } from '../src/ecs/component';
+import { createMockModule } from './mocks/wasm';
+
+vi.mock('../src/wasm/resourceManager', () => ({
+ requireResourceManager: () => ({
+ createTexture: vi.fn(() => 42),
+ registerExternalTexture: vi.fn(() => 42),
+ releaseTexture: vi.fn(),
+ getTextureGLId: vi.fn(() => 1),
+ registerTextureWithPath: vi.fn(),
+ acquireTextureByPath: vi.fn(() => 0),
+ invalidateTexturePath: vi.fn(() => false),
+ getTextureDimensions: vi.fn(() => ({ width: 64, height: 64 })),
+ }),
+ getResourceManager: () => null,
+ evictTextureDimensions: vi.fn(),
+}));
+
+// TextureLoader/imageDecode import the concrete base module (cycle-free); the
+// rest go through the barrel — mock both ids with one factory.
+const platformFactory = vi.hoisted(() => () => ({
+ platformCreateCanvas: () => ({
+ width: 256, height: 256,
+ getContext: () => ({
+ clearRect: vi.fn(),
+ drawImage: vi.fn(),
+ getImageData: () => ({ data: { buffer: new ArrayBuffer(256 * 256 * 4) } }),
+ }),
+ }),
+ platformCreateImage: () => {
+ const img: { width?: number; height?: number; onload?: () => void } = {};
+ setTimeout(() => { img.width = 64; img.height = 64; img.onload?.(); }, 0);
+ return img;
+ },
+ platformFetch: vi.fn(),
+ platformReadFile: vi.fn(),
+ platformReadTextFile: vi.fn(),
+ platformFileExists: vi.fn(),
+}));
+vi.mock('../src/platform', platformFactory);
+vi.mock('../src/platform/base', platformFactory);
+
+const mockModule = {
+ _malloc: vi.fn(() => 0),
+ _free: vi.fn(),
+ HEAPU8: new Uint8Array(1024 * 1024),
+ GL: null,
+ FS: null,
+} as never;
+
+const catalogData: CatalogData = {
+ version: 1, entries: { 'sprites/hero.png': { type: 'texture' } }, addresses: {}, labels: {},
+};
+
+describe('asset paths in engine-backed components', () => {
+ it('loads the path and writes the handle once it is in', async () => {
+ const mod = createMockModule();
+ const world = new World();
+ world.connectCpp(mod.getRegistry(), mod);
+ const backend = {
+ fetchBinary: vi.fn(async () => new ArrayBuffer(8)),
+ fetchText: vi.fn(async () => ''),
+ resolveUrl: (path: string) => `http://test/${path}`,
+ } as unknown as Backend;
+ const assets = Assets.create({ backend, catalog: Catalog.fromJson(catalogData), module: mockModule });
+ bindAssetReferenceTracking(world, assets, () => assets);
+
+ const e = world.spawn();
+ world.insert(e, Sprite, { texture: 'sprites/hero.png' as never, size: { x: 3, y: 4 } });
+ // Not a string in a handle field: a placeholder, until the load lands.
+ expect(world.get(e, Sprite).texture).toBe(0);
+ expect(world.get(e, Sprite).size).toEqual({ x: 3, y: 4 });
+
+ await vi.waitFor(() => expect(world.get(e, Sprite).texture).toBe(42));
+ expect(world.get(e, Sprite).size).toEqual({ x: 3, y: 4 });
+ });
+
+ it('a handle written during the load wins over the late one', async () => {
+ const mod = createMockModule();
+ const world = new World();
+ world.connectCpp(mod.getRegistry(), mod);
+ const backend = { fetchBinary: vi.fn(async () => new ArrayBuffer(8)), fetchText: vi.fn(async () => ''),
+ resolveUrl: (path: string) => `http://test/${path}` } as unknown as Backend;
+ const assets = Assets.create({ backend, catalog: Catalog.fromJson(catalogData), module: mockModule });
+ bindAssetReferenceTracking(world, assets, () => assets);
+ const e = world.spawn();
+ world.insert(e, Sprite, { texture: 'sprites/hero.png' as never });
+ world.set(e, Sprite, { ...world.get(e, Sprite), texture: 7 });
+ await new Promise((r) => setTimeout(r, 30));
+ expect(world.get(e, Sprite).texture).toBe(7);
+ });
+});