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.

16.0 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    ui/index.ts
 * @brief   UI module — public barrel.
 */

// Shared Helpers
export {
    initUIHelpers,
    nextPowerOf2,
    ensureComponent,
    walkParentChain,
    isPointerBlockedInTree,
    EntityStateMap,
} from './util/helpers';

// UI Constants
export {
    TEXT_PADDING_RATIO,
    TEXT_CANVAS_SHRINK_FRAMES,
    TEXT_CANVAS_OVERSIZE_RATIO,
    TEXT_INPUT_LINE_HEIGHT_RATIO,
    CURSOR_BLINK_INTERVAL,
    SCROLL_WHEEL_SENSITIVITY,
    SCROLL_MAX_DT,
    SCROLL_VELOCITY_THRESHOLD,
    SCROLL_VELOCITY_LERP_SPEED,
    SCROLL_ELASTIC_SMOOTH_TIME,
    SCROLL_ELASTIC_SNAP_THRESHOLD,
    SCROLL_MAX_OVERSCROLL_RATIO,
    SCROLL_MAX_VELOCITY_RATIO,
} from './util/constants';

// ─── Layer 0: Events ────────────────────────────────────────────────────────

export {
    UIEvents,
    UIEventQueue,
    UIEventType,
    type UIEvent,
    type UIEventHandler,
    type Unsubscribe,
} from './core/events';

// ─── Layer 1: Primitives ────────────────────────────────────────────────────

export { DimensionUnit, type Dimension, px, percent, auto, isAuto } from './core/dimension';
// `UIPointerEvents` rides along with the rest: it is the enum of a public UINode field,
// and without it a game turning a closing panel click-through has to write the raw 1.
export { UINode, UIPositionType, UIDisplay, UIPointerEvents, AlignSelf, type UINodeData } from './core/ui-node';

export {
    UIVisual,
    UIVisualType,
    UIVisualFit,
    FillMethod,
    FillOrigin,
    type UIVisualData,
} from './core/ui-visual';

export { UIMask, MaskMode, type UIMaskData } from './core/ui-mask';
export { UIWorldAnchor, placeOnScreen, type UIWorldAnchorData, type AnchorLens, type AnchorPlacement } from './core/world-anchor';
export { UIScroll, ScrollMovement, type UIScrollData } from './core/ui-scroll';
export { ContentRect, applyContentRect, contentRectContains, localPointInRect, type ContentRectData } from './core/content-rect';
export { contentRectPlugin, ContentRectPlugin } from './render/content-rect';
export { RectAnchors, rectAnchorsPlugin, RectAnchorsPlugin, AnchorFlag, AnchorMode, anchoredRect, alignRectAnchorsNow, alignAllRectAnchors, forgetRectAnchors, setRectAnchorsScreenFallback, type RectAnchorsData } from './layout/rect-anchors';

export {
    Text,
    TextAlign,
    TextVerticalAlign,
    TextOverflow,
    TextRenderMode,
    type TextData,
} from './core/text';

export {
    FlexContainer,
    FlexDirection,
    FlexWrap,
    JustifyContent,
    AlignItems,
    AlignContent,
    type FlexContainerData,
} from './layout/flex';

export {
    AnchorAxis,
    ANCHOR_AXES,
    anchorPresetFields,
    detectAnchor,
    detectAnchorAxes,
    type AnchorPreset,
    type AnchorFields,
} from './layout/anchor';

// ─── Layer 2: Behaviors ─────────────────────────────────────────────────────

export {
    Interactable,
    UIInteraction,
    makeWidgetInteractable,
    type InteractableData,
    type UIInteractionData,
    type WidgetInteractionInit,
} from './input/interactable';

export {
    Focusable,
    FocusManager,
    FocusManagerState,
    type FocusableData,
} from './input/focusable';

export {
    Draggable,
    DragState,
    type DraggableData,
    type DragStateData,
} from './input/draggable';

export { UIBehaviorPlugin, uiBehaviorPlugin } from './behavior/plugin';

export {
    UIDialog,
    isDialogOpen,
    openDialog,
    closeDialog,
    createDialogSystem,
    type UIDialogData,
} from './behavior/dialog';

export {
    UISlider,
    sliderClamp,
    sliderFraction,
    createSliderSystem,
    type UISliderData,
} from './behavior/slider';

