Skip to content

t1k:unity:tof:ui-create-prefab

FieldValue
Moduletof
Version3.46.8
Effortlow
Tools—

Keywords: BasePuzzlePopup, BasePuzzleScreen, HyperCasualRootUI, puzzleui, theonefeature ui, tof popup prefab, tof screen prefab, tof ui prefab

/t1k:unity:tof:ui-create-prefab
[screen-name] [layout-image-path] (both optional)

Create TheOneFeature UI Prefab (Screen / Popup)

Section titled “Create TheOneFeature UI Prefab (Screen / Popup)”

Scope — this is a candidate index, not an inventory. A capability missing here is not evidence it is absent. See scope-caveat.md (references/scope-caveat.md) before concluding otherwise.

Prefab-only authoring guide for TheOneFeature-scoped UI screens / popups. Scope is the .prefab asset: variant of base templates, hierarchy (Background / Content / Foreground / Timeline_Grp), SafeArea scope, anchor/pivot, layout groups, field-driven Content children, Addressables registration. Script side (View / Presenter / [ScreenInfo]) is OUT OF SCOPE — covered by other tof skills.

Mirror counterpart: t1k:unity:ui:create-prefab (at .claude/skills/t1k-unity-ui-create-prefab/SKILL.md) — generic Unity UI prefabs outside TOF paths. When editing either skill, mirror the change.

Scope — When to Use This Skill vs. the Generic Skill

Section titled “Scope — When to Use This Skill vs. the Generic Skill”
Target prefab pathUse skill
Packages/TheOneFeature* (anything under any TheOneFeature.* package)this skill
Assets/Prefabs/UIs/ (project-level TOF screen registry path)this skill
Anything else — Packages/com.gdk.<x>/, Packages/<consumer>/, Assets/Prefabs/<Feature>/UI/, project-side feature packages that do not use the TOF runtimet1k:unity:ui:create-prefab

If the target path does NOT match a TOF row above, STOP and switch to the generic skill — generic screens variant from a different base (UIBaseScreen.prefab / UIBasePopup.prefab in com.gdk.core), register in a different Addressables group, and parent to RootUI.prefab instead of HyperCasualRootUI.prefab.

Authoring Path: t1k unity eval (Track E) or YAML (Track Y)

Section titled “Authoring Path: t1k unity eval (Track E) or YAML (Track Y)”

The t1k unity facade has no prefab, GameObject, component, asset or Addressables verb (the old authoring tools are gone, see t1k:unity:editor:cli § “Not carried over”). Two paths replace them; §10 Authoring Path Matrix (references/authoring-path-matrix.md) maps each operation to one:

  • Track E (Editor open): t1k unity eval --file step.cs running PrefabUtility.LoadPrefabContents / SaveAsPrefabAsset / SerializedObject: recipes in live-prefab-edit.md (references/live-prefab-edit.md). It edits the prefab through the Editor, so a later refresh cannot revert it. Written from Unity’s documented API and not yet run live through the facade: test each recipe on a scratch prefab first.
  • Track Y (Editor closed, or Track E fails): direct YAML through t1k-unity-blind-edit-assets, following the exact templates in §1 (variant) (references/variant-creation.md), §9.3 (wiring) (../t1k-unity-ui-create-prefab/references/reference-wiring.md) and §7 (Addressables) (references/addressables-registration.md) — they pattern off existing working files, not free-form. Adding an Addressables entry is Track Y only.

Screenshots and Prefab Mode have no path at all: ask the user for a capture, or take the manual path.

See t1k:unity:editor:cli for the Editor setup and pin procedure. This IS the authoring recipe rules/prefab-only-construction-unity.md points to for “author the prefab in the editor, not a hand-written editor script” — that rule owns the ban, this skill owns the how.

IntentPath
“New full screen”Create variant of BasePuzzleScreen.prefab → §1 Create as Variant (references/variant-creation.md)
“New popup / modal”Create variant of BasePuzzlePopup.prefab → §1 Create as Variant (references/variant-creation.md)
“Spawn children for each [SerializeField] on the View”§9 Materialize Content Children (references/content-materialization.md)
“User provided a layout image”§9.4 Layout image input (references/layout-image-workflow.md)
“Add full-bleed background image”Place under Background → §2 Layer scope (below)
“Add main UI / popup body”Place under Content → §2 Layer scope (below)
“Add HUD overlay / toast”Place under Foreground → §2 Layer scope (below)
“Hook open/close animation”Bind to Timeline_Grp → §3 Timeline_Grp (below)
“Set anchors / pivot on a child”§5 Anchor / pivot rules (../t1k-unity-ui-create-prefab/references/anchor-pivot-rules.md)
“Grid that reflows by aspect ratio”§6 Layout groups (below)
“Register prefab in Addressables”§7 Addressables registration (references/addressables-registration.md)
“Which path does each prefab operation take?”§10 Authoring Path Matrix (references/authoring-path-matrix.md)

