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
// 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';
import { getResourceManager } from '../wasm/resourceManager';
const subscribed = new WeakSet<World>();
/**
* 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 {
if (!assets.getRefCounter()) assets.setRefCounter(new AssetRefCounter());
if (subscribed.has(world)) return;
subscribed.add(world);
world.onDespawn(entity => current()?.getRefCounter()?.removeAllRefsForEntity(entity));
world.setAssetFieldResolver((entity, component, authored) => {
const live = current();
// A core with no resource manager (a headless server, a test world) loads
// nothing: asking it to turned every authored path into a failed load with
// an Error behind it — 6000 a scene in the scale suite, where the JS heap
// budget then failed and a worker ran out of memory.
if (live && getResourceManager()) 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) {
// A path nothing resolved is still a string here, and a string written into a handle field is a path to
// load: writing it back asked for this same load again, without end. It keeps the placeholder.
if (typeof value === 'string') continue;
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);
}
}