t1k:unity:tof:ui-create-prefab
| Field | Value |
|---|---|
| Module | tof |
| Version | 3.46.8 |
| Effort | low |
| Tools | — |
Keywords: BasePuzzlePopup, BasePuzzleScreen, HyperCasualRootUI, puzzleui, theonefeature ui, tof popup prefab, tof screen prefab, tof ui prefab
How to invoke
Section titled “How to invoke”/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 path | Use 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 runtime | t1k: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.csrunningPrefabUtility.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.
Decision Tree
Section titled “Decision Tree”| Intent | Path |
|---|---|
| “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) |
1. Create as Variant
Section titled “1. Create as Variant”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.
4. Reuse Prefabs — DRY
Section titled “4. Reuse Prefabs — DRY”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):
| Need | Prefab |
|---|---|
| Currency / coin counter | CurrencyView.prefab |
| Title bar | Title.prefab |
| Bottom tab bar | Feature/bottom_nav_bar_location.prefab |
| Reusable button | Feature/btn_feature.prefab |
| Coin visuals | Coins/prefab_coin*.prefab |
| Timer / clock | Timer.prefab, Clock.prefab |
| Animated number | TextCounting.prefab, NumberHolder.prefab |
| Lives indicator | LivesView.prefab |
| Error / retry state | ErrorRetryView.prefab |
| Loader spinner | Loader.prefab |
| Notification badge | ic_noti.prefab |
| Background gradient | BgGradient.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.
5. Anchor / Pivot Rules
Section titled “5. Anchor / Pivot Rules”→ 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.
6. Layout Groups
Section titled “6. Layout Groups”Shared mechanics (pattern -> component table, the GridLayoutGroup ban): shared-prefab-mechanics.md (../t1k-unity-ui-create-prefab/references/shared-prefab-mechanics.md) § “Layout Groups”.
7. Addressables Registration
Section titled “7. Addressables Registration”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.prefaborBasePuzzlePopup.prefab— file starts with!u!1001 &and ends withm_SourcePrefab: {fileID: 100100000, guid: <base-guid>} - Prefab name
<ScreenName>View.prefabmatches the future[ScreenInfo]key - Every
[SerializeField]GameObject/Component field on the View has a matching child underContent(orBackground/Foregroundif explicitly placed there per §9) - Every UI child has an explicit
UnityEngine.RectTransform— never plainTransform(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 2SetParent, 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>Prefabuser-assigns. Post-wire verification:PrefabUtility.GetPrefabAssetType(...)MUST returnVariant(viat1k unity eval, unverified live). If it returnsRegularthe 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_Grpintact; 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, notGridLayoutGroup - Prefab added to the correct Addressables group with address = prefab basename
-
t1k unity refreshsucceeded andt1k unity console --level errorshows zero errors - If layout image was provided: every text-on-button region has a nested
<Button>/LabelTMP child withm_textset + RT placement applied (§9.4.B) - If layout image was provided: every standalone text region has a
Txt<Name>TMP child underFullScreenLayout(orForeground) withm_textset + 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_HorizontalAlignmentandm_VerticalAlignmentset per §9.4.E (not TMP’s left-top defaultm_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.
10. Authoring Path Matrix
Section titled “10. Authoring Path Matrix”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.
Hard rules
Section titled “Hard rules”- Layout-image text decorations are auto-spawned even without a
[SerializeField]field. Text inside a field-driven button becomes a nested<Button>/LabelTMP child (§9.4.B); standalone text becomes aTxt<Name>child underFullScreenLayout(§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, NOTtextorm_Text. Verified againstPackages/TheOneFeature.PuzzleUI/Common/Prefabs/titlePopup1.prefab.textis 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. Setm_HorizontalAlignment/m_VerticalAlignmentexplicitly — NOTm_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. Usem_AnchorMin.x/m_AnchorMin.yas separate keys — same form_AnchorMax,m_Pivot,m_AnchoredPosition,m_SizeDelta. (The typedrt.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 usesUIs.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
*Prefabfields 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 usenameof(MyScreenView)on the script side. - Full-bleed background placed under
Content— SafeArea insets it on notched devices, revealing letterboxing. Background images go underBackground. - Tap-targets placed under
BackgroundorForeground— they can fall under the notch or gesture bar. Interactive UI MUST live underContent. - 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. GridLayoutGroupfor responsive grids — fixed cell count breaks on landscape/portrait. UseFlexibleLayoutGroupVer2withBaseOnContentpreset.- 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
.prefabYAML 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
.prefabYAML can be silently REVERTED by the open Editor — on-disk verification is not proof. While an Editor holds the prefab, an unrelatedt1k unity refreshre-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 agit statustaken 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.mdRecipe 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.