ff9mapkit 1.0.0b3__py3-none-any.whl

ff9mapkit/content/cutscene.py

@@ -0,0 +1,290 @@
+"""Cutscenes -- ordered, control-locked scripted sequences.
+
+This is the one thing the declarative content (NPCs / events / flags) can't express: a SEQUENCE that
+runs in order. A cutscene runs its actions in order with the player's control disabled for the
+duration, optionally once (flag-gated), triggered on field entry.
+
+There are two flavours, by whether the cutscene names an ``actor``:
+
+* **Narration (v1, no actor)** -- a standalone code entry whose function steps through *controller-
+  level* actions that need no per-actor targeting: ``say`` (a dialogue/narration window),
+  ``wait`` (pause N frames), ``set_flag`` (set a story flag). Triggered on load via ``InitCode``.
+
+* **Actor cutscene (v2, ``actor = "<npc>"``)** -- the sequence is spliced into THAT NPC's Init (see
+  :func:`build_choreography`, used by :func:`ff9mapkit.content.npc.inject_npc` via its ``intro=``),
+  so it runs in the NPC's own object context (``gExec`` == the NPC). That lets the *actor* steps work
+  with plain base opcodes that act on the executing object: ``walk`` / ``teleport`` (MoveInstantXZY)
+  / ``animation`` (RunAnimation+WaitAnimation) / ``turn`` (TimedTurn+WaitTurn) / ``face_player``
+  (TurnTowardObject 250). ``say`` / ``wait`` / ``set_flag`` work there too (they're global). No
+  cross-entry RunScript or UID targeting is needed -- and ``Walk`` self-blocks until arrival, so the
+  steps stay ordered. The block is ``if (!once) { DisableMove; <steps>; EnableMove; once=1 }``.
+
+Both grounded in the standard FF9 pattern -- ``DisableMove`` (0x2D) ... actions ... ``EnableMove``
+(0x2E), flag-gated so a one-time scene doesn't replay -- and in real walk cutscenes (e.g. Gargan
+Roo's Kuja walk function: SetWalkSpeed -> RunAnimation -> WaitAnimation -> InitWalk -> Walk).
+"""
+
+from __future__ import annotations
+
+import struct
+
+from ..eb import EbScript, edit, opcodes
+from . import region as _region
+from . import event as _event
+
+# Default flag for a "play once" cutscene: the SAVE-PERSISTENT Global bool (survives reloads), high in
+# gEventGlobal and clear of the event auto-once band (8000+).
+CUTSCENE_FLAG_CLASS = _region.GLOB_BOOL
+DEFAULT_CUTSCENE_FLAG = 8100        # GLOB (save-persistent) once-flag: plays once EVER
+DEFAULT_CUTSCENE_MAP_FLAG = 80      # MAP-bit (transient, byte 10 -- clear of the field's init bits 144-159
+                                    # and the camera Map-byte 24): replays each visit, still once per visit
+
+PLAYER_UID = 250        # GetObjUID(250) resolves to the player's control character (engine convention)
+
+# A field's Main_Init enables control then runs a ~16-frame entry FadeFilter; for the first frames
+# the field is still fading + the smooth-frame-updater is settling actor positions. Issuing an actor
+# Walk during that window makes the actor circle and never converge (its synchronous Walk then hangs
+# -> softlock). So an ACTOR cutscene waits a warm-up before commanding the actor -- exactly what real
+# entry cutscenes do (Main_Loop `Wait(...)` before RunScript). Tunable via `[cutscene] warmup = N`.
+DEFAULT_WARMUP = 30     # frames (~1s @ 30fps); generous margin over the 16-frame entry fade
+
+
+# A compulsory / auto-advance ATE (FF9's FORCED "Active Time Event" cutscene -- no menu, plays at a story
+# beat, e.g. field 956 Gargant / the Festival-of-the-Hunt cluster) is an ordinary cutscene with two cosmetic
+# ATE flourishes, both grounded byte-for-byte in the real grey mode-6 fields (`docs/ATE_SYSTEM.md` Flavor A):
+#   * its dialogue windows carry the winATE caption flag (64) -> the "Active Time Event" header. This flag
+#     is ALSO what makes the engine tag the closed dialog `isCompulsory` (ETb.ProcessATEDialog) -- the
+#     defining, engine-recognized marker of a compulsory ATE.
+#   * the body is bracketed `ATE(6) ... ATE(0)` (0xD7) -- the grey-unskippable HUD-icon arm (Gray+force; the
+#     mode arg is a 3-bit flag word, not an enum -- &3==2 Gray, &4 force; see EIcon.cs:416-454 / ATE_SYSTEM.md).
+#     (NB field 1901's Eiko ATE is the OPTIONAL Blue mode-1 menu hub, NOT this forced flavor -- don't mirror it.)
+# TWO real templates for an auto-playing ATE (676-field byte sweep + the grey-unskippable re-classification,
+# docs/ATE_SYSTEM.md):
+#   * ate_mode = 6 (GREY + force-show) = the AUTHENTIC UNSKIPPABLE ATE and the DEFAULT -- the real game's forced
+#     ATEs (field 956, the Festival-of-the-Hunt cluster) use ATE(6): a grey, force-shown icon that renders even
+#     under the control-lock. It drives the bottom-left "ACTIVE TIME EVENT" HUD banner (ActiveTimeEvent.cs), whose
+#     grey "ATE" sprite blinks 1s on / 1s off (DisplayGrayATEText) and shows NO press glyph. ★ in-game proven @30008.
+#   * ate_mode = 1 (Blue, no force) = the opt-in quiet no-icon variant: mode 1's render gate
+#     (`mode>0 && ((mode&4) || GetUserControl())`) FAILS under the control-lock, so no HUD banner shows -- the
+#     winATE CAPTION window is the only marker (also proven @30008, before the mode-6 switch).
+# AVOID ate_mode = 5 (Blue + force): a force-shown Blue icon re-flashes the "Press SELECT" glyph (the Blue
+# coroutine), wrongly inviting a press during an auto-play. mode 2 is unused in the real game; the only grey is 6.
+# (NB the kit holds ATE(6) armed across the whole body so the grey banner blinks throughout -- more legible than
+# real 956, which clears it behind a white fade-in; this matches what players remember seeing.)
+# Seen-state + the ATE80 trophy register only on a REAL field id (MappingATEID keyed on fldMapNo/SC) -- the wall.
+# Mirrors `ate.WIN_ATE`; kept local to avoid importing the ate module (which imports choice -> region).
+ATE_CAPTION_FLAG = 64
+ATE_DEFAULT_MODE = 6     # ATE(mode) HUD arm. 6 = the authentic GREY UNSKIPPABLE banner (default, in-game proven
+                         # @30008); 1 = opt-in quiet no-icon variant. Avoid 5 (Blue force-show re-flashes press glyph)
+
+
+def say(text_id: int, *, window: int = 1, flags: int = 128) -> bytes:
+    """Step: open a dialogue/narration window showing ``text_id`` (blocks until the player dismisses).
+    ``flags = 64`` (winATE) renders it with the "Active Time Event" caption (a compulsory-ATE window)."""
+    return opcodes.window_sync(window, flags, text_id)
+
+
+def wait(frames: int) -> bytes:
+    """Step: pause for ``frames`` frames."""
+    return opcodes.wait(frames)
+
+
+def set_flag(idx: int, value: int = 1, *, flag_class=CUTSCENE_FLAG_CLASS) -> bytes:
+    """Step: set a GlobBool story flag (advance/record state from within the scene)."""
+    return _region.set_var(flag_class, idx, value)
+
+
+# --- actor-context steps (v2) -- only valid inside an `actor` cutscene (run in the NPC's entry) ---
+# How fast the actor rotates toward its destination while walking (omega, 0..255). High = the
+# turn-while-walk arc shrinks to ~nothing, so a walk to a point BEHIND the actor turns and goes
+# straight instead of orbiting it forever. This replaces a separate animated pre-turn
+# (TurnTowardPosition/TimedTurn + WaitTurn), which can HANG at ~180deg (the animated big-turn path
+# never completing -> WaitTurn stuck -> softlock). Self-converging + deterministic at exactly 180.
+WALK_TURN_SPEED = 255
+
+
+def actor_walk(x: int, z: int, speed: int | None = None) -> bytes:
+    """Step: the actor walks to world (x, z).
+
+    Sets a high walk-turn-speed first so the Walk rotates tightly toward the destination and walks
+    straight (no arc), converging even when the target is directly BEHIND the actor -- without the
+    animated pre-turn that hangs at ~180deg. ``StopAnimation`` clears the anim flags first so the
+    engine actually swaps idle->walk while moving (else a player-cloned NPC glides in its idle pose).
+    ``Walk`` blocks until arrival. Optional ``speed`` sets the walk movement speed. Uses the NPC's
+    walk animation (set in its Init)."""
+    pre = opcodes.set_walk_speed(int(speed)) if speed is not None else b""
+    return (pre + opcodes.set_walk_turn_speed(WALK_TURN_SPEED) + opcodes.stop_animation()
+            + opcodes.init_walk() + opcodes.walk(int(x), int(z)))
+
+
+def actor_teleport(x: int, z: int) -> bytes:
+    """Step: instantly move the actor to world (x, z) -- no walk animation -- then re-enable its
+    walkmesh pathing (MoveInstantXZY disables it). Use it as a cutscene's FIRST step to place the
+    actor off-screen for a walk-in (the kit handles the engine's POS3 Z-negation; a leading teleport
+    runs before the warm-up so the actor settles off-screen rather than flashing at its spawn)."""
+    return opcodes.move_instant_xzy(int(x), int(z), 0) + opcodes.set_pathing(1)
+
+
+# Cutscene steps are NON-BLOCKING on the animation system: we never use WaitAnimation/WaitTurn,
+# because they HANG if the actor's anim playback doesn't drive them to completion (a player-cloned
+# NPC's walk/turn anims don't always engage -> WaitTurn/WaitAnimation never return -> softlock). A
+# turn is done INSTANTLY (no turn anim needed); an animation is played then given a fixed hold.
+ANIM_HOLD = 40          # frames to let a played animation run before the next step (~1.3s)
+
+
+def actor_animation(anim: int, hold: int = ANIM_HOLD) -> bytes:
+    """Step: play animation ``anim`` on the actor, then hold ``hold`` frames (RunAnimation + a fixed
+    Wait -- NOT WaitAnimation, which hangs if the anim doesn't complete)."""
+    return opcodes.run_animation(int(anim)) + opcodes.wait(int(hold))
+
+
+def actor_turn(angle: int) -> bytes:
+    """Step: face ``angle`` INSTANTLY (0=south, 64=west, 128=north, 192=east). Instant (TurnInstant) so
+    it works without a turn animation and never hangs."""
+    return opcodes.turn_instant(int(angle))
+
+
+def actor_face(uid: int = PLAYER_UID, speed: int = 16) -> bytes:
+    """Step: turn the actor to face an object by UID (default 250 = the player), animated, non-blocking
+    (no WaitTurn). Visible only if the turn anim engages; for a guaranteed instant facing use ``turn``."""
+    return opcodes.turn_toward_object(int(uid), int(speed))
+
+
+def compile_steps(steps, txids, *, say_flags: int = 128) -> bytes:
+    """Compile ordered cutscene step dicts to bytes. Handles global steps (``say`` / ``wait`` /
+    ``set_flag``) and actor-context steps (``walk`` / ``path`` / ``teleport`` / ``animation`` /
+    ``turn`` / ``face_player``). ``say`` steps consume ``txids`` (a list of resolved text ids) in order.
+
+    Actor steps are only meaningful inside an ``actor`` cutscene (they act on the executing object);
+    :func:`ff9mapkit.build.validate` enforces that. ``say_flags`` is the window flag for every ``say``
+    step -- pass ``ATE_CAPTION_FLAG`` (64) to render a compulsory ATE's windows with the ATE caption.
+    Same encoders the round-trip tests cover."""
+    out, ti = [], 0
+    for s in steps:
+        if "say" in s:
+            out.append(say(txids[ti], flags=say_flags)); ti += 1
+        elif "wait" in s:
+            out.append(wait(int(s["wait"])))
+        elif "set_flag" in s:
+            sf = s["set_flag"]
+            out.append(set_flag(int(sf[0]), int(sf[1]) if len(sf) > 1 else 1))
+        elif "walk" in s:
+            out.append(actor_walk(s["walk"][0], s["walk"][1], s.get("speed")))
+        elif "path" in s:                          # a multi-waypoint route = consecutive straight walks
+            for pt in s["path"]:
+                out.append(actor_walk(int(pt[0]), int(pt[1])))
+        elif "teleport" in s:
+            out.append(actor_teleport(s["teleport"][0], s["teleport"][1]))
+        elif "animation" in s:
+            out.append(actor_animation(s["animation"]))
+        elif "turn" in s:
+            out.append(actor_turn(s["turn"]))
+        elif "face_player" in s:
+            out.append(actor_face())
+        else:
+            raise ValueError(f"unknown cutscene step: {s!r}")
+    return b"".join(out)
+
+
+def once_flag_for(cs: dict):
+    """(flag_class, flag_idx) for a cutscene's gate. ``once=true`` -> a SAVE-PERSISTENT Global bool
+    (plays once ever); ``once=false`` -> a TRANSIENT Map bool (replays each visit -- the Map var resets
+    on field load -- but still runs once per visit). An explicit ``flag = N`` overrides the index."""
+    if cs.get("once", True):
+        return _region.GLOB_BOOL, int(cs.get("flag", DEFAULT_CUTSCENE_FLAG))
+    return _region.MAP_BOOL, int(cs.get("flag", DEFAULT_CUTSCENE_MAP_FLAG))
+
+
+def build_choreography(steps, txids, flag_idx: int, *, flag_class=CUTSCENE_FLAG_CLASS,
+                       warmup: int = DEFAULT_WARMUP, ate_mode: int | None = None,
+                       say_flags: int = 128) -> bytes:
+    """The gated choreography block, PREPENDED to the actor NPC's LOOP (tag 1) -- NOT its Init -- by
+    :func:`ff9mapkit.content.npc.inject_npc`. Runs in the NPC's own context (so the actor steps target
+    it) AND while the object is 'running' (engine state 1), where the engine ADVANCES animation frames.
+    (An Init runs at state 2, where ProcessAnime is skipped -> the model glides frozen; confirmed by an
+    in-engine probe -- so the choreography must live in the loop, like real FF9 cutscenes.)
+
+    Shape: ``if (!flag) { DisableMove; Wait(warmup); <steps>; EnableMove; flag=1 }`` (no trailing RETURN
+    -- the loop body + its RETURN follow). ALWAYS gated -- the loop runs every frame, so an ungated
+    block would re-fire endlessly; the flag makes it run once per visit. The ``warmup`` Wait (after the
+    lock, so the player can't wander) lets the field's entry fade settle before the actor moves.
+
+    ``ate_mode`` (not None) styles it as a compulsory ATE: brackets the steps ``ATE(mode) ... ATE(0)``
+    and (with ``say_flags=ATE_CAPTION_FLAG``) gives its windows the ATE caption -- mirrors the real grey
+    mode-6 fields (e.g. 956 Gargant), NOT field 1901 (which is the optional Blue mode-1 menu hub)."""
+    inner = opcodes.DISABLE_MOVE
+    if warmup > 0:
+        inner += opcodes.wait(int(warmup))
+    if ate_mode is not None:
+        inner += opcodes.ate(int(ate_mode))                  # arm the blinking "Active Time Event" prompt
+    inner += compile_steps(steps, txids, say_flags=say_flags)
+    if ate_mode is not None:
+        inner += opcodes.ate(0)                              # disarm before control returns (close the bracket)
+    inner += opcodes.ENABLE_MOVE + _region.set_var(flag_class, flag_idx, 1)
+    return _region.if_block(_region.cond_not(flag_class, flag_idx), inner)
+
+
+# A narration cutscene runs in a SEPARATE code entry armed by `InitCode` in Main_Init -- but Main_Init
+# itself calls `EnableMove` (and a fade) AFTER that InitCode. If the director's `DisableMove` ran first
+# it would be immediately overridden by Main_Init's `EnableMove`, so the player keeps control during the
+# text. Yielding a couple of frames first lets Main_Init reach its `EnableMove` (it does so in the first
+# frame), so the director's `DisableMove` is the LAST control-setter and the lock sticks. (An ACTOR
+# cutscene avoids this by living in the NPC's LOOP, which only runs after Init completes.) ~2 frames is
+# imperceptible (<100ms) and the window only shows during the entry fade.
+REORDER_WAIT = 2
+
+
+def build_body(steps, once_flag: int | None, flag_class=CUTSCENE_FLAG_CLASS,
+               reorder: int = REORDER_WAIT, *, ate_mode: int | None = None,
+               then_warp: int | None = None) -> bytes:
+    """The cutscene function body: a brief reorder ``Wait`` (so the lock outlives Main_Init's EnableMove)
+    then ``DisableMove`` + the ordered ``steps`` + ``EnableMove``, all gated ``if (!once_flag) { ...;
+    once_flag = 1 }`` when ``once_flag`` is set (so it plays once).
+
+    ``ate_mode`` (not None) brackets the steps ``ATE(mode) ... ATE(0)`` -- a compulsory ATE's HUD prompt
+    (the winATE caption on its windows is set by the caller via ``compile_steps(say_flags=...)``).
+
+    ``then_warp`` (a field id) makes the scene AUTO-RETURN: it ends with a FADE-TO-BLACK then
+    ``Field(then_warp)`` instead of restoring control -- exactly how real grey ATEs end (field 956 ->
+    ``Field(2054)``). The warp sits OUTSIDE the once-gate so it ALWAYS fires (even on a re-entry that skips
+    a once'd cutscene, the player still warps back); it transitions away, so it's the last op (no
+    ``EnableMove`` -- the destination's Main_Init restores control). It fades out first (``warp(fade=True)``)
+    so the destination doesn't load in the clear (the static-screen bug). Field() transitions from this
+    InitCode'd entry just like the World-Hub menu-row warp does (same code-entry context -- NOT the
+    Main_Init no-op case)."""
+    pre = opcodes.wait(int(reorder)) if reorder and reorder > 0 else b""
+    inner = pre + opcodes.DISABLE_MOVE
+    if ate_mode is not None:
+        inner += opcodes.ate(int(ate_mode))
+    inner += b"".join(steps)
+    if ate_mode is not None:
+        inner += opcodes.ate(0)
+    if then_warp is None:
+        inner += opcodes.ENABLE_MOVE                      # restore control (a normal cutscene stays put)
+    if once_flag is not None:
+        inner += _region.set_var(flag_class, once_flag, 1)
+        body = _region.if_block(_region.cond_not(flag_class, once_flag), inner)
+    else:
+        body = inner
+    if then_warp is not None:
+        # fade=True: fade to black BEFORE the warp, like every field transition (gateway/ladder/choice).
+        # Without it the destination loads in the clear and you see its camera-init frames (the static-
+        # screen bug). A real grey-ATE return may already be black behind the ATE banner, but the kit
+        # doesn't reproduce that, so an explicit source-side fade is the safe default. See event.warp.
+        body += _event.warp(int(then_warp), fade=True)    # AUTO-RETURN: fade to black, then transition
+    return body + opcodes.RETURN
+
+
+def inject_cutscene(data, steps, *, once_flag: int | None = None, flag_class=CUTSCENE_FLAG_CLASS,
+                    spawn_wait_n: int = 2, spawn_wait_occurrence: int = 0,
+                    ate_mode: int | None = None, then_warp: int | None = None) -> bytes:
+    """Append a cutscene code entry (the sequence in :func:`build_body`) and run it on field load via
+    an ``InitCode`` (over a Wait filler, or inserted into Main_Init). Returns new .eb bytes.
+    ``ate_mode`` (not None) styles it as a compulsory ATE (the ``ATE(mode)`` HUD bracket); ``then_warp``
+    (a field id) makes it auto-return with ``Field(then_warp)`` at the end."""
+    body = build_body(steps, once_flag, flag_class, ate_mode=ate_mode, then_warp=then_warp)
+    entry = bytes([0x00, 0x01]) + struct.pack("<HH", 0, 4) + body
+    slot = EbScript.from_bytes(data).first_free_slot()
+    out = edit.append_entry(data, slot, entry)
+    return edit.activate(out, opcodes.init_code(slot, 0), spawn_wait_n=spawn_wait_n,
+                         spawn_wait_occurrence=spawn_wait_occurrence)

