@galacean/engine-ui 1.6.8 → 1.6.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@galacean/engine-ui",
-  "version": "1.6.8",
+  "version": "1.6.10",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"
@@ -26,10 +26,10 @@
     "types/**/*"
   ],
   "devDependencies": {
-    "@galacean/engine": "npm:@galacean/engine-backup@1.6.8"
+    "@galacean/engine": "1.6.10"
   },
   "peerDependencies": {
-    "@galacean/engine": "npm:@galacean/engine-backup@1.6.8"
+    "@galacean/engine": "1.6.10"
   },
   "scripts": {
     "b:types": "tsc"

package/types/Utils.d.ts

@@ -0,0 +1,18 @@
+import { UICanvas } from "./component/UICanvas";
+import { UIGroup } from "./component/UIGroup";
+import { IElement } from "./interface/IElement";
+import { IGroupAble } from "./interface/IGroupAble";
+export declare class Utils {
+    static setRootCanvasDirty(element: IElement): void;
+    static setRootCanvas(element: IElement, rootCanvas: UICanvas): void;
+    static cleanRootCanvas(element: IElement): void;
+    static searchRootCanvasInParents(element: IElement): UICanvas;
+    static setGroupDirty(element: IGroupAble): void;
+    static setGroup(element: IGroupAble, group: UIGroup): void;
+    static cleanGroup(element: IGroupAble): void;
+    static searchGroupInParents(element: IGroupAble): UIGroup;
+    private static _registerRootCanvas;
+    private static _registerGroup;
+    private static _registerListener;
+    private static _unRegisterListener;
+}

package/types/component/UICanvas.d.ts

@@ -0,0 +1,91 @@
+import { Camera, Component, Vector2 } from "@galacean/engine";
+import { CanvasRenderMode } from "../enums/CanvasRenderMode";
+import { ResolutionAdaptationMode } from "../enums/ResolutionAdaptationMode";
+import { IElement } from "../interface/IElement";
+/**
+ * The UI Canvas component serves as the root node for UI elements,
+ * handling rendering and events based on it.
+ */
+export declare class UICanvas extends Component implements IElement {
+    private static _targetTempPath;
+    private static _tempGroupAbleList;
+    private static _tempVec3;
+    private static _tempMat;
+    private _renderMode;
+    private _renderCamera;
+    private _cameraObserver;
+    private _resolutionAdaptationMode;
+    private _sortOrder;
+    private _distance;
+    private _referenceResolution;
+    private _referenceResolutionPerUnit;
+    private _hierarchyVersion;
+    private _center;
+    private _centerDirtyFlag;
+    /**
+     * The conversion ratio between reference resolution and unit for UI elements in this canvas.
+     */
+    get referenceResolutionPerUnit(): number;
+    set referenceResolutionPerUnit(value: number);
+    /**
+     * The reference resolution of the UI canvas in `ScreenSpaceCamera` and `ScreenSpaceOverlay` mode.
+     */
+    get referenceResolution(): Vector2;
+    set referenceResolution(value: Vector2);
+    /**
+     * The rendering mode of the UI canvas.
+     */
+    get renderMode(): CanvasRenderMode;
+    set renderMode(mode: CanvasRenderMode);
+    /**
+     * The camera used to render the UI canvas in `ScreenSpaceCamera` mode.
+     * @remarks If set `ScreenSpaceCamera` but no corresponding camera is assigned, the actual rendering mode defaults to `ScreenSpaceOverlay`.
+     */
+    get renderCamera(): Camera;
+    set renderCamera(value: Camera);
+    /**
+     * The screen resolution adaptation mode of the UI canvas in `ScreenSpaceCamera` and `ScreenSpaceOverlay` mode.
+     */
+    get resolutionAdaptationMode(): ResolutionAdaptationMode;
+    set resolutionAdaptationMode(value: ResolutionAdaptationMode);
+    /**
+     * The rendering order priority of the UI canvas in `ScreenSpaceOverlay` mode.
+     */
+    get sortOrder(): number;
+    set sortOrder(value: number);
+    /**
+     * The distance between the UI canvas and the camera in `ScreenSpaceCamera` mode.
+     */
+    get distance(): number;
+    set distance(value: number);
+    _onEnableInScene(): void;
+    _onDisableInScene(): void;
+    private _getRenderers;
+    private _adapterPoseInScreenSpace;
+    private _adapterSizeInScreenSpace;
+    private _walk;
+    private _updateCameraObserver;
+    private _onCameraModifyListener;
+    private _onCameraTransformListener;
+    private _addCanvasListener;
+    private _removeCanvasListener;
+    private _onCanvasSizeListener;
+    private _onReferenceResolutionChanged;
+    private _setIsRootCanvas;
+    private _getCenter;
+    private _getRealRenderMode;
+    private _setRealRenderMode;
+    private _isSameOrChildEntity;
+}
+/**
+ * @remarks Extends `EntityModifyFlags`.
+ */
+export declare enum EntityUIModifyFlags {
+    CanvasEnableInScene = 4,
+    GroupEnableInScene = 8
+}
+export declare enum RootCanvasModifyFlags {
+    None = 0,
+    ReferenceResolutionPerUnit = 1,
+    All = 1
+}

package/types/component/UIGroup.d.ts

@@ -0,0 +1,37 @@
+import { Component, Entity } from "@galacean/engine";
+import { IGroupAble } from "../interface/IGroupAble";
+export declare class UIGroup extends Component implements IGroupAble {
+    private _alpha;
+    private _interactive;
+    private _ignoreParentGroup;
+    /**
+     * Whether to ignore the parent group.
+     * @remarks If this parameter set to `true`,
+     * all settings of the parent group will be ignored.
+     */
+    get ignoreParentGroup(): boolean;
+    set ignoreParentGroup(value: boolean);
+    /**
+     * Whether the group is interactive.
+     */
+    get interactive(): boolean;
+    set interactive(value: boolean);
+    /**
+     * The alpha value of the group.
+     */
+    get alpha(): number;
+    set alpha(value: number);
+    constructor(entity: Entity);
+    _onEnableInScene(): void;
+    _onDisableInScene(): void;
+    private _isContainDirtyFlags;
+    private _isContainDirtyFlag;
+    private _setDirtyFlagTrue;
+    private _setDirtyFlagFalse;
+}
+export declare enum GroupModifyFlags {
+    None = 0,
+    GlobalAlpha = 1,
+    GlobalInteractive = 2,
+    All = 3
+}

package/types/component/UIRenderer.d.ts

@@ -0,0 +1,36 @@
+import { Color, Renderer, Vector3, Vector4 } from "@galacean/engine";
+import { IGraphics } from "../interface/IGraphics";
+export declare class UIRenderer extends Renderer implements IGraphics {
+    /**
+     * Custom boundary for raycast detection.
+     * @remarks this is based on `this.entity.transform`.
+     */
+    raycastPadding: Vector4;
+    private _raycastEnabled;
+    protected _color: Color;
+    /**
+     * Rendering color for the ui renderer.
+     */
+    get color(): Color;
+    set color(value: Color);
+    /**
+     * Whether this renderer be picked up by raycast.
+     */
+    get raycastEnabled(): boolean;
+    set raycastEnabled(value: boolean);
+    _canBatch(elementA: any, elementB: any): boolean;
+    _batch(elementA: any, elementB?: any): void;
+    _updateTransformShaderData(context: any, onlyMVP: boolean, batched: boolean): void;
+    _prepareRender(context: any): void;
+    _onEnableInScene(): void;
+    _onDisableInScene(): void;
+    private _onColorChanged;
+    protected _hitTest(localPosition: Vector3): boolean;
+    protected _onDestroy(): void;
+}
+/**
+ * @remarks Extends `RendererUpdateFlags`.
+ */
+export declare enum UIRendererUpdateFlags {
+    Color = 2
+}

package/types/component/UITransform.d.ts

@@ -0,0 +1,111 @@
+import { Entity, Transform, Vector2 } from "@galacean/engine";
+import { HorizontalAlignmentMode } from "../enums/HorizontalAlignmentMode";
+import { VerticalAlignmentMode } from "../enums/VerticalAlignmentMode";
+/**
+ * The Transform component exclusive to the UI element.
+ */
+export declare class UITransform extends Transform {
+    private _size;
+    private _pivot;
+    private _rect;
+    private _alignLeft;
+    private _alignRight;
+    private _alignCenter;
+    private _alignTop;
+    private _alignBottom;
+    private _alignMiddle;
+    private _horizontalAlignment;
+    private _verticalAlignment;
+    /**
+     * Width and height of UI element.
+     */
+    get size(): Vector2;
+    set size(value: Vector2);
+    /**
+     * Pivot of UI element.
+     */
+    get pivot(): Vector2;
+    set pivot(value: Vector2);
+    /**
+     * Horizontal alignment mode.
+     *
+     * @remarks
+     * Controls how the element aligns horizontally within its parent:
+     * - `Left` - Align to parent's left edge
+     * - `Center` - Align to parent's horizontal center
+     * - `Right` - Align to parent's right edge
+     * - `LeftAndRight` - Align to both left and right edges (stretch to fill width)
+     */
+    get horizontalAlignment(): HorizontalAlignmentMode;
+    set horizontalAlignment(value: HorizontalAlignmentMode);
+    /**
+     * Left margin when horizontalAlignment is Left or LeftAndRight.
+     *
+     * @remarks
+     * Only effective when horizontalAlignment includes Left mode.
+     * Distance from the parent's left edge to the element's left edge.
+     */
+    get alignLeft(): number;
+    set alignLeft(value: number);
+    /**
+     * Right margin when horizontalAlignment is Right or LeftAndRight.
+     *
+     * @remarks
+     * Only effective when horizontalAlignment includes Right mode.
+     * Distance from the parent's right edge to the element's right edge.
+     */
+    get alignRight(): number;
+    set alignRight(value: number);
+    /**
+     * Horizontal center offset when horizontalAlignment is Center.
+     *
+     * @remarks
+     * Only effective when horizontalAlignment is Center mode.
+     * Positive values move the element to the right, negative values to the left.
+     */
+    get alignCenter(): number;
+    set alignCenter(value: number);
+    /**
+     * Vertical alignment mode.
+     *
+     * @remarks
+     * Controls how the element aligns vertically within its parent:
+     * - `Top` - Align to parent's top edge
+     * - `Middle` - Align to parent's vertical center
+     * - `Bottom` - Align to parent's bottom edge
+     * - `TopAndBottom` - Align to both top and bottom edges (stretch to fill height)
+     */
+    get verticalAlignment(): VerticalAlignmentMode;
+    set verticalAlignment(value: VerticalAlignmentMode);
+    /**
+     * Top margin when verticalAlignment is Top or TopAndBottom.
+     *
+     * @remarks
+     * Only effective when verticalAlignment includes Top mode.
+     * Used to offset the element from the parent's top edge.
+     */
+    get alignTop(): number;
+    set alignTop(value: number);
+    /**
+     * Bottom inset used in vertical alignment formulas.
+     */
+    get alignBottom(): number;
+    set alignBottom(value: number);
+    /**
+     * Vertical middle offset relative to parent's middle.
+     */
+    get alignMiddle(): number;
+    set alignMiddle(value: number);
+    _cloneTo(target: UITransform, srcRoot: Entity, targetRoot: Entity): void;
+    protected _onLocalMatrixChanging(): void;
+    protected _onWorldMatrixChanging(): void;
+    protected _onPositionChanged(): void;
+    protected _onWorldPositionChanged(): void;
+    private _updatePositionByAlignment;
+    private _updateSizeByAlignment;
+    private _updateRectBySizeAndPivot;
+    private _onSizeChanged;
+    private _onPivotChanged;
+    private _updateWorldFlagWithSelfRectChange;
+    private _updateWorldFlagWithParentRectChange;
+}

package/types/component/advanced/Button.d.ts

@@ -0,0 +1,21 @@
+import { PointerEventData } from "@galacean/engine";
+import { UIInteractive } from "../interactive/UIInteractive";
+export declare class Button extends UIInteractive {
+    private _listeners;
+    /**
+     * Add a listening function for click.
+     * @param listener - The listening function
+     */
+    addClicked(listener: (event: PointerEventData) => void): void;
+    /**
+     * Remove a listening function of click.
+     * @param listener - The listening function
+     */
+    removeClicked(listener: (event: PointerEventData) => void): void;
+    onPointerClick(event: PointerEventData): void;
+    onDestroy(): void;
+}
+export interface IUIListener {
+    fn: (event: PointerEventData) => void;
+    destroyed?: boolean;
+}

package/types/component/advanced/Image.d.ts

@@ -0,0 +1,37 @@
+import { BoundingBox, ISpriteRenderer, Sprite, SpriteDrawMode, SpriteTileMode } from "@galacean/engine";
+import { UIRenderer } from "../UIRenderer";
+/**
+ * UI element that renders an image.
+ */
+export declare class Image extends UIRenderer implements ISpriteRenderer {
+    private _sprite;
+    private _drawMode;
+    private _assembler;
+    private _tileMode;
+    private _tiledAdaptiveThreshold;
+    /**
+     * The draw mode of the image.
+     */
+    get drawMode(): SpriteDrawMode;
+    set drawMode(value: SpriteDrawMode);
+    /**
+     * The tiling mode of the image. (Only works in tiled mode.)
+     */
+    get tileMode(): SpriteTileMode;
+    set tileMode(value: SpriteTileMode);
+    /**
+     * Stretch Threshold in Tile Adaptive Mode, specified in normalized. (Only works in tiled adaptive mode.)
+     */
+    get tiledAdaptiveThreshold(): number;
+    set tiledAdaptiveThreshold(value: number);
+    /**
+     * The Sprite to render.
+     */
+    get sprite(): Sprite;
+    set sprite(value: Sprite | null);
+    protected _updateBounds(worldBounds: BoundingBox): void;
+    protected _render(context: any): void;
+    protected _onTransformChanged(type: number): void;
+    protected _onDestroy(): void;
+    private _onSpriteChange;
+}

package/types/component/advanced/Text.d.ts

@@ -0,0 +1,88 @@
+import { BoundingBox, Entity, Font, FontStyle, ITextRenderer, OverflowMode, TextHorizontalAlignment, TextVerticalAlignment } from "@galacean/engine";
+import { UIRenderer } from "../UIRenderer";
+/**
+ * UI component used to render text.
+ */
+export declare class Text extends UIRenderer implements ITextRenderer {
+    private static _textTextureProperty;
+    private static _worldPositions;
+    private static _charRenderInfos;
+    private _textChunks;
+    private _subFont;
+    private _text;
+    private _localBounds;
+    private _font;
+    private _fontSize;
+    private _fontStyle;
+    private _lineSpacing;
+    private _horizontalAlignment;
+    private _verticalAlignment;
+    private _enableWrapping;
+    private _overflowMode;
+    /**
+     * Rendering string for the Text.
+     */
+    get text(): string;
+    set text(value: string);
+    /**
+     * The font of the Text.
+     */
+    get font(): Font;
+    set font(value: Font);
+    /**
+     * The font size of the Text.
+     */
+    get fontSize(): number;
+    set fontSize(value: number);
+    /**
+     * The style of the font.
+     */
+    get fontStyle(): FontStyle;
+    set fontStyle(value: FontStyle);
+    /**
+     * The space between two lines (in pixels).
+     */
+    get lineSpacing(): number;
+    set lineSpacing(value: number);
+    /**
+     * The horizontal alignment.
+     */
+    get horizontalAlignment(): TextHorizontalAlignment;
+    set horizontalAlignment(value: TextHorizontalAlignment);
+    /**
+     * The vertical alignment.
+     */
+    get verticalAlignment(): TextVerticalAlignment;
+    set verticalAlignment(value: TextVerticalAlignment);
+    /**
+     * Whether wrap text to next line when exceeds the width of the container.
+     */
+    get enableWrapping(): boolean;
+    set enableWrapping(value: boolean);
+    /**
+     * The overflow mode.
+     */
+    get overflowMode(): OverflowMode;
+    set overflowMode(value: OverflowMode);
+    /**
+     * The mask layer the sprite renderer belongs to.
+     */
+    get maskLayer(): number;
+    set maskLayer(value: number);
+    /**
+     * The bounding volume of the TextRenderer.
+     */
+    get bounds(): BoundingBox;
+    constructor(entity: Entity);
+    _cloneTo(target: Text, srcRoot: Entity, targetRoot: Entity): void;
+    protected _updateBounds(worldBounds: BoundingBox): void;
+    protected _render(context: any): void;
+    private _resetSubFont;
+    private _updatePosition;
+    private _updateColor;
+    private _updateLocalData;
+    protected _onTransformChanged(type: number): void;
+    private _isTextNoVisible;
+    private _buildChunk;
+    private _freeTextChunks;
+}

package/types/component/index.d.ts

@@ -0,0 +1,11 @@
+export { UICanvas } from "./UICanvas";
+export { UIGroup } from "./UIGroup";
+export { UIRenderer } from "./UIRenderer";
+export { UITransform } from "./UITransform";
+export { Button } from "./advanced/Button";
+export { Image } from "./advanced/Image";
+export { Text } from "./advanced/Text";
+export { ColorTransition } from "./interactive/transition/ColorTransition";
+export { ScaleTransition } from "./interactive/transition/ScaleTransition";
+export { SpriteTransition } from "./interactive/transition/SpriteTransition";
+export { Transition } from "./interactive/transition/Transition";

package/types/component/interactive/UIInteractive.d.ts

@@ -0,0 +1,55 @@
+import { Entity, Script } from "@galacean/engine";
+import { IGroupAble } from "../../interface/IGroupAble";
+import { Transition } from "./transition/Transition";
+/**
+ * Interactive component.
+ */
+export declare class UIInteractive extends Script implements IGroupAble {
+    private static _targetTempPath;
+    protected _transitions: Transition[];
+    protected _interactive: boolean;
+    protected _state: InteractiveState;
+    /** @todo Multi-touch points are not considered yet. */
+    private _isPointerInside;
+    private _isPointerDragging;
+    /**
+     * The transitions of this interactive.
+     */
+    get transitions(): Readonly<Transition[]>;
+    /**
+     * Whether the interactive is enabled.
+     */
+    get interactive(): boolean;
+    set interactive(value: boolean);
+    /**
+     * Add transition on this interactive.
+     * @param transition - The transition
+     */
+    addTransition(transition: Transition): void;
+    /**
+     * Remove a transition.
+     * @param shape - The transition.
+     */
+    removeTransition(transition: Transition): void;
+    /**
+     * Remove all transitions.
+     */
+    clearTransitions(): void;
+    onUpdate(deltaTime: number): void;
+    onPointerBeginDrag(): void;
+    onPointerEndDrag(): void;
+    onPointerEnter(): void;
+    onPointerExit(): void;
+    onDestroy(): void;
+    _cloneTo(target: UIInteractive, srcRoot: Entity, targetRoot: Entity): void;
+    _onEnableInScene(): void;
+    _onDisableInScene(): void;
+    private _updateState;
+    private _getInteractiveState;
+}
+export declare enum InteractiveState {
+    Normal = 0,
+    Pressed = 1,
+    Hover = 2,
+    Disable = 3
+}

package/types/component/interactive/transition/ColorTransition.d.ts

@@ -0,0 +1,17 @@
+import { Color } from "@galacean/engine";
+import { UIRenderer } from "../../UIRenderer";
+import { Transition } from "./Transition";
+/**
+ * Color transition.
+ */
+export declare class ColorTransition extends Transition<Color, UIRenderer> {
+    private _color;
+    constructor();
+    private _onNormalValueChanged;
+    private _onHoverValueChanged;
+    private _onPressedValueChanged;
+    private _onDisabledValueChanged;
+    protected _getTargetValueCopy(): Color;
+    protected _updateCurrentValue(srcValue: Color, destValue: Color, weight: number): void;
+    protected _applyValue(value: Color): void;
+}

package/types/component/interactive/transition/ScaleTransition.d.ts

@@ -0,0 +1,11 @@
+import { UIRenderer } from "../../UIRenderer";
+import { Transition } from "./Transition";
+/**
+ * Scale transition.
+ */
+export declare class ScaleTransition extends Transition<number, UIRenderer> {
+    constructor();
+    protected _getTargetValueCopy(): number;
+    protected _updateCurrentValue(srcValue: number, destValue: number, weight: number): void;
+    protected _applyValue(value: number): void;
+}

package/types/component/interactive/transition/SpriteTransition.d.ts

@@ -0,0 +1,11 @@
+import { Sprite } from "@galacean/engine";
+import { Image } from "../../advanced/Image";
+import { Transition } from "./Transition";
+/**
+ * Sprite transition.
+ */
+export declare class SpriteTransition extends Transition<Sprite, Image> {
+    protected _getTargetValueCopy(): Sprite;
+    protected _updateCurrentValue(srcValue: Sprite, destValue: Sprite, weight: number): void;
+    protected _applyValue(value: Sprite): void;
+}

package/types/component/interactive/transition/Transition.d.ts

@@ -0,0 +1,57 @@
+import { Color, Sprite } from "@galacean/engine";
+import { UIRenderer } from "../../UIRenderer";
+import { InteractiveState } from "../UIInteractive";
+/**
+ * The transition behavior of UIInteractive.
+ */
+export declare abstract class Transition<T extends TransitionValueType = TransitionValueType, K extends UIRenderer = UIRenderer> {
+    protected _target: K;
+    protected _normal: T;
+    protected _pressed: T;
+    protected _hover: T;
+    protected _disabled: T;
+    protected _duration: number;
+    protected _countDown: number;
+    protected _initialValue: T;
+    protected _finalValue: T;
+    protected _currentValue: T;
+    protected _finalState: InteractiveState;
+    /**
+     * The normal state of the transition.
+     */
+    get normal(): T;
+    set normal(value: T);
+    /**
+     * The pressed state of the transition.
+     */
+    get pressed(): T;
+    set pressed(value: T);
+    /**
+     * The hover state of the transition.
+     */
+    get hover(): T;
+    set hover(value: T);
+    /**
+     * The disabled state of the transition.
+     */
+    get disabled(): T;
+    set disabled(value: T);
+    /**
+     * The target of the transition.
+     */
+    get target(): K;
+    set target(value: K);
+    /**
+     * The duration of the transition.
+     */
+    get duration(): number;
+    set duration(value: number);
+    destroy(): void;
+    protected abstract _getTargetValueCopy(): T;
+    protected abstract _updateCurrentValue(srcValue: T, destValue: T, weight: number): void;
+    protected abstract _applyValue(value: T): void;
+    protected _onStateValueDirty(state: InteractiveState, preValue: T, curValue: T): void;
+    protected _updateValue(): void;
+    private _getValueByState;
+}
+export type TransitionValueType = number | Sprite | Color;

package/types/enums/CanvasRenderMode.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Render mode for ui canvas.
+ */
+export declare enum CanvasRenderMode {
+    /**
+     * The UI canvas will be rendered directly onto the screen and adapted to screen space,
+     * overlaying other rendering elements in the same scene.
+     * @remarks if the `engine.canvas` size change, the UI canvas will automatically adapt.
+     */
+    ScreenSpaceOverlay = 0,
+    /**
+     * The UI canvas is placed at a specified distance in front of the camera and adapted to screen space,
+     * with all objects rendered by the camera.
+     * @remarks if the camera's properties or the `engine.canvas` size change, the UI canvas will automatically adapt.
+     * @remarks if set `ScreenSpaceCamera` but no corresponding camera is assigned, the actual rendering mode defaults to `ScreenSpaceOverlay`.
+     */
+    ScreenSpaceCamera = 1,
+    /**
+     * The UI canvas is placed in the 3D world space and rendered by every camera in the same scene.
+     */
+    WorldSpace = 2
+}

package/types/enums/HorizontalAlignmentMode.d.ts

@@ -0,0 +1,13 @@
+/** Horizontal alignment mode. */
+export declare enum HorizontalAlignmentMode {
+    /** No horizontal alignment. */
+    None = 0,
+    /** Left-aligned, `alignLeft` drives `position.x`. */
+    Left = 1,
+    /** Right-aligned, `alignRight` drives `position.x`. */
+    Right = 2,
+    /** Horizontal stretch, `alignLeft` and `alignRight` drive `position.x` and `size.x`. */
+    LeftAndRight = 3,
+    /** Center-aligned, `alignCenter` drives `position.x`. */
+    Center = 4
+}