Totk Icon Pipeline

TOTK Icon Pipeline

Use this skill for TOTK icon work, especially inventory/pouch icons for generated actors.

For broader texture work such as non-icon BNTX/TXTG containers, material textures, DDS/ASTC packaging, or texture validation outside UI/Tex/Icon, use totk-texture-pipeline first and return here only for icon-specific capture/review behavior.

If a task is about UI layout glyphs, menu/category symbols, Adventure Log quest category marks, BFLYT/BFLAN texture references, or combined layout atlases such as timg/__Combined.bntx, use totk-texture-pipeline instead of this inventory-icon workflow.

Common targets:

• romfs/UI/Tex/Icon/<Actor>.bntx.zs
• BNTX container name <Actor>
• BNTX texture name <Actor>

Actor and pouch rows normally do not need an explicit icon path. The game resolves inventory icon files by actor id and the UI/Tex/Icon filename stem.

Vanilla RomFS Rule

Use a vanilla TOTK romfs path already supplied in the current turn or registered project guidance. Otherwise ask the user for it before inspecting game files. Treat the path as read-only; do not search unrelated folders or guess a location.

Workflow

1. Confirm the working folder, target actor list, source image folder, ZsDic.pack.zs, Switch Toolbox folder, and an existing working icon template if packaging BNTX.
2. Keep the user-facing output obvious. Put final files in a folder named like Ready To Install, put raw/intermediate files in Archive or a working folder, and write a short README beside the output.
3. If capturing icons from the emulator icon cache, take a before snapshot, collect only new icons, dedupe cloned save-slot copies, then review by actor name and human UI name before DDS conversion.
4. Convert accepted PNGs to DDS with the intended game texture format. For validated inventory icons, 480x480, ASTC_4x4_SRGB, 9 mips worked in game.
5. Package icons by cloning a known-good BNTX icon, replacing its texture with the DDS, renaming the BNTX container and texture to the actor, then compressing to .bntx.zs.
6. Build a small smoke overlay first, then the full overlay after validation passes.
7. Ask the user to test one to three representative icons in game before treating a large batch as complete.

Proven BNTX Route

Read references/bntx-icon-packaging.md before writing or debugging .bntx.zs icon files.

Use scripts/build_icon_bntx_overlay.py for the repeatable path when Python dependencies are available:

python scripts/build_icon_bntx_overlay.py --tasks-json <tasks.json> --dds-dir <dds-folder> --template-bntx-zs <working-icon.bntx.zs> --zsdic-pack <ZsDic.pack.zs> --toolbox-dir <Switch-Toolbox-folder> --output-dir <Ready-To-Install-folder>

Use scripts/replace_bntx_textures_with_toolbox.ps1 directly only when a task-local Python wrapper already handles .zs decompression/compression and reporting.

Capture And Review

Read references/capture-review-pipeline.md when generating icons through an in-game/emulator icon-cache capture loop.

Important capture lessons:

• Assign captured icons to actors by batch order only after deduping save-slot clones.
• Show both human-readable UI names and actor names in review pages.
• Preserve visible meaning for pristine/special UI markers in checklists and reports.
• If a fuse proxy item appears in the rendered icon, patch the existing spawnable proxy actor or overlay used by the capture tool. Do not invent a new proxy actor unless the user has a way to spawn it.

Validation

For every packaged icon:

• Reopen the saved raw BNTX and verify texture name, size, mip count, and format.
• Verify the raw BNTX no longer contains the template actor name.
• Compress with zs.zsdic, then decompress and byte-compare against the raw BNTX.
• Count output .bntx.zs files and compare against the target actor count.
• Keep a CSV or JSON report with actor, UI name, format, dimensions, mips, output path, and warnings.

Cross-Skill Use

• Use totk-toolkit for shared ZsDic, SARC, Switch Toolbox discovery, and general file plumbing.
• Use totk-texture-pipeline for general BNTX/TXTG, DDS/ASTC, and non-icon texture work.
• Use totk-local-operator for compact folder inventories and validation summaries.