Totk Toolkit

TOTK Toolkit

Use this skill when a TOTK task needs common file mechanics rather than task-specific design decisions. Prefer these bundled scripts before creating task-local one-off tools.

For general texture work, BNTX/TXTG containers, DDS/ASTC packaging, or texture validation, use totk-texture-pipeline. For inventory/UI icon capture and actor icon overlays, use totk-icon-pipeline. Use this toolkit for shared ZsDic, SARC, and Switch Toolbox discovery habits.

Available Scripts

• scripts/totk_local_tools.py: compact local inspection and validation for large TOTK files without loading decoded content into context.
• scripts/totk_actor_tools.py: actor-pack inspection, ZsDic/dictionary handling, SARC listing, component display, parent-chain resolution, and weapon stat summaries.
• scripts/totk_table_inspect.py: compact read-only RSDB row, Tag path, Tag actor-to-tags, and Mals/MSBT label inspectors. Its Mals output decodes known MSBT tags such as pristine sparkle and color wrappers into readable markup so tagged weapon abilities are not mistaken for corrupt text. show-tag-actor-tags is TKVSC-derived and experimental-read-only.
• scripts/tkvsc_experimental_archive_index.py: experimental read-only archive and canonical-path indexer inspired by TKVSC. Use it first for discovery tasks such as "find archive members across RomFS" or "which archives contain this canonical internal path"; keep proven targeted writers for patching.
• scripts/compare_mod_to_vanilla.py: compact file-level diff for key mod romfs areas against vanilla.
• scripts/toolbox_decompress_bfres_mc.ps1: decompress vanilla .bfres.mc through Switch Toolbox MeshCodec into an expanded editable .bfres.
• scripts/toolbox_resave_bfres.ps1: normalize an edited raw BFRES through Switch Toolbox save logic.
• scripts/toolbox_recenter_bfres_render_bounds.ps1: post-geometry-edit helper used by model pipelines to recenter serialized FSHP render boxes/spheres on the edited vertex bounds before .bfres.mc compression. This is part of the model edit path, not a separate test workflow.
• scripts/toolbox_compress_bfres_mc.ps1: compress normalized raw BFRES back to game-ready .bfres.mc through Switch Toolbox MeshCodec.
• scripts/inspect_toolbox_bfres_object.ps1: read a BFRES through the same Toolbox object model and print compact model, shape, vertex-count, and bounds summaries.
• scripts/find_switch_toolbox.ps1: search likely local folders for a Switch Toolbox directory and validate candidates by checking for Toolbox.Library.dll, Lib, and Lib/Plugins.
• totk-icon-pipeline/scripts/build_icon_bntx_overlay.py: specialized icon-packaging script in the icon skill. Use it for romfs/UI/Tex/Icon/<Actor>.bntx.zs overlays rather than adding icon-specific writers to this shared toolkit.
• scripts/find_node_runtime.ps1: find a working Node.js runtime by executing node --version; excludes old test-artifact folders unless explicitly allowed.
• scripts/ensure_node_runtime.ps1: Codex-managed Node.js runtime path. Searches first; can expand a user/local Node zip; with approval, can download the latest LTS portable Windows zip into the working folder.
• scripts/ensure_unsafe_compat.ps1: Codex-managed System.Runtime.CompilerServices.Unsafe.dll compatibility helper. Extracts or downloads the NuGet package version that contains assembly version 4.0.4.1, then prints the path to pass as -UnsafeCompatPath.
• scripts/diagnose_toolbox_meshcodec.ps1: checks Switch Toolbox, ZstdSharp.dll, FirstPlugin.Plg.dll, Unsafe candidates, and whether FirstPlugin.MeshCodec/ZstdSharp.Unsafe.Methods load cleanly.

TKVSC-Derived Experimental Layer

TKVSC (TKVSC-Team/totk-vscode) has useful beta-era readers, indexers, and filetype lessons. Read references/tkvsc-derived-tooling.md when a task touches archive/canonical search, AAMP-like files, ASB/BAEV, XLink, BNTX/TXTG textures, or Tag.Product formatting.

Use this staged policy:

• For low-risk reads, discovery, indexing, file classification, and round-trip checks, try the TKVSC-derived helper first and record whether it helped.
• If a proven toolkit workflow already writes working game files, the TKVSC-derived path is not a replacement yet. Treat it as experimental, read-only, or roundtrip-test-only until enough evidence promotes it.
• Fall back immediately to the proven script when the experimental helper fails, loses BYML/MSBT scalar/tag information, cannot resolve vendor dependencies, produces suspicious archive counts, or touches BFRES/MCPK model outputs.
• Do not delete or rewrite the proven workflow just because a TKVSC-derived script looks cleaner. Promotion requires repeated reparse/round-trip validation and at least one real mod workflow behaving correctly.

Usage Rules

