ff9mapkit 1.0.0b3__py3-none-any.whl

ff9mapkit/content/chest.py

@@ -0,0 +1,186 @@
+"""Inject a real openable TREASURE CHEST -- one object whose pose is save-flag-gated (closed/open) and
+whose press handler animates the lid, gives a fixed item or gil, shows a "Received X" box, and latches the
+flag so it STAYS OPEN across saves.
+
+Byte-grounded on real FF9 chests (field 200 entry 9; field 407 entries 12/22 -- model 75 = GEO_ACC_F0_TBX),
+decoded opcode-for-opcode. Init (tag 0): CreateObject + TurnInstant + SetObjectLogicalSize(1,40,45) [the
+collision box] + SetStandAnimation(7340) + SetObjectFlags(5) + SetHeadFocusMask(2,0) + a TWO-ARM pose branch
+on a save-persistent GLOB_BOOL opened-flag -> SetStandAnimation(OPEN 7338) when SET / (CLOSED 7339) when
+CLEAR + SetObjectFlags(49) [show + can't-walk-through(16) + don't-hide(32) = the chest's solid collision] +
+EnableHeadFocus(0). The model is ALWAYS shown; only the pose differs, so a re-entered / reloaded field
+re-poses the chest OPEN (the flag persists in gEventGlobal across saves) with zero per-visit bookkeeping.
+
+The open handler runs in the chest's OWN object context (so RunAnimation animates the chest's own model -- a
+separate region has no model and could not). SetObjectFlags bits (EventEngine.DoEventCode CFLAG 0x93:2040):
+1 show, 2 collide-player, 4 collide-NPC, 8 disable-talk, 16 can't-walk-through, 32 don't-hide.
+
+Fidelity note: real chests put the open in the object's tag-2 RANGE function and gate the ``Bubble`` "!" on
+the opened-flag; the kit uses the object's tag-3 talk handler (press X while near) and instead sets the
+**disable-talk** flag (bit 8) once opened, so a looted chest shows no "!" and ignores presses -- the same
+"approach + press once, then inert" behaviour, a different dispatch tag.
+"""
+from __future__ import annotations
+
+import struct
+
+from .. import items as _items
+from ..eb import edit, opcodes
+from . import event as _event
+from . import npc as _npc
+from . import region as _region
+
+CHEST_MODEL = 75              # GEO_ACC_F0_TBX (the kit prop archetype "chest")
+CLOSED_POSE = 7339            # SetStandAnimation rest pose when CLOSED
+OPEN_POSE = 7338             # ... when OPEN (after looting)
+NEUTRAL_POSE = 7340          # the transitional default the real Init sets before the pose branch
+OPEN_ANIM = 7336             # the RunAnimation lid-open clip
+CHEST_LOGICAL_SIZE = (1, 40, 45)      # SetObjectLogicalSize -- the real chest's collision box
+CHEST_FLAGS_INIT = 5         # SetObjectFlags initial: show(1) + collide-NPC(4) (matches the real Init)
+CHEST_FLAGS_CLOSED = 49      # show(1) + can't-walk-through(16) + don't-hide(32): solid + talkable (-> "!")
+CHEST_FLAGS_OPEN = 57       # CHEST_FLAGS_CLOSED + disable-talk(8): solid but NO "!" / inert once looted
+CHEST_FLAG_CLASS = _region.GLOB_BOOL   # 0xC4 -- save-persistent gEventGlobal bool
+# The opened-flag is REQUIRED (no auto-allocation): inject_chest takes it as `flag_idx`, and build.validate
+# enforces a DEFINED flag in the safe custom band [flags.FIRST_SAFE_FLAG, CHOICE_SCRATCH_FLOOR) -- so it can't
+# shift on reorder (a positional bit would) or collide with FF9's own chest bitfield ([8376, 8511]). A named
+# [[flag]] is the ergonomic, campaign-unique choice.
+
+SET_MODEL = 0x2F
+SET_OBJECT_LOGICAL_SIZE = 0x4B
+SET_OBJECT_FLAGS = 0x93
+SET_HEAD_FOCUS_MASK = 0x8B
+ENABLE_HEAD_FOCUS = 0x47
+SET_ANIMATION_FLAGS = 0x3F
+RUN_SOUND_CODE3 = 0xC8       # RunSoundCode3(bank, sound_id, p1, p2, p3) -- the SFX op the real chest uses
+LID_SFX = (637, 638)         # the two lid-creak sound ids the real chest plays
+ITEM_JINGLE = 108            # the item-get jingle the real chest plays when the Received box appears
+SFX_BANK = 53248             # 0xD000 -- the sound bank the chest SFX live in
+SFX_PARAMS = (0, 128, 125)   # the pan/volume params (byte-faithful to fields 200/407)
+
+# The 4 FF9 treasure-chest models (GEO_ACC_F0..F3_TBX) and their per-model animation ids -- decoded byte-for-byte
+# from real fields (the Init's [neutral, open, closed] SetStandAnimation order + the tag-2 lid RunAnimation) and
+# independently cross-verified across many fields, anchored to the in-game-proven F0 chest. The chest OBJECT is
+# otherwise byte-identical across models (same collision LogSize 1,40,45, flags 5->49, opened-flag branch), so
+# only the model id + these 4 animation ids vary. Two clip schemes: F0/F2 share the 73xx clips, F1/F3 share the
+# low ids. ★ Extracting the FBX+textures from p0data (models/1/<id>/) confirms only TWO DISTINCT LOOKS: F1 (91) and
+# F3 (702) are byte-identical (same mesh + both textures); F0 (75) and F2 (701) share the mesh + one texture and
+# differ ONLY in F2's other texture being a ~magenta UNUSED dummy -> renders the same as F0. F2/F3 are per-zone
+# duplicate ids kept here for fidelity; author with F0/F1 for the two real looks. tuple = (model_id, neutral, open, closed, lid).
+CHEST_VARIANTS = {
+    "F0": (75,  7340, 7338, 7339, 7336),   # GEO_ACC_F0_TBX -- the default wooden chest (in-game proven)
+    "F1": (91,  4,    1,    3,    22),      # GEO_ACC_F1_TBX -- the 2nd real look
+    "F2": (701, 7340, 7338, 7339, 7336),   # GEO_ACC_F2_TBX -- F0 with a magenta dummy texture (looks identical to F0)
+    "F3": (702, 4,    1,    3,    22),      # GEO_ACC_F3_TBX -- byte-identical to F1
+}
+_VARIANT_BY_MODEL = {tup[0]: tup for tup in CHEST_VARIANTS.values()}    # model id -> the same 5-tuple
+
+
+def resolve_chest_variant(model=None):
+    """Resolve a ``[[chest]] model`` to ``(model_id, neutral_pose, open_pose, closed_pose, lid_anim)``.
+    ``model`` is a variant NAME ("F0".."F3", case-insensitive), a raw model id (75/91/701/702), or ``None``
+    (= the default F0 wooden chest). Raises ``ValueError`` on an unknown model -- its open/closed/lid animation
+    ids aren't known, and a bare model swap (keeping F0's 73xx clips) would play the wrong / no lid + pose."""
+    if model is None or model == "":
+        return CHEST_VARIANTS["F0"]
+    if isinstance(model, str) and not model.strip().lstrip("-").isdigit():
+        key = model.strip().upper()
+        if key not in CHEST_VARIANTS:
+            raise ValueError(f"unknown chest model {model!r} -- use one of {sorted(CHEST_VARIANTS)} "
+                             f"(the F0..F3 treasure-chest variants) or a raw model id {sorted(_VARIANT_BY_MODEL)}")
+        return CHEST_VARIANTS[key]
+    mid = int(model)
+    if mid not in _VARIANT_BY_MODEL:
+        raise ValueError(f"chest model id {mid} has no known open/closed/lid animations -- use a TBX chest "
+                         f"variant {sorted(CHEST_VARIANTS)} (ids {sorted(_VARIANT_BY_MODEL)})")
+    return _VARIANT_BY_MODEL[mid]
+
+
+def chest_lid_sfx() -> bytes:
+    """The lid-creak open SFX, byte-faithful to the real chest (fields 200/407): SetAnimationFlags(1,0) +
+    two RunSoundCode3 (bank 53248, ids 637 then 638)."""
+    out = opcodes.encode(SET_ANIMATION_FLAGS, 1, 0)
+    for sid in LID_SFX:
+        out += opcodes.encode(RUN_SOUND_CODE3, SFX_BANK, sid, *SFX_PARAMS)
+    return out
+
+
+def build_chest_init(*, x: int, z: int, flag_idx: int, model: int = CHEST_MODEL, animset: int | None = None,
+                     face: int = 0, neutral_pose: int = NEUTRAL_POSE, open_pose: int = OPEN_POSE,
+                     closed_pose: int = CLOSED_POSE, gate=None) -> bytes:
+    """The chest Init (tag 0), opcode-faithful to the real chest, with the SAVABLE open-state: a two-arm
+    pose+flags branch on the opened flag -- the OPEN pose + the inert(disable-talk) flags when SET, the
+    CLOSED pose + the talkable flags when CLEAR. The collision (size + flags) is unconditional. ``gate`` =
+    ``(flag_index, require_set)`` prepends a story-flag gate (same as an NPC's): the chest is ABSENT unless
+    that APPEARANCE flag is in state -- a quest-reward chest that only materializes after a beat (distinct
+    from ``flag_idx``, the OPENED bit)."""
+    animset_v, _hf, _ls = _npc._npc_object_params(model, animset)
+    parts = []
+    if gate is not None:
+        gf, gset = gate
+        parts.append(_region.flag_gate(_region.GLOB_BOOL, gf, require_set=gset))
+    parts += [
+        _npc._d9_const(0, x), _npc._d9_const(4, z), _npc._d9_const(6, face), _npc._d9_const(2, 0),
+        bytes([SET_MODEL, 0x00]) + struct.pack("<H", int(model) & 0xFFFF) + bytes([animset_v & 0xFF]),
+        _npc._CREATE_OBJECT, _npc._TURN_INSTANT,
+        opcodes.encode(SET_OBJECT_LOGICAL_SIZE, *CHEST_LOGICAL_SIZE),     # the collision box
+        opcodes.set_stand_animation(neutral_pose),
+        opcodes.encode(SET_OBJECT_FLAGS, CHEST_FLAGS_INIT),
+        opcodes.encode(SET_HEAD_FOCUS_MASK, 2, 0),
+        _region.if_else(_region.cond_truthy(CHEST_FLAG_CLASS, flag_idx),
+                        opcodes.set_stand_animation(open_pose) + opcodes.encode(SET_OBJECT_FLAGS, CHEST_FLAGS_OPEN),
+                        opcodes.set_stand_animation(closed_pose) + opcodes.encode(SET_OBJECT_FLAGS, CHEST_FLAGS_CLOSED)),
+        opcodes.encode(ENABLE_HEAD_FOCUS, 0),
+        opcodes.RETURN,
+    ]
+    return b"".join(parts)
+
+
+def build_chest_open(flag_idx: int, *, give: bytes, received_text_id: int, payload_value: int,
+                     open_anim: int = OPEN_ANIM, open_pose: int = OPEN_POSE) -> bytes:
+    """The chest press handler (tag 3): no-op if already opened, else animate the lid open, give the
+    payload, show the Received box, latch the opened flag, and set the disable-talk flag (so it shows no
+    more "!" and ignores presses for the rest of the visit -- the Init handles it on the next load)."""
+    return b"".join([
+        _region.flag_gate(CHEST_FLAG_CLASS, flag_idx, require_set=False),    # already opened -> return
+        chest_lid_sfx(),                                                     # the lid-creak SFX (637/638)
+        opcodes.run_animation(open_anim), opcodes.wait_animation(),          # lid opens (on the chest's own model)
+        opcodes.set_stand_animation(open_pose),                             # hold the open pose for this visit
+        opcodes.encode(RUN_SOUND_CODE3, SFX_BANK, ITEM_JINGLE, *SFX_PARAMS),  # the item-get jingle (with the box)
+        give,                                                               # AddItem / AddGil
+        opcodes.set_text_variable(0, payload_value),                        # bind the item/amount for the box
+        opcodes.window_sync(7, 0, received_text_id),                        # window TYPE 7 = the "Received X" box
+        _region.set_var(CHEST_FLAG_CLASS, flag_idx, 1),                     # latch the opened flag (save-backed)
+        opcodes.encode(SET_OBJECT_FLAGS, CHEST_FLAGS_OPEN),                 # disable talk -> no "!" the rest of the visit
+        opcodes.RETURN,
+    ])
+
+
+def inject_chest(data, x, z, *, flag_idx: int, item=None, gil=None, count: int = 1,
+                 received_text_id: int = 62, model="F0", face: int = 0, gate=None,
+                 reserve_party_band: bool = False, spawn_wait_n: int = 2, spawn_wait_occurrence: int = 0):
+    """Inject an openable, savable treasure chest at world (x, z) -- ONE object (tag 0 Init + tag 3 open).
+    Exactly one of ``item`` (id/name + ``count``) or ``gil`` (amount). ``flag_idx`` (a GLOB_BOOL save index)
+    is the opened bit -- it drives the Init open/closed pose+flags and the open handler's once-guard + latch.
+    ``model`` picks the chest VARIANT (a name "F0".."F3" or a raw id 75/91/701/702 -- :func:`resolve_chest_variant`
+    supplies its own open/closed/neutral pose + lid clip). ``face`` rotates the model; ``gate`` =
+    ``(flag_index, require_set)`` makes the chest's APPEARANCE story-gated. Returns new ``.eb`` bytes."""
+    if (item is None) == (gil is None):
+        raise ValueError("inject_chest needs exactly one of item= or gil=")
+    model_id, neutral_pose, open_pose, closed_pose, lid_anim = resolve_chest_variant(model)
+    if item is not None:
+        item_id = _items.resolve(item)
+        give, payload = _event.give_item(item_id, count), item_id
+    else:
+        give, payload = _event.give_gil(int(gil)), int(gil)
+    init = build_chest_init(x=int(x), z=int(z), flag_idx=flag_idx, model=model_id, face=int(face), gate=gate,
+                            neutral_pose=neutral_pose, open_pose=open_pose, closed_pose=closed_pose)
+    openb = build_chest_open(flag_idx, give=give, received_text_id=received_text_id, payload_value=payload,
+                             open_anim=lid_anim, open_pose=open_pose)
+    if len(openb) < 9:                              # IsActuallyTalkable polls tag3[ip+7/8]; keep it >= 9 bytes
+        openb += b"\x00" * (9 - len(openb))
+    table_len = 2 * 4
+    table = struct.pack("<HH", 0, table_len) + struct.pack("<HH", 3, table_len + len(init))
+    entry = bytes([_npc.NPC_ENTRY_TYPE, 2]) + table + init + openb     # type-2 object: tag 0 + tag 3
+    from . import object as _object
+    out, slot = _object.seat_entry(data, entry, reserve_party_band=reserve_party_band)
+    return edit.activate(out, opcodes.init_object(slot, 0), spawn_wait_n=spawn_wait_n,
+                         spawn_wait_occurrence=spawn_wait_occurrence)