Pick exactly one base — never start from an empty Canvas, never duplicate the base (variant so future base fixes propagate). Base prefabs: BasePuzzleScreen.prefab (screen) / BasePuzzlePopup.prefab (popup), both under Packages/TheOneFeature.PuzzleUI/Common/Prefabs/Base/.

Full procedure (Track E live recipe, Track Y minimal-YAML template with the exact fields, and root-GO fileID resolution algorithm): → variant-creation.md (references/variant-creation.md)

2. Layer Scope — Background / Content / Foreground

Section titled “2. Layer Scope — Background / Content / Foreground”

Shared mechanics (layer table, SafeArea rule, CanvasScaler rule): shared-prefab-mechanics.md (../t1k-unity-ui-create-prefab/references/shared-prefab-mechanics.md) § “Layer Scope”. TOF-specific: CanvasScaler lives ONLY on HyperCasualRootUI (the generic skill’s root is RootUI).

3. Timeline_Grp — Open / Close Animations

Section titled “3. Timeline_Grp — Open / Close Animations”

Shared mechanics: shared-prefab-mechanics.md (../t1k-unity-ui-create-prefab/references/shared-prefab-mechanics.md) § “Timeline_Grp”. Author per-screen Timeline assets under Packages/TheOneFeature.PuzzleUI/<Feature>/Timelines/<ScreenName>_Appear.playable and <ScreenName>_Disappear.playable.

If the SAME widget appears twice or more anywhere in the project, it MUST be a prefab and instantiated as a prefab reference — never duplicated GameObjects.

Existing reusable widgets (compose with these first):

NeedPrefab
Currency / coin counterCurrencyView.prefab
Title barTitle.prefab
Bottom tab barFeature/bottom_nav_bar_location.prefab
Reusable buttonFeature/btn_feature.prefab
Coin visualsCoins/prefab_coin*.prefab
Timer / clockTimer.prefab, Clock.prefab
Animated numberTextCounting.prefab, NumberHolder.prefab
Lives indicatorLivesView.prefab
Error / retry stateErrorRetryView.prefab
Loader spinnerLoader.prefab
Notification badgeic_noti.prefab
Background gradientBgGradient.prefab, BgTop.prefab

If a needed widget is not in the catalog AND you’ll use it 2+ times, create a new prefab in Common/Prefabs/<Category>/ BEFORE adding the second instance.

→ anchor-pivot-rules.md (../t1k-unity-ui-create-prefab/references/anchor-pivot-rules.md) — SSOT for the anchor/pivot core principle and the per-layer rules.

Shared mechanics (pattern -> component table, the GridLayoutGroup ban): shared-prefab-mechanics.md (../t1k-unity-ui-create-prefab/references/shared-prefab-mechanics.md) § “Layout Groups”.

Required so ScreenManager.OpenScreen<T>() can resolve the prefab via the [ScreenInfo] key. No t1k unity verb adds an Addressables entry — the group entry must be added via direct YAML edit. Never hardcode the group asset name (TOFUIs.asset is NOT universal) — detect it per-project.

Full detection procedure, YAML entry template, and refresh step: → addressables-registration.md (references/addressables-registration.md)

8. Final Checklist (before declaring done)

