# Totk Eventflow Editor > Edit, inspect, patch, and validate Tears of the Kingdom EventFlow files (.bfevfl.zs), EventSetting/GameAnalyzedEventInfo wiring, AISchedule talk/near hooks, and Mals/MSBT dialogue entries. Use when Codex needs to add or modify NPC dialogue, choices, quest progress, GameData checks, subflows, actor actions/queries, or localized EventFlowMsg text in TOTK mods. - Skill: `cargocult-mods/totk-eventflow-editor` (Agent Skill, multi-file: 10 files) - Install (CLI): `npx skillmds@latest add cargocult-mods/totk-eventflow-editor` - Raw SKILL.md: https://api.skillmd.com/api/skills/cargocult-mods/totk-eventflow-editor/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: cargocult-mods (https://skillmd.com/u/cargocult-mods) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/cargocult-mods/totk-eventflow-editor --- # TOTK EventFlow Editor ## 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. ## Core Workflow Use this skill for EVFL work, but keep `totk-local-operator` loaded for compact file inspection and `totk-toolkit` loaded for shared file plumbing. Use `totk-msbt-mals-editor` for Mals/MSBT text wrapping, control tags, and EventTalk blank-slot padding. 1. Identify the gameplay trigger: - `AIScheduleParam` `EventEntry` maps interaction hooks such as `OnPlayerTalk` and `OnNearPlayer` to an `EventName`. - `RSDB/EventSetting.Product.*.rstbl.byml.zs` maps `EventName` to `FlowchartFileName` and `EntryPoint`. - `RSDB/GameAnalyzedEventInfo.Product.*.rstbl.byml.zs` must include the event and every subflow the event needs loaded. This is not recursive: if a custom flow calls a custom common flow that calls a vanilla flow, also include that vanilla flow and the vanilla flow's own listed dependencies. 2. Inspect the target flow before editing: - List actors, entry points, actions, queries, and reachable events from the edited entry point. - Trace from the exact entry point (`Talk`, `Near`, custom quest entry, etc.), not merely from the file root. - Search vanilla for the same actor action/query before inventing parameter shapes. 3. Patch the smallest surface: - Add action/query names to the actor's declared action/query list before using them in events. - When creating `evfl.Actor()` declarations, clone a vanilla declaration for the same performer when possible. For every actor record synthesized from scratch, populate all six safe-default event-member params: integer `EventMemberCreateMethod = 0`; booleans `IsGrounding = false`, `IsWorld = false`, and `IsBindNearestActor = false`; and strings `UseEventModelAnime = ""` and `UseEventAS = ""`. Do not emit `params = None` or an empty params container (`{}`). Newly added actor rows without a minimally populated parameter table can crash the game even when the file parses and reopens successfully. The mandatory minimal subset has not been isolated; no penalty is currently known for including all six, so builders must include the full set. Preserve or add actor-specific fields where vanilla uses them, such as `ExceptionalBindType = 1` for common `Npc_EventStarter` speaker patterns. Also set the correct `concurrent_clips`; `Npc_EventStarter` and `GameDataActor` talk-flow examples commonly use `1`. - Use `scripts/eventflow_actor_params.py` from builders and validators instead of retyping the six-field table. Call `ensure_safe_actor_params()` when synthesizing an actor and `assert_safe_actor_params()` on the written/reopened flow, scoped to the actor records the builder added. - For actor event-root AINB action/query work, trace the runtime actor's `EventPerformerParam.EventUniqueAin`; an EVFL actor declaration such as `Npc_EventStarter` may be a relay/facade and not the AINB owner that must be patched. - Preserve existing parameter keys and scalar types by cloning a nearby vanilla or local event when possible. - For `EventTalk`, update the referenced Mals/MSBT label in the same task as the EVFL edit. 4. Validate from written output: - Decompress and reparse the patched `.bfevfl.zs`. - Trace the edited entry point and confirm branch targets, params, and terminal events. - Read back `EventSetting` and `GameAnalyzedEventInfo`; confirm the event row names the intended entry point and includes the complete non-recursive subflow preload set. - For minimal/generated one-entry flows, also confirm there are no stale entry points or unreachable template events left in the written flow. - For vanilla-preserved flows, confirm retained vanilla events are reachable from explicit entry points. If the original `Talk` branch is kept while `Talk` is redirected, preserve the original branch as `vanillaTalk` instead of leaving it as a disconnected root. - Decompress and search the patched Mals archive for each new `MessageId`. - Validate every newly synthesized actor declaration after reopening the written output. Require all six safe-default keys with the expected scalar types; for blank-authored defaults, also require the expected values. Additional vanilla-derived keys are allowed. - Confirm the overlay contains only intentional files. ## Runtime Debugging Procedure Use this procedure whenever an EventFlow parses but does not run, stops before an expected branch, or behaves differently in game than static inspection suggests. 1. Separate launch failures from logic failures: - If the actor exists but the event never starts, first verify `AIScheduleParam` hook, `EventSetting`, `GameAnalyzedEventInfo`, target flow name, entry point, actor declarations, and Mals availability. - If any debug `EventTalk` appears, the event launched; debug from the last visible message forward instead of reworking actor/schedule wiring. 2. Build from a proven baseline: - Preserve the last mod folder that ran in game. - Create fresh versioned test overlays instead of mutating failed builds in place. - Keep source overlays read-only and write only the new test folder. 3. Use cropped breakpoint variants: - Physically remove every event after the chosen breakpoint and remove unrelated/unreachable late events from the test file. - Do not merely disconnect, bypass, or rewire around suspected nodes. A malformed unreachable node can still make the EventFlow fail at load time, so disconnected content can invalidate the test. - Keep only the entry path, required actors, required subflow entries, and the next small EventFlow surface under test. 4. Add diagnostic `EventTalk` nodes: - Put a short debug talk immediately before and after the newly tested section, plus branch-case talks where case meaning is uncertain. - Add matching Mals/MSBT labels in the same build, enforce the dialogue line-length rule, and verify labels after recompressing. - Once earlier sections are proven, put debug talks only in the newly added section so playtest output stays readable. 5. Advance in a ladder: - Add one class of surface per variant: direct `EventTalk`, a subflow call, a self-subflow with literal args, a GameData int/bool branch, a player equipment query, an attachment query, an item remove/award action, etc. - If a later variant reaches its after-debug message, earlier variants in the same ladder are normally proven and do not need more testing. - If a variant never starts, suspect load metadata or a malformed node still present in the cropped file. If it starts and stops, the failing surface is between the last visible debug talk and the next expected one. 6. Control stateful confounders: - Reset or explicitly read back GameData work variables before relying on them. - Add debug readouts before and after reset/classification branches when stale values could mimic a valid result. - Do not infer actor/query semantics from names alone; use debug branches to prove case meanings in the exact player state being tested. ## Editing Rules - Prefer a task-local Python builder script for binary edits. Do not hand-edit hex or rely on one-off GUI state for repeatable mod builds. - Use the vanilla `Pack/ZsDic.pack.zs` `zs.zsdic` dictionary for `.bfevfl.zs`, Mals `.sarc.zs`, RSDB, and most compressed BYML files unless a known file type requires a different dictionary. - Keep source mod files read-only when building tests; write outputs to a separate overlay folder. - Use event numbers that do not collide with existing names. Reparse after writing because EVFL index tables are easy to corrupt silently. - Be suspicious of event parameter types. In event-editor, write vector params as arrays like `[0,0,0]` when floats are intended; a string that looks like a vector is wrong. - For new or changed text, patch the correct locale archive, usually `Mals/USen.Product.*.sarc.zs`, under `EventFlowMsg/.msbt`. - Keep generated EventFlow dialogue lines short and validate every changed MSBT label before packaging. Use the established 48 UI-rendered character line limit for each line, excluding MSBT tags/markup from the count; insert explicit line breaks instead of leaving one long unwrapped line, preserve balanced tags, and pad intentional one-line EventTalk bubbles as `line\n\n` and two-line bubbles as `line 1\nline 2\n`. - When cloning an EventFlow to a new file, set both the EventFlow root name and `flowchart.name` to the new flow name if the editor library exposes both. EventSetting still points at `Work/Event/EventFlow/.evfc`, while the overlay file is normally `Event/EventFlow/.bfevfl.zs`. - Add the full transitive subflow set to `EventSetting` and `GameAnalyzedEventInfo`. Subflow preload does not cascade; include child subflows even from branches you do not expect to reach. Missing subflow load data can prevent the event from running even when the EVFL file itself parses. - Do not guess the closure from direct EVFL calls alone. Trace every custom subflow until it reaches vanilla flowcharts; for each vanilla flowchart you call, inspect its vanilla `GameAnalyzedEventInfo` row and copy/merge its `SubFlowList` into the custom event's row. For example, a custom flow that calls a custom common flow, which then calls vanilla `GetPouchContent`, must also include `GetPouchContent` and the vanilla `GetPouchContent` dependencies such as `Common` and `OpenActionGuideScreen`. - If the user is testing runtime behavior, follow the Runtime Debugging Procedure above: use cropped breakpoint variants, not rewired full graphs, and do not leave disconnected later events in the file. - Build breakpoint ladders from a proven minimal baseline. Each new variant should add one class of EventFlow surface at a time, such as a subflow call, a literal self-subflow, an int/bool branch, a player equipment query, an attachment query, or an award/remove action. If a later variant reaches its after-debug talk, earlier variants in the same ladder are normally redundant. - When an EventFlow task reaches into actor event-root AINB files to add or expose actions/queries, validate the AINB with more than the same writer that produced it. AINB round-trips can preserve parseability while corrupting unmodelled selector-default string fields, including Japanese "other" default labels on F32/String selectors. Cross-check untouched default selector labels and string-pool fields with a second parser/export or raw scan before handing back a test mod. ## Minimal Talk Flow Pattern For a simple placed NPC that only needs one custom `Talk` line: - Reuse a vanilla talk EventFlow as a template and keep the `Npc_EventStarter` actor plus its `EventTalk` action. - Start with the vanilla `InitTalk` subflow when the template uses it; wire its `nxt` to a new single `EventTalk` action whose `MessageId` is `EventFlowMsg/: