Skip to content

t1k:cocos:playable:ui-from-image

FieldValue
Moduleplayable
Version4.33.13
Efforthigh
Tools—

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

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

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.

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

  1. Read the image — inventory regions, hierarchy, text, alignment, colors, aspect ratio, and interaction states. Mark visual facts versus uncertain behavior.
  2. 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.
  3. Choose a base — prefer a structurally similar full-screen prefab. Inspect it; record reuse decisions and rejected near-matches.
  4. Compose — create a manifest using manifest-schema.md (references/manifest-schema.md). Run compose without --write, review its summary, then run with --write.
  5. 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.
Terminal window
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> --write
bun 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.

  • 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 (references/workflow.md) for the full visual-matching checklist (reference inventory → candidate evidence → manifest review → visual acceptance).

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

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

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

StepAgent
Run ui-from-image.cjs catalog / inspect / verify and scan-ui-project.cjs and report their outputt1k-list-classifier
Author the manifest and the prefabs from the imaget1k-cocos-base-developer writes (operator for editor-only/repair); t1k-gamedev-playable-visual-director reviews — reasoning tier
  • 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.

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.