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
feat(components): the two components a 2D game draws with are frozen
esengine0fb2302d748b
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.jsonindex 7030fe89d..e563488f4 100644--- a/docs/astro/src/data/apiStability.generated.json+++ b/docs/astro/src/data/apiStability.generated.json@@ -1,9 +1,9 @@{"note": "Generated by tools/api-stability.mjs from sdk/etc/*.api.md — do not edit.","counts": {- "public": 94,- "beta": 27,- "experimental": 1504,+ "public": 101,+ "beta": 29,+ "experimental": 1495,"deprecated": 3},"total": 1625,@@ -836,6 +836,30 @@"minigame"]},+ {+ "name": "Sprite",+ "kind": "const",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "SpriteData",+ "kind": "interface",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },{"name": "Stick","kind": "const",@@ -908,6 +932,66 @@"minigame"]},+ {+ "name": "Text",+ "kind": "const",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "TextAlign",+ "kind": "type",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "TextData",+ "kind": "interface",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "TextRenderMode",+ "kind": "type",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "TextVerticalAlign",+ "kind": "type",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },{"name": "Time","kind": "const",@@ -1138,6 +1222,30 @@}],"beta": [+ {+ "name": "Camera",+ "kind": "const",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "CameraData",+ "kind": "interface",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },{"name": "GraphNodeType","kind": "type",diff --git a/docs/astro/src/data/components.generated.json b/docs/astro/src/data/components.generated.jsonindex 2c0d98973..2dad778c6 100644--- a/docs/astro/src/data/components.generated.json+++ b/docs/astro/src/data/components.generated.json@@ -2858,6 +2858,7 @@"key": "overflow","type": "enum","default": "Visible",+ "doc": "Not honoured yet: nothing reads this field, so every value renders as Visible. Shown so the data a scene already carries stays editable.","values": ["Visible","Clip",diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 81878406a..419929364 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1,7 +1,7 @@# API surface — esengine/index<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 94 public · 20 beta · 1389 experimental · 3 deprecated+Symbols: 101 public · 22 beta · 1380 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -1330,7 +1330,7 @@ width: number{ create(width: number, height: number): BitmapCache; release(cache: BitmapCache): void; beginDraw(cache: BitmapCache, viewProjection: Float32Array): void; endDraw(): void; resize(cache: BitmapCache, width: number, height: number): void; }```-## Camera — const @experimental+## Camera — const @beta```BuiltinComponentDef<CameraData>```@@ -1348,7 +1348,7 @@ minX: numberminY: number```-## CameraData — interface @experimental+## CameraData — interface @beta```aspectRatio: numberclearFlags: number@@ -6423,7 +6423,7 @@ name: stringtype: "spine"```-## Sprite — const @experimental+## Sprite — const @public```BuiltinComponentDef<SpriteData>```@@ -6507,7 +6507,7 @@ playing: booleanspeed: number```-## SpriteData — interface @experimental+## SpriteData — interface @public```color: Colorenabled: boolean@@ -6890,17 +6890,17 @@ tileTerrain: Map<number, number>'edge' | 'corner' | 'wang'```-## Text — const @experimental+## Text — const @public```ComponentDef<TextData>```-## TextAlign — type @experimental+## TextAlign — type @public```(typeof TextAlign)[keyof typeof TextAlign]```-## TextData — interface @experimental+## TextData — interface @public```align: TextAlignbold: boolean@@ -7044,7 +7044,7 @@ static new (): TextPluginstatic prototype: TextPlugin```-## TextRenderMode — type @experimental+## TextRenderMode — type @public```(typeof TextRenderMode)[keyof typeof TextRenderMode]```@@ -7059,7 +7059,7 @@ text: stringtype: "text"```-## TextVerticalAlign — type @experimental+## TextVerticalAlign — type @public```(typeof TextVerticalAlign)[keyof typeof TextVerticalAlign]```diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex d00ddcf2c..c796e1abb 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.native<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 94 public · 25 beta · 1408 experimental · 3 deprecated+Symbols: 101 public · 27 beta · 1399 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -1330,7 +1330,7 @@ width: number{ create(width: number, height: number): BitmapCache; release(cache: BitmapCache): void; beginDraw(cache: BitmapCache, viewProjection: Float32Array): void; endDraw(): void; resize(cache: BitmapCache, width: number, height: number): void; }```-## Camera — const @experimental+## Camera — const @beta```BuiltinComponentDef<CameraData>```@@ -1348,7 +1348,7 @@ minX: numberminY: number```-## CameraData — interface @experimental+## CameraData — interface @beta```aspectRatio: numberclearFlags: number@@ -6616,7 +6616,7 @@ name: stringtype: "spine"```-## Sprite — const @experimental+## Sprite — const @public```BuiltinComponentDef<SpriteData>```@@ -6700,7 +6700,7 @@ playing: booleanspeed: number```-## SpriteData — interface @experimental+## SpriteData — interface @public```color: Colorenabled: boolean@@ -7083,17 +7083,17 @@ tileTerrain: Map<number, number>'edge' | 'corner' | 'wang'```-## Text — const @experimental+## Text — const @public```ComponentDef<TextData>```-## TextAlign — type @experimental+## TextAlign — type @public```(typeof TextAlign)[keyof typeof TextAlign]```-## TextData — interface @experimental+## TextData — interface @public```align: TextAlignbold: boolean@@ -7237,7 +7237,7 @@ static new (): TextPluginstatic prototype: TextPlugin```-## TextRenderMode — type @experimental+## TextRenderMode — type @public```(typeof TextRenderMode)[keyof typeof TextRenderMode]```@@ -7252,7 +7252,7 @@ text: stringtype: "text"```-## TextVerticalAlign — type @experimental+## TextVerticalAlign — type @public```(typeof TextVerticalAlign)[keyof typeof TextVerticalAlign]```diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex fbbbecec2..70abc87a2 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.node<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 94 public · 22 beta · 1388 experimental · 3 deprecated+Symbols: 101 public · 24 beta · 1379 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -1325,7 +1325,7 @@ width: number{ create(width: number, height: number): BitmapCache; release(cache: BitmapCache): void; beginDraw(cache: BitmapCache, viewProjection: Float32Array): void; endDraw(): void; resize(cache: BitmapCache, width: number, height: number): void; }```-## Camera — const @experimental+## Camera — const @beta```BuiltinComponentDef<CameraData>```@@ -1343,7 +1343,7 @@ minX: numberminY: number```-## CameraData — interface @experimental+## CameraData — interface @beta```aspectRatio: numberclearFlags: number@@ -6418,7 +6418,7 @@ name: stringtype: "spine"```-## Sprite — const @experimental+## Sprite — const @public```BuiltinComponentDef<SpriteData>```@@ -6502,7 +6502,7 @@ playing: booleanspeed: number```-## SpriteData — interface @experimental+## SpriteData — interface @public```color: Colorenabled: boolean@@ -6885,17 +6885,17 @@ tileTerrain: Map<number, number>'edge' | 'corner' | 'wang'```-## Text — const @experimental+## Text — const @public```ComponentDef<TextData>```-## TextAlign — type @experimental+## TextAlign — type @public```(typeof TextAlign)[keyof typeof TextAlign]```-## TextData — interface @experimental+## TextData — interface @public```align: TextAlignbold: boolean@@ -7039,7 +7039,7 @@ static new (): TextPluginstatic prototype: TextPlugin```-## TextRenderMode — type @experimental+## TextRenderMode — type @public```(typeof TextRenderMode)[keyof typeof TextRenderMode]```@@ -7054,7 +7054,7 @@ text: stringtype: "text"```-## TextVerticalAlign — type @experimental+## TextVerticalAlign — type @public```(typeof TextVerticalAlign)[keyof typeof TextVerticalAlign]```diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex f2c59c039..628f635f9 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -1,7 +1,7 @@# API surface — esengine/minigame<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 94 public · 20 beta · 1409 experimental · 3 deprecated+Symbols: 101 public · 22 beta · 1400 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -1325,7 +1325,7 @@ width: number{ create(width: number, height: number): BitmapCache; release(cache: BitmapCache): void; beginDraw(cache: BitmapCache, viewProjection: Float32Array): void; endDraw(): void; resize(cache: BitmapCache, width: number, height: number): void; }```-## Camera — const @experimental+## Camera — const @beta```BuiltinComponentDef<CameraData>```@@ -1343,7 +1343,7 @@ minX: numberminY: number```-## CameraData — interface @experimental+## CameraData — interface @beta```aspectRatio: numberclearFlags: number@@ -6663,7 +6663,7 @@ name: stringtype: "spine"```-## Sprite — const @experimental+## Sprite — const @public```BuiltinComponentDef<SpriteData>```@@ -6747,7 +6747,7 @@ playing: booleanspeed: number```-## SpriteData — interface @experimental+## SpriteData — interface @public```color: Colorenabled: boolean@@ -7130,17 +7130,17 @@ tileTerrain: Map<number, number>'edge' | 'corner' | 'wang'```-## Text — const @experimental+## Text — const @public```ComponentDef<TextData>```-## TextAlign — type @experimental+## TextAlign — type @public```(typeof TextAlign)[keyof typeof TextAlign]```-## TextData — interface @experimental+## TextData — interface @public```align: TextAlignbold: boolean@@ -7284,7 +7284,7 @@ static new (): TextPluginstatic prototype: TextPlugin```-## TextRenderMode — type @experimental+## TextRenderMode — type @public```(typeof TextRenderMode)[keyof typeof TextRenderMode]```@@ -7299,7 +7299,7 @@ text: stringtype: "text"```-## TextVerticalAlign — type @experimental+## TextVerticalAlign — type @public```(typeof TextVerticalAlign)[keyof typeof TextVerticalAlign]```diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex bf6a7065c..a2cf77178 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -1,7 +1,7 @@# API surface — esengine/wechat<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 94 public · 20 beta · 1399 experimental · 3 deprecated+Symbols: 101 public · 22 beta · 1390 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -1325,7 +1325,7 @@ width: number{ create(width: number, height: number): BitmapCache; release(cache: BitmapCache): void; beginDraw(cache: BitmapCache, viewProjection: Float32Array): void; endDraw(): void; resize(cache: BitmapCache, width: number, height: number): void; }```-## Camera — const @experimental+## Camera — const @beta```BuiltinComponentDef<CameraData>```@@ -1343,7 +1343,7 @@ minX: numberminY: number```-## CameraData — interface @experimental+## CameraData — interface @beta```aspectRatio: numberclearFlags: number@@ -6425,7 +6425,7 @@ name: stringtype: "spine"```-## Sprite — const @experimental+## Sprite — const @public```BuiltinComponentDef<SpriteData>```@@ -6509,7 +6509,7 @@ playing: booleanspeed: number```-## SpriteData — interface @experimental+## SpriteData — interface @public```color: Colorenabled: boolean@@ -6892,17 +6892,17 @@ tileTerrain: Map<number, number>'edge' | 'corner' | 'wang'```-## Text — const @experimental+## Text — const @public```ComponentDef<TextData>```-## TextAlign — type @experimental+## TextAlign — type @public```(typeof TextAlign)[keyof typeof TextAlign]```-## TextData — interface @experimental+## TextData — interface @public```align: TextAlignbold: boolean@@ -7046,7 +7046,7 @@ static new (): TextPluginstatic prototype: TextPlugin```-## TextRenderMode — type @experimental+## TextRenderMode — type @public```(typeof TextRenderMode)[keyof typeof TextRenderMode]```@@ -7061,7 +7061,7 @@ text: stringtype: "text"```-## TextVerticalAlign — type @experimental+## TextVerticalAlign — type @public```(typeof TextVerticalAlign)[keyof typeof TextVerticalAlign]```diff --git a/sdk/src/ecs/component.generated.ts b/sdk/src/ecs/component.generated.tsindex ea7cb132c..102bb89cb 100644--- a/sdk/src/ecs/component.generated.ts+++ b/sdk/src/ecs/component.generated.ts@@ -1127,6 +1127,12 @@ export interface SpineAnimationData {enabled: boolean;}+/**+ * The fields of the engine's `Sprite` component, generated from+ * the C++ struct so the two shapes cannot drift.+ *+ * @public+ */export interface SpriteData {texture: number;color: Color;diff --git a/sdk/src/ecs/component.ts b/sdk/src/ecs/component.tsindex d6330f747..eb77213c7 100644--- a/sdk/src/ecs/component.ts+++ b/sdk/src/ecs/component.ts@@ -759,6 +759,11 @@ export type WorldTransformData = TransformData;// Camera = the generated C++ field shape + one editor-only field. `showFrustum`// drives gizmo rendering and has no C++ Camera member, so it is added here rather// than in the generated interface (the only hand-written Camera field).+/**+ * {@link Camera}'s fields, and one the editor adds.+ *+ * @beta+ */export interface CameraData extends CameraDataCpp {showFrustum: boolean;}@@ -823,6 +828,14 @@ export const WorldTransform = Transform;// size's authoring default (100×100 vs the {1,1} ctor value) is authored at the// C++ ES_PROPERTY site (editor_default=) and merged in by metaDefaults.+/**+ * A textured quad. `size` is in world units and is the drawn extent — the texture+ * is stretched into it rather than deciding it — and `pivot` says where in that+ * rectangle the entity's position sits. `layer` is the painter order between+ * sprites; within a layer, storage order decides.+ *+ * @public+ */export const Sprite = defineBuiltin<SpriteData>('Sprite',metaDefaults<SpriteData>('Sprite'));@@ -845,6 +858,16 @@ export const ShadowCaster2D = defineBuiltin<ShadowCaster2DData>('ShadowCaster2D'// at orthoSize 540 vs a Perspective/inactive runtime default) are authored at// the C++ ES_PROPERTY sites (editor_default=) and merged in by metaDefaults.// Only the TS-only field's default stays here.+/**+ * What a viewport draws and from where. One camera per render target;+ * `priority` breaks the tie and `isActive` takes one out.+ *+ * `@beta`: `clearFlags` is a bitmask whose C++ enum has no TypeScript spelling,+ * and `cullingMask` names layers no exported constant identifies — so two of+ * these fields are typed `number` for want of the vocabulary, not by design.+ *+ * @beta+ */export const Camera = defineBuiltin<CameraData>('Camera',metaDefaults<CameraData>('Camera', {showFrustum: false,diff --git a/sdk/src/ui/core/text.ts b/sdk/src/ui/core/text.tsindex 5d207e90c..dc1f43bbd 100644--- a/sdk/src/ui/core/text.ts+++ b/sdk/src/ui/core/text.ts@@ -3,20 +3,40 @@import { defineComponent, enumOptions } from '../../ecs/component';import type { Color } from '../../types';+/**+ * Horizontal alignment. With a layout box it aligns inside the box; without one it+ * anchors the run relative to the entity's own position.+ *+ * @public+ */export const TextAlign = {Left: 0,Center: 1,Right: 2,} as const;+/** @public */export type TextAlign = (typeof TextAlign)[keyof typeof TextAlign];+/**+ * Vertical alignment, on the same rule as {@link TextAlign}: inside the box when+ * there is one, otherwise relative to the origin.+ *+ * @public+ */export const TextVerticalAlign = {Top: 0,Middle: 1,Bottom: 2,} as const;+/** @public */export type TextVerticalAlign = (typeof TextVerticalAlign)[keyof typeof TextVerticalAlign];+/**+ * What a run too big for its box does — NOT HONOURED YET. No layout or render+ * path reads {@link TextData.overflow}, so every value behaves as `Visible`.+ * Unfrozen for that reason: freezing it would promise a behaviour that does not+ * exist.+ */export const TextOverflow = {Visible: 0,Clip: 1,@@ -24,7 +44,8 @@ export const TextOverflow = {} as const;export type TextOverflow = (typeof TextOverflow)[keyof typeof TextOverflow];-/** Glyph pipeline for a Text. */+/** Glyph pipeline for a Text.+ * @public */export const TextRenderMode = {/** Hinted bitmap while the entity is unscaled, SDF once it scales. */Auto: 0,@@ -33,8 +54,15 @@ export const TextRenderMode = {/** Signed-distance field — a stable ~1px edge at any scale/zoom. */Sdf: 2,} as const;+/** @public */export type TextRenderMode = (typeof TextRenderMode)[keyof typeof TextRenderMode];+/**+ * {@link Text}'s fields. Alignment and `overflow` read differently with and+ * without a layout box — see {@link TextAlign} and {@link TextOverflow}.+ *+ * @public+ */export interface TextData {content: string;/**@@ -60,6 +88,7 @@ export interface TextData {align: TextAlign;verticalAlign: TextVerticalAlign;wordWrap: boolean;+ /** Not honoured yet — see {@link TextOverflow}. Stored and ignored. */overflow: TextOverflow;lineHeight: number;bold: boolean;@@ -91,6 +120,13 @@ export interface TextData {enabled: boolean;}+/**+ * A run of text. Under a `UINode` it lays out in that box; standing alone it draws+ * in the world at the entity's transform, anchored by its alignment. `content` is+ * derived rather than authored once `i18nKey` is set.+ *+ * @public+ */export const Text = defineComponent<TextData>('Text', {content: '',i18nKey: '',@@ -130,7 +166,11 @@ export const Text = defineComponent<TextData>('Text', {i18nKey: { label: 'I18n Key', enumSource: 'localeKeys', tooltip: 'Localization key — when set, content is resolved from the Localization catalogs (and re-resolved on locale switch). Leave empty for plain text.' },align: { enum: enumOptions(TextAlign), tooltip: 'Horizontal alignment: within the layout box when the entity has a UINode, else it anchors the text to the entity origin (left/center/right edge).' },verticalAlign: { enum: enumOptions(TextVerticalAlign), tooltip: 'Vertical alignment: within the layout box when the entity has a UINode, else it anchors the text to the entity origin (top/middle/bottom).' },- overflow: { enum: enumOptions(TextOverflow) },+ overflow: {+ enum: enumOptions(TextOverflow),+ label: 'Overflow (not implemented)',+ tooltip: 'Not honoured yet: nothing reads this field, so every value renders as Visible. Shown so the data a scene already carries stays editable.',+ },renderMode: { enum: enumOptions(TextRenderMode) },layer: { tooltip: 'Draw layer for a text standing in the WORLD (no UINode) — read like Sprite/ShapeRenderer layer, so a label can sit in front of the content around it. Ignored inside a Canvas, where the UI render order decides.' },},diff --git a/sdk/src/ui/text/text-renderer.ts b/sdk/src/ui/text/text-renderer.tsindex d831cf12a..21dfeb5a9 100644--- a/sdk/src/ui/text/text-renderer.ts+++ b/sdk/src/ui/text/text-renderer.ts@@ -108,6 +108,21 @@ export function tapAlpha(target: number, n: number): number {return 1 - Math.pow(1 - Math.min(1, Math.max(0, target)), 1 / n);}+/**+ * How far a laid-out block sits from `originX`. `layoutText` already aligned each+ * line — within the box width when there is one, within the widest line when there+ * is not — so this only has the boxless job: anchoring the whole block against the+ * origin, left edge / centre / right edge.+ *+ * @param boxWidth the layout box's width; 0 ⇒ boxless, the origin IS the box+ */+export function textBlockOffsetX(+ align: number | undefined, boxWidth: number, blockWidth: number,+): number {+ if (boxWidth > 0 || !align) return 0;+ return -(align === 1 ? blockWidth / 2 : blockWidth); // 1 center, 2 right+}+/*** How far a laid-out block sits from `originY`, once vertical alignment and* half-leading are applied.@@ -184,13 +199,7 @@ export function drawTextWith(atlas: GlyphAtlas, sink: GlyphBatchSink, p: DrawTexarr.push(g);}- // Horizontal: layoutText aligned each LINE within the box width (boxed) or the- // widest line (boxless). For a boxless label, anchor the whole block to the origin- // per align — left = left edge at origin, center = centered, right = right edge.- let baseX = p.originX ?? 0;- if (boxWidth <= 0 && p.align) {- baseX -= p.align === 1 ? layout.width / 2 : layout.width; // 1 center, 2 right- }+ const baseX = (p.originX ?? 0) + textBlockOffsetX(p.align, boxWidth, layout.width);// Emit the glyph set once per page, recolored + offset. All passes are SDF// glyphs in the same atlas/layer, so they batch and draw in submit order —// shadow + outline first (behind), fill last (on top).diff --git a/sdk/tests/ui-text-block-origin.test.ts b/sdk/tests/ui-text-block-origin.test.tsindex b3bc2e158..69dafc5ef 100644--- a/sdk/tests/ui-text-block-origin.test.ts+++ b/sdk/tests/ui-text-block-origin.test.ts@@ -12,53 +12,69 @@* chessboard, which is how it was found.*/import { describe, it, expect } from 'vitest';-import { textBlockOriginY } from '../src/ui/text/text-renderer';+import { textBlockOffsetX, textBlockOriginY } from '../src/ui/text/text-renderer';import { rectTextBox } from '../src/ui/text/text-transform';+// The frozen alignment vocabulary, rather than the 0/1/2 it is: these ARE the+// names, and a test spelling them as numbers cannot catch a renumbering.+import { TextAlign, TextVerticalAlign } from '../src/ui/core/text';const FS = 50;const LINE = FS * 1.2; // the laid block's height at the default lineHeight/** Boxed, pivot-centred: what a UINode of `h` hands the renderer. */-const boxed = (h: number, valign: number): number =>+const boxed = (h: number, valign: TextVerticalAlign): number =>textBlockOriginY(rectTextBox(0.5, 0.5, 100, h, FS).originY, h, LINE, FS, valign, LINE);/** Boxless: the entity origin, nothing else. */-const boxless = (valign: number): number => textBlockOriginY(0, 0, LINE, FS, valign, LINE);+const boxless = (valign: TextVerticalAlign): number => textBlockOriginY(0, 0, LINE, FS, valign, LINE);describe('textBlockOriginY', () => {it('centres a boxless Middle label on the entity, not on its baseline', () => {// The same answer a zero-height box would give, which is the definition// of "the origin IS the box".- expect(boxless(1)).toBeCloseTo(boxed(0.000001, 1), 5);+ expect(boxless(TextVerticalAlign.Middle)).toBeCloseTo(boxed(0.000001, TextVerticalAlign.Middle), 5);// And 0.8em below where it used to land.- expect(boxless(1)).toBeCloseTo(-0.8 * FS + LINE / 2 - (LINE - FS) / 2, 5);+ expect(boxless(TextVerticalAlign.Middle)).toBeCloseTo(-0.8 * FS + LINE / 2 - (LINE - FS) / 2, 5);});it('puts Top, Middle and Bottom on ONE ladder, hanging below to sitting above', () => {- expect(boxless(0)).toBeLessThan(boxless(1));- expect(boxless(1)).toBeLessThan(boxless(2));+ expect(boxless(TextVerticalAlign.Top)).toBeLessThan(boxless(TextVerticalAlign.Middle));+ expect(boxless(TextVerticalAlign.Middle)).toBeLessThan(boxless(TextVerticalAlign.Bottom));// Each is the answer a zero-height box gives — the rule is the same one.- for (const valign of [0, 1, 2]) {+ for (const valign of Object.values(TextVerticalAlign)) {expect(boxless(valign)).toBeCloseTo(boxed(0.000001, valign), 5);}});it('treats an unspecified alignment as Top, not as a third behaviour', () => {- expect(textBlockOriginY(0, 0, LINE, FS, undefined, LINE)).toBeCloseTo(boxless(0), 5);+ expect(textBlockOriginY(0, 0, LINE, FS, undefined, LINE)).toBeCloseTo(boxless(TextVerticalAlign.Top), 5);});it('does not touch the boxed path — a Middle label in a box is unmoved', () => {// Centred in its box: the block's middle lands on the box's middle, which// for a pivot-centred box is the entity. (0.8em baseline, half a line back// up, less half-leading.)- expect(boxed(200, 1)).toBeCloseTo(-0.8 * FS + LINE / 2 - (LINE - FS) / 2, 5);+ expect(boxed(200, TextVerticalAlign.Middle)).toBeCloseTo(-0.8 * FS + LINE / 2 - (LINE - FS) / 2, 5);// Taller box, same answer: centring cannot depend on the box's height.- expect(boxed(400, 1)).toBeCloseTo(boxed(200, 1), 5);+ expect(boxed(400, TextVerticalAlign.Middle)).toBeCloseTo(boxed(200, TextVerticalAlign.Middle), 5);});it('honours half-leading only when the line is taller than the em', () => {// Boxed, so the boxless baseline term is not in play — this isolates leading.- expect(textBlockOriginY(0, 100, FS, FS, 0, FS)).toBe(0);- expect(textBlockOriginY(0, 100, FS, FS, 0, FS * 0.9)).toBe(0); // never negative+ expect(textBlockOriginY(0, 100, FS, FS, TextVerticalAlign.Top, FS)).toBe(0);+ expect(textBlockOriginY(0, 100, FS, FS, TextVerticalAlign.Top, FS * 0.9)).toBe(0); // never negative+ });++ it('anchors a boxless label horizontally per TextAlign, and centres inside a box', () => {+ // The other half of the same rule: no box means the alignment anchors the+ // run against the origin instead of positioning it inside a width.+ const at = (align: TextAlign, boxWidth: number) =>+ textBlockOffsetX(align, boxWidth, 100);+ expect(at(TextAlign.Left, 0)).toBe(0);+ expect(at(TextAlign.Center, 0)).toBeCloseTo(-50, 5);+ expect(at(TextAlign.Right, 0)).toBeCloseTo(-100, 5);+ // Boxed: layoutText already aligned each line inside the width, so the+ // block itself does not move.+ for (const align of Object.values(TextAlign)) expect(at(align, 400)).toBe(0);});});diff --git a/src/esengine/ecs/components/Sprite.hpp b/src/esengine/ecs/components/Sprite.hppindex 2dc8cb180..9ba726196 100644--- a/src/esengine/ecs/components/Sprite.hpp+++ b/src/esengine/ecs/components/Sprite.hpp@@ -43,7 +43,7 @@ namespace esengine::ecs {* sprite.layer = 10; // Render on top* @endcode*/-ES_COMPONENT(renderable=enabled)+ES_COMPONENT(renderable=enabled, stability=public)struct Sprite {/** @brief Texture resource handle (type-safe) */ES_PROPERTY(asset = texture)diff --git a/tools/check-freeze-bar.mjs b/tools/check-freeze-bar.mjsindex 63a9aa77a..de822729f 100644--- a/tools/check-freeze-bar.mjs+++ b/tools/check-freeze-bar.mjs@@ -81,6 +81,10 @@ export const BLOCKED = {Not: { needs: 'called by no golden project', why: 'as And' },addSystem: { needs: 'called by no golden project', why: 'the schedule-less spelling; every project writes addSystemToSchedule instead' },loadInputMapAsset: { needs: 'called by no golden project', why: 'nothing we certify loads an input map from an asset' },+ // Not a corpus gap: nothing reads TextData.overflow, so Clip and Ellipsis+ // render as Visible. Freezing it would promise a behaviour that is missing,+ // and the Inspector still offers the dropdown — now labelled as such.+ TextOverflow: { needs: 'named by no SDK test', why: 'no layout or render path honours it, so there is no behaviour to pin' },};/** Snapshot kinds that a game calls at runtime; the rest are shapes. */diff --git a/tools/check-tier-leaks.mjs b/tools/check-tier-leaks.mjsindex d8152aa8a..ed824dfcd 100644--- a/tools/check-tier-leaks.mjs+++ b/tools/check-tier-leaks.mjs@@ -25,10 +25,12 @@ import { parseSnapshot } from './lib/apiSnapshot.mjs';/*** Frozen symbols known to name unfrozen types, and what is still missing. Empty- * is the goal state, not an oversight: the ECS vocabulary the frozen calls are- * spelled in has all been through the freeze bar, World included.+ * is the goal state: the whole ECS vocabulary went through the bar, World+ * included. A line here is a promise with a declared hole in it.*/-export const ACCEPTED = {};+export const ACCEPTED = {+ TextData: 'names TextOverflow, unfrozen because no layout or render path reads the field it types',+};/** Every symbol across every entry, keeping the strongest tier any entry gives it. */function surface() {