t1k:unity:ui:create-prefab
| Field | Value |
|---|---|
| Module | ui |
| Version | 3.43.4 |
| Effort | low |
| Tools | — |
Keywords: common ui, content children, Content layering, field-driven, FlexibleLayoutGroupVer2, Foreground, gdk core, generic ui, layout image, popup prefab, prefab variant, responsive ui, RootUI, SafeArea, screen prefab, Timeline_Grp, ui prefab, UIBasePopup, UIBaseScreen
How to invoke
Section titled “How to invoke”/t1k:unity:ui:create-prefab[screen-name] [layout-image-path] (both optional)Create Generic Unity UI Prefab (Screen / Popup)
Section titled “Create Generic Unity UI Prefab (Screen / Popup)”Prefab-only authoring guide for generic Unity UI screens / popups (NOT TheOneFeature-scoped). Scope is the .prefab asset: variant of the com.gdk.core 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.
Mirror counterpart:
t1k:unity:tof:ui-create-prefab(at.claude/skills/t1k-unity-tof-ui-create-prefab/SKILL.md). When editing either skill, mirror the change.
Scope — When to Use This Skill vs. the TOF Skill
Section titled “Scope — When to Use This Skill vs. the TOF Skill”| Target prefab path | Use skill |
|---|---|
Packages/TheOneFeature* (anything under any TheOneFeature.* package) | t1k:unity:tof:ui-create-prefab |
Assets/Prefabs/UIs/ (project-level TOF screen registry path) | t1k:unity:tof:ui-create-prefab |
Anything else — Packages/com.gdk.<x>/, Packages/<consumer>/, Assets/Prefabs/<Feature>/UI/, project-side feature packages that do not use the TOF runtime | this skill |
If the target path matches a TOF row, STOP and switch to the TOF skill — TOF screens variant from a different base, register in a different Addressables group, and integrate with ScreenManager differently.
Execution — run through t1k-unity-base-ui-developer
Section titled “Execution — run through t1k-unity-base-ui-developer”Do not build the prefab from the calling session. Spawn t1k-unity-base-ui-developer natively (never routed: a routed hop cannot reach the Editor) with a brief carrying: the screen name, the layout image path or the t1k:unity:ui:describe-image output (paths, never pasted payloads), the target prefab path, and a pointer to this SKILL.md. It applies the Scope, Decision Tree, layer, anchor and §9 rules below as the spec, then briefs t1k-unity-base-developer to author the prefab through t1k unity eval (Track E) or the YAML track (Track Y), per §1/§7, t1k-unity-base-visual-director to review the screenshot, and t1k-unity-base-mono-tester for any UI tests. It accepts the result against §8 and reports pass/fail per checklist line.
Only one editor-driving helper runs at a time (mutating t1k unity verbs queue on a per-project lock and exit 10 when it stays busy); do not start a parallel t1k unity call while it works. Ambiguity it cannot resolve (Addressables group, TOF vs generic path) comes back as a question — relay it with AskUserQuestion. If Agent is unavailable (leaf sub-agent, MR_SPAWNED=1), follow the sections below inline and say so.
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) (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 UIBaseScreen.prefab → §1 Create as Variant (references/variant-creation.md) |
| “New popup / modal” | Create variant of UIBasePopup.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 (Tl_Appears / Tl_Disappears) → §3 Timeline_Grp (below) |
| “Set anchors / pivot on a child” | §5 Anchor / pivot rules (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: UIBaseScreen.prefab (screen) / UIBasePopup.prefab (popup, itself a variant of UIBaseScreen), both under Packages/com.gdk.core/Prefabs/CommonUIPrefab/.
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): references/shared-prefab-mechanics.md § “Layer Scope”. Generic-skill-specific: CanvasScaler lives ONLY on RootUI (TOF’s is HyperCasualRootUI).
3. Timeline_Grp — Open / Close Animations
Section titled “3. Timeline_Grp — Open / Close Animations”Shared mechanics: references/shared-prefab-mechanics.md § “Timeline_Grp”. Author per-screen Timeline assets under Packages/<consumer-package>/Timelines/<ScreenName>_Appears.playable and <ScreenName>_Disappears.playable (or equivalent project path).
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.
Workflow:
- Build the widget once as a standalone prefab under
Prefabs/UI/Widgets/. - Drop prefab instances with
PrefabUtility.InstantiatePrefab(<widget prefab>, parent)(Track E, live-prefab-edit.md (references/live-prefab-edit.md)) or a nestedPrefabInstanceblock (Track Y). - Override only per-instance fields.
If com.gdk.core or another generic UI package in the project ships reusable widgets, prefer those before building new ones. For TheOneFeature-scoped widgets at Packages/TheOneFeature.PuzzleUI/Common/Prefabs/, consult the TOF skill — they may carry TOF-runtime dependencies.
5. Anchor / Pivot Rules
Section titled “5. Anchor / Pivot Rules”→ anchor-pivot-rules.md (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): references/shared-prefab-mechanics.md § “Layout Groups”.
7. Addressables Registration
Section titled “7. Addressables Registration”Required so the screen-loading system (ScreenManager.OpenScreen<T>() or equivalent) can resolve the prefab. No t1k unity verb adds an Addressables entry — the group entry must be added via direct YAML edit. Never hardcode a group name — detect it per-project, and ask the user via AskUserQuestion if the consumer hasn’t committed to one.
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
UIBaseScreen.prefaborUIBasePopup.prefab— file starts with!u!1001 &and ends withm_SourcePrefab: {fileID: 100100000, guid: <base-guid>} - Target path is OUTSIDE
Packages/TheOneFeature*andAssets/Prefabs/UIs/(use TOF skill otherwise) - Prefab name
<ScreenName>View.prefabmatches the future[ScreenInfo]key - Every
[SerializeField]GameObject/Component field on the View has a matching child underContent(or other layer if explicitly tagged) 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
Content/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 (withTl_Appears+Tl_Disappears); per-screen Timelines overridden 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 consumer’s chosen UI Addressables group with address = prefab name (or confirmed not required)
-
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 underContent(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
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.<Field>.<Member> because the field 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): → 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 for generic Unity UI screens / popups OUTSIDE TheOneFeature paths. Does NOT cover: View/Presenter C# scripts, [ScreenInfo] attribute wiring, VContainer registration, runtime open/close calls, or TheOneFeature-runtime integration.
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 underContent(§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 against existing TMP prefabs (e.g.titlePopup1.prefab).textis the runtime C# property;m_Text(capitalised) is wrong. - 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. Never hardcode — detect via §7.1 grep, then
AskUserQuestionif undetermined. - Skeleton prefab without children → runtime NullReferenceException. Skipping §9 leaves
[SerializeField]refs unwired. §9 is MANDATORY, not advisory. - Field-name
*Prefabfields are user-assigns, not children. Used by Presenter for runtime spawning — do NOT materialize as children. - Layout image hallucination. §9.4 MUST echo interpretation before applying. Never silently spawn children from a guessed layout.
- Variant-of-variant root-GO fileID lookup. For chains like
UIBasePopup → UIBaseScreen, root GO fileID points to the grandparent. Detail: variant-creation.md (references/variant-creation.md). - Used the wrong skill — TOF-path prefab authored with this skill (or vice versa) variants from the wrong base and silently fails. Always check the path-based rule in Scope.
- Duplicating the base instead of variant-ing it — duplicated screens stop receiving base-prefab fixes. Always Track E (or Track Y).
- Prefab name = Addressables address =
[ScreenInfo]key. Drift = silent load failure. Usenameof(MyScreenView). - Full-bleed background placed under
Content— SafeArea insets it, revealing letterboxing. - Tap-targets placed under
BackgroundorForeground— notch / gesture-bar risk. Interactive UI MUST live underContent. - Deleting
Timeline_Grp,Tl_Appears, orTl_Disappears— transitions silently no-op. - Editing the base’s Timeline assets directly — changes every screen. Override per-variant.
- Adding a second SafeArea — double inset. Base ships exactly one on
Content. - CanvasScaler / AspectRatioFitter on the variant root — fights
RootUI’s scaler. GridLayoutGroupfor responsive grids — fixed cell count breaks under aspect changes. UseFlexibleLayoutGroupVer2.- Pivot not matching anchor edge — element drifts across resolutions. Apply §5 rigidly.
- Silently picking an Addressables group — locks in a hard-to-reverse convention. Ask the user when unclear.
- Renaming a prefab after Addressables registration without updating the address — address does NOT auto-rename.
- Hand-editing
.prefabYAML beyond the §1 Track Y template — corrupts variant overrides silently. - 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.
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.