# Totk Actor Cloner > Generate clean Tears of the Kingdom actor clones from a registered or user-provided read-only vanilla romfs and vanilla actor pack. Use when Codex needs to clone or fork any TOTK actor type, inspect actor pack SARC contents, derive ZsDic.pack.zs dictionaries from a vanilla romfs, infer actor type/category, create or add to an output mod project, optionally edit larger mod files with clean Codex_Working backups, set up AI schedule talk hooks, or produce paste-ready RSDB and Mals/MSBT chunks for ActorInfo, EventSetting, GameActorInfo checks, actor display names, or custom eventflow wiring. Cross-reference totk-toolkit for shared file tools, totk-local-operator for compact local inspection, and totk-bfres-model for model work. - Skill: `cargocult-mods/totk-actor-cloner` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add cargocult-mods/totk-actor-cloner` - Raw SKILL.md: https://api.skillmd.com/api/skills/cargocult-mods/totk-actor-cloner/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: cargocult-mods (https://skillmd.com/u/cargocult-mods) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/cargocult-mods/totk-actor-cloner --- # TOTK Actor Cloner ## 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 this skill to turn a high-level TOTK actor clone request into local output files plus paste-ready chunks for the large shared game tables. Default to asking whether the user wants direct edits to larger mod files now that the workflow is established; still produce a text file with all generated chunks either way. Treat the vanilla romfs as read-only source material. Never edit, overwrite, delete, reformat, or create files inside the vanilla romfs folder. ## Related TOTK Skills - Use `totk-local-operator` first for inventories, targeted searches, compact diffs, and validation of large decoded TOTK files. - Use `totk-msbt-mals-editor` for display names, dialogue text, MSBT control tags, line wrapping, and EventTalk blank-slot padding. ## Required Inputs Ask for these before doing work: - Vanilla `romfs` folder path, unless already supplied in the current conversation or a user-approved local settings file. Derive `Pack/ZsDic.pack.zs` from this folder. This is copyrighted game data; never bundle it in the skill or ask the user to distribute it. - Output folder for this operation. This may be a new folder or an existing mod project. - Intended install/merge workflow when producing direct mod files or touching shared files: TKMM/TKMM-style merge, manual Atmosphere/emulator layering, append into an existing mod, or unknown. Do not assume TKMM. If the user uses TKMM or is unsure, prefer vanilla-derived minimal edits and avoid using an already merged output as the base unless they choose an append-to-existing workflow. - Ask whether to edit/add to larger files directly where appropriate or only generate separate paste-ready chunks. If direct editing is requested, back up existing larger files under the output folder's `Codex_Working/Backups_Pre_/` tree before modifying them. - Vanilla actor pack to fork, e.g. `/Pack/Actor/Npc_Raul_01.pack.zs`. If the user gives only an actor name, look it up under the vanilla romfs. - New actor name, e.g. `Example_Npc_Raul_01`. - Eventflow file name that the talk interaction should call, e.g. `Example_Npc_Raul_01` for `Work/Event/EventFlow/Example_Npc_Raul_01.evfc`. - Actor display name text for Mals, e.g. `Rauru`. - For talk-capable NPCs, ask whether the user wants a perfect clone, a selected schedule branch redirected to a custom eventflow, all matching talk branches redirected, or a newly simplified talk schedule. Do not infer this only from the presence of an eventflow name. - If any EventFlow will be generated, cloned, or edited, ask whether the user wants a stripped/cleaned flow or a vanilla-preserved flow. Recommend stripped/cleaned for simple one-line test NPCs because it keeps editor graphs and validation clear; use vanilla-preserved when the user wants to keep other entry points, branches, diagnostics, or future-edit context. In vanilla-preserved mode, preserve the original `Talk` entry path as `vanillaTalk` before repointing `Talk` to the new requested chain. - For runtime EventFlow debugging variants, do not preserve a full ambitious graph with disconnected late events. Use the `totk-eventflow-editor` Runtime Debugging Procedure: start from the last build that ran, make fresh versioned cropped overlays, keep only the proven entry path and the next small tested surface, add before/after debug `EventTalk` nodes with matching Mals labels, and physically remove everything after the breakpoint. Disconnected late events are not safe evidence because malformed unreachable nodes can still prevent EventFlow load. If the user wants a placed actor, also ask for placement details. If they provide a plain-English location name instead of a precise Banc/map cell, resolve the location through Mals and Banc first rather than asking them to guess the cell. If they only want actor clone assets/snippets, skip Banc edits. ## Actor Name Lookup Rules When the user names an in-game character rather than a precise actor ID, start from Mals instead of visual/file-name guesses: - Search the requested locale, usually `Mals/.Product..sarc.zs`, for the visible display text in `ActorMsg/*.msbt` first. Labels such as `_Name` give the most direct actor-ID candidates. - Then cross-check each candidate in `RSDB/ActorInfo.Product..rstbl.byml.zs`, `RSDB/GameActorInfo.Product..rstbl.byml.zs`, `Pack/Actor/.pack.zs`, and any related `EventFlowMsg/.msbt` files. - If the character has many vanilla variants, compare the candidates and choose deliberately. Prefer a canonical/base actor when the mod only needs the character's model and a simple custom behavior; prefer a location/shop/quest variant only when the requested behavior depends on that variant's schedule, inventory, route, or eventflow. - Do not infer identity from generic clues such as "has a backpack", nearby dialogue topics, or a single component name. UMii/Hylian actors often share broad resources while bespoke NPCs usually have distinctive `ActorInfo` model fields and actor-pack model resources. - Report the chosen base actor and why it was chosen before generating outputs when the lookup was nontrivial. ## Location Name Lookup Rules When the user names an in-game location rather than a precise Banc file, start from Mals instead of map-cell guesses: - Search the requested locale for the visible place name, especially `LocationMsg/Location.msbt`. Labels such as `City_*`, `Cave_*`, `Well_*`, `Stable_*`, or `Tower*` are the internal references the map/UI often uses. - Search parsed Banc records for that internal label, commonly under `Dynamic.Location` on `LocationArea` actors or related area/volume actors. - Treat the Banc file containing that location actor/volume as the authoritative tile for the player-facing location. For new placed actors, usually patch the corresponding Dynamic file in the same tile; use Static only when matching an existing static placement pattern is intentional. - Cross-check by scanning nearby vanilla actors around the requested coordinates inside the resolved tile. This proves both the human-readable location and the coordinate neighborhood agree. - Interpret Banc `Translate` coordinates as `X` east-west, `Y` altitude/elevation, and `Z` north-south. If a user gives compass directions, adjust `X` for east/west and `Z` for north/south; do not use `Y` for north/south movement. Validate `Y` against nearby surface actors so placed NPCs do not end up underground or floating. - Do not choose a Banc tile from coordinate intuition, remembered grid names, or previous tests when Mals/Banc lookup is possible. ## Runtime Prerequisites Before using the TOTK helper tools, verify a working Python 3.11+ runtime is available with these packages: ```powershell python -m pip install zstandard sarc byml PyYAML ``` If Windows only has broken Store aliases for `python`/`py`, use the Python embeddable zip as a local workspace runtime: download an embeddable Python 3.11+ zip from python.org, extract it, change `#import site` to `import site` in `python311._pth`, bootstrap pip with `get-pip.py`, then install `zstandard`, `sarc`, `byml`, and `PyYAML`. This keeps dependencies local and avoids rediscovering the toolchain setup. For JavaScript helpers, verify Node.js is available. ## Local TOTK Tools Do not assume the active workspace has a reusable `tools/` folder. Use bundled skill scripts first, then project-local helpers if they exist, then write a narrow task-local script when needed. Recommended discovery order: 1. `totk-toolkit` TKVSC-derived experimental helpers for read-only archive/member indexing and canonical-path discovery when the task is "find every copy" or "where does this internal file live". Cross-check before writing. 2. Bundled `scripts/totk_actor_tools.py` for proven read-only actor pack inspection, comparison, ZsDic/dictionary handling, SARC listing, and MSBT label inspection. 3. `totk-local-operator` bundled tools for compact file inventories, JSON diffs, and validation summaries. 4. Existing workspace `tools/` utilities only if the folder actually exists and the command clearly matches the current task. 5. A small task-local script under the current workspace working area for missing write capabilities, with explicit inputs and validation. Do not fail or ask the user for a missing `tools/` folder unless the user explicitly requested a specific missing tool and no bundled/scripted fallback is practical. Old `Codex_Working` builders are reference/debug artifacts, not required reusable tooling. If a workspace `tools/` folder exists, useful historical utilities may include actor pack cloning, exact BYML string rewriting, or AI schedule template editing, but their presence is optional. Explain each command in plain English before running it, especially when it writes output files. Treat TKVSC-derived helpers as trial-first for inspection only. They are useful for broad archive and canonical-path awareness, but they do not replace proven actor-pack writers or direct-output validation. When customizing actor-pack member files for one actor, do not edit generic/shared internal paths in place. Generic files are included redundantly across many packs, and the game may already have a same-path copy loaded before consulting the current actor. Clone each customized member to a new actor-specific internal filename, repoint the actor's live component/controller chain to that filename, and validate the exact path from `ActorParam` with `totk_actor_tools.py trace-actor-links --expect-reachable`. Shared canonical paths should be edited only when the requested change is intentionally global; discuss that intent with the user and manage all redundant same-path copies. Keep generated intermediate files under `/Codex_Working//`, not inside `romfs`. ## Actor Pack Cleanup Policy Current actor-pack cloning and patching workflows are intentionally conservative and may leave excess internal files in the output pack. These unused members are usually harmless because the game follows live refs from `ActorParam`, component refs, and nested refs rather than loading every member as behavior. Do not add ad hoc cleanup that deletes unreferenced-looking files from actor packs. A safe cleanup routine needs careful design, parent-chain awareness, live-ref tracing, merged-output testing, and repeated spawn/gameplay validation. Deleting too much can make an actor fail to spawn or remove behavior that was inherited, loaded indirectly, or needed by another component. When reporting output quality, distinguish between: - **Live edited refs**: must be validated and should be treated as correctness-critical. - **Excess dormant members**: acceptable unless they create a known conflict, size problem, or user-requested cleanup target. - **Cleanup candidates**: record them for future tooling, but leave them in place unless a tested cleanup routine exists for that actor type. ## Compression Preflight Find `/Pack/ZsDic.pack.zs` first. Load it before inspecting compressed files. It decompresses to a SARC containing: - `pack.zsdic`: actor `.pack.zs` files. - `bcett.byml.zsdic`: Banc `.bcett.byml.zs` files. - `zs.zsdic`: RSDB `.rstbl.byml.zs`, Mals `.sarc.zs`, and most other `.zs` files. Do not attempt generic `.zs` decompression without these dictionaries; most TOTK files will fail with dictionary mismatch or produce unusable output. Use `scripts/totk_actor_tools.py` for read-only inspection and comparisons: ```powershell python scripts/totk_actor_tools.py list-pack --romfs --pack python scripts/totk_actor_tools.py compare-packs --romfs --base --clone python scripts/totk_actor_tools.py msbt-label --romfs --mals --file ActorMsg/Npc.msbt --label Example_Npc_Raul_01_Name ``` If Python dependencies are missing, install `zstandard`, `sarc`, `byml`, and `PyYAML` only with user approval. ## Clone Workflow 1. Confirm the vanilla romfs folder and output/mod project folder. Verify the vanilla romfs is not inside the output folder and will remain read-only. 2. Identify the exact vanilla base actor pack. If the user supplied a visible character name, resolve it through Mals first, then compare `ActorInfo`, `GameActorInfo`, actor pack presence, and related event/message files. Do not assume `Npc_X.pack.zs` is the base for `Npc_X_01.pack.zs`; compare candidates if needed. 3. Infer the actor type/category from filename prefixes, actor pack contents, and the base actor's `ActorInfo` row, especially `Category`, `ClassName`, `ActorName`, `FmdbName`, and related model/link fields. Report the inferred type and any uncertainty before generating actor-type-specific files. 4. Inspect the output folder. Ask whether to merge/add to existing mod files or create separate generated chunks/files. If direct edits are approved, back up each existing larger file before editing it using the `Codex_Working/Backups_Pre_/` layout. 5. Extract or prepare the base actor param under `/Codex_Working//`, then use `rewrite_byml_string.py` or a structured BYML edit to create the new actor param. 6. Fork minimally. Preserve vanilla internal filenames only for untouched resources; once a member's contents are customized, give it a new actor-specific internal filename and repoint the live references that should use it. 7. Add or rename only `Actor/.engine__actor__ActorParam.bgyml` for a basic clone when that matches the inferred actor type. 8. Use `clone_actor_pack.py` to repack as `/romfs/Pack/Actor/.pack.zs` using the same SARC layout and `pack.zsdic`. 9. For talk-capable actors, inspect the base AISchedule before generating or changing any schedule file. Preserve the base schedule for a perfect clone unless the user explicitly chooses which branch or branches to redirect. 10. When creating a simple redirected talk schedule from a template, use `build_ai_schedule_from_template.js` rather than hand-editing BYML string-table offsets. 11. Generate or merge paste-ready chunks for the larger shared files listed below, according to the user's chosen output mode. 12. If direct output includes a changed shared non-model file that TKMM probably cannot merge, or a whole copied shared table/archive that may carry unrelated edits, flag that risk to the user. Do not produce a routine compatibility report for normal merge-aware RSDB, GameData, BYML/BGYML, SARC/pack, or Mals edits. 13. Always write a reference text file in `Codex_Working/` containing every generated chunk, the intended destination file, actor type inference, unresolved warnings, direct edits made, and backup locations. ## Fast Static Talk-NPC Clone When the user asks for a clone of an NPC standing in a specific place with one custom line, prefer this small, testable path unless they explicitly want the base NPC's route, shop, quest, or conditional schedule behavior: 1. Clone the actor pack from the base actor and change only the cloned `Actor/.engine__actor__ActorParam.bgyml` `Components.AIScheduleRef` to `?Component/AIScheduleParam/.game__component__AIScheduleParam.bgyml`. 2. Preserve the base pack's model, UMii, physics, voice, SLink/ELink, shop, and other internal resources unless the user asked to alter them. 3. Generate a minimal standalone AISchedule with one `DefaultSchedule.ActionSchedule` idle entry and one `DefaultSchedule.EventEntry`: - `$parent: Work/AISchedule/OnPlayerTalk/OnPlayerTalkBase.game__aischedule__OnPlayerTalk.gyml` - `$type: game__aischedule__OnPlayerTalk` - `EventName: Work/Event/EventSetting/_D_T.engine__event__EventSettingParam.gyml` 4. Use this instead of preserving traveler/shop schedules when the clone should stay put. Traveler/shop schedules often contain route, checkpoint, rain, shelter, and shop-choice behavior that is undesirable for a simple placed screenshot/test NPC. 5. For the custom line, create or clone a small EventFlow, set `EventSetting _D_T` to entry point `Talk`, and add the matching `GameAnalyzedEventInfo` row with the full non-recursive subflow preload set. If the flow calls a custom common flow that calls a vanilla flow, inspect that vanilla flow's `GameAnalyzedEventInfo` row and copy/merge its listed `SubFlowList`; do not list only the direct custom subflow. 6. Before writing that EventFlow, ask which graph policy to use: - Stripped/cleaned: use the vanilla flow only as a template for actor/action/parameter shape, then write only the intended entry point(s) and reachable events. For a normal one-line output, this should be one `Talk` entry point and only the reachable `InitTalk -> EventTalk` events. Reopen the output and fail validation if stale template entry points or events remain unreachable from `Talk`. - Vanilla-preserved: keep the vanilla template's other entry points/events and minimally redirect or insert the requested custom line. Before changing `Talk`, preserve the original `Talk` target under a renamed entry point called `vanillaTalk`, then point `Talk` at the new chain. Reopen the output and validate that the selected entry path reaches the new message and every retained vanilla event is reachable from some entry point; do not leave disconnected template roots. - Runtime debug variant: when the goal is to isolate a crash, non-starting event, or suspicious branch, use stripped/cleaned output even if the final intended design is larger. Keep only the entry path up to the breakpoint, required actors/subflow entries, the next tested EventFlow surface, and short before/after debug `EventTalk` nodes. Delete every later non-test node instead of disconnecting it. Build a ladder of fresh variants that add one surface at a time. ## EventFlow Runtime Debugging For Actor Clones When a cloned actor spawns but its custom talk/event logic does not run, debug the EventFlow chain before changing actor-pack or Banc work that was already proven: 1. Verify launch wiring: AISchedule `EventEntry`, `EventSetting` flow name and entry point, `GameAnalyzedEventInfo` row, actor declarations, and Mals labels. 2. Verify preload closure explicitly. `EventSetting` and `GameAnalyzedEventInfo` must list the launched flow's complete non-recursive subflow set. If the custom flow calls a custom common flow that calls vanilla flowcharts, inspect each reached vanilla flow's `GameAnalyzedEventInfo` row and copy/merge its listed subflows. 3. Make cropped test variants from the last working overlay. Remove later graph content completely; do not only disconnect it. 4. Add diagnostic `EventTalk` nodes around the new tested section and on uncertain switch cases, then add matching MSBT labels, line-length validation, and raw three-line bubble padding for one-/two-line dialogue. 5. Record which debug message was last seen in game. Use that as the next breakpoint. ## AISchedule Inspection Rules Do not treat `OnPlayerTalk` as a single unique hook. `OnPlayerTalk` is a hook type, and a single AISchedule can contain multiple `OnPlayerTalk` entries under different conditional schedule branches. Before changing a talk-capable NPC's AISchedule: - Parse the AISchedule BYML when possible instead of relying on string search. - Group event hooks by schedule branch: `DefaultSchedule` and each entry in `ConditionalSchedule`. - For every conditional branch, surface `ConditionFlag`, `IsReverseCondition`, time/action entries, anchor names, and behavior clues such as `ArrivalAS`, `WaitArrivalAS`, `MovingAS`, rainy variants, posture, equipment state, and start times. - List every `EventEntry` in each branch, especially each `OnPlayerTalk` and `OnNearPlayer`, with its target `EventName`. - Explain likely behavior in human terms, with uncertainty: e.g. "normal daytime shopkeeper", "sleep/rest state", "pre-arrival travel state", "rain movement variant". - Ask which branch or branches to redirect if the user has not already selected them. Hook meanings: - `OnPlayerTalk`: runs when the player actively interacts with the NPC. This is the usual path into a conversation/eventflow. - `OnNearPlayer`: runs when the player is nearby. It is usually used for short overhead speech bubbles or prompts that encourage the player to talk. Schedule branch meanings: - `DefaultSchedule` is the fallback schedule when no conditional schedule overrides it. - `ConditionalSchedule` entries are selected by conditions such as quest/save flags, arrival flags, weather-related logic, dungeon/boss state, prior conversations, or other actor state. - `ConditionFlag` names the flag or bool being tested. - `IsReverseCondition: true` means the branch is used when the condition is false; `false` means it is used when the condition is true. Clone options to surface to the user: - Perfect clone: preserve the base AISchedule and point the actor at the original schedule resources unless a fork is required for actor identity. - Selected redirect: fork the AISchedule and redirect only the user-selected `OnPlayerTalk` branch or branches. - All-talk redirect: fork the AISchedule and redirect every `OnPlayerTalk` entry while preserving other hooks such as `OnNearPlayer`. - Simplified talk schedule: replace the base schedule with a minimal custom schedule only when the user explicitly asks for that behavior simplification. ## Output Chunks For a cloned actor, produce the relevant outputs and label where each chunk goes. NPC talk wiring is currently the best-developed path; for other actor categories, infer type and clone conservatively while documenting uncertainty. - `/romfs/Pack/Actor/.pack.zs`: standalone actor pack. - Actor-pack-only overlays are valid for targeted replacement when the tested base mod supplies registration and placement. Name the intended base mod explicitly in the build notes. Do not present a pack-only output as a standalone spawn test unless the actor's `ActorInfo` row and a Banc/Event/AI spawn source are included or known to exist in the final merged output. - `/romfs/Component/AIScheduleParam/.game__component__AIScheduleParam.bgyml`: standalone AI schedule file. - `RSDB/ActorInfo.Product..rstbl.byml.zs`: row with `__RowId` and `ActorName` set to ``, usually cloned from the base actor's row. - `RSDB/EventSetting.Product..rstbl.byml.zs`: row with `__RowId: _D_T`, `EntryPointName: Talk`, and `FlowchartFileName: Work/Event/EventFlow/.evfc`. - `Mals/.Product..sarc.zs > ActorMsg/Npc.msbt`: label `_Name` mapped to the requested display text. - `Mals/.Product..sarc.zs > EventFlowMsg/.msbt`: add event text only when the user asks for message content generation. - `RSDB/GameActorInfo.Product..rstbl.byml.zs`: check whether a matching row is needed. Until confirmed, report whether the base actor has a row and warn if `` does not. - `RSDB/GameAnalyzedEventInfo.Product..rstbl.byml.zs`: for talk events, clone or create the `_D_T` preload row and keep `SubFlowList` to the exact non-recursive preload closure used by the generated flow. For any vanilla flow reached through custom subflows, inspect the vanilla row and copy/merge that vanilla flow's own listed subflows, because the game does not recursively discover them. - `/Codex_Working/_generated_chunks.txt`: always write a plain text reference file with all chunks and destinations, even when direct edits were also applied. - `/Build Notes - .txt`: top-level build notes beside `romfs`; include build type, intended overlay target/base mod when applicable, one-sentence goal, source baseline, merge assumptions, merged-output status when relevant, and bug-hunting notes or unresolved risks. Do not use this file as a manifest of included files. Do not assume the RSDB and Mals product suffixes match examples from another project. Detect them from the user's romfs each run, e.g. `RSDB/ActorInfo.Product.*.rstbl.byml.zs`, `RSDB/EventSetting.Product.*.rstbl.byml.zs`, and `Mals/.Product.*.sarc.zs`. ## Banc Placement Rules When directly placing a cloned actor: If no Banc, event, AI spawner, or other placement source is included in the output, state whether this is a standalone test or an overlay delta. For overlays, name the intended base mod and verify spawn registration/placement in the final merged output when debugging no-spawn. - Use `Pack/ZsDic.pack.zs` `bcett.byml.zsdic` for Banc `.bcett.byml.zs` files. - If the target is described by a visible location name, resolve that name through Mals and a Banc `LocationArea` or equivalent volume before selecting the Banc file. Record the resolved internal label and owning Banc file in build notes or validation output. - Prefer a Dynamic Banc overlay for newly added test/spawn actors unless there is a specific reason to patch a Static Banc. - Use the Banc axis convention explicitly: `Translate[0]` / `X` is east-west, `Translate[1]` / `Y` is altitude/elevation, and `Translate[2]` / `Z` is north-south. Apply compass offsets only to `X` or `Z`; choose `Y` from nearby surface actors, anchors, or validated prior placements. - Add one actor record with `Gyaml: `, a stable unique `Hash`, `Phive.Placement.ID` equal to that hash, a stable unique `SRTHash`, `Translate`, `Rotate`, and optionally `Name` plus `Bakeable: true` if matching nearby dynamic placements. - Preserve BYML scalar wrappers: `Hash` and `Phive.Placement.ID` as `UInt64`, `SRTHash` as `UInt`, and each `Translate`/`Rotate` component as `Float`. Many BYML writers reject implicit Python/JS numeric values or silently change types. - Make reruns idempotent by removing or replacing the previous placement for the same generated actor/name before appending a new one. - Reopen the compressed output and verify exactly one placement with the expected `Gyaml`, hash, coordinates, and rotation. Confirm the axis meaning in the report, especially that `Y` is height and `Z` is north-south. For named-location placements, validation must also include the Mals label/internal token and the vanilla Banc actor/volume that established the tile; a row in a guessed file is not enough. When the output folder is an existing mod project and the user approves direct edits/additions, add new standalone files under that mod's `romfs` tree and update existing mod copies of RSDB/Mals files only if they are already present or the user explicitly wants them forked from vanilla. Otherwise provide paste-ready chunks and clear file destinations. For no-spawn failures under TKMM, another mod manager, or an overlay workflow, this is a hard gate: inspect the final merged output folder before changing actor-pack internals or adding registration/placement files. Source mod folders, overlay deltas, base mods, archived builds, and build notes are not substitutes for the merged output. 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 a registration/placement/ResourceSizeTable test package before this gate is satisfied, even when a source-side mistake looks obvious. ## Working Folder and Backup Rules Keep `romfs` install-clean. Do not write generated notes, temporary files, scripts, or backups inside `romfs`. For every run, create a working folder alongside `romfs`: ```text /Codex_Working/ ``` For direct edits to existing files, create pre-edit backups under: ```text /Codex_Working/Backups_Pre_/ ``` Mirror the edited file's path relative to `/romfs`. Examples: ```text Edited file: /romfs/RSDB/ActorInfo.Product.112.rstbl.byml.zs Backup: /Codex_Working/Backups_Pre_Example_Npc_Road_008/RSDB/ActorInfo.Product.112.rstbl.byml.zs Edited file: /romfs/Mals/USen.Product.110.sarc.zs Backup: /Codex_Working/Backups_Pre_Example_Npc_Road_008/Mals/USen.Product.110.sarc.zs ``` If the backup path already exists, do not overwrite it silently. Create a clearly numbered sibling run folder such as `Backups_Pre__02`, or inspect and report that the backup already exists before proceeding. Put generated chunk/reference notes, extracted source actor params, temporary decoded BYML, comparison logs, and helper outputs under `Codex_Working//` or `Codex_Working/` as appropriate. The final mod-installable payload should live under `romfs` only. ## Chunk Formatting Rules For RSDB/YAML-like rows, preserve the file's local style and keep keys alphabetical within each actor entry, with `__RowId` as the final line. If adding a field such as `ActorName`, insert it at the correct alphabetical position rather than appending it below `__RowId`. Before writing direct edits to larger mod files, explain in plain English which file will be edited, which backup path under `Codex_Working/Backups_Pre_/` will be created, and what row/entry will be added or changed. Then perform the backup and edit only after the user approves or has already requested direct editing. ## Crosslink Rules The key spawn chain for a basic talk NPC is: `Banc Gyaml=` -> `Pack/Actor/.pack.zs` -> actor param/AISchedule -> selected schedule branch -> selected `OnPlayerTalk EventName` -> `EventSetting _D_T` -> `Work/Event/EventFlow/.evfc` entry point `Talk`. Actor packs unpack internal SARC files into a shared working namespace. Editing a vanilla internal filename can affect every actor that references it, and a redundant same-path copy in the current pack may not be the file the game uses. Only fork internal resources when customization is intentional, and then update every crosslink that points at the forked resource. For actor behavior edits, prove the edited file is live through the actor's pointer chain before judging the result. Common chains include: - damage behavior: `ActorParam.Components.LifeRef -> Component/LifeParam/... -> DamageParameters -> Life/DamageParameters/...`; - weakpoint attachment: body `ActorParam.Components.WeakPointUserRef -> WeakPointActorArray[].ActorPath`; - weakpoint damage: weakpoint `ActorParam.Components.LifeRef -> LifeParam.DamageParameters`; - physics behavior: `ActorParam.Components.PhysicsRef -> Component/Physics/... -> ControllerSetPath -> Phive/ControllerSetParam/... -> Shape/RigidBody arrays`. Before signing off an actor pack, trace every customized internal file from the live `ActorParam`. If a customized component or damage table exists in the SARC but is not reached from the live `ActorParam`, treat it as dead data and patch the pointer chain first. For elemental explosion tuning, remember that fused-arrow AoE may use `Fire`, `Impulse`, `Undefined`, chemical contact, or burn/ignition internals even when `Bomb` and `Shockwave` rates are zero. When handing a generated actor or overlay pack back for playtesting, finish with a pasteable plain-text test card. Keep each `Expected` line brief and focused on the success criterion. ## References Read `references/actor-cloning.md` when generating clone outputs or explaining how clone files interoperate.