Skip to content
T1KTheOneKit

t1k:unity:tof:image-to-script-plan

FieldValue
Moduletof
Version2.2.2
Effortmedium
Tools—

Keywords: BaseFeatureScreenPresenter, feature plan, fight screen, hud, image to script, IUIActionHandler, mockup, PuzzleUIActionHandler, scaffold screen, screen mockup, screen view, ScreenInfo, screenshot, theonefeature, tof, ui to feature

How to invoke

Section titled “How to invoke”
/t1k:unity:tof:image-to-script-plan
<path-or-attached image> [feature name] — e.g. 'FightScreenView.png as Battle feature'

Image → Script Plan (TheOneFeature screen scaffolding)

Section titled “Image → Script Plan (TheOneFeature screen scaffolding)”

Given a UI mockup/screenshot, produce a grounded, phased implementation plan for a new Core feature + Puzzle UI screen following TheOneFeature conventions, opened through the action-handler indirection. The output is a plan file under plans/, not implementation (unless the user then approves building it).

This is the script / feature-plan complement to the prefab/layout skills: t1k:unity:ui:describe-image breaks a screenshot into a RectTransform hierarchy, t1k:unity:tof:ui-create-prefab authors the prefab — this skill plans the View/Presenter + Core feature + wiring.

Concrete code templates (asmdef JSON, service/DI/validator/View/Presenter skeletons) live in references/theonefeature-conventions.md. Read it before writing the plan — do not re-derive conventions from scratch.

Workflow

Section titled “Workflow”

1. Locate the framework (do this first — it has a worktree trap)

Section titled “1. Locate the framework (do this first — it has a worktree trap)”
  • The Unity project is Unity<ProjectName>/ (the project dir is named Unity<ParentFolderName> per the puzzle-template convention), not the repo root.
  • Core features: Assets/TheOneFeature/Core/Features/<Feature>/. UI screens: Assets/TheOneFeature/UI/Layouts/Puzzle/Scripts/<Feature>/.
  • ⚠️ Assets/TheOneFeature is a git submodule. In a feature worktree it is often empty/uninitialized (git submodule status shows a leading -). The populated copy lives in the main checkout (git worktree list → the non-worktree path). Study conventions from the populated copy; flag that the submodule must be git submodule update --init Assets/TheOneFeature in the current worktree before any code can compile here.

2. Analyze the image → UI regions

Section titled “2. Analyze the image → UI regions”
  • If human-mcp (mcp__human-mcp__eyes_analyze) is installed, route image analysis through it; otherwise native vision is the intended fallback.
  • Enumerate every visible region, then map each to the data it needs. Build a table: Region | Mockup element | Stub data fields.
  • Name deferred regions explicitly so they aren’t re-discovered later.

3. Study 2 analog features (don’t invent the pattern)

Section titled “3. Study 2 analog features (don’t invent the pattern)”

Pick the closest existing combat/gameplay analogs as templates and read them: Core → one full feature (e.g. Dungeons) + one minimal placeholder (e.g. Pvp); UI → the same full feature + Gameplay; plus UI/Layouts/Puzzle/Scripts/README.md and ASYNC_PATTERNS.md. Delegate this to parallel Explore agents pointed at the populated checkout. The reusable findings are already distilled in the references file — refresh only if the framework has drifted.

4. Resolve scope with AskUserQuestion (mandatory)

Section titled “4. Resolve scope with AskUserQuestion (mandatory)”

Never assume these — they change the whole plan. Batch into one AskUserQuestion call (load schema via ToolSearch(query="select:AskUserQuestion") if deferred):

  • Logic depth — full self-contained Mono sim vs. thin bridge to an existing DOTS/combat package vs. view + stub data only.
  • Feature name — drives folder + namespace (TheOne.Features.<Name>.Core).
  • Which regions are in scope this iteration — the user may cut the screen down to a subset (e.g. only map header + wave slider + skills).

5. Write the phased plan to plans/<feature>-screen-view-plan.md

Section titled “5. Write the phased plan to plans/<feature>-screen-view-plan.md”

Cover, in this order (full templates in the references file):

  1. Image analysis — the region→data table + explicit deferred list.
  2. Core feature Core/Features/<Feature>/ — Scripts/Models/*, Services/I<Feature>Service + stub impl, DI/<Feature>VContainer.Register<Feature>(), Editor/<Feature>Validator, three asmdefs (.Core, .DI, .Core.Editor).
  3. UI screen UI/Layouts/Puzzle/Scripts/<Feature>/ — <Feature>ScreenView : BaseView + [ScreenInfo] <Feature>ScreenPresenter : BaseFeatureScreenPresenter<TView>, pooled child components via IObjectPoolManager, one UI asmdef.
  4. Action-handler integration — add Open<Feature>() to TheOne.Features.Puzzle.ActionHandlers.Core.IUIActionHandler and implement in PuzzleUIActionHandler (the only screen-opening inheritor); add the TheOne.Features.Puzzle.UI.<Feature> reference to TheOne.Features.Puzzle.ActionHandlers.Default.asmdef.
  5. Wiring & assets — Register<Feature>() into GameLifetimeScope (validator auto-injects); prefab whose Addressables address == nameof(<Feature>ScreenView).
  6. Phases & verification — compile-gate after Core and after UI (read_console clean; batch-verify per ai-velocity-batch-compile-unity); smoke = uiActionHandler.Open<Feature>() shows the stub data.
  7. Open items / deferred — every cut region + the seam where real data/sim lands later.

Gotchas

Section titled “Gotchas”
  • Submodule-empty-in-worktree is the #1 blocker — check it before promising anything compiles here (§1).
  • [ScreenInfo(nameof(<Feature>ScreenView))] — the prefab Addressables address must equal the screen class name or the screen won’t resolve.
  • Naming: feature name drives the class names; if the user named the image differently from the feature (e.g. mockup “FightScreenView” but feature “Battle”), confirm whether the screen class keeps the mockup name or the feature name.
  • Dynamic UI (skill buttons, list items) → IObjectPoolManager.Spawn/Recycle, never Instantiate (per mono-pool-spawn-unity rule).
  • An interface change to IUIActionHandler forces the compiler to flag any secondary inheritor — let it; non-screen consumers (e.g. CardCollectionService, RateUsService) need no change.
  • Prefab authoring: MCP cannot author prefab variants — a plain prefab (copy a simple existing screen prefab and re-wire serialized fields) is the supported path.
Section titled “Related”
  • references/theonefeature-conventions.md — concrete asmdef + code templates.
  • t1k:unity:ui:describe-image — screenshot → RectTransform hierarchy/anchor breakdown (the layout-planning complement; run it for the prefab layout, this skill for the scripts).
  • t1k:unity:tof:ui-create-prefab — authors the screen/popup prefab once the layout is known.
  • t1k:unity:tof:blueprint-csv — when the feature needs real CSV/ScriptableObject blueprint data instead of stubs.
  • t1k:unity:tof:gameplay — analog Core-feature pattern (session loop, signals, DI) to model I<Feature>Service on.
  • rules/scan-shared-code-update-skill.md — if you read TOF source to learn an API this skill omits, fold it back here.
  • rules/mono-pool-spawn-unity.md, rules/ai-velocity-batch-compile-unity.md, rules/code-conventions-unity.md.