export {
    UIToggle,
    UIToggleGroup,
    createToggleSystem,
    type UIToggleData,
    type UIToggleGroupData,
} from './behavior/toggle';
export { UITabView, createTabViewSystem, applyTabViewSelection, tabViewBindings } from './behavior/tab-view';
export type { UITabViewData } from './behavior/tab-view';
export { UITreeView } from './behavior/tree-view';
export type { UITreeViewData, TreeViewNode } from './behavior/tree-view';
export { UIColorPicker } from './behavior/color-picker';
export type { UIColorPickerData } from './behavior/color-picker';
export { TreeViewModel } from './collection/tree-data-source';
export type { TreeDataSource, TreeItemId, TreeRow, TreeDropRequest } from './collection/tree-data-source';
export { createTreeView, setTreeViewData } from './widgets/tree-view';
export type { TreeViewOptions, TreeViewHandle } from './widgets/tree-view';
export { createColorPicker } from './widgets/color-picker';
export type { ColorPickerOptions, ColorPickerHandle } from './widgets/color-picker';
export { UITooltip, createTooltipSystem, placeTooltip, previewTooltip } from './behavior/tooltip';
export type { UITooltipData, TooltipPrefabHost } from './behavior/tooltip';
export { createTabView } from './widgets/tab-view';
export type { TabViewOptions, TabViewHandle } from './widgets/tab-view';
export { attachTooltip, createTooltip } from './widgets/tooltip';
export type { TooltipOptions, TooltipHandle } from './widgets/tooltip';

export {
    UIDropdown,
    isDropdownOpen,
    openDropdown,
    closeDropdown,
    createDropdownSystem,
    type UIDropdownData,
} from './behavior/dropdown';

export { createScrollbarSystem } from './behavior/scrollbar';

// ─── Controllers + Gears (shared UI state) ──────────────────────────────────

export {
    UIController,
    INTERACTION_CONTROLLER,
    INTERACTION_PAGES,
    interactionController,
    controllerState,
    findControllerOwner,
    getControllerPage,
    setControllerPage,
    type ControllerState,
    type UIControllerData,
} from './controller/ui-controller';

export {
    UIGear,
    gearBinding,
    type GearValue,
    type GearTween,
    type GearBinding,
    type UIGearData,
} from './controller/ui-gear';

export {
    createInteractionControllerDriverSystem,
    createGearApplySystem,
    driverStateFor,
    readFieldPath,
    writeFieldPath,
    isLerpable,
    lerpGearValue,
} from './controller/gear-apply';

export { bindControllerPage } from './controller/bind-page';
export { ensureControllerAiRegistrations } from './controller/ai-builtins';

export { UIControllerPlugin, uiControllerPlugin } from './controller/plugin';

// ─── Collection ─────────────────────────────────────────────────────────────

export {
    ViewPool,
    type ViewPoolOptions,
    type ViewPoolTemplate,
} from './collection/view-pool';

export {
    type DataSource,
    type DataSourceChange,
    ArrayDataSource,
    arrayDataSource,
} from './collection/data-source';

export {
    type LayoutProvider,
    type Rect,
    type LinearLayoutOptions,
    type MeasuredLinearLayoutOptions,
    type GridLayoutOptions,
    LinearLayoutProvider,
    MeasuredLinearLayoutProvider,
    GridLayoutProvider,
} from './collection/layout-provider';

export {
    ListView,
    ListViewRegistry,
    type ListViewOptions,
    type ListViewItemTemplate,
} from './collection/list-view';

export {
    ScrollContainer,
    ScrollContainerRegistry,
    type ScrollContainerOptions,
    type ScrollListener,
    type OverscrollListener,
    rubberBand,
    rubberBandInverse,
} from './collection/scroll-container';

export { ScrollMotion } from './collection/scroll-motion';

export {
    KineticScroll,
    type KineticScrollOptions,
} from './collection/kinetic-scroll';

// ─── Widgets (Layer 3 factories) ────────────────────────────────────────────

export {
    identityTransform,
    buildUINode,
    buildUIVisual,
    buildText,
    spawnUIEntity,
    setUIVisible,
    FILL_AXIS,
    type LinearFillDirection,
    type UINodeInit,
    type UIVisualInit,
    type TextInit,
    type UIEntityInit,
} from './core/compose';

