Skip to content

t1k:unity:ui:dots-kit

FieldValue
Moduleui
Version3.43.4
Effortmedium
Tools—

Keywords: dots-ui-kit, DOTSUiKit, EcsAccess, game UI scaffolding, IVirtualListAdapter, MagnitudeWriter, NumberFormatConventions, RequestQueueUtility, RowFitMath, screen router stack, ScreenBase, ScreenCloseReason, ScreenId, ScreenLayer, ScreenOpenContext, ScreenOpenSource, ScreenRouter, UiMetrics, UiNumberFormat, WidgetFactory

/t1k:unity:ui:dots-kit

Game-UI scaffolding for DOTS games — an opaque ScreenId + ScreenBase + ScreenRouter stack, the EcsAccess/RequestQueueUtility Tier-3→Tier-1 read/write seam, list-virtualisation interfaces, a code-built-UI widget factory + row-fit arithmetic + mobile-portrait layout metrics, and a zero-alloc UiNumberFormat. Depends on com.the1studio.dots-core only — no demo assembly, no third-party vendor (OSA, NiceVibrations, DOTween) is referenced anywhere in this package.

Package: Packages/unity-dots-library/com.the1studio.dots-ui-kit/ · v0.2.0 · asmdef DOTSUiKit (namespace DOTSUiKit) · references DOTSCore, DOTSCore.UI, LitMotion, ZString, Unity.InputSystem, TextMeshPro. Editor asmdef DOTSUiKit.Editor. 11 EditMode test files under Tests/EditMode/ (2 new in 5e0cc3cf: ScreenEcsEventRegistrationTests, ScreenIdSerializationTests).

⚠️ Adoption status — read before reaching for this

Section titled “⚠️ Adoption status — read before reaching for this”

Zero demo consumers as of this writing. This package is a harvest of TinyTerraces’ UI code (TinyTerracesScreenBase, TinyTerracesWidgetFactory, TinyTerracesRowFitMath, TinyTerracesUiMetrics, the Format trio) generalised and renamed, but no screen in any demo has been rewritten against it yet. Its own plan doc (phase-5-ui-kit.md § “Risks”) warns the follow-on chrome API (panel/header/footer/tab-strip templates — not yet built, see “What is deliberately NOT here” below) is “genuinely at risk of over-fitting to farming” and should be designed against two demos, not one, before freezing. Treat the shipped surface (Screens/, Ecs/, Format/, Layout/) as plausible but unproven against a real screen rewrite — expect rough edges on first adoption, and feed anything you find back into this skill (rules/kit-wide-fix-discipline.md).

⚠️ Submodule commit 5e0cc3cf (“resolve second-consumer over-fit findings OF-1..OF-6”) is itself an uncompiled, library-only batch edit — landed with no Unity Editor access, no t1k unity console, no t1k unity test pass. It fixed real API gaps found while scoping a second consumer (BackpackCrawler) — EcsEventType is now an overridable virtual defaulting to 0 instead of a mandatory abstract, ScreenId dropped [Serializable] entirely, fade seconds and the router’s sorting-order base are now overridable, back-input gained an opt-out, and a public ScreenTestDriver seam was added for consumer EditMode tests. This skill documents that surface as current source, but “current source” and “compiler-verified” are not the same claim here — verify with an actual compile before relying on any of it in a shipped screen.

When to reach for this vs. t1k-unity-ui-ugui / t1k-unity-ui-toolkit

Section titled “When to reach for this vs. t1k-unity-ui-ugui / t1k-unity-ui-toolkit”
NeedUse
A screen that opens/closes, stacks against other screens (modal/overlay/HUD), and reads ECS state while openThis skill — ScreenBase + ScreenRouter
Raw Canvas/RectTransform/Image/Button/TMP_Text mechanics, drag-and-drop, a DOTS↔UI bridge pattern from first principlest1k-unity-ui-ugui
UXML/USS/VisualElement, runtime data binding, non-ECS menus/settings screenst1k-unity-ui-toolkit
Formatting a number for a HUD chip or a screen labelThis skill — Format.UiNumberFormat (works from ANY UI code, not only a ScreenBase)
Building the actual prefab (Rect hierarchy, anchors, .prefab asset) for a new screent1k-unity-ui-create-prefab for the asset, this skill for the script side

