Skip to content

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.

4.9 KB
Raw Blame
// 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 };
    }
}