Totk Texture Pipeline

TOTK Texture Pipeline

Use this skill for TOTK texture work in general. It is the texture counterpart to the model skills.

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.

Use totk-icon-pipeline as the specialized workflow when the target is specifically an inventory/UI actor icon under:

romfs/UI/Tex/Icon/<Actor>.bntx.zs

Texture Workflow

1. Identify the target surface: raw image, DDS, BNTX/TXTG container, compressed .zs, SARC member, model material reference, or UI icon.
2. Inspect an existing working game file before writing. Match the target container's dimensions, format, mip count, texture count, names, and compression route unless there is a tested reason to change them.
3. Keep image conversion separate from container packaging. DDS/ASTC success does not prove BNTX/TXTG packaging success.
4. For BNTX DDS replacement, prefer the proven Switch Toolbox plugin route in references/bntx-dds-switch-toolbox.md.
5. For UI layout archive glyphs or masks referenced by BFLYT/BFLAN, read references/ui-layout-bntx-glyph-extraction.md before assuming the artwork is embedded in the layout file.
6. Validate by reopening the saved container and by round-tripping any final .zs compression.
7. For in-game failures, inspect the final installed or merged output, not only the source overlay folder.

Proven BNTX Lessons

The in-game validated path from the icon work was:

• Convert source image to DDS.
• Clone a known-working BNTX container.
• Replace the texture through Switch Toolbox's FirstPlugin.BNTX / TextureData.Replace(<dds>) path.
• Rename the BNTX container and texture to the expected runtime name.
• Save raw BNTX.
• Compress with zs.zsdic to .bntx.zs.
• Decompress and byte-compare against the raw BNTX.
• Test in game.

Important edge cases:

• Lower-level Syroot.NintenTools.NSW.Bntx.Texture.Import() expects an internal BNTX texture block, not a DDS.
• Headless Switch Toolbox can throw a GUI null reference after TextureData.Replace(). Treat it as non-fatal only when metadata proves the DDS replacement landed and the saved BNTX validates.
• Do not assume the template dimensions or format match the replacement. The template can be only a container shell; the post-replacement BNTX metadata is the proof.
• BFLYT/BFLAN files are layout/animation files. Use their strings to identify panes, materials, texture names, and font references, then inspect the referenced atlas or font container. Do not assume pixel artwork lives directly in BFLYT.
• Some TOTK UI glyphs are one-channel masks in combined layout BNTX atlases, not RGBA images. When a texture record uses 0x1D01, expect a BC4-like alpha mask stored in Nintendo Switch block-linear order; deswizzle and decode it before writing PNG.

Boundaries

• Inventory icon metadata proven in game: 480x480, ASTC_4x4_SRGB, 9 mips. Do not blindly apply those values to model/material textures.
• For non-icon BNTX/TXTG work, inspect a vanilla or known-good target from the same texture family and preserve its structure unless deliberately testing a change.
• Treat TKVSC-derived texture handling as useful for read-only inspection and file-type lessons, not as a proven writer unless the specific target has round-trip and in-game evidence.

Cross-Skill Use

• totk-icon-pipeline: icon-cache capture, review pages, actor icon overlays, and UI icon packaging.
• totk-toolkit: ZsDic, SARC, Switch Toolbox discovery, and general file plumbing.
• totk-bfres-model: BFRES model/material context when texture names or material bindings are tied to model files.
• totk-local-operator: compact inventories and final-output checks.