ScreenBase is a MonoBehaviour and composes with t1k-unity-ui-ugui’s Canvas mechanics — this skill does not replace uGUI knowledge, it adds a lifecycle/stack/ECS-seam layer on top of it.

FolderProvidesHarvest source
Screens/IScreen, ScreenBase (abstract MonoBehaviour), ScreenId (opaque struct, NOT an enum), ScreenLayer (FullScreenModal / Overlay / Hud), ScreenCloseReason (4 values), ScreenOpenSource (3 values), ScreenOpenContext, ScreenRouter (+ .BackInput partial), ScreenUiConstants, ScreenTestDriver (public EditMode test seam — Tick/DestroyBeforeDestroyImmediate, see below)TinyTerracesScreenBase + TinyTerracesScreenRouter
Ecs/EcsAccess (world/EntityManager/liveness/dispose guards), RequestQueueUtility.EnsureQueueSingleton<TTag>TinyTerraces* request-seam consolidation
Format/UiNumberFormat (+ .Rates partial) — Count/Currency/Rate/Duration/Percent; MagnitudeWriter (internal digit core); NumberFormatConventions (locale glyph struct)TinyTerraces* Format trio, renamed
Layout/WidgetFactory (Rect/Image/Label trio), RowFitMath.ComputeFittedRowWidths (fixed-row-of-N-buttons arithmetic, no GameObjects), UiMetrics (re-exports DOTSCore.UI.Mobile.MobileUiDefaults + ScreenEdgePaddingPx)Same, deduped from 6 per-screen factories
Lists/IVirtualListAdapter, IVirtualListDataSource<T>, IVirtualListRowBinder<TRow,TData> — interfaces only, no implementation ships hereNew — the seam a concrete vendor adapter (e.g. OSA) implements in an opt-in bridge package
Editor/Tools/Library/UI Kit/Validate Screen Registrations menu item — flags duplicate ScreenId and non-RectTransform screen roots across every open scene’s ScreenRoutersNew

Full per-type API notes (constructor shapes, gotchas per member): references/screens-lifecycle.md (Screens/) and references/ecs-format-layout-lists.md (Ecs/, Format/, Layout/, Lists/, Editor/).

The ECS → UI seam — no second event bus

Section titled “The ECS → UI seam — no second event bus”

ScreenBase implements IUIModalHandler and ScreenRouter registers every discovered screen with DOTSCore.UI.Bridge.UIModalDirector — the same bus/director pair the library already ships in dots-core/Runtime/UI/Bridge/ (see t1k-unity-dots-core-ecs for that mechanism). An ECS system appends to UIEventBus; the director drains it in LateUpdate and calls IUIModalHandler.HandleUIEvent; ScreenBase turns that into ScreenRouter.OpenFromEcsEvent. A player tapping a nav button calls ScreenRouter.Open directly — UI→UI navigation does not round-trip through the ECS bus. Both paths converge on the same stack-policy code, so behaviour is identical either way. A screen never mutates simulation state directly — it submits intent through a consumer-owned *Actions class built on RequestQueueUtility.EnsureQueueSingleton<TTag>.

Three hard-won lifecycle rules (violating any one silently breaks a screen)

Section titled “Three hard-won lifecycle rules (violating any one silently breaks a screen)”
  1. Never declare Awake/OnDisable/OnDestroy/LateUpdate in a ScreenBase subclass — it hides the base’s private Unity message with no compiler error, and the base’s router resolution / fade cancellation / listener cleanup / open-gated tick silently stop running. Override OnScreenAwake, OnScreenClosed, OnScreenDestroyed, OnScreenTick instead.
  2. Static strings go in ApplyStaticStrings, never OnScreenAwake — Unity does not order Awake across GameObjects, so text stamped during Awake can permanently freeze on a raw localisation-resolver default if the consumer’s loc wiring registers itself in its own later Awake. ApplyStaticStrings re-runs on every Open, so it cannot lose that race, and it also makes a runtime language switch take effect.
  3. ScreenId is a readonly struct, not a consumer enum. A game declares its own screens as public static readonly ScreenId Inventory = new(1); fields (append-only — a consumer may derive UIEventBus event-type IDs from .Value, so renumbering breaks that mapping). It is not [SerializeField]-able at all — the type dropped [Serializable] at the source specifically so a [SerializeField] ScreenId field cannot be authored in the Inspector (it would otherwise have silently read back ScreenId.None after every domain reload, because its only field, readonly int Value, is a shape Unity’s serializer cannot write back to). Code declaration (new(1)) is not just the recommended pattern, it is the only one available.

