Skip to content

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

FieldValue
Moduletof
Version3.46.8
Effortmedium
Tools—

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

/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)”

Scope — this is a candidate index, not an inventory. This skill indexes one source folder. A feature can span Assets/TheOneFeature/, Packages/com.gdk.*, and sibling Assets/TheOne.* packages, and this skill will only show the folder it was built from. A capability missing here is not evidence that it is absent — verify against source (grep over a stated scope) before concluding anything does not exist. See The1Studio/theonekit-unity#350.

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.

  1. Reuse the TOF module for the feature/screen; customize it even when the mockup or reference differs slightly. Prefer TOF’s structure; absorb the visual difference into the module rather than rebuilding it.
  2. A project-local rival needs a stated reason TOF cannot be customized — “the design differs” is not one.
  3. UI goes through t1k:unity:tof:ui-create-prefab (prefab) and this skill (screen logic) — never a hand-rolled screen outside the TOF/Puzzle conventions.

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.
  • Image analysis uses the router’s vision role command (bun <claudeDir>/scripts/mr-role.cjs call --role vision --file <path> --prompt "...") when the agent has Bash, else the native Read tool.
  • 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 (t1k unity console --level error 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.
  • 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: there is no prefab verb in t1k unity; a plain prefab (copy a simple existing screen prefab and re-wire serialized fields) is the simple path, and a true variant follows t1k:unity:tof:ui-create-prefab (Track E / Track Y).
  • 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:base: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/kit-wide-fix-discipline.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.