t1k:cocos:playable:ui-from-image

Field	Value
Module	`playable`
Version	`2.14.4`
Effort	`high`
Tools	—

Keywords: hud, mockup, recreate ui, reference image, screenshot to ui, ui from image, visual matching

How to invoke

/t1k:cocos:playable:ui-from-image
<image-path> [output-prefab]

UI From Image

Turn one attached/local reference image into a Cocos Creator 3.x UI prefab by reusing the closest UI nodes, prefabs, sprites, and fonts already present in the project.

Command

/t1k:cocos:playable:ui-from-image <image-path> [assets/resources/prefab/UI/NewView.prefab]

If the image is attached without a filesystem path, inspect the attachment directly. Infer the project root from assets/; ask only when multiple Cocos projects are plausible.

Workflow

Read the image — inventory regions, hierarchy, text, alignment, colors, aspect ratio, and interaction states. Mark visual facts versus uncertain behavior.
Catalog reuse — run scripts/ui-from-image.cjs catalog --project <root> --hints "<visual + semantic terms>". Inspect the highest-ranked candidates; never invent an asset before this scan.
Choose a base — prefer a structurally similar full-screen prefab. Inspect it; record reuse decisions and rejected near-matches.
Compose — create a manifest using manifest-schema.md. Run compose without --write, review its summary, then run with --write.
Verify — run verify --strict-uuid when all dependencies are project assets, then open/reimport the new prefab in Cocos and compare portrait + landscape against the image.

Runtime Commands

node scripts/ui-from-image.cjs catalog --project <root> --hints "timer top hud green install button"
node scripts/ui-from-image.cjs inspect --project <root> --prefab <candidate.prefab>
node scripts/ui-from-image.cjs compose --manifest <ui-plan.json>
node scripts/ui-from-image.cjs compose --manifest <ui-plan.json> --write
node scripts/ui-from-image.cjs verify --project <root> --prefab <output.prefab>

The composer edits existing nodes and reuses plain subtrees. It never writes during dry-run, overwrites only with --force, never copies .meta, and rejects output outside assets/.

scripts/scan-ui-project.cjs is a legacy prefab-only compatibility scanner — prefer catalog above, which also indexes sprite-frame subMetas and accepts visual hints. See scan-schema.md for the stable output schema of both scanners.

Matching Rules

Match structure before decoration: safe area → major panels → repeated controls → text/icon details.
Reuse whole subtrees for coupled UI such as button + label + widget; use set for layout, text, sprite, size, active state, and transforms.
Preserve the base prefab’s custom components, script bindings, nested instances, and serialization version.
Prefer Widget/layout conventions already used by the base; do not convert responsive UI into fixed screenshot coordinates.
Report fidelity as exact / close reuse / placeholder and identify every remaining visual gap.

See workflow.md for the full visual-matching checklist (reference inventory → candidate evidence → manifest review → visual acceptance).

Completion Gate

Deliver only when output is a new .prefab, dry-run and write summaries agree, validator errors are zero, no existing .meta was copied, and the Editor reimport/manual visual check is recorded. See prefab-safety.md.

Gotchas

Nested prefab overrides are not portable subtrees. The composer rejects instance/override records. Use that whole prefab as base or unpack/duplicate it in Cocos Editor.
Sprite references use the sprite-frame subMeta UUID, usually @f9941, not the image or texture UUID. Multiple frames require sprite.subMeta.
Cloned prefab file IDs must be unique. The composer deterministically regenerates copied prefab-info file IDs and validates duplicates.
A screenshot proves appearance, not behavior. Preserve existing wiring where evidence exists; explicitly flag unknown click actions and states.
Filesystem success is not Editor success. Reimport/open the result; custom scripts and nested overrides are Editor-resolved concerns.

t1k:cocos:playable:layout — responsive sizing and safe areas.
t1k:cocos:playable:asset-management — runtime resource loading.
t1k:cocos:playable:editor-tools — Editor-side automation.