# Totk Texture Pipeline

> Work with Tears of the Kingdom texture files and texture containers, including BNTX, TXTG, DDS, ASTC formats, Switch Toolbox texture replacement, ZsDic .zs packaging, UI and inventory icons, actor icon textures, material texture investigation, and texture validation. Use when a user asks about TOTK texture work, replacing textures, converting PNG or DDS files, editing BNTX or TXTG, packaging .bntx.zs files, or debugging texture output in game.

- Skill: `cargocult-mods/totk-texture-pipeline` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add cargocult-mods/totk-texture-pipeline`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cargocult-mods/totk-texture-pipeline/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: cargocult-mods (https://skillmd.com/u/cargocult-mods)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/cargocult-mods/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:

```text
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.