Totk Local Operator

TOTK Local Operator

Use this skill as the entry point for local Tears of the Kingdom modding work. Prefer local scripts for bulk file operations and show Codex only compact summaries, targeted records, diffs, and validation logs.

Related TOTK Skills

• Use totk-actor-cloner for actor pack cloning, ZsDic dictionary use, AISchedule talk wiring, RSDB chunks, and Mals/MSBT actor labels.
• Use totk-eventflow-editor for .bfevfl.zs flowchart edits, EventSetting/GameAnalyzedEventInfo wiring, AISchedule talk/near event chains, actor action/query selection, and Mals/MSBT dialogue branch validation.
• Use totk-msbt-mals-editor for Mals locale archive edits, MSBT labels/text, control tags, line wrapping, and EventTalk blank-slot padding.
• Use totk-bfres-model for low-level BFRES/MCPK model inspection, internal renaming, skeleton/vertex edits, and compression.
• Use totk-as-xlink for ASB command surfaces, AnimationEvent BAEV timing, and ELink/SLink/XLink effect or sound routing.
• Use totk-toolkit's TKVSC-derived experimental helpers for read-only archive/member indexing, canonical-path discovery, broader filetype classification, and Tag.Product actor-to-tags inspection. Keep proven writers as fallbacks.

Token Policy

• Do not print entire decoded GameData, Mals, BYML/BGYML, RSDB, or actor pack contents into context.
• Use local commands to inventory, search, extract, diff, and validate.
• For binary writer output, especially AINB string-pool files, include a compact drift check for untouched localized strings and selector-default sentinel labels. Do not accept "reparsed successfully" as sufficient proof when a writer round-tripped the whole file; compare a second parser/export or raw string-field scan against vanilla/source for unrelated string changes.
• For actor-pack modifications, validation must prove the edited internal file is reachable from the actor's live ActorParam, not merely present in the SARC. Resolve component refs through the actor parent chain before declaring a leaf actor missing a component. For Phive controllers, follow every reachable controller $parent; parent shape/external-shape/rigid-body arrays can remain live. For any BYML/BGYML with $parent, recursively back-trace parents until no parent remains and reason about the final composed file: child files overwrite or add properties, while inherited parent properties can still drive behavior. Use totk-toolkit/scripts/totk_actor_tools.py trace-actor-links --expect-reachable for edited behavior files. Do not add a new parent to a custom actor as a shortcut; if a parent relationship is required, clone an existing actor child that already uses that parent and then edit the clone.
• For per-actor actor-pack edits, custom files must use actor-specific internal filenames. Do not modify generic/shared canonical member paths in place unless the intended behavior is global and all redundant same-path copies are being managed.
• For collision work, validate both pointer reachability and generated shape extents. A correctly reached ShapeParam can still be wrong if an automatic AABB/polytope generator included stale rigid vertices, hidden cut-side clusters, or flexible tassel/cloth mesh. If a dimension-tuning edit does not change the in-game result, build an extreme collision canary before continuing; a giant canary is the clearest proof that the game is or is not using the edited shapes. If a parent controller mentions a shape whose template file is absent from the pack, skip it unless another reachable local template exists.
• Ask for targeted records by actor name, quest name, flag name, path, or JSON path.
• 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.
• Preserve large intermediate files on disk and report their paths.
• Prefer dry-run or preview operations before writing mod outputs.

Toolkit Location

Run helper commands from this skill folder:

.\totk-tools.cmd --help

The .cmd wrapper prefers a nearby workspace embedded Python at ..\python-embed\python.exe, then checks %USERPROFILE%\Documents\New project\python-embed\python.exe, and falls back to python if needed. Direct invocation also works:

..\python-embed\python.exe .\scripts\totk_local_tools.py --help

First Operations

If a task needs vanilla game files, use a path already supplied in the current turn or registered project guidance. Otherwise ask for the path before inspection. Treat it as read-only and do not probe unrelated directories.

