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(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.mdxindex 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.mdxindex 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.tsindex 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 Teamimport 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.tsindex 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.tsindex 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 thediff --git a/sdk/tests/asset-field-paths.test.ts b/sdk/tests/asset-field-paths.test.tsnew file mode 100644index 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);+ });+});