ff9mapkit/content/choice.py

@@ -0,0 +1,163 @@
+"""Dialogue CHOICES -- show the player a menu of options and branch on the pick.
+
+This is the interaction / puzzle primitive: a merchant, a lever with a "Yes/No", a quest-giver. It's
+the conditional-region expression machinery (:mod:`ff9mapkit.content.region`) pointed at the engine's
+choice result instead of a story flag.
+
+Grounded BYTE-FOR-BYTE in real FF9 (the Black Mage shop, field 817):
+
+    WindowSync( 0, 128, 97 )                 // the PROMPT + the option rows are ONE text entry:
+                                             //   "...Can I help you?[CHOO][MOVE=18,0]Buy/Sell\n...Nothing"
+    switch ( GetDialogChoice ) from 0 {      // branch on the picked row
+        case +0: ...   case +1: ... }
+
+Engine facts (Memoria source):
+  * The window is SYNCHRONOUS (``MES`` 0x1F "wait until it closes"), so the pick is finalised before
+    the next opcode runs; ``Dialog`` stores it in ``ETb.sChoose``.
+  * A script READS the pick via the expression sysvar token ``B_SYSVAR`` (0x7A) with code 9 ->
+    ``GetSysvar(9)`` -> ``ETb.GetChoose()`` (0-based row index). See :func:`region.cond_sysvar_eq`.
+  * With no ``[PCHC]``/``[PCHM]`` pre-tags the choice count comes from the rows (all enabled), and
+    CANCEL (B) returns the LAST row -- so put the "decline" option last.
+
+The prompt/option TEXT (the ``[CHOO][MOVE=18,0]`` rows) is assembled in :mod:`ff9mapkit.build`
+(``collect_text``); here we build only the SCRIPT side: the window call + the per-option branch.
+"""
+
+from __future__ import annotations
+
+from ..eb import opcodes
+from . import event as _event, region as _region
+
+# zone-triggered choices auto-allocate a GLOB gate flag from here (clear of events 8000 + cutscene
+# 8100). It must be GLOB (gEventGlobal is large); the per-field MAP array is only 80 bytes, so a high
+# index there is out of bounds and crashes. once-per-visit is done by resetting this flag in the
+# region's Init (re-runs each field load), not by a transient MAP flag.
+CHOICE_FLAG_BASE = 8200
+
+
+def option_body(opt: dict, reply_txid: int | None = None) -> bytes:
+    """Compose ONE option's actions (the body run if the player picks it). Reuses the event action
+    vocabulary so a choice option does exactly what an event does: an optional reply line, then
+    give/take item, gil, set a story flag, optionally advance the ScenarioCounter, and (LAST) WARP to
+    another field. Order: reply -> give_item -> remove_item -> gil -> set_flag -> set_scenario -> warp.
+    ``warp`` is last because a Field op transitions away (anything after it is unreachable) -- this is the
+    World-Hub journey-pick primitive: a menu row that seeds the beat then warps into the chosen field."""
+    parts = []
+    if reply_txid is not None:
+        parts.append(_event.message(reply_txid))
+    if "give_item" in opt:
+        gi = opt["give_item"]
+        parts.append(_event.give_item(gi[0], int(gi[1]) if len(gi) > 1 else 1))   # gi[0] = id or name
+    if "remove_item" in opt:
+        ri = opt["remove_item"]
+        parts.append(_event.take_item(ri[0], int(ri[1]) if len(ri) > 1 else 1))   # symmetric: a trade option
+    if "gil" in opt:
+        parts.append(_event.give_gil(int(opt["gil"])))
+    if "set_flag" in opt:
+        sf = opt["set_flag"]
+        parts.append(_event.set_flag(int(sf[0]), int(sf[1]) if len(sf) > 1 else 1))
+    if "set_scenario" in opt:
+        parts.append(_event.set_scenario(int(opt["set_scenario"])))
+    if "warp" in opt:
+        # A choice that warps is ALWAYS a field transition, so it fades out first (fade=True) -- exactly
+        # like a gateway/ladder. Without the fade the destination loads in the clear and you see its
+        # camera-init frames (the World-Hub static-screen bug). entrance (optional) sets the arrival
+        # entrance var; it is not the camera fix (the fade is) -- see event.warp.
+        parts.append(_event.warp(int(opt["warp"]), entrance=opt.get("entrance"), fade=True))  # LAST: away
+    return b"".join(parts)
+
+
+def _gated(o: dict) -> bool:
+    """An option whose visibility depends on a story flag at runtime (flag-gated hide)."""
+    return "requires_flag" in o or "requires_flag_clear" in o
+
+
+def dynamic_mask_setup(options, default: int) -> bytes:
+    """Build the availability mask AT RUNTIME from per-option story flags, then point
+    ``EnableDialogChoices`` at it -- the real-field pattern (Dali/Storage's moogle-mail menu:
+    ``set_var`` the base, ``if(flag) or_var`` each conditional bit, then ``EnableDialogChoices(VAR | .., 0)``).
+
+    Always-visible rows form the base word; each flag-gated row ORs its bit in only when its condition
+    holds (``requires_flag`` -> visible when SET, ``requires_flag_clear`` -> visible when CLEAR). The
+    mask lives in a high scratch word (``region.MASK_SCRATCH_IDX``) and is read back as an UNSIGNED
+    UInt16 expression-arg (no sign trap). Statically ``disabled`` rows are simply never ORed in."""
+    base = sum(1 << i for i, o in enumerate(options) if not o.get("disabled") and not _gated(o))
+    parts = [_region.set_var(_region.GLOB_UINT16, _region.MASK_SCRATCH_IDX, base)]
+    for i, o in enumerate(options):
+        if o.get("disabled") or not _gated(o):
+            continue
+        if "requires_flag" in o:
+            cond = _region.cond_truthy(_region.GLOB_BOOL, int(o["requires_flag"]))
+        else:
+            cond = _region.cond_not(_region.GLOB_BOOL, int(o["requires_flag_clear"]))
+        parts.append(_region.if_block(cond, _region.or_var(_region.GLOB_UINT16, _region.MASK_SCRATCH_IDX, 1 << i)))
+    mask_expr = _region.var_expr(_region.GLOB_UINT16, _region.MASK_SCRATCH_IDX)
+    parts.append(opcodes.enable_dialog_choices_var(mask_expr, default))
+    return b"".join(parts)
+
+
+def pre_choose(ch: dict) -> tuple[bytes, str]:
+    """Pre-choose config for a choice: which row is highlighted by DEFAULT, which row CANCEL (B) picks,
+    and which options are HIDDEN (statically via ``disabled``, or flag-gated via ``requires_flag`` /
+    ``requires_flag_clear``). Returns ``(setup_bytes, text_tag)`` -- ``setup`` runs before the window
+    (see :func:`region_body`), ``tag`` is prepended to the choice text. ``(b"", "")`` when nothing is
+    configured, so a plain choice stays byte-identical.
+
+    Mechanism (Memoria ``Dialog.SetupChoose`` + ``ETb.SetChooseParam``): an ``EnableDialogChoices``
+    opcode sets the availability mask (bit i = row i shown, LSB-first) + the default row; the
+    ``[PCHM=count,cancel]`` text tag tells the dialog to APPLY the mask (hidden rows get no widget),
+    ``[PCHC=count,cancel]`` sets count/cancel/default WITHOUT hiding. ``GetChoose()`` returns the
+    ABSOLUTE row index regardless of hides, so the per-option :func:`branch` is unaffected.
+
+    Three modes: flag-gated (any ``requires_flag``) -> a runtime mask (:func:`dynamic_mask_setup`);
+    static-hide (any ``disabled``) -> a literal partial mask; default/cancel only -> a literal all-on
+    mask ``(1<<n)-1`` (NOT 0xFFFF, which sign-extends to -1 and breaks ``SetChooseParam``'s
+    ``while availMask>0`` loop -> default collapses to 0)."""
+    options = ch.get("options", [])
+    n = len(options)
+    default = int(ch.get("default", 0))
+    cancel = int(ch["cancel"]) if "cancel" in ch else (n - 1)   # engine default cancel = last row
+    has_static = any(o.get("disabled") for o in options)
+    has_dynamic = any(_gated(o) for o in options)
+    if not (has_static or has_dynamic or "default" in ch or "cancel" in ch):
+        return b"", ""                                          # nothing configured -> byte-identical
+    if has_dynamic:
+        return dynamic_mask_setup(options, default), f"[PCHM={n},{cancel}]"
+    if has_static:
+        mask = sum(1 << i for i in range(n) if not options[i].get("disabled"))
+        return opcodes.enable_dialog_choices(mask, default), f"[PCHM={n},{cancel}]"
+    return opcodes.enable_dialog_choices((1 << n) - 1, default), f"[PCHC={n},{cancel}]"
+
+
+def branch(option_bodies) -> bytes:
+    """``if (GetChoose()==0){b0} if (GetChoose()==1){b1} ...`` -- one independent if-block per option
+    (exactly how FF9 lays out choice handlers). Options with an empty body emit nothing."""
+    out = b""
+    for i, body in enumerate(option_bodies):
+        if body:
+            out += _region.if_block(_region.cond_sysvar_eq(_region.SYSVAR_CHOICE, i), body)
+    return out
+
+
+def region_body(prompt_txid: int, option_bodies, *, window: int = 1, flags: int = 128,
+                setup: bytes = b"") -> bytes:
+    """The choice block usable in ANY trigger context (an NPC talk OR a walk-in region): lock the
+    player, (optional pre-choose ``setup``), open the prompt+options window, branch on the pick, restore
+    control. **No RETURN** -- the caller adds it (NPC) or wraps it in a flag-gated region body (zone).
+
+    ``setup`` is the optional ``EnableDialogChoices`` opcode from :func:`pre_choose` (default/cancel/
+    disabled config); it MUST run before the window opens. Why DisableMove/EnableMove: the engine does
+    NOT block field movement while a dialog is open, so without this the d-pad would move BOTH the menu
+    cursor AND the character. Real FF9 wraps a choice in DisableMove...EnableMove (e.g. the Black Mage
+    shop), and the menu still navigates because choice input comes from the dialog system, not field
+    control."""
+    return (opcodes.DISABLE_MOVE + setup + opcodes.window_sync(window, flags, prompt_txid)
+            + branch(option_bodies) + opcodes.ENABLE_MOVE)
+
+
+def speak_body(prompt_txid: int, option_bodies, *, window: int = 1, flags: int = 128,
+               setup: bytes = b"") -> bytes:
+    """A complete ``_SpeakBTN`` (NPC talk) body for a choice: the choice block + RETURN. ``flags`` 128
+    is the standard field dialogue flag (same as plain NPC dialogue). ``setup`` = optional pre-choose
+    opcode (see :func:`pre_choose`)."""
+    return region_body(prompt_txid, option_bodies, window=window, flags=flags, setup=setup) + opcodes.RETURN

