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 { StreamTailInfo } from './AddressableManifest';
import { extractUuid, UUID_REF_PREFIX } from './AssetRegistry';
export interface AtlasFrameInfo {
atlas: string;
frame: { x: number; y: number; w: number; h: number };
uvOffset: [number, number];
uvScale: [number, number];
trim?: { sourceW: number; sourceH: number; offsetX: number; offsetY: number };
}
export interface CatalogEntry {
type: string;
atlas?: string;
frame?: { x: number; y: number; w: number; h: number };
uv?: { offset: [number, number]; scale: [number, number] };
trim?: { sourceW: number; sourceH: number; offsetX: number; offsetY: number };
deps?: string[];
buildPath?: string;
/** A small copy of the texture that texture streaming fetches first. */
streamTail?: StreamTailInfo;
}
export interface CatalogData {
version: number;
entries: Record<string, CatalogEntry>;
addresses?: Record<string, string>;
labels?: Record<string, string[]>;
}
/** The atlas record a cook/export manifest carries for a packed texture. */
export interface CookedAtlasInfo {
page?: number;
frame: { x: number; y: number; width: number; height: number };
pageWidth: number;
pageHeight: number;
}
/**
* Derive a CatalogEntry's atlas fields from a cook-manifest atlas record.
* Frame pixels are image-space (y from the page TOP); uv is emitted for
* flipY-uploaded textures (v origin = image bottom), matching the
* Sprite/UIVisual `uvOffset`/`uvScale` convention. `pagePath` is the page's
* fetch identity — the same string every frame of the page shares, so texture
* loading can collapse them onto one GPU texture.
*/
export function atlasCatalogFields(
atlas: CookedAtlasInfo,
pagePath: string,
): Pick<CatalogEntry, 'atlas' | 'frame' | 'uv'> {
const { frame, pageWidth, pageHeight } = atlas;
return {
atlas: pagePath,
frame: { x: frame.x, y: frame.y, w: frame.width, h: frame.height },
uv: {
offset: [frame.x / pageWidth, 1 - (frame.y + frame.height) / pageHeight],
scale: [frame.width / pageWidth, frame.height / pageHeight],
},
};
}
export class Catalog {
private entries_: Map<string, CatalogEntry>;
private addresses_: Map<string, string>;
private labels_: Map<string, string[]>;
/** Built on first ask; a pack has thousands of entries and most callers never ask. */
private addressByBuildPath_: Map<string, string> | null = null;
private constructor(
entries: Map<string, CatalogEntry>,
addresses: Map<string, string>,
labels: Map<string, string[]>,
) {
this.entries_ = entries;
this.addresses_ = addresses;
this.labels_ = labels;
}
static fromJson(data: CatalogData): Catalog {
const entries = new Map(Object.entries(data.entries));
const addresses = new Map(Object.entries(data.addresses ?? {}));
const labels = new Map(Object.entries(data.labels ?? {}));
return new Catalog(entries, addresses, labels);
}
static empty(): Catalog {
return new Catalog(new Map(), new Map(), new Map());
}
resolve(ref: string): string {
const addressPath = this.addresses_.get(ref);
if (addressPath) return addressPath;
if (this.entries_.has(ref)) return ref;
return ref;
}
getEntry(path: string): CatalogEntry | null {
return this.entries_.get(path) ?? null;
}
getAtlasFrame(path: string): AtlasFrameInfo | null {
// A frame is keyed by its `@uuid:` spelling; a scene or clip may name the
// same asset by its bare uuid, in either case.
const uuid = extractUuid(path);
const entry = this.entries_.get(uuid ? `${UUID_REF_PREFIX}${uuid}` : path);
if (!entry?.atlas || !entry.frame || !entry.uv) return null;
return {
atlas: entry.atlas,
frame: entry.frame,
uvOffset: entry.uv.offset,
uvScale: entry.uv.scale,
trim: entry.trim,
};
}
/**
* The authored logical address a staged path came from, or null. A document
* that names a SIBLING — a spine atlas page, a font page — resolves it against
* where the document was AUTHORED, and content-addressed staging renames every
* asset to a hash under one flat directory, which loses that.
*/
addressOf(path: string): string | null {
if (!this.addressByBuildPath_) {
const byBuild = new Map<string, string>();
for (const [key, entry] of this.entries_) {
// `@uuid:` and the "/"-rooted spelling are alternative keys for the
// same asset; the bare address is the authored one.
if (key.startsWith('@uuid:') || key.startsWith('/')) continue;
const built = entry.buildPath;
if (built && built !== key && !byBuild.has(built)) byBuild.set(built, key);
}
this.addressByBuildPath_ = byBuild;
}
return this.addressByBuildPath_.get(path) ?? null;
}
/** The small copy of a texture streaming fetches first, or null when the build shipped none. */
getStreamTail(path: string): StreamTailInfo | null {
return this.entries_.get(path)?.streamTail ?? null;
}
getBuildPath(path: string): string {
const entry = this.entries_.get(path);
return entry?.buildPath ?? path;
}
getDeps(path: string): string[] {
const entry = this.entries_.get(path);
return entry?.deps ?? [];
}
getByLabel(label: string): string[] {
return this.labels_.get(label) ?? [];
}
getAllLabels(): string[] {
return Array.from(this.labels_.keys());
}
hasEntry(path: string): boolean {
return this.entries_.has(path);
}
hasAddress(address: string): boolean {
return this.addresses_.has(address);
}
get isEmpty(): boolean {
return this.entries_.size === 0;
}
}