t1k:unity:ui:dots-kit
| Field | Value |
|---|---|
| Module | ui |
| Version | 3.43.4 |
| Effort | medium |
| 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
How to invoke
Section titled “How to invoke”/t1k:unity:ui:dots-kitDOTS UI Kit (com.the1studio.dots-ui-kit)
Section titled “DOTS UI Kit (com.the1studio.dots-ui-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”| Need | Use |
|---|---|
| A screen that opens/closes, stacks against other screens (modal/overlay/HUD), and reads ECS state while open | This skill — ScreenBase + ScreenRouter |
| Raw Canvas/RectTransform/Image/Button/TMP_Text mechanics, drag-and-drop, a DOTS↔UI bridge pattern from first principles | t1k-unity-ui-ugui |
| UXML/USS/VisualElement, runtime data binding, non-ECS menus/settings screens | t1k-unity-ui-toolkit |
| Formatting a number for a HUD chip or a screen label | This skill — Format.UiNumberFormat (works from ANY UI code, not only a ScreenBase) |
Building the actual prefab (Rect hierarchy, anchors, .prefab asset) for a new screen | t1k-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.
Core surface
Section titled “Core surface”| Folder | Provides | Harvest 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 here | New — 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 ScreenRouters | New |
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)”- Never declare
Awake/OnDisable/OnDestroy/LateUpdatein aScreenBasesubclass — 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. OverrideOnScreenAwake,OnScreenClosed,OnScreenDestroyed,OnScreenTickinstead. - Static strings go in
ApplyStaticStrings, neverOnScreenAwake— Unity does not orderAwakeacross GameObjects, so text stamped duringAwakecan permanently freeze on a raw localisation-resolver default if the consumer’s loc wiring registers itself in its own laterAwake.ApplyStaticStringsre-runs on everyOpen, so it cannot lose that race, and it also makes a runtime language switch take effect. ScreenIdis areadonly struct, not a consumer enum. A game declares its own screens aspublic static readonly ScreenId Inventory = new(1);fields (append-only — a consumer may deriveUIEventBusevent-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] ScreenIdfield cannot be authored in the Inspector (it would otherwise have silently read backScreenId.Noneafter 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.
Charter position (per CLAUDE.md)
Section titled “Charter position (per CLAUDE.md)”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:182Assets/Demos/Farming/TinyTerraces/Runtime/UI/Screens/Ladder/LadderScreen.cs:170Assets/Demos/Farming/TinyTerraces/Runtime/UI/Screens/Achievements/AchievementsScreen.cs:164Assets/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.
Reference
Section titled “Reference”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— whyLists/ships interfaces only.t1k-unity-dots-core-ecs— theUIEventBus/UIModalDirector/IUIModalHandlermechanism this package’s screens plug into.t1k-unity-ui-ugui— Canvas/RectTransform mechanics this package assumes but does not teach.
Visual change notice
Section titled “Visual change notice”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:
ScreenCapturein Play mode pert1k-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.