t1k:unity:tof:image-to-script-plan
| Field | Value |
|---|---|
| Module | tof |
| Version | 3.46.8 |
| Effort | medium |
| Tools | — |
Keywords: BaseFeatureScreenPresenter, feature plan, fight screen, hud, image to script, IUIActionHandler, PuzzleUIActionHandler, scaffold screen, screen mockup, screen view, ScreenInfo, screenshot, 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)”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 siblingAssets/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.
Decision defaults — do not ask
Section titled “Decision defaults — do not ask”- 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.
- A project-local rival needs a stated reason TOF cannot be customized — “the design differs” is not one.
- 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.
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 namedUnity<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/TheOneFeatureis a git submodule. In a feature worktree it is often empty/uninitialized (git submodule statusshows 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 begit submodule update --init Assets/TheOneFeaturein the current worktree before any code can compile here.
2. Analyze the image → UI regions
Section titled “2. Analyze the image → UI regions”- 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 nativeReadtool. - 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):
- Image analysis — the region→data table + explicit deferred list.
- 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). - UI screen
UI/Layouts/Puzzle/Scripts/<Feature>/—<Feature>ScreenView : BaseView+[ScreenInfo] <Feature>ScreenPresenter : BaseFeatureScreenPresenter<TView>, pooled child components viaIObjectPoolManager, one UI asmdef. - Action-handler integration — add
Open<Feature>()toTheOne.Features.Puzzle.ActionHandlers.Core.IUIActionHandlerand implement inPuzzleUIActionHandler(the only screen-opening inheritor); add theTheOne.Features.Puzzle.UI.<Feature>reference toTheOne.Features.Puzzle.ActionHandlers.Default.asmdef. - Wiring & assets —
Register<Feature>()intoGameLifetimeScope(validator auto-injects); prefab whose Addressables address ==nameof(<Feature>ScreenView). - Phases & verification — compile-gate after Core and after UI (
t1k unity console --level errorclean; batch-verify perai-velocity-batch-compile-unity); smoke =uiActionHandler.Open<Feature>()shows the stub data. - Open items / deferred — every cut region + the seam where real data/sim lands later.
Hard rules
Section titled “Hard rules”- 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, neverInstantiate(permono-pool-spawn-unityrule). - An interface change to
IUIActionHandlerforces 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 followst1k:unity:tof:ui-create-prefab(Track E / Track Y).
Related
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: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 modelI<Feature>Serviceon.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.