export {
    interactionGears,
    type ButtonStateVisual,
} from './controller/interaction-gears';

export {
    createButton,
    setButtonState,
    themeButtonStates,
    type ButtonOptions,
    type ButtonHandle,
} from './widgets/button';

export {
    createTextInput,
    type TextInputOptions,
    type TextInputHandle,
} from './widgets/text-input';

export {
    createScrollView,
    type ScrollViewOptions,
    type ScrollViewHandle,
} from './widgets/scroll-view';

export {
    createToggle,
    type ToggleOptions,
    type ToggleHandle,
} from './widgets/toggle';

export {
    createProgress,
    type ProgressOptions,
    type ProgressHandle,
} from './widgets/progress';

export {
    createDialog,
    type DialogOptions,
    type DialogHandle,
} from './widgets/dialog';

export {
    createSlider,
    type SliderOptions,
    type SliderHandle,
} from './widgets/slider';

export {
    createDropdown,
    type DropdownOptions,
    type DropdownHandle,
} from './widgets/dropdown';

export {
    createListView,
    type CreateListViewOptions,
    type ListViewHandle,
    type ListViewHost,
    type ListItemTemplate,
    type ListLayoutSpec,
} from './widgets/list-view';

export { widgetToPrefab } from './widgets/toPrefab';
export { BUILTIN_UI_PREFABS, BUILTIN_UI_WIDGET_NAMES } from './widgets/prefabs/generated';

// ─── Rendering / text helpers ───────────────────────────────────────────────

// All text — display (Text) and editable (TextInput) — now renders through the
// SDF glyph atlas; the Canvas2D TextRenderer was retired.
export { TextPlugin, textPlugin, preloadGlyphs, resolveTextRenderMode, glyphContentScale } from './text/plugin';
export type { GlyphPreload, GlyphPreloadOptions } from './text/glyph-preload';
export { InlineImagePlugin, inlineImagePlugin } from './text/inline-image-plugin';
export { measureText, type MeasureTextOptions, type TextMetrics } from './text/measure-text';
export { inspectTextLayout, type TextInspection, type TextInspectionOptions } from './text/inspect-text';

// UI Math Utilities
export {
    intersectRects,
    invertMatrix4,
    screenToWorld,
    screenRay,
    rayPlaneHit,
    pointInWorldRect,
    pointInOBB,
    quaternionToAngle2D,
    projectWorldPoint,
    projectDirectionAt,
    nearPlaneSide,
    isProjectable,
    createInvVPCache,
    type ScreenRect,
    type WorldRay,
    type ProjectedPoint,
} from './util/math';

// ─── Plugins (composed UI pipeline + the concept plugins it builds) ─────────

// `uiPlugin` is the single declarative UI pipeline. The concept
// plugins below remain exported for granular/advanced wiring.
export { UIPlugin, uiPlugin } from './ui-plugin';

export { UIMaskPlugin, uiMaskPlugin } from './render/mask';

export {
    UICameraInfo,
    type UICameraData,
} from './core/ui-camera-info';

export { screenToUiWorld, uiWorldToScreen, screenToUiLayout, uiLayoutToScreen, isScreenEntity, uiHitTestWorld, uiHitAtScreen, uiPickWorld, uiPickAllWorld } from './util/ui-pick';
export type { PickableWorld } from './util/ui-pick';

export {
    UILayoutGeneration,
    type UILayoutGenerationData,
} from './layout/ui-layout-generation';

export { UILayoutPlugin, uiLayoutPlugin } from './layout/layout';

export { UIInteractionPlugin, uiInteractionPlugin } from './input/interaction';

export {
    TextInput,
    type TextInputData,
    TextInputFilter,
    applyTextInputFilter,
} from './text/text-input';

export { TextInputPlugin, textInputPlugin } from './text/text-input-plugin';

export { DragPlugin, dragPlugin } from './input/drag';

export { inspectFocusTraversal, type FocusTraversalInspection, type FocusInspectionWorld, type FocusTraversalEntry, type FocusSkipReason } from './input/focus-inspection';

export { FocusPlugin, focusPlugin } from './input/focus';