For whole-mod inspection or patch planning, use totk-toolkit/references/tkmm-merge-awareness.md when merge/install workflow matters. Do not produce routine file-by-file compatibility reports. Instead, flag only likely risks such as changed shared non-model files that TKMM probably cannot merge, whole copied shared tables/archives with unrelated edits, or unconfirmed paths intended to supersede another mod. When a no-spawn or failed in-game test happens under TKMM or another merge workflow, the final merged output is the diagnostic source of truth. If the user has not provided that folder, stop and ask for the final merged output folder path or explicit permission to continue without it before inspecting source overlays, proposing fixes, or building tests.

When inspecting, debugging, or building fused-equipment names through AttachedEquipmentNamingRuleTable, Bootup naming rows, Mals StaticMsg/AttachedEquipmentNamingRule.msbt, or subtype marker fingerprints, read totk-toolkit/references/attached-equipment-fuse-naming.md before writing or proposing tests.

When a task asks "where is this file used?" or "find all copies of this internal archive member", use the toolkit's TKVSC-derived canonical/archive indexer first for discovery. Treat its output as experimental until cross-checked with targeted actor/table scripts before writing patches.

Use these commands before reading large files:

.\totk-tools.cmd inventory <project-root> --hash
.\totk-tools.cmd identify-file <path>
.\totk-tools.cmd search-records <decoded-root> Ganondorf_Mummy --ignore-case

When building direct overlay outputs from a vanilla romfs, detect product suffixes from the romfs instead of copying examples from another project. RSDB files may use a different Product.<n> suffix from Mals locale archives in the same game dump.

When inspecting, designing, or editing NPC daily/social actions through Component/AIScheduleParam and Banc anchors, read references/npc-aischedule-banc-actions.md before proposing schedule structure, action-slot changes, rain behavior, or anchor edits.

When a user gives a plain-English place, landmark, town, stable, cave, or region name, resolve the game-facing internal reference before choosing Banc files. Start by searching Mals text, especially LocationMsg/Location.msbt, for the visible name. Then search parsed Banc records for the resolved label or internal token, commonly in Dynamic.Location on LocationArea actors or related volumes. Use the owning Banc tile from that hit as the placement/search context, and only then choose the matching Dynamic or Static file for new actors. Do not guess map-cell names from coordinates or memory when Mals/Banc lookup is available.

Banc Translate coordinates use X for east-west, Y for altitude/elevation, and Z for north-south. Compass-language offsets must not be applied to Y; use X for east/west, Z for north/south, and reserve Y for height. Before changing placement coordinates, scan nearby vanilla or merged-output actors in the same Banc tile and compare their Translate values so the row stays on the intended surface instead of underground or floating.

For before/after comparisons:

.\totk-tools.cmd compare-inventory old.json new.json --ignore-mtime
.\totk-tools.cmd diff-json old.json new.json --json-path some.path

Compact Overlay Validation

For generated NPC, EventFlow, Mals, RSDB, actor-pack, and Banc overlays, validate by reopening the compressed outputs rather than trusting that writes completed:

• Actor pack: decompress with pack.zsdic, open SARC, confirm Actor/<NewActor>.engine__actor__ActorParam.bgyml exists and key component refs point to the generated resources.
• No-spawn merged-output hard gate: when an in-game test reports that an actor did not spawn under TKMM, another mod manager, or an overlay workflow, do not infer from source mod folders, overlay deltas, base mods, archived builds, or build notes. Do not build a registration/placement package or propose actor-pack, RSDB, Banc, placement, or ResourceSizeTable fixes yet. First inspect the final merged output folder: the files the game will actually load. 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. Until one is provided, only explain why the gate is required. Do not bypass this gate because a source-side mistake seems obvious; confirm whether the launched merged output contains that mistake before making the next build.
• Overlay deltas: files absent from an overlay may be intentionally supplied by the base mod. Source folders are not substitutes for the final merged output. Treat missing ActorInfo, Banc, ResourceSizeTable, Mals, GameData, or other shared files in the overlay as normal until the merged output proves they are missing, stale, or mismatched.
• Actor pack reachability: do not treat an internal file as live just because it exists in the pack. Start from the live ActorParam.Components pointer, follow each referenced component, then follow nested component refs such as LifeRef -> LifeParam.DamageParameters, PhysicsRef -> ControllerSetPath, and WeakPointUserRef -> WeakPointActorArray. If a customized file is not reached by that chain, it is dead data.
• Parent composition: for any reached file with $parent, resolve parents recursively and inspect the final effective property set before blaming the child file or declaring the edit ineffective.
• Actor pack cleanup: current clone/patch workflows may leave excess dormant members in a pack. Do not treat this as a failure by itself, and do not delete unreferenced-looking members opportunistically. Cleanup needs a separately tested routine with parent-chain awareness, live-ref tracing, merged-output checks, and spawn/gameplay validation.
• Actor identity: decompress the generated ActorInfo row and confirm both __RowId and ActorName are correct for <NewActor> unless deliberately cloning a vanilla alias pattern. Also confirm key model fields such as ModelProjectName and FmdbName still match the chosen source actor.
• AISchedule: parse the standalone .bgyml and confirm the selected OnPlayerTalk EventName points to the expected EventSetting row. For NPC action schedules, cross-check ActionType, AnchorInstanceName, linked AnchorAction*, AnchorSleep, AnchorWander*, _Rain anchors, and Rainy* settings.
• RSDB: decompress with zs.zsdic, parse each patched table, and confirm exactly the intended __RowId rows and key fields such as FlowchartFileName.
• EventFlow: decompress .bfevfl.zs, reparse, and confirm the entry point or inserted event references each expected MessageId.
• Mals: decompress the locale SARC and confirm the target MSBT contains each new label plus the UTF-16LE text. For EventTalk dialogue, also validate raw three-line bubble padding: one visible line should have two LF blank slots, and two visible lines should have one LF blank slot.
• Banc: decompress with bcett.byml.zsdic, parse, and confirm one intended actor placement with expected Gyaml, hash, coordinates, and rotation. Interpret Translate as X east-west, Y altitude, Z north-south, and validate Y against nearby surface actors rather than compass directions. For placement at a named location, also record the Mals label/internal token used to identify the location and the Banc actor or volume that proves the target tile. Validating only that a new row exists in a guessed Banc file is insufficient.
• Build notes: every generated testable mod or overlay must include a top-level file beside romfs named exactly Build Notes - <mod folder name>.txt. Start with a header block: mod folder name, build type (standalone or overlay), intended overlay target/base mod, build date, and one-sentence goal. Then add bug-hunting notes: source baseline or known-good reference, merge assumptions, merged-output path/status when relevant, unresolved risks, and recommended next checks. Do not list included files as a manifest.

Keep validation output compact: row IDs, file names relative to the overlay, event names, message IDs, coordinates, and counts are enough. When handing back a testable mod or overlay, finish with a pasteable plain-text test card and keep Expected lines short.

Weakpoint and damage-routing checks:

• For weakpoint actors, verify the body actor reaches the weakpoint through WeakPointUserRef, then verify the weakpoint actor reaches its intended damage table through ActorParam.Components.LifeRef -> Component/LifeParam/... -> DamageParameters.
• For weakpoint actors that are separate spawned actors, validate the child actor's ActorInfo row in the final merged output when debugging no-spawn. In an overlay workflow, do not require the overlay delta itself to include that row if the intended base supplies it.
• If the body actor also has a weakpoint-user blackboard table, compare it against WeakPointUserParam and verify the field that actually controls spawning/attachment in the final merged output.
• If damage edits appear to have no gameplay effect, first check for a stale or missing DamageParameters pointer before tuning more damage-rate fields.
• For elemental fused-arrow issues, do not stop at Bomb and Shockwave. Explosion or elemental damage can arrive through Fire, Ice, Electric, Water, Body, Impulse, Undefined, chemical contact, entity material damage, or burn/ignition internals depending on the actor.
• For direct-hit-only weakpoints, combine damage-table filtering with SensorHitParam filtering when available. Zero AoE/elemental rates and disable chemical/entity material damage, but preserve explicitly desired direct routes such as arrows, melee, or beams.
• When shrinking Phive weakpoint shapes, check both the explicit shape primitive and any derived/broadphase metadata such as AutoCalc bounds. A tiny capsule with unchanged large bounds may still be generous for AoE or broadphase hit collection.