ff9mapkit/content/encounter.py

@@ -0,0 +1,41 @@
+"""Add random-battle encounters to a field.
+
+Appends a type-0 "code" entry whose function runs ``SetRandomBattles`` +
+``SetRandomBattleFrequency``, and activates it from Main_Init via ``InitCode`` written over a
+``Wait`` filler (shift-free). The battle scene id selects which encounter table is used (e.g.
+67 = Evil Forest / the first, weakest battles). Frequency 0..255 (higher = more frequent).
+
+NOTE: a field that hosts encounters also needs an after-battle reinit handler or the player
+freezes on return — see :mod:`ff9mapkit.content.reinit`.
+"""
+
+from __future__ import annotations
+
+import struct
+
+from ..eb import EbScript, edit, opcodes
+
+
+def _battle_entry(pattern: int, scenes, freq: int) -> bytes:
+    scenes = list(scenes)
+    if len(scenes) != 4:
+        raise ValueError("need exactly 4 battle scene ids")
+    code = opcodes.set_random_battles(pattern, *scenes) + opcodes.set_random_battle_frequency(freq) \
+        + opcodes.RETURN
+    # entry: type 0, funcCount 1, funcTable[(tag 0, fpos 4)], then code
+    return bytes([0x00, 0x01]) + struct.pack("<HH", 0, 4) + code
+
+
+def inject_encounter(eb_bytes, *, scene: int, freq: int = 255, pattern: int = 1, scenes=None,
+                     slot: int | None = None, spawn_wait_n: int = 2,
+                     spawn_wait_occurrence: int = 0) -> bytes:
+    """Add encounters of ``scene`` (or an explicit 4-tuple ``scenes``) at ``freq``."""
+    if scenes is None:
+        scenes = (scene,) * 4
+    eb = EbScript.from_bytes(eb_bytes)
+    if slot is None:
+        slot = eb.first_free_slot()
+    out = edit.append_entry(eb_bytes, slot, _battle_entry(pattern, scenes, freq))
+    out = edit.activate(out, opcodes.init_code(slot, 0), spawn_wait_n=spawn_wait_n,
+                        spawn_wait_occurrence=spawn_wait_occurrence)
+    return out