• Do not rebuild these mechanics in a fresh chat unless a bundled script is missing a specific capability.
• If a specialized skill also bundles a copy of a script, prefer this shared toolkit copy unless the specialized copy has a task-specific patch.
• For AINB or other string-pool binary writes, a successful reparse is not enough validation. Some writers can silently rewrite unmodelled selector-default sentinel fields. After writing, cross-check untouched localized strings, default selector labels, and raw/string-dump output against vanilla or the source file; fail the build or patch the writer when unrelated string-pool fields drift.
• For actor event-root AINB command injection, patch the AINB named by the runtime actor's EventPerformerParam.EventUniqueAin, not merely an EVFL placeholder actor name. See totk-eventflow-editor/references/research-findings.md before writing or validating these overlays.
• Before using toolkit commands to inspect vanilla game content, use a romfs path already supplied in the current turn or registered project guidance. Otherwise ask for it. Treat the path as read-only; do not probe unrelated directories.
• For archive and canonical-path discovery, prefer the experimental TKVSC-derived indexer first, then cross-check with targeted actor/table scripts before making patches.
• For actor-pack writes, internal member paths can behave as canonical identities across redundant copies. Per-actor custom edits should clone generic/shared members to actor-specific internal filenames and repoint the actor/component/controller references to the unique paths; do not customize shared names in place unless the change is intentionally global and the user has confirmed that intent. Generic same-path files can be loaded from another actor pack before the game consults the current actor's redundant copy.
• Current actor-pack writers and clone helpers may leave excess dormant members in output packs. This is usually preferable to unsafe pruning: unused members are generally harmless when live refs point to the intended files. Do not delete unreferenced-looking actor-pack members as a cleanup shortcut. A cleanup routine must be designed and validated separately with parent-chain awareness, live-ref tracing, merged-output checks, and spawn/gameplay tests, because deleting too much can cause no-spawn or subtle behavior loss.
• For whole-mod work, read references/tkmm-merge-awareness.md when the user's installation/merge workflow affects file choices. Do not assume TKMM, but when the user uses TKMM or is unsure, prefer vanilla-derived minimal edits and flag only likely shared non-model files that TKMM may not know how to merge. For no-spawn or failed in-game tests under a merge workflow, the final merged output is the diagnostic source of truth. If the user has not provided that folder, ask for the final merged output folder path or explicit permission to continue without it, then stop before proposing fixes or building tests.
• For failed custom actor spawns under a mod manager or overlay workflow, this is a hard gate: inspect the final merged output first and verify it contains the actor pack, matching RSDB/ActorInfo.Product.* rows for the actor and spawned child actors, and a Banc/Event/AI spawn source that references the actor. Do not infer a defect from source mod folders, overlay deltas, base mods, archived builds, or build notes. If the user has not provided the merged output folder, ask for its path or for explicit permission to continue without it, then stop. Do not build registration/placement/ResourceSizeTable test packages before this gate is satisfied.
• For generated testable mods and overlays, create a top-level build notes file beside romfs named exactly Build Notes - <mod folder name>.txt. Include a header with build type (standalone or overlay), intended overlay target/base mod, build date, and goal. Record bug-hunting notes such as source baseline, merge assumptions, merged-output status, unresolved risks, and recommended next checks; do not list files as a manifest.
• For inventory icon overlays, prefer totk-icon-pipeline. The proven BNTX convention is romfs/UI/Tex/Icon/<Actor>.bntx.zs with internal BNTX and texture names set to <Actor>. Validate by reopening the raw BNTX and round-tripping the final .bntx.zs through zs.zsdic.
• For fused-equipment naming rules, AttachedEquipmentNamingRuleTable, naming-rule Bootup edits, or subtype fingerprints used as naming conditions, read references/attached-equipment-fuse-naming.md. Do not assume arbitrary custom subtype strings can match naming rules.
• Keep machine-specific paths in user-provided config or command arguments only.
• Keep task-specific scripts in the task-local working folder, not inside this toolkit.
• For any task that needs BFRES MeshCodec decompression, resave, or compression, ask for switchToolboxDir during preflight. Explain that Codex can search common local locations if the user does not know the path, but an explicit path is preferred and more reliable.
• For any task that runs bundled JavaScript tools, Codex is responsible for ensuring a working Node.js runtime. Do not expect the user to know what Node is or provide a path. First run scripts/ensure_node_runtime.ps1 -InstallDir <working>/Node. If it reports no runtime, ask permission to rerun it with -AllowDownload so it can download the latest LTS portable Node.js zip into the working folder. Pass the resulting executable to preflight with --node-path. Do not use Node binaries from old test/build folders unless the user explicitly permits that fallback.
• For any actor-pack behavior edit, validate reachability from Actor/<actor>.engine__actor__ActorParam.bgyml before treating the edit as live. Resolve component refs through the actor parent chain before concluding a leaf actor is missing a ref. For physics edits, trace ActorParam.Components.PhysicsRef -> Component/Physics/...ControllerSetPath, then follow the controller and every reachable controller $parent through shape, external-shape, rigid-body, and controller/sensor arrays. Parent controllers can contribute live shapes even when the child controller overrides some direct shapes. More generally, for any file with $parent, back-trace recursively until there are no more parents and inspect the final composed file because child files overwrite or add properties while parent properties remain live. Use scripts/totk_actor_tools.py trace-actor-links --expect-reachable <internal-file> and treat a missing expected path as a build failure.
• For Phive collision edits, reachability is necessary but not sufficient. Also validate generated shape bounds against model vertex distribution and in-game test intent. Mesh-derived AABBs can include stale rigid vertices, hidden clusters, or flexible cosmetic meshes; if capped bounds still do not change in game, make an extreme canary collision overlay before more tuning. Prefer a giant canary when the goal is to prove whether the game is using the edited shapes at all. If a parent controller names a shape whose template file is absent from the actor pack, skip that shape unless another reachable local template exists; do not invent a placeholder that no live controller can reach.
• Do not treat IsGet, IsGetAnyway, MaterialShortCutCounter, or PictureBookData as generic flags for every fusable actor. They are known-item/collection registries. Non-collectible fuse materials can display names without them, and adding them to actors that gameplay never marks known can make loose-world fused-equipment prompts resolve as ???.
• For GameData hash or registry research, read references/gamedata-hash-preimages.md when the user supplies reverse-engineered hash-preimage files. Use those references to label GameData hashes and enum domains before guessing; keep the supplied file paths task-local.
• After any model pipeline step that changes vertex positions or live shape selection, serialized BFRES FSHP render boxes/spheres must be recentered and then validated by reopening the saved raw BFRES or final MeshCodec-decompressed .bfres.mc. Stale render bounds can cause correct geometry to cull or disappear even when ActorInfo and vertices are correct.
• Raw MCPK/ZSTD unwrapping is inspection-only for model geometry tasks; it is not a replacement for MeshCodec decompression when vertex buffers are needed.
• Final model validation must compare the selected source shape's declared _p0 positions to the post-Toolbox normalized BFRES, or to a MeshCodec-decompressed final .bfres.mc roundtrip when available. Reject plausible vertex counts with collapsed or drifted position bounds.
• Model pipeline scripts must stop when the parsed source _p0 stream is collapsed/all-zero or when a final expanded BFRES has no finite, non-collapsed position candidate. Those states can still produce plausible counts and tool-readable files, but they render as invisible geometry.
• Model stream selection must reject placeholder-like _p0 candidates where more than max(8, 5%) of vertices are clustered near 0,0,0, and raw edit validation must reuse the exact selected stream instead of re-running heuristic candidate selection after edits.
• toolbox_decompress_bfres_mc.ps1 is not automatically equivalent to a model viewer's exported/decompressed BFRES in every setup. In the v4 failure, direct FirstPlugin.MeshCodec.DecompressMeshCodec(Stream) produced same-sized BFRES files with zero/placeholder position streams, while the existing models (decompressed) BFRES files had real vertex buffers. If direct decompression yields collapsed positions, switch to known-good expanded BFRES inputs instead of continuing.
• If Switch Toolbox fails because ZstdSharp cannot load System.Runtime.CompilerServices.Unsafe, Version=4.0.4.1, ask for a working Toolbox setup, the exact compatible Unsafe DLL, or already expanded .bfres files. Do not repeatedly try arbitrary newer Unsafe DLLs.

