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.

fix(text): a bitmap font's baseline comes from the font's own base over its size, not a 0.8em guess that put a 0.88 font four pixels high at 48px

yhh737a0516c47d
diff --git a/sdk/src/ui/text/bitmap-font.ts b/sdk/src/ui/text/bitmap-font.ts
index 62885d4e2..a60876511 100644
--- a/sdk/src/ui/text/bitmap-font.ts
+++ b/sdk/src/ui/text/bitmap-font.ts
@@ -135,6 +135,16 @@ export function bitmapFontFamily(handle: number): string | null {
return byHandle.get(handle)?.family ?? null;
}
+/**
+ * Where a family's first baseline sits below the top of its line, as a fraction of the font size: a bitmap font says
+ * (`base` over the size it was drawn at — a glyph's top is `yoffset` below the line top and its baseline `base`), any
+ * other font gets @p fallback.
+ */
+export function fontAscent(family: string, fallback: number): number {
+ const font = byFamily.get(family)?.font;
+ return font && font.size > 0 && font.base > 0 ? font.base / font.size : fallback;
+}
+
/** The font a family names, or null when the family is an ordinary (outline) one. */
export function bitmapFontOf(family: string): BmFont | null {
return byFamily.get(family)?.font ?? null;
diff --git a/sdk/src/ui/text/plugin.ts b/sdk/src/ui/text/plugin.ts
index 55d64b928..a56f3d021 100644
--- a/sdk/src/ui/text/plugin.ts
+++ b/sdk/src/ui/text/plugin.ts
@@ -18,9 +18,9 @@ import type { Entity } from '../../types';
import type { World } from '../../ecs/world';
import { SdfTextRenderer } from './text-renderer';
import type { RGBA } from './layout';
-import { composeTRS, rectTextBox, UI_TEXT_BOLD, UI_TEXT_ITALIC } from './text-transform';
+import { composeTRS, DEFAULT_ASCENT, rectTextBox, UI_TEXT_BOLD, UI_TEXT_ITALIC } from './text-transform';
import { Text, TextRenderMode, type TextData } from '../core/text';
-import { bitmapFontOf } from './bitmap-font';
+import { bitmapFontOf, fontAscent } from './bitmap-font';
import { UINode } from '../core/ui-node';
import { Localization } from '../../i18n/Localization';
import { applyTextLocalization, type TextWorldView } from './localize';
@@ -399,7 +399,7 @@ export class TextPlugin implements Plugin {
const w = frame.w, h = frame.h;
const hasBox = w > 0 || h > 0;
if (hasBox) {
- const box = rectTextBox(frame.px, frame.py, w, h, t.fontSize);
+ const box = rectTextBox(frame.px, frame.py, w, h, t.fontSize, fontAscent(family, DEFAULT_ASCENT));
originX = box.originX;
originY = box.originY;
boxWidth = box.maxWidth; // align within the box regardless of word-wrap
@@ -508,7 +508,7 @@ export class TextPlugin implements Plugin {
const frame = textFrame(world, entity, t);
const hasBox = frame.w > 0 || frame.h > 0;
if (hasBox) {
- const box = rectTextBox(frame.px, frame.py, frame.w, frame.h, t.fontSize);
+ const box = rectTextBox(frame.px, frame.py, frame.w, frame.h, t.fontSize, fontAscent(resolveTextFamily(t.font, t.fontFamily), DEFAULT_ASCENT));
originX = box.originX;
originY = box.originY;
boxWidth = box.maxWidth; // align within the box regardless of word-wrap
diff --git a/sdk/src/ui/text/text-renderer.ts b/sdk/src/ui/text/text-renderer.ts
index 677b3671f..1ee32aae8 100644
--- a/sdk/src/ui/text/text-renderer.ts
+++ b/sdk/src/ui/text/text-renderer.ts
@@ -20,7 +20,8 @@ import { EngineAtlasPageStore } from './atlas-page-store';
import { TextAlign, TextVerticalAlign, TextOverflow } from '../core/text';
import { layoutText, buildGlyphVertices, MAX_TEXT_BATCH_GLYPHS, type LaidGlyph, type RGBA } from './layout';
import { submitTextBatch, TEXT_VERTEX_FLOATS, TextGlyphMode } from './submit';
-import { bitmapFontOf } from './bitmap-font';
+import { bitmapFontOf, fontAscent } from './bitmap-font';
+import { DEFAULT_ASCENT } from './text-transform';
import { withScratch } from '../../wasm/wasmScratch';
import type { EngineApi } from '../../ecs/bridge/engineApi';
@@ -149,7 +150,7 @@ export function textBlockOffsetX(
*/
export function textBlockOriginY(
originY: number, boxHeight: number, lineHeight: number, fontSizePx: number,
- verticalAlign: number | undefined, lineHeightPx: number | undefined,
+ verticalAlign: number | undefined, lineHeightPx: number | undefined, ascent = DEFAULT_ASCENT,
): number {
let y = originY;
// Boxless: the entity origin is a zero-height box, so it gets the same
@@ -157,7 +158,7 @@ export function textBlockOriginY(
// every alignment, not only the ones that then shift — otherwise Top means
// "baseline on the origin" while Middle means "block centred on it", and the
// three do not sit on one ladder.
- if (boxHeight <= 0) y -= fontSizePx * 0.8;
+ if (boxHeight <= 0) y -= fontSizePx * ascent;
// Shift the block down (y-up) by the slack between box and content. With a
// zero-height box the slack is -blockHeight, which anchors the block to the origin.
if (verticalAlign) {
@@ -205,10 +206,12 @@ export function drawTextWith(atlas: GlyphAtlas, sink: GlyphBatchSink, p: DrawTex
// half-leading, the outline — is measured in the size it got. A boxed origin already carries 0.8em of the asked-for
// size (rectTextBox), which is put right.
const fontSizePx = layout.fontSizePx ?? p.fontSizePx;
+ // Where this font puts its baseline under the line top: a bitmap font's own number, 0.8em for the rest.
+ const ascent = fontAscent(p.fontFamily, DEFAULT_ASCENT);
const lineHeightPx = p.lineHeight !== undefined ? p.lineHeight * fontSizePx / p.fontSizePx : undefined;
const originY = textBlockOriginY(
- (p.originY ?? 0) + (p.originY !== undefined ? (p.fontSizePx - fontSizePx) * 0.8 : 0),
- boxHeight, layout.lineHeight, fontSizePx, p.verticalAlign, lineHeightPx,
+ (p.originY ?? 0) + (p.originY !== undefined ? (p.fontSizePx - fontSizePx) * ascent : 0),
+ boxHeight, layout.lineHeight, fontSizePx, p.verticalAlign, lineHeightPx, ascent,
);
// A string can reference glyphs across several atlas pages; each page is a
diff --git a/sdk/src/ui/text/text-transform.ts b/sdk/src/ui/text/text-transform.ts
index 521583c9b..20cf27f76 100644
--- a/sdk/src/ui/text/text-transform.ts
+++ b/sdk/src/ui/text/text-transform.ts
@@ -9,6 +9,13 @@
*/
import type { Vec3, Quat } from '../../types';
+/**
+ * How far the first baseline sits below the top of its line, as a fraction of the font size, for a font that does not say.
+ * An outline font's real ascent is not known here (the platform's text stack rasterizes it); a bitmap font's is, and
+ * {@link fontAscent} asks it.
+ */
+export const DEFAULT_ASCENT = 0.8;
+
/** Style bit flags — bold | italic (the atlas cache-key + rasterizer style arg). */
export const UI_TEXT_BOLD = 1;
export const UI_TEXT_ITALIC = 2;
@@ -42,11 +49,11 @@ export function composeTRS(out: Float32Array, t: Vec3, q: Quat, s: Vec3): Float3
* (ascent ≈ fontSize × 0.8). Pure.
*/
export function rectTextBox(
- pivotX: number, pivotY: number, width: number, height: number, fontSizePx: number,
+ pivotX: number, pivotY: number, width: number, height: number, fontSizePx: number, ascent = DEFAULT_ASCENT,
): { originX: number; originY: number; maxWidth: number; boxHeight: number } {
return {
originX: -pivotX * width,
- originY: (1 - pivotY) * height - fontSizePx * 0.8,
+ originY: (1 - pivotY) * height - fontSizePx * ascent,
maxWidth: width,
boxHeight: height,
};
diff --git a/sdk/tests/ui-text-bitmap-font.test.ts b/sdk/tests/ui-text-bitmap-font.test.ts
index 8e5db9d16..69605e193 100644
--- a/sdk/tests/ui-text-bitmap-font.test.ts
+++ b/sdk/tests/ui-text-bitmap-font.test.ts
@@ -11,13 +11,14 @@
import { afterEach, describe, expect, it } from 'vitest';
import { GlyphAtlas, type AtlasPageStore, type GlyphRasterizer } from '../src/ui/text/glyph-atlas';
import {
- bitmapFontFamily, bitmapFontOf, bitmapGlyph, parseBmFont, registerBitmapFont, resetBitmapFonts, unregisterBitmapFont,
+ bitmapFontFamily, bitmapFontOf, bitmapGlyph, fontAscent, parseBmFont, registerBitmapFont, resetBitmapFonts, unregisterBitmapFont,
} from '../src/ui/text/bitmap-font';
import { resolveTextFamily } from '../src/ui/text/font-registry';
import { layoutText, measureWidth } from '../src/ui/text/layout';
import { TextOverflow } from '../src/ui/core/text';
import { drawTextWith, type DrawTextParams } from '../src/ui/text/text-renderer';
import { TextGlyphMode } from '../src/ui/text/submit';
+import { DEFAULT_ASCENT, rectTextBox } from '../src/ui/text/text-transform';
const FNT = [
'info face="Demo" size=-40 bold=0 italic=0 charset="" unicode=1 stretchH=100 smooth=1 aa=1 padding=0,0,0,0 spacing=1,1',
@@ -194,3 +195,28 @@ describe('the engine boundary names how a page is read', () => {
expect(TextGlyphMode).toEqual({ Color: 0, Sdf: 1, Mask: 2, Fill: 3 });
});
});
+
+describe('where a bitmap font puts its baseline', () => {
+ // The font says: a glyph's top is yoffset below its line's top and the baseline is `base` below it. The layout used to assume
+ // every font's baseline is 0.8em down, which put a font with base/size of 0.95 four pixels high at 48px.
+ it('takes the ascent from the font\'s own base over its size, and 0.8em for a font that does not say', () => {
+ registerBitmapFont(5, parseBmFont(FNT), PAGE_TEXTURE);
+ expect(fontAscent('bmfont:5', DEFAULT_ASCENT)).toBeCloseTo(38 / 40);
+ expect(fontAscent('Arial', DEFAULT_ASCENT)).toBe(0.8);
+ });
+
+ it('lands a glyph\'s top yoffset below the top of the box, for any font size', () => {
+ registerBitmapFont(5, parseBmFont(FNT), PAGE_TEXTURE);
+ const a = atlas();
+ for (const fontSize of [20, 40, 64]) {
+ const box = rectTextBox(0.5, 1, 200, 100, fontSize, fontAscent('bmfont:5', DEFAULT_ASCENT));
+ const q = layoutText('A', a, 'bmfont:5', { fontSizePx: fontSize }).glyphs[0]!;
+ // box top is at y = 0 here (pivot at the top); the first baseline is box.originY, the glyph's top q.y1 above it
+ expect(box.originY + q.y1).toBeCloseTo(-4 * (fontSize / 40)); // yoffset 4, scaled
+ }
+ });
+
+ it('leaves the box of an ordinary font where it was', () => {
+ expect(rectTextBox(0.5, 0.5, 200, 60, 20).originY).toBe(30 - 16);
+ });
+});