Skip to content

t1k:unity:ui:create-prefab

FieldValue
Moduleui
Version3.43.4
Effortlow
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

/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 pathUse 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 runtimethis 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.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) (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 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)

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).

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:

  1. Build the widget once as a standalone prefab under Prefabs/UI/Widgets/.
  2. Drop prefab instances with PrefabUtility.InstantiatePrefab(<widget prefab>, parent) (Track E, live-prefab-edit.md (references/live-prefab-edit.md)) or a nested PrefabInstance block (Track Y).
  3. 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.

→ anchor-pivot-rules.md (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): references/shared-prefab-mechanics.md § “Layout Groups”.

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.prefab or UIBasePopup.prefab — file starts with !u!1001 & and ends with m_SourcePrefab: {fileID: 100100000, guid: <base-guid>}
  • Target path is OUTSIDE Packages/TheOneFeature* and Assets/Prefabs/UIs/ (use TOF skill otherwise)
  • 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 other layer if explicitly tagged) 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 Content / 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 (with Tl_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, not GridLayoutGroup
  • Prefab added to the consumer’s chosen UI Addressables group with address = prefab name (or confirmed not required)
  • 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 Content (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

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.

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.

  • 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 Content (§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 existing TMP prefabs (e.g. titlePopup1.prefab). text is 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. 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. Never hardcode — detect via §7.1 grep, then AskUserQuestion if undetermined.
  • Skeleton prefab without children → runtime NullReferenceException. Skipping §9 leaves [SerializeField] refs unwired. §9 is MANDATORY, not advisory.
  • Field-name *Prefab fields 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. Use nameof(MyScreenView).
  • Full-bleed background placed under Content — SafeArea insets it, revealing letterboxing.
  • Tap-targets placed under Background or Foreground — notch / gesture-bar risk. Interactive UI MUST live under Content.
  • Deleting Timeline_Grp, Tl_Appears, or Tl_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.
  • GridLayoutGroup for responsive grids — fixed cell count breaks under aspect changes. Use FlexibleLayoutGroupVer2.
  • 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 .prefab YAML beyond the §1 Track Y template — corrupts variant overrides silently.
  • 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.

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.