Section titled “8. Final Checklist (before declaring done)”
  • Prefab is a variant of BasePuzzleScreen.prefab or BasePuzzlePopup.prefab — file starts with !u!1001 & and ends with m_SourcePrefab: {fileID: 100100000, guid: <base-guid>}
  • Prefab name <ScreenName>View.prefab matches the future [ScreenInfo] key
  • Every [SerializeField] GameObject/Component field on the View has a matching child under Content (or Background/Foreground if explicitly placed there per §9)
  • Every UI child has an explicit UnityEngine.RectTransform — never plain Transform (would warn under Canvas)
  • Every child’s RectTransform fields (anchor/pivot/sizeDelta/anchoredPos) were set via §9.2.5 — verified by reading the hierarchy back (live-prefab-edit.md § “Read the hierarchy”) or an on-disk grep
  • Every UI child was parented under FullScreenLayout / Background / Foreground (Recipe 2 SetParent, or placed under the layer in YAML) — NOT left at prefab root
  • Every such field is wired on the View component via §9.3 (Track E Recipe 4, or the Track Y direct-YAML fileID edit) — no null refs except documented <Widget>Prefab user-assigns. Post-wire verification: PrefabUtility.GetPrefabAssetType(...) MUST return Variant (via t1k unity eval, unverified live). If it returns Regular the variant link is gone — restore from git and re-author.
  • Full-bleed art placed under Background (no SafeArea inset)
  • Main UI / popup body placed under Content (SafeArea-respecting)
  • Overlays / toasts placed under Foreground (no SafeArea inset)
  • Timeline_Grp intact; per-screen Appear/Disappear Timelines overridden on the variant if customized
  • No second SafeArea added; no CanvasScaler on root; no AspectRatioFitter on root
  • Every child’s pivot sits on the same edge as its anchor (§5)
  • Any widget used 2+ times is referenced as a prefab instance, not duplicated
  • Grids use FlexibleLayoutGroupVer2, not GridLayoutGroup
  • Prefab added to the correct Addressables group with address = prefab basename
  • t1k unity refresh succeeded and t1k unity console --level error shows zero errors
  • If layout image was provided: every text-on-button region has a nested <Button>/Label TMP child with m_text set + RT placement applied (§9.4.B)
  • If layout image was provided: every standalone text region has a Txt<Name> TMP child under FullScreenLayout (or Foreground) with m_text set + RT placement applied (§9.4.C)
  • No TMP child was spawned for text that ALREADY has a [SerializeField] TMP field on the View — those are covered by the §9.4.A field-driven path
  • Every TMP child has m_HorizontalAlignment and m_VerticalAlignment set per §9.4.E (not TMP’s left-top default m_HorizontalAlignment: 1 / m_VerticalAlignment: 256)

9. Materialize Content Children from View Fields (MANDATORY)

Section titled “9. Materialize Content Children from View Fields (MANDATORY)”

A skeleton variant with no children is incomplete — the Presenter’s OnViewReady will null-ref on this.View.BtnPause.onClick.AddListener(...) because BtnPause was never spawned. Field-driven child creation is MANDATORY, not advisory.

  • §9.1–9.3 — field-driven workflow (inspect the View script, widget-type → child template mapping, apply RectTransform post-create, wire references): → content-materialization.md (references/content-materialization.md)
  • §9.4 — layout image workflow (optional; auto-spawn text-on-button labels, standalone text decorations, TMP alignment rules): → layout-image-workflow.md (references/layout-image-workflow.md)

Checklist gates for this section are folded into §8 Final Checklist above.

Which path (Track E t1k unity eval, Track Y YAML, or none) each prefab operation takes now that the authoring tools are gone, with the flat-axis RectTransform property form.

Full matrix: → authoring-path-matrix.md (references/authoring-path-matrix.md)

