t1k:unity:sexygame:ftue-unlock
| Field | Value |
|---|---|
| Module | sexygame |
| Version | 1.7.2 |
| Effort | low |
| Tools | — |
Keywords: element intro, ftue icon, ftue unlock, new booster ftue, unlock popup
How to invoke
Section titled “How to invoke”/t1k:unity:sexygame:ftue-unlockt1k-unity-sexygame-ftue-unlock
Section titled “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 action | thumbnail | skin | skinType | subTitle | |
|---|---|---|---|---|---|
| Element | ShowBoosterUnlockPopupAction | = icon key | = icon key | sprite | New Element Unlocked! |
| Booster | ShowBoosterUnlockPopupAction | = icon key | = icon key (or gif) | sprite or gif | New 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).
One command
Section titled “One command”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-runDrop --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.
| Key | Default | Meaning |
|---|---|---|
ftueDir | Assets/Resources/FTUE | where FTUE_<Kind>_<Name>.asset goes when --out is not given |
group | Assets/AddressableAssetsData/AssetGroups/Preloads.asset | Addressables group that receives the icon entry |
label | PreloadGameObject | label of that entry |
iconDir | none (required to wire an icon) | where the icon PNG + .meta go |
iconPrefix | none (required) | element icon key = iconPrefix + element, e.g. ic_<game>_elem_ |
elements | [] | element names the game’s Blender script can draw |
render | none (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).
Decision table
Section titled “Decision table”| Situation | Command kind | Template |
|---|---|---|
| Booster unlocked during gameplay (button on the gameplay HUD) | booster | FTUE_Booster_Name.asset: popup, currency grant, flying icon, tooltip, focus click |
Booster unlocked on the pre-play screen (trigger BeforePlayPopupPresenter) | prebooster | FTUE_PreBooster_Name.asset |
| New element (nut/bolt mechanic) introduced on the board | element | FTUE_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)”- 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)). new_ftue.py <kind> --name .. --level .. --description .. --icon .. --out <FTUE dir> [--dry-run]writesFTUE_<Kind>_<Name>.asset+.meta.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 theelementsthe game lists in its settings file and runs the game’s own Blender script.register_ftue.py <asset> [--config ..]appends the guid tosequences:(idempotent, byte-preserving).sync_localization.py [--scan] [--no-translate]runs FTUE Localization Sync headless (localization (references/localization.md)).check_ftue.py <FTUE dir> --boosters FTUE_Hint,FTUE_Undo [--config ..](verification (references/verification.md)).- See the popup on screen before calling it done (verification layer 3).
Generator flags
Section titled “Generator flags”new_ftue.py booster|prebooster|element --name <Id> --level <N> --description <text> --icon <address> [--out <dir>]
| Flag | Default | Notes |
|---|---|---|
--skin-type sprite|gif | sprite | gif requires --skin |
--skin | = --icon | popup art address (elements: always = icon) |
--title | = --name | popup title and itemName |
--currency-id, --amount, --ui-element | Name, 1, BoosterButton_<Name> (prebooster: <Name>) | booster/prebooster only |
--seed N | random | same seed gives byte-identical output |
--dry-run | off | print 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.
Other scripts
Section titled “Other scripts”| Script | Exit 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 | —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.
Boundaries
Section titled “Boundaries”- Writes: the asset + meta into
--out; the icon + meta intoiconDir; one line into the settings’ Addressablesgroupand one intoFTUEConfig.asset; the Game localization table through Unity. No C# edits beyondAssets/Scripts/Editor/FtueTools/. - Icon rendering only: Blender (flatpak
org.blender.Blenderworks), 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; uset1k-unity-sexygame-template-setupreferences/ftue.md.