Useful read-only inspector commands:

python scripts/totk_actor_tools.py show-weapon-stats --romfs <vanilla-romfs> --actor Weapon_Sword_125
python scripts/totk_actor_tools.py resolve-parent-chain --romfs <vanilla-romfs> --actor Weapon_Sword_125
python scripts/totk_table_inspect.py show-rsdb-rows --romfs <vanilla-romfs> --table ActorInfo.Product.112.rstbl.byml.zs --ids Weapon_Sword_125
python scripts/totk_table_inspect.py show-tag-paths --romfs <vanilla-romfs> --ids Weapon_Sword_125
python scripts/totk_table_inspect.py show-tag-actor-tags --romfs <vanilla-romfs> --ids Weapon_Sword_125 --include-tags
python scripts/totk_table_inspect.py show-mals-labels --romfs <vanilla-romfs> --labels Weapon_Sword_125_Name
python scripts/tkvsc_experimental_archive_index.py list-archive --romfs <vanilla-romfs> --archive <some.pack.zs> --recursive --contains ActorParam
python scripts/tkvsc_experimental_archive_index.py build-canonical-index --romfs <vanilla-romfs> --output <working>/canonical.sqlite
python scripts/compare_mod_to_vanilla.py --vanilla-romfs <vanilla-romfs> --mod <mod-root-or-romfs>

Specialized Skills

• Use totk-texture-pipeline for BNTX/TXTG, DDS/ASTC, Switch Toolbox texture replacement, and non-icon texture validation.
• Use totk-icon-pipeline for inventory/UI icon capture, review, DDS conversion, and BNTX .bntx.zs overlay packaging.
• Use totk-bfres-model for low-level BFRES/MCPK mechanics and validation.
• Use totk-actor-cloner for actor cloning policy.
• Use totk-local-operator for local inspection habits and compact summaries.
• Use totk-as-xlink for ASB command graphs, BAEV animation events, and ELink/SLink/XLink routing tied to animations.

Read references/runtime-errors.md when Node, Python packages, PowerShell, BYML, or Switch Toolbox dependencies fail.