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
/**
* @file ui/core/ui-visual.ts
* @brief UIVisual — the single UI visual component.
*
* Merges the former low-level `UIRenderer` (what the renderer drew) and the
* high-level `Image` (Simple/Sliced/Tiled/Filled intent that used to be copied
* into a UIRenderer every frame). One component authored directly; the C++
* `UIElementPlugin` reads it and derives the sampled UV inline (Tiled by
* box/tileSize, Filled by fillAmount) — the deferred Image→UIRenderer copy is
* gone. Geometry comes from the sibling {@link UINode}. Mirrors the C++
* `UIVisual` builtin.
*/
import { defineBuiltin } from '../../ecs/component';
import type { Color, Vec2, Vec4 } from '../../types';
// Draw mode (None = invisible but render-order/hit-participating; SolidColor;
// Image with a uvOffset/uvScale sub-region; NineSlice via sliceBorder; Tiled
// every tileSize px; Filled = cropped to fillAmount along fillMethod/fillOrigin),
// the Filled fill mode (linear X/Y crops; clockwise Radial360/90/180 sweeps) and
// its anchor edge. All single-sourced from the C++ ES_ENUMs via the generated
// module; FillMethod/FillOrigin keep their public names as aliases of the C++
// UIFillMethod/UIFillOrigin.
import {
UIVisualType,
UIVisualFit,
UIFillMethod as FillMethod,
UIFillOrigin as FillOrigin,
} from '../../wasm/wasm.generated';
export { UIVisualType, UIVisualFit, FillMethod, FillOrigin };
/** The fields of the `UIVisual` component, whose tier this shape carries.
* @beta */
export interface UIVisualData {
visualType: UIVisualType;
texture: number;
color: Color;
/** CSS `object-fit`: Fill stretches to the box (default), Contain
* letterboxes the whole image inside it, Cover fills the box and crops.
* Ignored by NineSlice and Tiled, which exist to adapt to the box. */
fit: UIVisualFit;
/** Base UV sub-region offset (identity = whole texture). */
uvOffset: Vec2;
/** Base UV sub-region scale (identity = whole texture). */
uvScale: Vec2;
/** NineSlice border (texture metadata wins when present). */
sliceBorder: Vec4;
/** Tiled: texture repeats every tileSize px of the box. */
tileSize: Vec2;
/** Filled: axis to crop along. */
fillMethod: FillMethod;
/** Filled: edge the fill grows from. */
fillOrigin: FillOrigin;
/** Filled: visible fraction [0,1]. */
fillAmount: number;
material: number;
enabled: boolean;
}
/**
* What a {@link UINode} draws — a colour, a texture, a nine-slice, a tiled fill
* or a partial one. The node decides the box; this decides what fills it.
*
* @beta
*/
export const UIVisual = defineBuiltin<UIVisualData>('UIVisual', {
visualType: UIVisualType.None,
texture: 0,
color: { r: 1, g: 1, b: 1, a: 1 },
fit: UIVisualFit.Fill,
uvOffset: { x: 0, y: 0 },
uvScale: { x: 1, y: 1 },
sliceBorder: { x: 0, y: 0, z: 0, w: 0 },
tileSize: { x: 32, y: 32 },
fillMethod: FillMethod.Horizontal,
fillOrigin: FillOrigin.Left,
fillAmount: 1,
material: 0,
enabled: true,
});