t1k:cocos:playable:ui-from-image
| Field | Value |
|---|---|
| Module | playable |
| Version | 4.33.13 |
| Effort | high |
| Tools | — |
Keywords: hud, mockup, recreate ui, reference image, screenshot to ui, ui from image, visual matching
How to invoke
Section titled “How to invoke”/t1k:cocos:playable:ui-from-image<image-path> [output-prefab]UI From Image
Section titled “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
Section titled “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
Section titled “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(references/manifest-schema.md). Runcomposewithout--write, review its summary, then run with--write. - Verify — run
verify --strict-uuidwhen all dependencies are project assets, then open/reimport the new prefab in Cocos and compare portrait + landscape against the image.
Runtime Commands
Section titled “Runtime Commands”bun scripts/ui-from-image.cjs catalog --project <root> --hints "timer top hud green install button"bun scripts/ui-from-image.cjs inspect --project <root> --prefab <candidate.prefab>bun scripts/ui-from-image.cjs compose --manifest <ui-plan.json>bun scripts/ui-from-image.cjs compose --manifest <ui-plan.json> --writebun 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 (references/scan-schema.md) for the stable output schema of both scanners.
Matching Rules
Section titled “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
setfor 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 (references/workflow.md) for the full visual-matching checklist (reference inventory → candidate evidence → manifest review → visual acceptance).
Visual director loop
Section titled “Visual director loop”t1k-gamedev-playable-visual-director (advisory — never edits, never calls editor MCP): take a measurable brief of the target before composing the manifest, and a screenshot pass/fix list of the built prefab before calling the work done.
Max 2 rounds — after the second, remaining items are the caller’s call, not a third pass.
Its fixes land through t1k-cocos-base-developer (prefab/TS) or t1k-cocos-base-editor-operator (editor writes).
Completion Gate
Section titled “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 (references/prefab-safety.md).
Geometry pass (also required). bun scripts/check-ui-geometry.cjs <output.prefab> [--canvas WxH] exits 0: no pairwise overlap above 1 px on both axes among visible text and button nodes, nothing outside the canvas by more than 2 px, no label under the px floor (authored font px x cumulative node scale, default 12), no labelled panel scaled below 0.9. A nonzero _euler on a path is reported as needs-editor-check, not passed. The script reads positions, scales and sizes from the saved JSON only: it cannot see a label that overflows at render time or a Layout/Widget result, so also run the runtime overlap measurement from t1k-gamedev-playable-preview-verify at 2+ aspect ratios. A prefab cloned from a template or donor must also have every visible cc.Label/cc.Sprite enumerated and bound or deactivated (ui-rule (../../../base/skills/t1k-cocos-base-apk-port/references/ui-rule.md) § donor leftovers). Evidence: ForceMasterPort overlapping tab buttons and 5-7 px panel text (owner decisions).
Executed by
Section titled “Executed by”Catalog, inspect, compose and verify are ui-from-image.cjs modes; matching a reference image is judgment. Routing SSOT: theonekit-core/.claude/modules/t1k-orchestration/rules/orchestration-rules.md § “Task-Type → Agent Routing”.
| Step | Agent |
|---|---|
Run ui-from-image.cjs catalog / inspect / verify and scan-ui-project.cjs and report their output | t1k-list-classifier |
| Author the manifest and the prefabs from the image | t1k-cocos-base-developer writes (operator for editor-only/repair); t1k-gamedev-playable-visual-director reviews — reasoning tier |
Hard rules
Section titled “Hard rules”- 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 requiresprite.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.
Related
Section titled “Related”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.
Visual change notice
Section titled “Visual change notice”Rule visual-change-discord-notice: building a UI prefab from a reference image is a visible change. Capture OLD before the first edit and NEW after the last (preview-verify shot steps, or the image file itself for a 2D asset), return the paths and a draft Discord post (what changed, undo = revert the PR) to the orchestrator, who posts; never post from here. Logic-only: no visible change. No capture possible: screenshots pending: <reason>, never a mock image. The PR needs the Discord link or visual-notice-waiver: <reason>; the owning agent’s Visual change notice section has the full steps.