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
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.tsindex 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.tsindex 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-wrapdiff --git a/sdk/src/ui/text/text-renderer.ts b/sdk/src/ui/text/text-renderer.tsindex 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 adiff --git a/sdk/src/ui/text/text-transform.ts b/sdk/src/ui/text/text-transform.tsindex 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.tsindex 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);+ });+});