Authoring of .prefab assets under Packages/TheOneFeature.PuzzleUI/, Packages/TheOneFeature/UI/, and Assets/Prefabs/UIs/. Does NOT cover: View/Presenter C# scripts, [ScreenInfo] attribute wiring, VContainer registration, or runtime open/close calls — those are handled by the implementation skills.

  • Layout-image text decorations are auto-spawned even without a [SerializeField] field. Text inside a field-driven button becomes a nested <Button>/Label TMP child (§9.4.B); standalone text becomes a Txt<Name> child under FullScreenLayout (§9.4.C). Neither is wired to the View script — purely visual, promotable to [SerializeField] later. Without this, image-driven UIs ship with empty buttons and missing labels. Detail: layout-image-workflow.md (references/layout-image-workflow.md).
  • TMP serialized text property is m_text, NOT text or m_Text. Verified against Packages/TheOneFeature.PuzzleUI/Common/Prefabs/titlePopup1.prefab. text is the runtime C# property; m_Text (capitalised) is wrong.
  • TMP children spawn with left-top alignment by default (m_HorizontalAlignment: 1, m_VerticalAlignment: 256). Without §9.4.E setting H=2 (Center) / V=512 (Middle), text-on-button labels render in the upper-left of the button rect. Set m_HorizontalAlignment / m_VerticalAlignment explicitly — NOT m_textAlignment (legacy combined enum). Detail: layout-image-workflow.md (references/layout-image-workflow.md) §9.4.E.
  • RectTransform Vector2 properties need flat-axis form through SerializedProperty / YAML. m_AnchorMin: {x: 0, y: 1} is not a valid property path. Use m_AnchorMin.x / m_AnchorMin.y as separate keys — same for m_AnchorMax, m_Pivot, m_AnchoredPosition, m_SizeDelta. (The typed rt.anchorMin = new Vector2(..) in Track E has no such constraint.)
  • Children without the §9.2.5 RectTransform step stack at center. Set anchors/pivot/size and the layer parent when you create the child (Recipe 2), not as an afterthought.
  • Prefab-Mode save collapses a Track Y variant to standalone. Skip Prefab Mode for structural changes (the facade has no verb for it anyway) — use Track E (LoadPrefabContents + SaveAsPrefabAsset) against the asset path instead, which preserves variant overrides. Silent-failure symptom of a lost variant link: the file starts --- !u!1 &<id>\nGameObject: instead of --- !u!1001 &<id>\nPrefabInstance:.
  • Addressables group name is project-specific. Older skill versions hardcoded TOFUIs.asset; the TheOneFeatureProject actually uses UIs.asset. Always detect via §7.1 grep, never assume.
  • Skeleton prefab without children → runtime NullReferenceException. Skipping §9 leaves [SerializeField] refs unwired; §9 is MANDATORY.
  • Field-name *Prefab fields are user-assigns, not children. BoosterButtonPrefab, ItemPrefab, etc. are Presenter-spawned prefab references — do NOT materialize as children.
  • Layout image hallucination. §9.4 MUST echo its interpretation to the user before applying — never silently spawn children from a guessed layout.
  • Variant-of-variant root-GO fileID lookup. For deep variant chains, the root GO fileID in the variant’s target: lines points to the grandparent’s GO, not the immediate parent’s. Detail: variant-creation.md (references/variant-creation.md).
  • Duplicating the base instead of variant-ing it — duplicated screens stop receiving base-prefab fixes. Always Track E (or Track Y) for a true variant.
  • Prefab name = Addressables address = [ScreenInfo] key. Drift between the three is the #1 silent-failure mode. Always use nameof(MyScreenView) on the script side.
  • Full-bleed background placed under Content — SafeArea insets it on notched devices, revealing letterboxing. Background images go under Background.
  • Tap-targets placed under Background or Foreground — they can fall under the notch or gesture bar. Interactive UI MUST live under Content.
  • Deleting Timeline_Grp — open/close transitions silently no-op. Never delete it.
  • Editing the base’s Timeline assets directly — changes every screen. Author per-screen Timeline assets and override the binding on the variant.
  • Adding a second SafeArea — double inset. The base ships exactly one on Content — leave it as the only one.
  • CanvasScaler / AspectRatioFitter on the variant root — fights HyperCasualRootUI’s scaler. Never add either to the variant.
  • GridLayoutGroup for responsive grids — fixed cell count breaks on landscape/portrait. Use FlexibleLayoutGroupVer2 with BaseOnContent preset.
  • Backdrop above PopupBody (popup variant) — Backdrop renders on top, hiding the popup. Backdrop must be the FIRST child of its parent.
  • Pivot not matching anchor edge — element drifts on different resolutions. Apply §5 rigidly.
  • Renaming a prefab after Addressables registration without updating the address — Addressables does NOT auto-rename. Re-edit the group asset entry after any rename.
  • Hand-editing .prefab YAML beyond the §1 Track Y template — corrupts variant overrides silently. The Track Y template is a fixed pattern; do not improvise inside it.
  • A hand-edited .prefab YAML can be silently REVERTED by the open Editor — on-disk verification is not proof. While an Editor holds the prefab, an unrelated t1k unity refresh re-serializes the Editor’s in-memory copy back over the file; the result is byte-identical to HEAD, with no error, nothing in the console, and a git status taken before the overwrite reporting exactly what you wanted to see. Observed 2026-09-10: Dumpling3D, Unity 6000.3.15f1, Linux Editor, DumplingSqueezePopupView.prefab — 3 GameObjects hand-deleted from the YAML, verified clean on disk, then totally overwritten by a later unrelated refresh. Make the edit through the Editor instead so the in-memory copy IS the edit: Track E (live-prefab-edit.md Recipe 5 for a delete). Saving through the Editor also drops serialized fields whose C# declarations no longer exist, so no separate dangling-reference cleanup is needed. Verify with both a hierarchy readback (live-prefab-edit.md § “Read the hierarchy”) and an on-disk grep, and re-verify after any later refresh — either check alone produced a false “clean” report.