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
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import { defineComponent, enumOptions } from '../../ecs/component';
import type { Color, Vec2 } 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. Needs a box: `Clip` and `Ellipsis` drop the
* lines past the box height, and trim a line past the box width. Trimming is
* whole-glyph — text does not go through a scissor, so a partial glyph is not
* something this can draw.
*
* @public
*/
export const TextOverflow = {
Visible: 0,
Clip: 1,
Ellipsis: 2,
/** Smaller type until the text fits the box: the size drops a whole pixel at a time, and line height and letter spacing with it. */
Shrink: 3,
/** Every line shows, and the box grows to hold them: the entity's `ContentRect` height becomes the text's own. */
ResizeHeight: 4,
} as const;
/** @public */
export type TextOverflow = (typeof TextOverflow)[keyof typeof TextOverflow];
/** Glyph pipeline for a Text.
* @public */
export const TextRenderMode = {
/** Hinted bitmap while the entity is unscaled, SDF once it scales. */
Auto: 0,
/** Canvas2D native AA at the on-screen pixel size. Sharpest when static. */
Bitmap: 1,
/** 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;
/**
* Localization key. Non-empty ⇒ `content` is DERIVED: every frame the
* text-localization system resolves the key through the app's Localization
* resource (opt-in plugin) and writes the result into `content`, so a
* `setLocale` re-flows every bound label. Empty (default) or no
* Localization resource ⇒ `content` stands as authored.
*/
i18nKey: string;
/**
* A font asset the game SHIPS (`.ttf` / `.otf` / `.woff`). When set it wins
* over {@link fontFamily}: the loader registers the file with the platform's
* text stack and this handle resolves back to that family. Leave it empty to
* name a font the host already has, through `fontFamily`.
*/
font: number;
/** Font family resolved by the platform's text stack — a font the HOST
* already has. For a font you ship, use {@link font} instead. */
fontFamily: string;
fontSize: number;
color: Color;
align: TextAlign;
verticalAlign: TextVerticalAlign;
wordWrap: boolean;
overflow: TextOverflow;
lineHeight: number;
/**
* Extra space after every glyph, in the same px as `fontSize`; negative draws them closer. It is CSS's
* `letter-spacing` and a Cocos Label's `spacingX`. Wrapping, alignment, `Ellipsis` and `Shrink` all measure
* with it, and `Shrink` scales it with the size. Absent is 0.
*/
letterSpacing?: number;
bold: boolean;
italic: boolean;
strokeColor: Color;
strokeWidth: number;
shadowColor: Color;
shadowBlur: number;
shadowOffsetX: number;
shadowOffsetY: number;
/** A line under each line of text, in the font's own underscore. Absent is off. */
underline?: boolean;
richText: boolean;
renderMode: TextRenderMode;
/**
* Draw layer, for a text with NO layout box — a label standing in the world
* rather than inside a Canvas. It is read the same way Sprite.layer and
* ShapeRenderer.layer are, so a label can be put in front of (or behind) the
* world content around it.
*
* Ignored under a UINode: inside a Canvas the UI render order decides, and a
* second knob there would let a text sort against its own panel.
*
* It exists because world text was pinned to layer 0 with no way off it, so
* any ShapeRenderer or Sprite that also sat on layer 0 and drew later simply
* covered it — a board hiding its own pieces, a name tag behind the character
* it names — with nothing in the component to reach for.
*/
layer: number;
/**
* Width of the layout box for a text with NO `UINode` — 0 (the default) means no box, and the entity origin
* is the box, as it always was. With a box, alignment, wrapping and overflow work inside it, exactly as
* under a `UINode`, while the text stays world content sorted by `layer`. A `UINode`, when present, decides
* the box and these three are ignored.
*/
boxWidth?: number;
/** Height of that box; 0 for none. Vertical alignment and `Clip`/`Ellipsis` need it. */
boxHeight?: number;
/**
* Where the entity origin sits inside the box, as a fraction from its left and bottom edges: (0.5, 0.5) is
* the centre, (0, 1) the top-left corner. It is the anchor point of a Cocos or Unity rect transform.
*/
boxPivot?: Vec2;
/** Render toggle — the editor's eye and runtime hiding both flip this. */
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: '',
font: 0,
fontFamily: '',
fontSize: 24,
color: { r: 1, g: 1, b: 1, a: 1 },
align: TextAlign.Left,
verticalAlign: TextVerticalAlign.Top,
wordWrap: true,
overflow: TextOverflow.Visible,
lineHeight: 1.2,
letterSpacing: 0,
bold: false,
italic: false,
strokeColor: { r: 0, g: 0, b: 0, a: 1 },
strokeWidth: 0,
shadowColor: { r: 0, g: 0, b: 0, a: 1 },
shadowBlur: 0,
shadowOffsetX: 0,
shadowOffsetY: 0,
underline: false,
richText: false,
renderMode: TextRenderMode.Auto,
layer: 0,
boxWidth: 0,
boxHeight: 0,
boxPivot: { x: 0.5, y: 0.5 },
enabled: true,
}, {
// Text draws itself (the plugin skips a disabled one) rather than through a
// sibling UIVisual, so hiding an entity has to reach this flag — the same
// declaration the C++ renderables make at their ES_COMPONENT site.
renderableField: 'enabled',
// A shipped font is a real asset reference: declaring it here is what gives
// it dependency tracking, cook inclusion, `@uuid:` refs and hot-update for
// free — the same machinery every other asset slot rides.
assetFields: [{ field: 'font', type: 'font' }],
fields: {
font: { label: 'Font', tooltip: 'A font file this project ships (.ttf / .otf). Overrides Font Family when set; leave empty to use a font the host already has.' },
fontFamily: { tooltip: 'A font the HOST already has (system or page-loaded). Ignored when Font is set.' },
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),
tooltip: 'What text too big for its box does. Needs a layout box: Clip and Ellipsis drop the lines past its height and trim a line past its width; Shrink sets the text smaller until it fits both.',
},
letterSpacing: { tooltip: 'Extra space after every glyph, in the same px as Font Size. Negative draws the glyphs closer. Wrapping, alignment and overflow measure with it.' },
underline: { tooltip: 'Draw a line under each line of text, using the underscore of the font.' },
renderMode: { enum: enumOptions(TextRenderMode) },
boxWidth: { tooltip: 'Layout box width for a text with no UINode (0 = no box: the origin is the box). Alignment, wrapping and overflow work inside it. A UINode, if present, decides the box instead.' },
boxHeight: { tooltip: 'Layout box height (0 = none). Vertical alignment and Clip/Ellipsis need it.' },
boxPivot: { tooltip: 'Where the entity origin sits in the box, as a fraction from its left/bottom edge: (0.5, 0.5) is the centre, (0, 1) the top-left corner.' },
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.' },
},
});