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 { App, Plugin } from '../app/app';
import type { World } from '../ecs/world';
import type { Entity } from '../types';
import type { Assets as AssetsClass } from '../asset/Assets';
import { Assets } from '../asset/AssetPlugin';
import { SceneManager, type SceneManagerState } from '../scene/sceneManager';
import { defineResource } from '../ecs/resource';
import {
instantiatePrefab,
type PrefabData,
type PrefabOverride,
type InstantiatePrefabResult,
} from '../prefab';
/**
* An override as written at a SPAWN: the entity id may be left out, and then it
* is the prefab's root — which is the entity a one-sprite prefab has.
*
* @beta
*/
export type SpawnOverride = Omit<PrefabOverride, 'prefabEntityId'> & { prefabEntityId?: string };
/**
* Prefab instantiation, as `Res(Prefabs)` hands it over.
*
* `@beta`: `instantiate` is the whole surface and it has not moved, but its result
* and override shapes are spelled in the prefab document model, which is also the
* on-disk format — so their names are settled ahead of the shapes.
*
* @beta
*/
export class PrefabServer {
private readonly world_: World;
private readonly getAssets_: () => AssetsClass;
private readonly getScenes_: () => SceneManagerState | null;
// Resolved per call, not captured: the play/cooked runtime replaces the
// Assets resource after plugin build (ensureRuntimeAssets), and a captured
// instance would silently bypass its resolveRef/manifest channel.
constructor(
world: World,
getAssets: () => AssetsClass,
getScenes: () => SceneManagerState | null = () => null,
) {
this.world_ = world;
this.getAssets_ = getAssets;
this.getScenes_ = getScenes;
}
/**
* Spawn a prefab into the world. What it spawns belongs to the scene that
* was live when it landed, exactly like an entity that scene authored —
* ownerless, a bullet or a called minion leaks into the next room. Pass
* `scene: false` for something meant to outlive the area it came from.
*/
async instantiate(pathOrAddress: string, options?: {
baseUrl?: string;
parent?: Entity;
overrides?: SpawnOverride[];
scene?: boolean;
}): Promise<InstantiatePrefabResult> {
const assets = this.getAssets_();
const lease = await assets.acquireTyped<{ data: PrefabData }>('prefab', pathOrAddress);
try {
const prefab = lease.value.data;
const result = await instantiatePrefab(this.world_, prefab, {
assets,
assetBaseUrl: options?.baseUrl,
parent: options?.parent,
overrides: resolveSpawnOverrides(prefab, pathOrAddress, options?.overrides),
});
if (options?.scene !== false) this.adoptIntoActiveScene_(result);
return result;
} finally { lease.release(); }
}
/**
* Load a prefab and everything its entities use - meshes, materials,
* textures - and hold them, so that an instantiate later finds them loaded
* and its entities appear on the frame they are asked for rather than when
* their files arrive. Release what it answers when they are no longer
* wanted.
*/
async prepare(pathOrAddress: string): Promise<{ release(): void }> {
const prepared = await this.getAssets_().preparePrefab(pathOrAddress);
let held = true;
return { release: () => { if (held) { held = false; prepared.release(); } } };
}
/**
* The load is asynchronous, so the scene that asked may already be gone by
* the time the entities exist — adopting into whatever is active now is the
* only owner that is real, and a switch that already happened takes it.
*/
private adoptIntoActiveScene_(result: InstantiatePrefabResult): void {
const scenes = this.getScenes_();
const active = scenes?.getActive();
const ctx = active ? scenes?.getScene(active) : null;
if (!ctx) return;
for (const entity of result.entities.values()) ctx.adopt(entity);
}
}
/**
* Aim each override at an entity this prefab actually has — and say so when one
* does not.
*
* `prefabEntityId` is a STABLE ADDRESS inside the prefab, and an override
* carrying one nobody answers to is dropped without a word: the bullet spawns,
* at the position the prefab was authored with, and the only symptom is that
* every one of them appears in the same place. Two things make that easy to
* write. `'0'` is the id every prefab had before stable ids, so it is what every
* older example still shows — and a prefab saved since gets a uuid instead. And
* the common case, spawning one sprite, has exactly one entity to aim at, so
* naming it at all is ceremony: an omitted id means the root.
*
* The editor's own instance path deliberately does NOT do this — an override
* left over from a since-deleted child is a normal thing to carry there. This is
* the RUNTIME spawn door, where the override was written moments ago by someone
* who can still fix it.
*/
function resolveSpawnOverrides(
prefab: PrefabData,
path: string,
overrides: SpawnOverride[] | undefined,
): PrefabOverride[] | undefined {
if (!overrides?.length) return undefined;
const known = new Set(prefab.entities.map((e) => e.prefabEntityId));
return overrides.map((o): PrefabOverride => {
if (!o.prefabEntityId) return { ...o, prefabEntityId: prefab.rootEntityId };
if (!known.has(o.prefabEntityId)) {
throw new Error(
`prefab "${path}" has no entity "${o.prefabEntityId}" for this override `
+ `(${o.type}${o.componentType ? ` ${o.componentType}.${o.propertyName}` : ''}). `
+ `Its root is "${prefab.rootEntityId}" — or leave prefabEntityId out and the root is used. `
+ `Entities: ${[...known].join(', ')}`,
);
}
return o as PrefabOverride;
});
}
/**
* Prefab instantiation, as a resource. Spawning from a prefab is asynchronous
* because its assets may not be loaded yet.
*
* @beta
*/
export const Prefabs = defineResource<PrefabServer>(null!, 'Prefabs');
export class PrefabsPlugin implements Plugin {
name = 'prefabs';
dependencies = [Assets];
build(app: App): void {
app.insertResource(Prefabs, new PrefabServer(
app.world,
() => app.getResource(Assets),
() => (app.hasResource(SceneManager) ? app.getResource(SceneManager) : null),
));
}
}
export const prefabsPlugin = new PrefabsPlugin();