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 { AssetLoader, LoadContext, FontResult } from '../AssetLoader';
import { resolveDocumentRef } from '../documentRef';
import { requireResourceManager } from '../../wasm/resourceManager';
import { getAssetTypeEntry } from '../../assetTypes';
import { getPlatform } from '../../platform/base';
import {
freshProjectFontFamily, projectFontFamily, registerProjectFontEra, releaseProjectFontEra,
} from '../../ui/text/font-registry';
import { parseBmFont, registerBitmapFont, unregisterBitmapFont } from '../../ui/text/bitmap-font';
import { log } from '../../util/logger';
import type { FontHandle } from '../../types';
/** Outline fonts — rasterized per glyph by the text stack, not pre-baked pages. */
const OUTLINE_RE = /\.(ttf|otf|woff2?)$/i;
export class FontAssetLoader implements AssetLoader<FontResult> {
readonly type = 'font';
readonly extensions = ['.bmfont', '.fnt', '.ttf', '.otf', '.woff', '.woff2'];
async load(path: string, ctx: LoadContext): Promise<FontResult> {
// Two genuinely different things share the `font` asset type: a bitmap
// font is a pre-baked page + metrics (a C++ resource, drawn by
// BitmapText), an outline font is a file the platform's text stack
// rasterizes on demand (used by Text). They diverge here and nowhere else.
if (OUTLINE_RE.test(path)) return this.loadOutlineFont(path, ctx);
const entry = getAssetTypeEntry(path);
if (entry?.editorType === 'bitmap-font' && entry.contentType === 'json') {
return this.loadBmfontJson(path, ctx);
}
return this.loadFntFile(path, ctx);
}
unload(asset: FontResult): void {
// A project font has no C++ resource — only a registration and a name.
if (asset.family !== undefined || asset.path !== undefined || projectFontFamily(asset.handle) !== null) {
releaseProjectFontEra(asset.handle);
return;
}
unregisterBitmapFont(asset.handle);
const rm = requireResourceManager();
rm.releaseBitmapFont(asset.handle);
}
/**
* Hand the file to the platform's text stack under a minted family name, so
* `Text` can name a shipped font exactly as it names a system one. A host
* with no `registerFont` (a headless realm) still resolves and returns a
* handle — the family simply will not rasterize, and Text falls back.
*/
private async loadOutlineFont(path: string, ctx: LoadContext): Promise<FontResult> {
const bytes = await ctx.loadBinary(ctx.catalog.getBuildPath(path));
const family = freshProjectFontFamily(path);
await getPlatform().registerFont?.(family, bytes);
return { handle: registerProjectFontEra(path, family) as FontHandle, family, path };
}
private async loadBmfontJson(path: string, ctx: LoadContext): Promise<FontResult> {
const buildPath = ctx.catalog.getBuildPath(path);
const text = await ctx.loadText(buildPath);
const json = JSON.parse(text) as {
type: string;
fntFile?: string;
generatedFnt?: string;
};
const fntFile = json.type === 'label-atlas' ? json.generatedFnt : json.fntFile;
if (!fntFile) {
throw new Error(`Invalid bmfont asset: no fnt file specified in ${path}`);
}
const dir = path.substring(0, path.lastIndexOf('/'));
const fntPath = dir ? `${dir}/${fntFile}` : fntFile;
return this.loadFntFile(fntPath, ctx);
}
private async loadFntFile(path: string, ctx: LoadContext): Promise<FontResult> {
const buildPath = ctx.catalog.getBuildPath(path);
const fntContent = await ctx.loadText(buildPath);
const pageMatch = fntContent.match(/file="([^"]+)"/);
if (!pageMatch) {
throw new Error(`No page texture found in .fnt file: ${path}`);
}
const texPath = resolveDocumentRef(path, pageMatch[1]);
const texResult = await ctx.loadTexture(texPath, false);
const rm = requireResourceManager();
const handle = rm.loadBitmapFont(
fntContent, texResult.handle, texResult.width, texResult.height,
) as FontHandle;
// The same font serves `Text`, which draws it from the page texture with this table — `BitmapText` keeps using the
// C++ resource above. A font the parser cannot read still loads for BitmapText; Text just will not find it.
try {
// the batch binds a page by GL texture id, as it does for the glyph atlas's own pages
registerBitmapFont(handle, parseBmFont(fntContent), rm.getTextureGLId(texResult.handle));
} catch (err) {
log.warn('text', `${path}: not usable by Text as a bitmap font — ${err instanceof Error ? err.message : String(err)}`);
}
return { handle };
}
}