Skip to content

t1k:unity:sexygame:ftue-unlock

FieldValue
Modulesexygame
Version1.7.2
Effortlow
Tools—

Keywords: element intro, ftue icon, ftue unlock, new booster ftue, unlock popup

/t1k:unity:sexygame:ftue-unlock

Author FTUE unlock assets with scripts, never by hand-editing YAML or by hand-clicking Editor tools. Kit-owned (module sexygame, with t1k-unity-sexygame-template-setup). Runs inline in the main session or in any implementer lane. Python 3, stdlib only except make_icon.py (Pillow, Blender).

Hard rule: every unlock popup shows an icon (elements use the booster action too)

Section titled “Hard rule: every unlock popup shows an icon (elements use the booster action too)”
Popup actionthumbnailskinskinTypesubTitle
ElementShowBoosterUnlockPopupAction= icon key= icon keyspriteNew Element Unlocked!
BoosterShowBoosterUnlockPopupAction= icon key= icon key (or gif)sprite or gifNew Booster Unlocked!

Owner rule: every unlock popup carries a thumbnail. The old element action ShowUnlockPopupAction has no thumbnail field and is retired: do not use it. check_ftue.py fails an element asset that lacks the booster action or contains the old one (element-actions), whose thumbnail is empty or differs from skin (popup-keys, element-thumbnail), a booster without the popup (booster-popup), a guid missing from FTUEConfig (config-registered) and an icon key that is not an Addressables address (icon-addressable).

python3 .claude/skills/t1k-unity-sexygame-ftue-unlock/scripts/ftue_all.py element --name Gear --level 35 \
--description "A gear needs its key cleared first." --icon ic_<game>_elem_gear --dry-run

