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.

7.5 KB
Raw Blame

UI Module Architecture

The UI module is an ECS-native UI system: UI is built from the same entities, components, and systems as the rest of the engine — there is no separate retained widget tree. Layout is flexbox (Yoga-driven in the C++ core), text is rendered through an SDF glyph atlas, and styling flows from a design-token theme.

This document is the contract that keeps the module unified. Read it before adding a file. The rules below exist because the module previously accreted parallel export surfaces, back-compat shims, and root-level files that broke the layering — that drift has been removed and should not come back.

Layer model

Layers depend downward only. A file may import from its own layer and any layer above it in this list; it must not import from a layer below it.

Layer 0  Events        core/events.ts                      (the UI event bus)
Layer 1  Primitives    core/  + layout/flex.ts             (components = data)
Layer 2  Behaviors     input/  controller/  behavior/      (interaction, controllers+gears, drag, focus)
         Layout/Render layout/  render/                    (Yoga driver, masking, draw order)
Layer 3  Collection    collection/                         (lists, scroll, virtualization)
Layer 4  Widgets       widgets/                            (factory functions: button, dialog, …)
Cross    Text          text/                               (SDF/atlas/rich-text pipeline)
Cross    Theme         theme/                              (design tokens)
Cross    Util          util/                               (pure helpers, math, constants)

util/, text/, and theme/ are cross-cutting: they sit beside the layers and may be used by any of them, but they must not import up into behaviors, collection, or widgets.

Directory map

Folder Responsibility Key files
core/ Layer 0–1 primitives: the components that are the UI, plus composition sugar over them ui-node, ui-visual, ui-mask, text, dimension, events, ui-camera-info, compose
layout/ Flexbox layout + safe area + layout bookkeeping anchor, flex, layout (Yoga driver plugin), safe-area, ui-layout-generation
input/ Pointer/keyboard interaction primitives + their plugins interactable, draggable, focusable, drag, focus, interaction
controller/ The one widget-state mechanism: named pages + per-component property gears, tween-applied ui-controller, ui-gear, gear-apply, interaction-gears, bind-page, ai-builtins, plugin
behavior/ Runtime systems: scroll/collection ticking, data-driven widget behavior, scrollbars, theme re-resolution plugin (UIBehaviorPlugin), dialog, slider, toggle, dropdown, scrollbar, theme-apply
render/ UI-specific render concerns mask, render-order
collection/ Data-driven collections + view recycling list-view, scroll-container, view-pool, data-source, layout-provider
text/ SDF glyph atlas, text layout, rich text, editable text glyph-atlas, text-renderer, layout, rich-text-parser, text-input, text-input-plugin, text-input-view
theme/ Design tokens + per-entity role markers tokens, theme-style
util/ Cross-cutting helpers (no engine state of their own) helpers, math, constants, ui-pick
widgets/ Layer-4 widget factory functions + their prefab capture button, toggle, slider, progress, dialog, dropdown, text-input, list-view, scroll-view, helpers, toPrefab, prefabs/

Only two files live at the module root, and that is deliberate:

  • index.ts — the module's single public barrel (see below).
  • ui-plugin.ts — uiPlugin, the one composed pipeline that builds every concept plugin in dependency order. Apps add this single plugin; the concept plugins stay individually exported for granular/test wiring only.

The single public surface (no parallel barrels)

There are exactly two export surfaces, with distinct jobs:

  1. ui/index.ts is the complete module surface — everything the module offers, including low-level text/atlas internals for advanced use.
  2. sdk/src/core-ui.ts promotes the stable, curated subset into the top-level esengine namespace. It re-exports only intentional public API — never @internal glue (EntityStateMap, ensureComponent, …). Those stay importable from ./ui for SDK-internal use.

Rules:

  • Do not create a third re-export file for UI symbols, and do not hand-copy a symbol into more than one barrel "for convenience." Add it once, in the layer file, and export it through index.ts.
  • No back-compat shim files. When a symbol moves, repoint every importer and delete the old file in the same change. (The behavior/{interactable,draggable, focusable}.ts and root SafeArea.ts shims were removed for exactly this reason.) A grep for the old path must come back empty.

Conventions

Collection widgets accept project data through adapters with stable application IDs. They must not require ECS entities, scene paths, inventory item types or other gameplay schemas. TreeViewModel projects hierarchy data into the existing DataSource / ListView virtualization path. Selection and expansion belong to the control; drop validation and domain mutations belong to the host.

UICollections captures the collection registries of its app. Widget adoption is installed by the composed UI plugin after those registries exist; the behavior layer does not import widget factories. Runtime row wrappers and prefab views remain ordinary ECS UI entities. Removing a widget releases its registrations, subscriptions and pending views.

Color editing uses the canonical Color shape and shared col HSV helpers. HSV is an editing coordinate system, not a new color-space convention. UI, sprite and material consumers bind through the same RGBA change event; the picker does not mutate targets or write global history storage. Pointer capture, focus, text editing, theme roles and rendering use the existing pipeline. A control that consumes its drag blocks an enclosing collection's drag scroll while leaving wheel input available.

  • File names are kebab-case (ui-camera-info.ts, not UICameraInfo.ts). Exported symbols keep their natural casing (UICameraInfo, createButton).
  • A concept's component and its plugin are co-located in one file when small (e.g. layout/safe-area.ts holds both SafeArea and SafeAreaPlugin). Split into <concept>.ts (component) + <action>.ts (plugin) only when the plugin is substantial (e.g. input/draggable.ts + input/drag.ts).
  • Components are data — define them with defineComponent / defineBuiltin and keep behavior in systems, not on the component.
  • Widgets are factory functions (createX) that compose primitives; they do not introduce a parallel widget hierarchy.

Checklist before adding/moving a file

  • It lives in the layer folder that matches its responsibility (root is off-limits).
  • Its name is kebab-case.
  • It imports only downward / cross-cutting — never up a layer.
  • It is exported through index.ts exactly once; promoted to core-ui.ts only if it is stable public API (no @internal).
  • No shim left behind: old import paths grep clean.
  • npx tsc --noEmit -p sdk/tsconfig.json and npx vitest run ui both pass.