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_<NewActor>/ tree before modifying them.
• Vanilla actor pack to fork, e.g. <vanilla-romfs>/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/<locale>.Product.<detected>.sarc.zs, for the visible display text in ActorMsg/*.msbt first. Labels such as <Actor>_Name give the most direct actor-ID candidates.
• Then cross-check each candidate in RSDB/ActorInfo.Product.<detected>.rstbl.byml.zs, RSDB/GameActorInfo.Product.<detected>.rstbl.byml.zs, Pack/Actor/<Actor>.pack.zs, and any related EventFlowMsg/<Actor>.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:

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 <output>/Codex_Working/<NewActor>/, 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 <vanilla-romfs>/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:

python scripts/totk_actor_tools.py list-pack --romfs <vanilla-romfs> --pack <Actor.pack.zs>
python scripts/totk_actor_tools.py compare-packs --romfs <vanilla-romfs> --base <Base.pack.zs> --clone <Clone.pack.zs>
python scripts/totk_actor_tools.py msbt-label --romfs <vanilla-romfs> --mals <USen.Product.121.sarc.zs> --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_<NewActor>/ layout.
5. Extract or prepare the base actor param under <output>/Codex_Working/<NewActor>/, 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/<NewActor>.engine__actor__ActorParam.bgyml for a basic clone when that matches the inferred actor type.
8. Use clone_actor_pack.py to repack as <output>/romfs/Pack/Actor/<NewActor>.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/<NewActor>.engine__actor__ActorParam.bgyml Components.AIScheduleRef to ?Component/AIScheduleParam/<NewActor>.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/<NewActor>_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 <NewActor>_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.

• <output>/romfs/Pack/Actor/<NewActor>.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.
• <output>/romfs/Component/AIScheduleParam/<NewActor>.game__component__AIScheduleParam.bgyml: standalone AI schedule file.
• RSDB/ActorInfo.Product.<detected>.rstbl.byml.zs: row with __RowId and ActorName set to <NewActor>, usually cloned from the base actor's row.
• RSDB/EventSetting.Product.<detected>.rstbl.byml.zs: row with __RowId: <NewActor>_D_T, EntryPointName: Talk, and FlowchartFileName: Work/Event/EventFlow/<EventflowName>.evfc.
• Mals/<locale>.Product.<detected>.sarc.zs > ActorMsg/Npc.msbt: label <NewActor>_Name mapped to the requested display text.
• Mals/<locale>.Product.<detected>.sarc.zs > EventFlowMsg/<EventflowName or chosen message file>.msbt: add event text only when the user asks for message content generation.
• RSDB/GameActorInfo.Product.<detected>.rstbl.byml.zs: check whether a matching row is needed. Until confirmed, report whether the base actor has a row and warn if <NewActor> does not.
• RSDB/GameAnalyzedEventInfo.Product.<detected>.rstbl.byml.zs: for talk events, clone or create the <NewActor>_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.
• <output>/Codex_Working/<NewActor>_generated_chunks.txt: always write a plain text reference file with all chunks and destinations, even when direct edits were also applied.
• <output>/Build Notes - <mod folder name>.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/<locale>.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: <NewActor>, 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:

<output>/Codex_Working/

For direct edits to existing files, create pre-edit backups under:

<output>/Codex_Working/Backups_Pre_<NewActor>/

Mirror the edited file's path relative to <output>/romfs. Examples:

Edited file:
<output>/romfs/RSDB/ActorInfo.Product.112.rstbl.byml.zs

Backup:
<output>/Codex_Working/Backups_Pre_Example_Npc_Road_008/RSDB/ActorInfo.Product.112.rstbl.byml.zs

Edited file:
<output>/romfs/Mals/USen.Product.110.sarc.zs

Backup:
<output>/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_<NewActor>_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/<NewActor>/ 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_<NewActor>/ 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=<NewActor> -> Pack/Actor/<NewActor>.pack.zs -> actor param/AISchedule -> selected schedule branch -> selected OnPlayerTalk EventName -> EventSetting <NewActor>_D_T -> Work/Event/EventFlow/<EventflowName>.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.