ff9mapkit/content/entry_settle.py

@@ -0,0 +1,50 @@
+"""Hold the screen black briefly on entry so the camera SETTLES before it is revealed.
+
+The Memoria engine runs a per-frame smooth-camera follower (``FieldMap.CenterCameraOnPlayer``, scaled by
+``Memoria.ini``'s ``CameraStabilizer``) for EVERY field. On a warp-in it eases the camera from its
+carried-over position to the spawn-centred target over many frames. Real fields hide this because the
+warp's fade-out blacks the screen while the camera settles; the kit's synthesized ``Main_Init`` reveals
+immediately (its FadeFilter fires right after ``EnableMove``), so on a large-delta entry -- e.g. the World
+Hub entered via a New-Game / F6 warp -- you SEE the camera drift to rest over a few seconds.
+
+Fix (engine-independent, ships on stock Memoria -- no DLL, no ``SmoothCamExcludeMaps`` edit): insert
+``DisableMove ; Wait(n) ; EnableMove`` immediately BEFORE Main_Init's reveal fade. The screen is still
+black at that point (the field loads black; the reveal fade is what brings it in), so the smooth-cam
+converges UNSEEN during the wait; the existing fade then reveals the already-settled camera. Control is
+locked during the wait so the player can't wander blind. (memory ``project-ff9-world-hub``;
+``FieldMap.cs`` ``CenterCameraOnPlayer`` / ``SmoothCamExcludeMaps`` / ``CameraStabilizer``.)
+"""
+
+from __future__ import annotations
+
+from ..eb import EbScript, edit, opcodes
+
+FADE_FILTER = 0xEC          # WIPERGB / "FadeFilter"; arg0 & 2 set => SUB == a fade-IN (reveal)
+
+
+def add_entry_settle(eb_bytes, wait_frames: int = 45) -> bytes:
+    """Insert ``DisableMove ; Wait(wait_frames) ; EnableMove`` just before Main_Init's reveal fade so the
+    smooth-camera settles behind the black screen. Returns the input unchanged when ``wait_frames <= 0`` or
+    Main_Init has no reveal fade (nothing to hide behind)."""
+    if wait_frames <= 0:
+        return eb_bytes
+    eb = EbScript.from_bytes(eb_bytes)
+    e0 = eb.entry(0)
+    f0 = e0.func_by_tag(0) if e0 is not None else None
+    if f0 is None:
+        return eb_bytes
+    fade = None
+    for i in eb.instrs(f0):
+        if i.op == FADE_FILTER and i.args:
+            try:
+                mode = int(i.args[0])
+            except (TypeError, ValueError):
+                continue                      # an expression-mode fade: not the template reveal -- skip
+            if mode & 2:                      # SUB == fade-IN (reveal); ADD (fade-out) would not help
+                fade = i
+                break
+    if fade is None:
+        return eb_bytes
+    rel = fade.off - f0.abs_start
+    body = opcodes.DISABLE_MOVE + opcodes.wait(wait_frames) + opcodes.ENABLE_MOVE
+    return edit.insert_in_function(eb_bytes, 0, 0, rel, body)