Current Capabilities

• inventory: create a compact manifest of files, sizes, timestamps, guessed types, and optional hashes.
• compare-inventory: compare two inventory JSON files and report added, removed, and changed files.
• identify-file: classify a path and recommend the next local operation.
• search-records: search decoded/plain text folders with compact match output.
• show-json: print a whole JSON file or one dot-path inside it.
• diff-json: produce stable sorted-key JSON diffs.
• Local project scripts may also be used for direct RSDB Tag edits and GameData copy/patch preparation when they preserve BYML scalar types and emit compact validation summaries. Prefer this over asking the user to paste Tag rows manually.
• File identification now knows TKVSC-derived surfaces such as .genvb, .blarc, .bfarc, .bntx, .txtg, .belnk, .bslnk, .asb, .baev, .tkproj, .tkvsc, .pchtxt, and common AAMP-like parameter extensions. This is classification only, not write approval.

Tag And GameData Operations

For structurally complex Tag and GameData work:

• Prefer direct local editing of RSDB/Tag.Product.*.rstbl.byml.zs when the available script can decode, patch, re-encode, and validate without dumping the whole table into context.
• Use totk_table_inspect.py show-tag-actor-tags for read-only TKVSC-derived Tag.Product actor-to-tags checks. It can help decide which source actor row to copy, but it does not replace the proven hilt Tag writer.
• Validate Tag changes with compact counts and expected row names only.
• Do not use a generic RSDB/BYML writer on Tag unless it explicitly preserves binary BitTable and RankTable payloads and pads binary BYML nodes back to 4-byte boundaries. Tag is not a bare row array; it contains PathList, TagList, and binary bit/rank tables.
• Proven fallback: if a known-good local compressed Tag file already has exactly the desired paths, copy that whole .rstbl.byml.zs file into the target mod and validate it against vanilla. This is safer than reconstructing the binary tables by hand.
• Minimum Tag validation after copy or generation: output decompresses/reopens; added PathList entries are exactly expected; no unintended removals; TagList count is unchanged unless using a true Tag-aware writer that intentionally adds tags; string indexes are in range after binary-node padding.
• If no Tag-aware writer and no matching known-good whole-file candidate exists, produce an _INPUTREQUIRED_... helper file rather than writing an unsafe Tag file.
• For GameDataList.Product.*.byml.zs, patch known-item/material rows only when the actor genuinely needs those registries. Use scalar-preserving tools, or copy the vanilla file into the output mod as a ready-to-patch baseline and emit the exact actor names/preimages/hashes needed by the user/tool.
• For GameData hash-preimage or hidden-registry research, use totk-toolkit/references/gamedata-hash-preimages.md when the user provides hash reference files. Merge typed CSV and JSON hash maps by hash/preimage, search exact candidate tokens in the references and in decompressed GameDataList, and report compact negative evidence instead of dumping GameData.
• For loose-world ??? prompts on fused equipment, inspect actor IDs and known-item state instead of assuming a missing text label. Pouch.*.Content.Name stores the base actor and Pouch.*.Content.Combined.Name stores the attachment actor, not a resolved UI string. Compare the attachment actor against vanilla examples under IsGet, IsGetAnyway, MaterialShortCutCounter, and PictureBookData; non-collectible fusable actors should generally be absent from those registries unless gameplay will set them.
• Never paste full decoded Tag or GameData tables into the conversation.

Planned Capabilities

Add these as project knowledge becomes available:

• decode-one and encode-one wrappers for the chosen TOTK tools.
• roundtrip-check for decode/re-encode safety.
• show-record for BYML/BGYML, RSDB, GameData, and Mals records.
• xref for actor, quest, item, flag, and localization references.
• preview-patch, clone-actor, validate-actor.
• create-quest-template, patch-gamedata, validate-quest.

References

• Read references/tool-design.md for the design rules behind the local tools.
• Read references/totk-knowledge-template.md when collecting project-specific modding knowledge.
• Use recipes/clone-actor.recipe.json as the first workflow recipe shape.