In scope, and what this package is: screen base + router/stack, the ECS→UI binding seam, number/currency/rate/duration/percent formatting, a code-built widget factory + row-fit + mobile layout metrics, list-virtualisation interfaces.

Still out of scope — and deliberately absent from this package: rendering, audio, platform code, any concrete game’s screens, and any third-party UI vendor. OSA support was planned as a separate com.the1studio.dots-ui-kit-osa bridge package and was DELETED before shipping — the Phase 5 plan (plans/260820-1352-dots-library-restructure/phase-5-ui-kit.md) found it failed the seam-worth test (code-conventions.md § Modular Boundaries) at one consumer. Lists/ therefore ships the interface a future OSA (or any other) adapter would implement, and nothing more. Do not go looking for an -osa package — it does not exist, and IVirtualListAdapter is the seam a consumer implements itself today.

Not yet built (Phase 5’s step 4, deferred): the panel/header/footer/scrim/tab-strip chrome templates that would absorb bucket-A duplication across screens. Icons/, Feedback/, Toast/, Hud/ (chip strip only — the farming-specific HUD read models stay in TinyTerraces) also remain unextracted pending a decoupling seam each. This skill covers only what is on disk today.

Known defect carried in from the harvest — NOT fixed

Section titled “Known defect carried in from the harvest — NOT fixed”

EcsAccess is bypassed at 4 TinyTerraces call sites today — each re-derives World.DefaultGameObjectInjectionWorld directly instead of going through EcsAccess’s dispose/liveness guards:

  • Assets/Demos/Farming/TinyTerraces/Runtime/UI/Screens/Journal/JournalScreen.cs:182
  • Assets/Demos/Farming/TinyTerraces/Runtime/UI/Screens/Ladder/LadderScreen.cs:170
  • Assets/Demos/Farming/TinyTerraces/Runtime/UI/Screens/Achievements/AchievementsScreen.cs:164
  • Assets/Demos/Farming/TinyTerraces/Runtime/UI/Selection/ProductionBatchActions.cs:43

This is stated as fact, not something to verify — all four were re-read at the line numbers above and still contain the raw World.DefaultGameObjectInjectionWorld call.

Tests/EditMode/EcsAccessSeamArchitectureTests.cs passing is NOT evidence these are fixed. Its NoProductionFileOutsideTheSeamReDerivesTheDefaultWorld scan root is hard-coded to Packages/unity-dots-library/com.the1studio.dots-ui-kit/Runtime/ only — it structurally cannot see Assets/Demos/** files, so it will read green forever regardless of what the four sites above do. The gate protects new violations inside this package; it was never wired to catch the harvest’s own carried-over defect. Fixing these four sites is demo-side work (route each through DOTSUiKit.Ecs.EcsAccess.TryGetEntityManager), not a library-side test failure to chase.

  • references/screens-lifecycle.md, references/ecs-format-layout-lists.md — per-file member listing with the gotcha each guards against.
  • plans/260820-1352-dots-library-restructure/phase-5-ui-kit.md — the harvest plan, LOC ledger, and the full seam/risk analysis this skill summarises.
  • skills/t1k-library-decoupling/references/third-party-decoupling.md (theonekit-core), rules/prefer-interface-over-concrete-injection-unity.md — why Lists/ ships interfaces only.
  • t1k-unity-dots-core-ecs — the UIEventBus/UIModalDirector/IUIModalHandler mechanism this package’s screens plug into.
  • t1k-unity-ui-ugui — Canvas/RectTransform mechanics this package assumes but does not teach.

A visible change made with this skill (UI, sprites, 3D, shaders, VFX, animation, lighting, scene layout; audio excluded) follows core rule visual-change-discord-notice:

  • Capture OLD before the first edit and NEW after the last (screen: ScreenCapture in Play mode per t1k-unity-editor-cli, windowed or Xvfb only because rendering is needed; 3D, shader, VFX: same-scene frame grab; 2D asset: the file).
  • Return the paths and a draft Discord post to the orchestrator, which posts; the PR links the post or carries visual-notice-waiver: <reason>. Logic only: “no visible change”. No capture: “screenshots pending: ”, never a fake image.