ff9mapkit/content/equipment.py

@@ -0,0 +1,93 @@
+"""``[[equipment]]`` -- author a character's STARTING equipment (its new-game default loadout).
+
+Writes a PARTIAL ``<mod>/StreamingAssets/Data/Characters/DefaultEquipment.csv`` delta -- only the characters
+you specify. The engine MERGES DefaultEquipment low->high (``ff9play.LoadCharacterDefaultEquipment``), so a
+partial file overrides just those characters' default sets and unspecified characters keep the base game's.
+
+★ A slot you OMIT starts EMPTY. The row REPLACES that character's whole default set (it is not a per-slot
+patch), so list the full intended loadout. Per-character default equipment is applied at new-game / when a
+character JOINS (``FF9Play_SetDefEquips``), so it composes with story_flags' ``[party]`` -- an added member
+joins wearing its DefaultEquipment gear. New-game scope (no mid-game retro-apply). Lives on the ENTRY field's
+``field.toml``, emitted at the mod-write stage. (memory project-ff9-items-equipment / project-ff9-branch-lanes.)
+
+    [[equipment]]
+    character = "steiner"
+    weapon = "Excalibur"
+    head   = "Genji Helmet"
+    armor  = "Genji Armor"
+    # head/wrist/armor/accessory omitted -> that slot starts empty
+"""
+from __future__ import annotations
+
+from .. import items as _items
+
+# Character name -> EquipmentSetId (Memoria.Data.Characters.EquipmentSetId enum; names/ids only -> provenance-clean).
+EQUIP_SET_ID = {
+    "zidane": 0, "vivi": 1, "garnet": 2, "steiner": 3, "freya": 4, "quina": 5,
+    "eiko": 6, "amarant": 7, "cinna": 8, "marcus": 9, "blank": 10, "beatrix": 11,
+    "marcus2": 12, "beatrix2": 13, "blank2": 14,
+    "dagger": 2, "salamander": 7,                      # aliases (Garnet's alias, Amarant's nickname)
+}
+SET_NAME = {0: "Zidane", 1: "Vivi", 2: "Garnet", 3: "Steiner", 4: "Freya", 5: "Quina", 6: "Eiko",
+            7: "Amarant", 8: "Cinna", 9: "Marcus", 10: "Blank", 11: "Beatrix",
+            12: "Marcus2", 13: "Beatrix2", 14: "Blank2"}
+SLOTS = ("weapon", "head", "wrist", "armor", "accessory")   # the 5 DefaultEquipment.csv equip columns, in order
+MAX_SET_ID = 14
+
+
+def resolve_set_id(name) -> int:
+    """A character name/alias (or a bare 0-14 set id) -> EquipmentSetId. Raises ValueError on unknown/out-of-range."""
+    if isinstance(name, bool) or name is None:
+        raise ValueError("[[equipment]] needs a 'character' (zidane..beatrix, marcus2/beatrix2/blank2)")
+    if isinstance(name, int) or (isinstance(name, str) and name.strip().lstrip("-").isdigit()):
+        i = int(name)
+        if not 0 <= i <= MAX_SET_ID:
+            raise ValueError(f"equipment character id {i} out of range (0-{MAX_SET_ID})")
+        return i
+    key = "".join(c for c in str(name).lower() if c.isalnum())
+    if key not in EQUIP_SET_ID:
+        raise ValueError(f"unknown equipment character {name!r} (zidane..beatrix, marcus2/beatrix2/blank2)")
+    return EQUIP_SET_ID[key]
+
+
+def _slot_id(val) -> int:
+    """An equip-slot value -> item id, or -1 for empty (None / 'none' / '' / -1). Resolves names via items."""
+    if val is None:
+        return -1
+    if isinstance(val, str) and val.strip().lower() in ("", "none", "-1"):
+        return -1
+    if isinstance(val, int) and val < 0:
+        return -1
+    return _items.resolve(val)
+
+
+def equipment_rows(entries) -> list:
+    """``[[equipment]]`` dicts -> sorted ``[(set_id, [weapon, head, wrist, armor, accessory]), ...]`` -- one
+    COMPLETE row per character (an omitted slot = -1 empty). De-dups by set id (last wins). Resolves item +
+    character names; raises ValueError on an unknown name."""
+    by_id: dict = {}
+    for e in entries:
+        sid = resolve_set_id(e.get("character"))
+        by_id[sid] = [_slot_id(e.get(s)) for s in SLOTS]
+    return sorted(by_id.items())
+
+
+def render_default_equipment(entries) -> str:
+    """The PARTIAL ``DefaultEquipment.csv`` text (header + one row per authored character). Merged over the
+    base by the engine, so it overrides only these characters' default sets."""
+    lines = [
+        "# ff9mapkit [[equipment]] -- a partial starting-equipment delta (merged over the base by the engine).",
+        "# Comment;Id;Weapon;Head;Wrist;Armor;Accessory",
+        "# ;Int32;Int32;Int32;Int32;Int32;Int32",
+    ]
+    for sid, slots in equipment_rows(entries):
+        cmt = SET_NAME.get(sid, f"set{sid}")
+        lines.append(f"{cmt};{sid};" + ";".join(str(x) for x in slots))
+    return "\n".join(lines) + "\n"
+
+
+def write_default_equipment(layout, entries) -> None:
+    """Pure writer: emit the equipment delta into ``layout``'s mod root (``Data/Characters/DefaultEquipment.csv``)."""
+    path = layout.default_equipment_csv
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(render_default_equipment(entries), encoding="utf-8", newline="\n")