Drop --dry-run to run: generate asset (new_ftue.py) -> icon (make_icon.py, Blender, only when the icon file does not exist yet) -> register in FTUEConfig (register_ftue.py) -> sync localization (sync_localization.py, headless Unity through the batch gate) -> check (check_ftue.py). --skip a,b / --only a,b select steps (names: generate, icon, register, sync, check). It stops at the first failing step; exit 75 from sync = gate busy, rerun with --only sync,check. Then commit the new asset + .meta, icon + .meta, the Addressables group asset, FTUEConfig and the changed LocalizationSetting/Game/* files. The run only ends once the popup has been seen on screen (verification (references/verification.md) layer 3).

Per-game settings (the skill ships no game data)

Section titled “Per-game settings (the skill ships no game data)”

Everything that differs per game lives in ONE game-owned file, .claude/sgame-setup/ftue-icons.json (schema sgame-ftue-icons/1, example templates/ftue-icons.example.json; the file is optional for boosters and prebooster, which need no icon render). sgame-setup/ is a game-owned folder: a template pull never overwrites it. Paths are relative to the Unity project unless noted.

KeyDefaultMeaning
ftueDirAssets/Resources/FTUEwhere FTUE_<Kind>_<Name>.asset goes when --out is not given
groupAssets/AddressableAssetsData/AssetGroups/Preloads.assetAddressables group that receives the icon entry
labelPreloadGameObjectlabel of that entry
iconDirnone (required to wire an icon)where the icon PNG + .meta go
iconPrefixnone (required)element icon key = iconPrefix + element, e.g. ic_<game>_elem_
elements[]element names the game’s Blender script can draw
rendernone (required){"script": <repo-relative path of the game's Blender script>, "gameplayDir": <project-relative dir handed to it>, "requires": <subdir of gameplayDir that must exist>}

The project root is found from the cwd (the folder with ProjectSettings/ProjectVersion.txt, or its Unity* child of the repo root); --project overrides. An unknown key, a wrong schema or invalid JSON exits 2 naming the file. The Blender script contract is in icon-contract (references/icon-contract.md).

SituationCommand kindTemplate
Booster unlocked during gameplay (button on the gameplay HUD)boosterFTUE_Booster_Name.asset: popup, currency grant, flying icon, tooltip, focus click
Booster unlocked on the pre-play screen (trigger BeforePlayPopupPresenter)preboosterFTUE_PreBooster_Name.asset
New element (nut/bolt mechanic) introduced on the boardelementFTUE_Element_Name.asset: step 1 [ShowBoosterUnlockPopupAction (with thumbnail), PauseGameAction], step 2 [ResumeGameAction]

Templates are verbatim copies of the studio booster/element unlock templates (<Name>/<name>/<Description> kept). The generator also writes a fresh 32-hex persistentId on every action, fresh rids, and a .meta with a fresh guid (the shape Unity writes, mainObjectFileID: 11400000).

Workflow (what each script does, for running a step alone)

Section titled “Workflow (what each script does, for running a step alone)”
  1. Pick the kind from the table. Confirm the level gate and the icon key (authoring-rules (references/authoring-rules.md), icon-contract (references/icon-contract.md)).
  2. new_ftue.py <kind> --name .. --level .. --description .. --icon .. --out <FTUE dir> [--dry-run] writes FTUE_<Kind>_<Name>.asset + .meta.
  3. make_icon.py <element> [--preview-dir DIR] renders the icon from the game’s own models and wires it (icon-contract (references/icon-contract.md)). Boosters: art comes from the economy/art lane; the script renders the elements the game lists in its settings file and runs the game’s own Blender script.
  4. register_ftue.py <asset> [--config ..] appends the guid to sequences: (idempotent, byte-preserving).
  5. sync_localization.py [--scan] [--no-translate] runs FTUE Localization Sync headless (localization (references/localization.md)).
  6. check_ftue.py <FTUE dir> --boosters FTUE_Hint,FTUE_Undo [--config ..] (verification (references/verification.md)).
  7. See the popup on screen before calling it done (verification layer 3).

new_ftue.py booster|prebooster|element --name <Id> --level <N> --description <text> --icon <address> [--out <dir>]

FlagDefaultNotes
--skin-type sprite|gifspritegif requires --skin
--skin= --iconpopup art address (elements: always = icon)
--title= --namepopup title and itemName
--currency-id, --amount, --ui-elementName, 1, BoosterButton_<Name> (prebooster: <Name>)booster/prebooster only
--seed Nrandomsame seed gives byte-identical output
--dry-runoffprint to stdout, write nothing

Exit codes: 0 ok, 2 bad arguments, 3 would overwrite (or ftueId already in --out), 4 template missing. It never overwrites; delete the old pair deliberately if you mean to regenerate.

ScriptExit codes
make_icon.py <element> [--project P] [--preview-dir D] [--dry-run]0 ok, 2 args, 3 icon/meta/address already exists (no --force exists), 4 Blender missing or render failed
register_ftue.py <asset>... [--config C] [--dry-run]0 registered or already registered (says which), 2 config missing/odd shape, 3 asset has no .meta/guid (nothing written)
sync_localization.py [--project P] [--scan] [--no-translate] [--timeout S]0 ok (incl. nothing to do), 3 translation quota (progress saved), 4 module not found, 5 an Editor already has the project open, 75 gate busy, 77 Unity ran but proved nothing, 1 other
`ftue_all.py …flags of new_ftue.py… [—skip—only steps] [—dry-run]`
check_ftue.py <dir> [--boosters ids] [--config C] [--json]`PASS

config-registered and icon-addressable print SKIP (never PASS) when FTUEConfig cannot be found. Headless Unity rules apply: the sync goes through the batch gate, never kills an Editor, refuses when one has the project open.

  • Writes: the asset + meta into --out; the icon + meta into iconDir; one line into the settings’ Addressables group and one into FTUEConfig.asset; the Game localization table through Unity. No C# edits beyond Assets/Scripts/Editor/FtueTools/.
  • Icon rendering only: Blender (flatpak org.blender.Blender works), Pillow, and the game’s gameplay models checked out.
  • Tests: python3 -m unittest discover -s .claude/skills/t1k-unity-sexygame-ftue-unlock/tests -v (each check and script proven RED on a broken fixture).
  • Out of scope: tutorial-style text FTUE (FTUEShowTextAction), card-shop or first-level sequences; use t1k-unity-sexygame-template-setup references/ftue.md.