ff9mapkit/content/conductor.py

@@ -0,0 +1,217 @@
+"""Multi-actor cutscene CONDUCTOR -- FF9's central-director idiom (memory project-ff9-cutscene-multiactor).
+
+A from-9-real-fields study (565/909/2554/2207/2169 ...) found FF9 coordinates 2+ scripted actors with a
+single CONDUCTOR function -- NOT a per-actor flag handshake. ONE function (a code entry armed by
+``InitCode`` in Main_Init) owns the control lock and sequences every actor, addressing each one BY UID via
+the ``*Ex`` opcode family (``WindowSyncEx`` / ``TimedTurnEx`` / ``RunAnimationEx`` ...) so it never has to
+context-switch into the actor. An actor's UID is its entry slot (``sid``); the player/control character is
+uid 250 (the engine remaps 250 -> the active control uid). Timing between beats is a plain ``Wait``.
+
+This module is the INCREMENT-1 director: SEQUENTIAL beats from a flat, actor-tagged ``steps`` list --
+``say`` / ``turn`` / ``anim`` driven on a named actor by id, plus ``wait`` / ``set_flag`` at the conductor
+level. Deliberately deferred (later increments, see the memory):
+  * animated WALK -- needs ``RunScript`` into a per-actor walk tag (base ``Walk`` only animates in the
+    actor's own tag-1 LOOP, state 1), so it's a bigger change than an inline ``*Ex`` op;
+  * PARALLEL beats ("these run together") -- FF9 forks with ``RunScriptAsync`` and joins on the script
+    *level* (``WaitSharedScript`` only joins the ONE shared script the SAME object spawned, not a global
+    barrier), which needs its own grounding pass.
+
+Softlock care, mirroring the kit's existing cutscene rules on player-cloned actors:
+  * ``turn`` uses ``TurnInstantEx`` (instant, no wait) -- never ``WaitTurnEx`` (a player clone's turn anim
+    may not drive the wait to completion -> hang);
+  * ``anim`` uses ``RunAnimationEx`` + a fixed ``Wait`` hold -- never ``WaitAnimationEx`` (same hang risk).
+"""
+
+from __future__ import annotations
+
+import struct
+
+from ..eb import EbScript, cmdasm, edit, opcodes
+from . import object as _object        # seat_entry (verbatim below-party-band seating)
+from . import region as _region
+from . import event as _event
+from . import cutscene as _cutscene   # shared: once_flag_for / DEFAULT_WARMUP / ANIM_HOLD / REORDER_WAIT / say
+
+PLAYER_UID = _cutscene.PLAYER_UID      # 250 -> the engine's control-character sentinel
+
+# Spin-wait (frames) for the field/engine to grant control before locking. A field's entry transition
+# (fade + scrolling-camera settle) RE-ENABLES control at a frame a fixed warmup can't predict -- in-game
+# (2026-06-28) the player could walk + dismiss the first dialogue while the camera settled, then lost
+# control. So: DisableMove, then SPIN until the engine RE-grants control, then DisableMove again -- the
+# re-lock lands AFTER the grant and holds. Capped so a field that never re-grants can't hang.
+CONTROL_POLL_CAP = 90                  # frames (~3s) -- the entry settle is ~0.5-1.5s; this is a safe ceiling
+
+
+def wait_for_control_then_lock(cap: int = CONTROL_POLL_CAP) -> bytes:
+    """Bytecode that spins until ``IsMovementEnabled`` (sysvar 2) becomes true -- the field/engine's entry
+    control-grant -- then ``DisableMove`` so the lock lands AFTER that grant. Used AFTER an initial
+    DisableMove, so it waits for the engine to RE-enable control (its entry-transition grant) and re-locks.
+
+    Unrolled (no loop counter -> no MAP-byte out-of-bounds risk): ``cap`` copies of
+    ``push IsMovementEnabled; JMP_IF granted; Wait(1)`` then ``granted: DisableMove``. Each check exits early
+    via a forward ``JMP_IF`` the moment control is granted; if it's never granted the block falls through
+    after ``cap`` frames and locks anyway. Assembled with :func:`cmdasm.assemble_block` (resolves the jumps)."""
+    lines = []
+    for _ in range(int(cap)):
+        lines.append("SET({B_SYSVAR[2] B_EXPR_END})")   # push IsMovementEnabled (engine usercontrol)
+        lines.append("JMP_IF(granted)")                  # granted -> stop spinning
+        lines.append("op_22(1)")                         # else wait one frame and re-check
+    lines += ["granted:", "DisableMove()"]               # lock NOW (after the grant) -- the lock that sticks
+    return cmdasm.assemble_block("\n".join(lines))
+
+
+def _uid_for(name, uid_by_name):
+    """Resolve an actor NAME to its runtime UID: ``"player"`` -> 250 (control char); else its entry slot."""
+    if name == "player":
+        return PLAYER_UID
+    return uid_by_name.get(name)
+
+
+def actor_say(uid: int, text_id: int, *, flags: int = 128) -> bytes:
+    """Step: the actor at ``uid`` speaks ``text_id`` -- ``WindowSyncEx(uid, 0, flags, txid)`` (the window
+    is attributed to that actor by id, so its tail points at them). Blocks until dismissed."""
+    return opcodes.window_sync_ex(uid, 0, flags, int(text_id))
+
+
+def actor_turn(uid: int, angle: int) -> bytes:
+    """Step: face ``angle`` INSTANTLY (0=S, 64=W, 128=N, 192=E) -- ``TurnInstantEx(uid, angle)``. Instant
+    (no ``WaitTurnEx``) so it never hangs on a player-cloned actor whose turn anim doesn't complete."""
+    return opcodes.turn_instant_ex(uid, int(angle))
+
+
+def actor_anim(uid: int, anim: int, hold: int = _cutscene.ANIM_HOLD) -> bytes:
+    """Step: play ``anim`` on the actor then hold ``hold`` frames -- ``RunAnimationEx(uid, anim)`` + a fixed
+    ``Wait`` (NOT ``WaitAnimationEx``, which hangs if the clip doesn't drive the wait to completion)."""
+    return opcodes.run_animation_ex(uid, int(anim)) + opcodes.wait(int(hold))
+
+
+WALK_LEVEL = 2          # RunScript script-level for a walk call (matches real fields 565/909/2554)
+WALK_TAG_BASE = 20      # first walk-choreography tag added to an actor's entry (clear of inject_npc's 0/1/3)
+
+
+def compile_steps(steps, uid_by_name, txids, *, say_flags: int = 128, relock: bool = False,
+                  walk_calls=None) -> bytes:
+    """Compile actor-tagged conductor steps to bytes. Each step is a dict with at most one action:
+    ``say`` / ``turn`` / ``anim`` / ``walk`` (need an ``actor = "<name>"``; ``say`` without an actor = a
+    narration line), or ``wait`` / ``set_flag`` (conductor-level, no actor). ``say`` steps consume ``txids``
+    in order. The actor name resolves to a UID via ``uid_by_name`` (or ``"player"`` -> 250).
+
+    A ``walk`` step compiles to ``RunScriptSync(2, uid, tag)`` -- the conductor can't walk an actor inline
+    (base ``Walk`` acts on the EXECUTING object and there is no targeted WalkEx), so the caller pre-generates
+    a walk-choreography tag on the actor's OWN entry (``edit.add_function``) and passes ``walk_calls`` (a
+    dict ``step_index -> (uid, tag)``); RunScriptSync runs it in the actor's context (so it animates) and
+    BLOCKS until it returns (sequential). ``walk_calls`` is required iff any step has ``walk``.
+
+    ``relock`` prefixes every beat with ``DisableMove`` -- see :func:`build_body` for why the entry control
+    grant needs the spin-lock + per-beat re-lock."""
+    walk_calls = walk_calls or {}
+    out, ti = [], 0
+    for i, s in enumerate(steps):
+        if relock:
+            out.append(opcodes.DISABLE_MOVE)          # re-lock: undo any entry-transition control re-grant
+        name = s.get("actor")
+        uid = _uid_for(name, uid_by_name) if name else None
+        if "say" in s:
+            out.append(actor_say(uid, txids[ti], flags=say_flags) if uid is not None
+                       else _cutscene.say(txids[ti], flags=say_flags))
+            ti += 1
+        elif "wait" in s:
+            out.append(opcodes.wait(int(s["wait"])))
+        elif "set_flag" in s:
+            sf = s["set_flag"]
+            out.append(_cutscene.set_flag(int(sf[0]), int(sf[1]) if len(sf) > 1 else 1))
+        elif "turn" in s:
+            if uid is None:
+                raise ValueError(f"conductor step {s!r}: turn needs actor = \"<name>\"")
+            out.append(actor_turn(uid, s["turn"]))
+        elif "anim" in s:
+            if uid is None:
+                raise ValueError(f"conductor step {s!r}: anim needs actor = \"<name>\"")
+            out.append(actor_anim(uid, s["anim"]))
+        elif "walk" in s:
+            if i not in walk_calls:
+                raise ValueError(f"conductor step {s!r}: walk needs a pre-generated walk tag (walk_calls)")
+            w_uid, w_tag = walk_calls[i]
+            out.append(opcodes.run_script_sync(WALK_LEVEL, w_uid, w_tag))   # run the actor's walk tag, block
+        else:
+            raise ValueError(f"unknown conductor step: {s!r}")
+    return b"".join(out)
+
+
+def walk_tag_body(x: int, z: int, speed: int | None = None) -> bytes:
+    """The body of a per-actor WALK tag, run via RunScript in the actor's own context (gExec == the actor,
+    so base ``Walk`` moves IT and animates). Reuses the kit's actor-walk recipe (SetWalkTurnSpeed(255) +
+    StopAnimation + InitWalk + Walk -- no WaitTurn/WaitAnimation, which hang on a player clone) + a RETURN
+    so the blocking ``RunScriptSync`` caller unblocks on arrival.
+
+    A base ``Walk`` SELF-BLOCKS until arrival, so if another actor's collision box sits in the path it never
+    arrives => softlock (in-game 2026-06-28: a walk into a neighbor locked). The cure is faithful STAGING --
+    author clear paths between an actor's start and its target (real FF9 does the same; the kit can't reroute
+    around live actors). A ``SetPathing(0)`` collision-off wrap was tried and dropped: off the walkmesh the
+    Walk can fail to register arrival (a different hang) and the actor can drift off-mesh -- clean spacing is
+    both safer and how the real game stages cutscene walks."""
+    return _cutscene.actor_walk(int(x), int(z), speed) + opcodes.RETURN
+
+
+def build_body(steps, uid_by_name, txids, once_flag: int | None, *, flag_class=_region.GLOB_BOOL,
+               warmup: int = _cutscene.DEFAULT_WARMUP, owns_control: bool = True,
+               exit_warp: int | None = None, say_flags: int = 128,
+               reorder: int = _cutscene.REORDER_WAIT, walk_calls=None) -> bytes:
+    """The conductor function body, run from a standalone ``InitCode``-armed code entry.
+
+    Shape: ``[Wait(reorder)] [DisableMove] [Wait(warmup)] <beats> [EnableMove]`` gated
+    ``if (!once_flag) { ...; once_flag = 1 }`` when ``once_flag`` is set. The leading ``reorder`` Wait lets
+    Main_Init reach its own ``EnableMove`` first so the conductor's ``DisableMove`` is the last control-setter
+    (the lock sticks); the ``warmup`` Wait (after the lock, so the player can't wander) lets the field's entry
+    fade settle AND lets the actor objects finish spawning before the conductor addresses them by uid.
+
+    ``exit_warp`` (a field id) ends the scene with a fade-to-black ``Field(exit_warp)`` instead of restoring
+    control (the warp sits OUTSIDE the once-gate so it always fires); the fade avoids the destination loading
+    in the clear. With ``exit_warp`` set, no ``EnableMove`` is emitted (the destination restores control).
+
+    Control lock (the load-bearing part -- two in-game iterations to get right, 2026-06-28): a fixed warmup
+    can't beat the field's entry control-grant, which re-enables control as the fade + scrolling-camera settle
+    finish (the player could walk + dismiss the first window mid-settle). So under ``owns_control`` the conductor
+    (1) ``DisableMove`` immediately, (2) ``wait_for_control_then_lock`` -- SPINS until the engine RE-grants
+    control, then ``DisableMove`` again so the lock lands AFTER the grant -- and (3) ``compile_steps(relock=True)``
+    re-locks before every beat as a backstop. The spin doubles as the actor-spawn settle (it runs ~until the
+    grant, by which point the InitObject'd actors exist for the by-id ``*Ex`` ops)."""
+    inner = opcodes.wait(int(reorder)) if reorder and reorder > 0 else b""
+    if owns_control:
+        inner += opcodes.DISABLE_MOVE                 # disable, so the spin waits for the engine's RE-grant
+        inner += wait_for_control_then_lock()         # ... spin to that grant, then re-lock (the lock that holds)
+    elif warmup > 0:
+        inner += opcodes.wait(int(warmup))            # no lock: still settle so the actors exist before the beats
+    inner += compile_steps(steps, uid_by_name, txids, say_flags=say_flags, relock=owns_control,
+                           walk_calls=walk_calls)
+    if owns_control and exit_warp is None:
+        inner += opcodes.ENABLE_MOVE
+    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 exit_warp is not None:
+        body += _event.warp(int(exit_warp), fade=True)
+    return body + opcodes.RETURN
+
+
+def inject_conductor(data, steps, uid_by_name, txids, *, once_flag: int | None = None,
+                     flag_class=_region.GLOB_BOOL, warmup: int = _cutscene.DEFAULT_WARMUP,
+                     owns_control: bool = True, exit_warp: int | None = None, say_flags: int = 128,
+                     walk_calls=None, reserve_party_band: bool = False,
+                     spawn_wait_n: int = 2, spawn_wait_occurrence: int = 0) -> bytes:
+    """Seat the conductor as a single-function code entry and arm it via ``InitCode`` in Main_Init (over a
+    Wait filler), exactly like a narration cutscene. Returns new .eb bytes. ``walk_calls`` (a dict
+    ``step_index -> (uid, tag)``) maps each ``walk`` step to its pre-generated per-actor walk tag.
+
+    ``reserve_party_band``: on a VERBATIM fork the donor's last 9 slots are the playable characters, so the
+    conductor INSERTS just below them (``object.seat_entry``) -- keeping the band as the top slots and not
+    perturbing the actors it addresses (which seat below the band before it, so their uids stay valid)."""
+    body = build_body(steps, uid_by_name, txids, once_flag, flag_class=flag_class, warmup=warmup,
+                      owns_control=owns_control, exit_warp=exit_warp, say_flags=say_flags,
+                      walk_calls=walk_calls)
+    entry = bytes([0x00, 0x01]) + struct.pack("<HH", 0, 4) + body
+    out, slot = _object.seat_entry(data, entry, reserve_party_band=reserve_party_band)
+    return edit.activate(out, opcodes.init_code(slot, 0), spawn_wait_n=spawn_wait_n,
+                         spawn_wait_occurrence=spawn_wait_occurrence)