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.
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:
ui/index.tsis the complete module surface — everything the module offers, including low-level text/atlas internals for advanced use.sdk/src/core-ui.tspromotes the stable, curated subset into the top-levelesenginenamespace. It re-exports only intentional public API — never@internalglue (EntityStateMap,ensureComponent, …). Those stay importable from./uifor 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}.tsand rootSafeArea.tsshims 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, notUICameraInfo.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.tsholds bothSafeAreaandSafeAreaPlugin). 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/defineBuiltinand 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.tsexactly once; promoted tocore-ui.tsonly if it is stable public API (no@internal). - No shim left behind: old import paths grep clean.
-
npx tsc --noEmit -p sdk/tsconfig.jsonandnpx vitest run uiboth pass.