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 { Backend } from './Backend';
import type { AssetLease } from './AssetLease';
import type { ScriptGraphSignature } from '../logic/nodes';
import type { PreparedPrefab } from '../prefab/preparedPrefab';
import type { RegistryEra } from './registryAssets';
import type { Catalog } from './Catalog';
import type { TextureHandle, FontHandle } from '../types';
import type { CppResourceManager } from '../wasm';
import type { SpineAssetValue } from '../spine/prepareSpine';
export interface TextureResult {
handle: TextureHandle;
width: number;
height: number;
/** The file's own size, where it was made smaller than that (texture streaming); absent when it is the file's size. */
fullWidth?: number;
fullHeight?: number;
}
/**
* One spine PAIR: the two documents it is, and the atlas pages it holds. No
* native skeleton — that belongs to a runtime backend of a particular Spine
* version, is built from this, and dies with the entities posing it.
*/
export type SpineResult = SpineAssetValue;
export interface SpineLoadResult {
success: boolean;
error?: string;
}
export interface MaterialResult {
handle: number;
shaderHandle: number;
}
export interface FontResult {
handle: FontHandle;
/** Outline fonts (.ttf/.otf/.woff) only: the family name the font was
* registered with, which is what `Text` rasterizes against. Absent for
* bitmap fonts, whose handle IS the resource. */
family?: string;
/** Outline fonts only: the source path, so unload can drop the registration. */
path?: string;
}
export interface AudioResult {
bufferId: string;
}
export interface AnimClipResult {
clipId: string;
}
export interface TilemapResult {
sourceId: string;
}
export interface TilesetResult {
/** The `.estileset` path the resolved tileset is cached under. */
tilesetId: string;
}
export interface TimelineResult {
timelineId: string;
}
export interface FsmResult {
fsmId: string;
}
export interface AnimatorControllerResult {
controllerId: string;
}
export interface AvatarResult {
avatarId: string;
}
export interface LocaleResult {
/** The locale the table's entries were merged into. */
locale: string;
/** How many keys the table carried. */
keyCount: number;
}
export interface BtResult {
btId: string;
}
export interface ScriptGraphResult {
graphId: string;
/**
* What this graph takes and hands back, for one CALLING it: a caller's pins
* come from the callee's declaration, and acquiring it is how the caller
* gets both the ownership and the shape in one door.
*/
signature?: ScriptGraphSignature;
}
export interface PrefabResult {
data: unknown;
}
/**
* A data asset's parsed document. `T` is the caller's claim about the file's
* shape — the loader parses, it does not validate, so a wrong claim is a wrong
* claim about untyped JSON exactly as `JSON.parse` would give.
*/
export interface JsonResult<T = unknown> {
data: T;
}
export interface LoadContext {
backend: Backend;
catalog: Catalog;
resourceManager: CppResourceManager;
loadTexture(path: string, flipY?: boolean): Promise<TextureResult>;
/**
* Load a texture and get the receipt for THIS acquisition — what a loader
* holding a texture past its own `load` needs, because a path-addressed
* release after an invalidate gives back the oldest era rather than the one
* this loader was handed.
*/
acquireTexture(path: string, flipY?: boolean): Promise<AssetLease<TextureResult>>;
/** Say that material @p material binds texture @p texture, before it is acquired: a mesh material's textures may start small. */
noteMaterialTexture?(material: string, texture: string): void;
/**
* Say what is wrong with an asset that LOADED anyway: a part of it was left out (a texture that would not load, a value of a shape nothing
* reads) and what draws is the rest. Replaces the list this asset had; an empty list says it is whole. Without this a half-loaded material
* looks exactly like a good one: a log line, and then a default-looking surface nobody can attribute.
*/
noteAssetProblems?(asset: string, problems: readonly string[]): void;
/**
* The same for an asset of ANY type — a material instance acquiring the
* parent it diffs against. The general door; {@link acquireTexture} is the
* one specialization, for the flip variants a texture has.
*/
acquireAsset<T>(type: string, ref: string): Promise<AssetLease<T>>;
/**
* The path an asset ref names, or null when it names nothing known. Optional: a loader that wants to
* compare two spellings of one asset (a timeline deciding whether a clip plays itself) asks it.
*/
resolveRef?(ref: string): string | null;
/**
* A prefab loaded, flattened and resolved, so it can be spawned in one
* frame. Optional: a context built for a loader that never spawns has no
* reason to carry it.
*/
preparePrefab?(ref: string): Promise<AssetLease<PreparedPrefab>>;
loadText(path: string): Promise<string>;
loadBinary(path: string): Promise<ArrayBuffer>;
/**
* Decode a texture ref to top-first RGBA pixels through the platform's ONE
* decode path (a runtime-injected pixel decoder when present, else the
* shared fetch→ImageBitmap route). For loaders that COMPOSE textures — the
* tilemap loader folding an image-collection tileset into a grid atlas —
* rather than uploading refs 1:1. Optional: minimal providers may lack it;
* consumers fail loud.
*/
decodePixels?(path: string): Promise<{ width: number; height: number; pixels: Uint8Array }>;
/** Upload raw top-first RGBA as a texture (TextureLoader.loadFromPixels).
* Optional, same caveat as {@link decodePixels}. */
createTextureFromPixels?(
width: number, height: number, pixels: Uint8Array, flipY: boolean,
): Promise<TextureResult>;
/**
* The same upload, as something an era can OWN: a texture composed from
* pixels has no path, no generation and no cache, so there is no receipt to
* acquire — but it still has to be given back, and only the era that
* composed it knows when. Releasing destroys it.
*/
createOwnedTexture?(
width: number, height: number, pixels: Uint8Array, flipY: boolean,
): Promise<AssetLease<TextureResult>>;
/**
* Read another asset's content because it shapes what this one becomes — a
* `.tsj` folded into a `.tmj`. Takes the REF, not a build path: what is
* recorded is the identity an invalidation will name.
*
* Nothing is held; what is recorded is that this asset must be rebuilt when
* that content changes. A log setting read during a load is not one.
*/
readSource?(ref: string): Promise<string>;
/**
* Audio API for the owning app, resolved lazily so that
* AudioPlugin / AssetPlugin can be installed in either order.
* Returns null when no AudioPlugin is installed — audio-typed
* assets will fail to preload.
*/
getAudio(): import('../audio/Audio').AudioAPI | null;
/**
* Sprite-animation API for the owning app (clip registry), resolved lazily
* like {@link getAudio}. Returns null when no AnimationPlugin is installed.
*/
getSpriteAnimation(): import('../animation/SpriteAnimator').SpriteAnimationAPI | null;
/**
* Localization service for the owning app, resolved lazily like
* {@link getAudio}. Returns null when no LocalizationPlugin is installed —
* loading a `.eslocale` then fails loud (a table with nowhere to register
* is a setup error, not a soft skip).
*/
getLocalization(): import('../i18n/Localization').LocalizationAPI | null;
}
/**
* A loader whose asset lives in a REGISTRY under its ref: what a component
* carries is the name, and every lookup asks what that name means now.
*
* Preparing is all of it. The slot holds the era and answers the lookup, so
* there is no second place to write and nothing to keep in step with it.
*/
export interface RegistryAssetLoader<T> {
prepare(path: string, ctx: LoadContext): Promise<RegistryEra<T>>;
}
/**
* How one asset type is loaded. A loader implements EXACTLY ONE door: `load` +
* `unload` for an asset a component holds by handle, or `registry` for one it
* holds by ref. Two doors to the same asset is two answers about who owns it.
*/
export interface AssetLoader<T> {
readonly type: string;
readonly extensions: string[];
load?(path: string, ctx: LoadContext): Promise<T>;
/** Destroy what `load` made. What it ACQUIRED is the preparation's and goes
* back with the era — a loader releasing it here would free it twice. */
unload?(asset: T): void;
/** Set instead of `load`/`unload` when the asset is published by name. */
registry?: RegistryAssetLoader<T>;
/**
* Sever any residency identity the loader's subsystem keeps for `path`
* (hot reload: the source bytes changed, so a warm-cache entry must never
* be revived). Called by `Assets.invalidate` for every registered loader,
* whether or not the Assets-level cache held the path — the subsystem
* cache can outlive it. Returns true if anything was dropped. Optional:
* loaders whose results carry no out-of-Assets residency omit it.
*/
invalidate?(path: string): boolean;
}