export {
    SafeArea,
    SafeAreaPlugin,
    safeAreaPlugin,
    type SafeAreaData,
} from './layout/safe-area';

export { UIRenderOrderPlugin, uiRenderOrderPlugin } from './render/render-order';
export { UIVisibilityPlugin, uiVisibilityPlugin } from './core/visibility';

// ─── Theme (design tokens) ──────────────────────────────────────────────────

export {
    DARK_TOKENS,
    LIGHT_TOKENS,
    getTheme,
    setTheme,
    themeColors,
    themeType,
    resolveThemeTokens,
    parseThemeOverrides,
    THEME_COLOR_ROLES,
    type ThemeTokens,
    type ThemeColors,
    type ThemeType,
    type ThemeOverrides,
} from './theme/tokens';

export {
    ThemeStyle,
    markThemed,
    type ThemeStyleData,
    type ColorRole,
} from './theme/theme-style';

export { applyThemeToWorld, switchTheme } from './behavior/theme-apply';

// ─── Binding (reactive data → component fields) ─────────────────────────────

export { signal, derived, type Signal, type ReadonlySignal } from './binding/signal';
export { bind } from './binding/bind';
export { bindWidgetValue } from './binding/two-way';

// Property Path Utilities — the engine's generic reflection writer, which UI
// gears drive fields through. It lives in core now (nothing about it is UI, and
// core actions like `property.set` need it); re-exported here for the UI's own
// call sites.
export {
    getNestedProperty,
    setNestedProperty,
    parsePropertyPath,
    getEntityProperty,
    setEntityProperty,
    type ParsedPropertyPath,
} from '../ecs/propertyPath';

// Rich Text
export {
    parseRichText,
    type TextRun,
    type TextSegment,
    type ImageSegment,
    type ImageValign,
    type RichTextRun,
} from './text/rich-text-parser';

// ─── SDF glyph-atlas text ───────────────────────────────────────────────────

export {
    UI_TEXT_BOLD,
    UI_TEXT_ITALIC,
    composeTRS,
    rectTextBox,
} from './text/text-transform';

export {
    SdfTextRenderer,
    drawTextWith,
    type DrawTextParams,
    type GlyphBatchSink,
    type TextRendererOptions,
} from './text/text-renderer';

export {
    familyNameFor,
    projectFontFamily,
    resolveTextFamily,
} from './text/font-registry';

export {
    GlyphAtlas,
    type GlyphRasterizer,
    type AtlasPageStore,
    type RasterGlyph,
    type GlyphEntry,
    type GlyphAtlasOptions,
} from './text/glyph-atlas';

export {
    CanvasGlyphRasterizer,
    extractAlpha,
    sdfToAtlasRgba,
    type CanvasGlyphRasterizerOptions,
} from './text/glyph-rasterizer';

export { EngineAtlasPageStore } from './text/atlas-page-store';

export {
    layoutLine,
    layoutRichLine,
    layoutRichRuns,
    wrapRichRuns,
    layoutText,
    wrapLine,
    measureWidth,
    buildGlyphVertices,
    TEXT_ALIGN_LEFT,
    TEXT_ALIGN_CENTER,
    TEXT_ALIGN_RIGHT,
    type TextLayout,
    type TextLayoutOptions,
    type RichTextLayoutOptions,
    type MultilineTextOptions,
    type LaidGlyph,
    type LaidImage,
    type RGBA,
    type GlyphVertexData,
} from './text/layout';

export { ShelfPacker, type Packer, type PackPos } from '../util/shelfPack';
export { sdfFromAlpha } from './text/sdf';
export { submitTextBatch, TEXT_VERTEX_FLOATS, TextGlyphMode } from './text/submit';

export { ScreenOverlay, type ScreenOverlayData } from './core/screen-overlay';
export { canvasRootEntities } from './core/canvas-roots';

export { UIPages, type PageDef, type PageHandle } from './pages/ui-pages';
export { VirtualJoystick, VirtualButton, VirtualJoystickMode, joystickAxis, type VirtualJoystickData, type VirtualButtonData } from './behavior/virtual-controls';
export { createVirtualJoystick, createVirtualButton, type VirtualJoystickOptions, type VirtualButtonOptions } from './widgets/virtual-controls';