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.

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.json
index 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.json
index 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.md
index 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: number
minY: number
```
-## CameraData — interface @experimental
+## CameraData — interface @beta
```
aspectRatio: number
clearFlags: number
@@ -6423,7 +6423,7 @@ name: string
type: "spine"
```
-## Sprite — const @experimental
+## Sprite — const @public
```
BuiltinComponentDef<SpriteData>
```
@@ -6507,7 +6507,7 @@ playing: boolean
speed: number
```
-## SpriteData — interface @experimental
+## SpriteData — interface @public
```
color: Color
enabled: 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: TextAlign
bold: boolean
@@ -7044,7 +7044,7 @@ static new (): TextPlugin
static prototype: TextPlugin
```
-## TextRenderMode — type @experimental
+## TextRenderMode — type @public
```
(typeof TextRenderMode)[keyof typeof TextRenderMode]
```
@@ -7059,7 +7059,7 @@ text: string
type: "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.md
index 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: number
minY: number
```
-## CameraData — interface @experimental
+## CameraData — interface @beta
```
aspectRatio: number
clearFlags: number
@@ -6616,7 +6616,7 @@ name: string
type: "spine"
```
-## Sprite — const @experimental
+## Sprite — const @public
```
BuiltinComponentDef<SpriteData>
```
@@ -6700,7 +6700,7 @@ playing: boolean
speed: number
```
-## SpriteData — interface @experimental
+## SpriteData — interface @public
```
color: Color
enabled: 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: TextAlign
bold: boolean
@@ -7237,7 +7237,7 @@ static new (): TextPlugin
static prototype: TextPlugin
```
-## TextRenderMode — type @experimental
+## TextRenderMode — type @public
```
(typeof TextRenderMode)[keyof typeof TextRenderMode]
```
@@ -7252,7 +7252,7 @@ text: string
type: "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.md
index 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: number
minY: number
```
-## CameraData — interface @experimental
+## CameraData — interface @beta
```
aspectRatio: number
clearFlags: number
@@ -6418,7 +6418,7 @@ name: string
type: "spine"
```
-## Sprite — const @experimental
+## Sprite — const @public
```
BuiltinComponentDef<SpriteData>
```
@@ -6502,7 +6502,7 @@ playing: boolean
speed: number
```
-## SpriteData — interface @experimental
+## SpriteData — interface @public
```
color: Color
enabled: 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: TextAlign
bold: boolean
@@ -7039,7 +7039,7 @@ static new (): TextPlugin
static prototype: TextPlugin
```
-## TextRenderMode — type @experimental
+## TextRenderMode — type @public
```
(typeof TextRenderMode)[keyof typeof TextRenderMode]
```
@@ -7054,7 +7054,7 @@ text: string
type: "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.md
index 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: number
minY: number
```
-## CameraData — interface @experimental
+## CameraData — interface @beta
```
aspectRatio: number
clearFlags: number
@@ -6663,7 +6663,7 @@ name: string
type: "spine"
```
-## Sprite — const @experimental
+## Sprite — const @public
```
BuiltinComponentDef<SpriteData>
```
@@ -6747,7 +6747,7 @@ playing: boolean
speed: number
```
-## SpriteData — interface @experimental
+## SpriteData — interface @public
```
color: Color
enabled: 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: TextAlign
bold: boolean
@@ -7284,7 +7284,7 @@ static new (): TextPlugin
static prototype: TextPlugin
```
-## TextRenderMode — type @experimental
+## TextRenderMode — type @public
```
(typeof TextRenderMode)[keyof typeof TextRenderMode]
```
@@ -7299,7 +7299,7 @@ text: string
type: "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.md
index 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: number
minY: number
```
-## CameraData — interface @experimental
+## CameraData — interface @beta
```
aspectRatio: number
clearFlags: number
@@ -6425,7 +6425,7 @@ name: string
type: "spine"
```
-## Sprite — const @experimental
+## Sprite — const @public
```
BuiltinComponentDef<SpriteData>
```
@@ -6509,7 +6509,7 @@ playing: boolean
speed: number
```
-## SpriteData — interface @experimental
+## SpriteData — interface @public
```
color: Color
enabled: 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: TextAlign
bold: boolean
@@ -7046,7 +7046,7 @@ static new (): TextPlugin
static prototype: TextPlugin
```
-## TextRenderMode — type @experimental
+## TextRenderMode — type @public
```
(typeof TextRenderMode)[keyof typeof TextRenderMode]
```
@@ -7061,7 +7061,7 @@ text: string
type: "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.ts
index 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.ts
index 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.ts
index 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.ts
index 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: DrawTex
arr.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.ts
index 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.hpp
index 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.mjs
index 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.mjs
index 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() {