ff9mapkit 1.0.0b3__py3-none-any.whl

ff9mapkit/content/prop.py

@@ -0,0 +1,75 @@
+"""Place a static set-dressing PROP -- the real FF9 prop recipe (no emulation; replicated from bytes).
+
+A prop is the NPC object MINUS the character behaviours: it holds a single static pose and does NOT turn
+to face the player. Verified byte-for-byte against shipping fields -- the save-moogle (field 300, entry 5)
+and the chest (field 115, entry 9) -- whose Init does:
+
+    SetModel + CreateObject + SetStandAnimation(<pose>) + SetObjectFlags(..) + EnableHeadFocus(0)
+
+`EnableHeadFocus(0)` (engine source: "Enable or disable the character turning his head toward an active
+object") is exactly the switch that kills the turn-to-player behaviour an NPC has. So a prop is just the
+proven NPC injection (:func:`content.npc.inject_npc`) with the static pose in all gesture slots plus that
+tail appended to Init -- we add nothing the engine doesn't already do for its own props.
+"""
+from __future__ import annotations
+
+from ..eb import EbScript, opcodes
+from .npc import ANIM_ORDER, inject_npc
+
+ENABLE_HEAD_FOCUS = 0x47    # "Enable or disable the character turning his head toward an active object"
+TURN_INSTANT = 0x36
+ATTACH_OBJECT = 0x4C        # "Attach an object to another one" -- AttachObject(attachedUid, carryingUid, bone)
+SET_OBJECT_FLAGS = 0x93     # bits: 1 show model, 2 collide player, 4 collide NPC, 8 disable talk
+HELD_FLAGS = 7              # show + collide + collideNPC -- the flags the shipping held cup sets
+# NB: do NOT blanket-apply SetObjectFlags here. Per the engine (EventEngine.DoEventCode, CFLAG 0x93) the
+# flag bits are {1: show model, 2: collide player, 4: collide NPC, 8: disable talk, ...} and it REPLACES
+# the object's low 6 bits. The shipping props' SetObjectFlags(14) (= 2+4+8) omits bit 1 -> "show model"
+# off -> the prop vanishes (in-game-verified: adding it hid all four props). Our prop is a cloned player
+# object that is already shown + collidable, so we only need to kill head-tracking. A future
+# interactivity option can add a SHOW-preserving flag (e.g. 1|8 to also disable the talk prompt).
+
+
+def prop_init_tail(face: int | None = None) -> bytes:
+    """The bytes a prop's Init runs after CreateObject: disable head-tracking (+ an optional instant
+    facing). Mirrors the shipping save-moogle / chest objects minus the model-hiding SetObjectFlags."""
+    tail = opcodes.encode(ENABLE_HEAD_FOCUS, 0)                 # EnableHeadFocus(0): no turn-to-face
+    if face:
+        tail += opcodes.encode(TURN_INSTANT, int(face) & 0xFF)  # TurnInstant(face)
+    return tail
+
+
+def inject_prop(data, x: int, z: int, *, model: int, pose: int, face: int | None = None,
+                dialogue_text_id: int | None = None, slot: int | None = None,
+                attach_to: int | None = None, bone: int = 11,
+                spawn_wait_n: int = 2, spawn_wait_occurrence: int = 0,
+                gate_flag: int | None = None, gate_require_set: bool = True,
+                reserve_party_band: bool = False) -> bytes:
+    """Place a prop ``model`` at world (x, z), held at ``pose`` (an animation id), head-tracking OFF.
+
+    ``attach_to`` (a carrying object's uid = its entry slot) binds this prop to that object's ``bone``
+    so it follows it -- the real held-item recipe ``AttachObject(self_uid, carrier_uid, bone)`` (bone
+    defaults to 11, the right hand the shipping cup uses). The prop's own uid IS its entry slot, so the
+    slot is resolved up front. ``dialogue_text_id`` makes it readable; ``face``/``gate_flag`` as usual.
+    ``reserve_party_band`` (the VERBATIM-fork path) seats the prop BELOW the party-character band (only for
+    a STATIC prop; an ``attach_to`` held item resolves its slot up front and is unsupported there).
+    Returns new ``.eb`` bytes."""
+    anims = {k: pose for k in ANIM_ORDER}                       # all five gesture slots = the (held) pose
+    if attach_to is not None:                                   # ATTACHED: bind to the carrier's bone
+        if reserve_party_band:
+            raise ValueError("inject_prop: attach_to (held item) is not supported with reserve_party_band "
+                             "(its uid is its slot, resolved before the band-aware insert)")
+        if slot is None:
+            slot = EbScript.from_bytes(data).first_free_slot()  # the prop's uid == its slot (= attachedUid)
+        tail = opcodes.encode(ATTACH_OBJECT, slot, int(attach_to), int(bone))
+        tail += opcodes.encode(SET_OBJECT_FLAGS, HELD_FLAGS)    # show + collide (like the shipping cup)
+    else:                                                       # STATIC: just kill head-tracking
+        tail = prop_init_tail(face)
+    # a non-interactive prop is BARE (Init-only, no tag-3 talk func -> the engine's IsActuallyTalkable
+    # short-circuits instead of indexing past it = no per-frame IndexOutOfRange). A prop with dialogue
+    # keeps a real tag-3 WindowSync so it stays readable.
+    return inject_npc(data, x, z, model=model, anims=anims,
+                      talk_text_id=(dialogue_text_id if dialogue_text_id is not None else 62),
+                      init_tail=tail, slot=slot, bare=(dialogue_text_id is None),
+                      spawn_wait_n=spawn_wait_n, spawn_wait_occurrence=spawn_wait_occurrence,
+                      gate_flag=gate_flag, gate_require_set=gate_require_set,
+                      reserve_party_band=reserve_party_band)

ff9mapkit/content/region.py

@@ -0,0 +1,340 @@
+"""General conditional region triggers + the field-script flag/expression primitives.
+
+This is the kit's first *authored-logic* injector. Every other content module stamps a canned
+block (an exit, an NPC, an encounter); this one builds a region whose ``_Range`` trigger runs a
+flag-gated body you compose -- the reusable primitive behind multi-camera switch zones (see
+:mod:`ff9mapkit.content.camera`) and, by the same shape, chests / story flags / one-shot events
+(``if (!done) { give...; set done = 1 }``).
+
+Everything here is grounded BYTE-FOR-BYTE in real FF9 field bytecode -- decoded from the camera
+switch regions of Gargan Roo/Passage (``evt_gargan_gr_lef_0``) + the field-109 exit region. The
+field event "expression" sub-language (opcode ``0x05``) is a little RPN stack terminated by ``0x7F``:
+
+    push a variable :  <class> <idx>            class 0xD5 = GlobUInt8, 0xC5 = GlobBool
+    push a constant :  0x7D <i16>
+    operators       :  0x0E = logical NOT, 0x20 = '==', 0x2C = '=' (assign)
+    end             :  0x7F
+
+So ``set V = k``  -> ``05 <cls> <idx> 7D <k:i16> 2C 7F``
+   ``if (V)``     -> ``05 <cls> <idx> 7F``            (truthy)
+   ``if (!V)``    -> ``05 <cls> <idx> 0E 7F``
+   ``if (V == k)``-> ``05 <cls> <idx> 7D <k:i16> 20 7F``
+
+Control flow uses two relative jumps whose operand is the byte length of the block they skip:
+``0x02`` = jump-if-FALSE (the ``if`` skip), ``0x03`` = jump-if-TRUE (used by ``ifnot``). A region
+entry is engine type ``1`` with an Init func (tag 0 = ``SetRegion`` polygon) and a Range func
+(tag 2 = the trigger body, which only runs while ``usercontrol == 1``).
+"""
+
+from __future__ import annotations
+
+import struct
+
+from ..eb import EbScript, edit, opcodes
+
+# --- expression var classes (the engine's variable scopes) ---
+# A var token byte = 0xC0 | (VariableType << 2) | VariableSource (EBin.getVarOperation). CRITICAL: the
+# SOURCE decides PERSISTENCE -- Global (src 0) reads/writes the SAVE-BACKED gEventGlobal (survives
+# field reloads); Map (src 1) is a PER-FIELD array WIPED on every field load. (HW's naming is
+# inverted: HW "GenBool" = engine Global = persistent; HW "GlobBool" = engine Map = transient.)
+GLOB_BOOL = 0xC4      # Global + Bit  -> SAVE-PERSISTENT bool (story flags, chest "once", etc.)
+MAP_BOOL = 0xC5       # Map + Bit     -> transient per-field bool (resets on reload; rarely what you want)
+GLOB_UINT8 = 0xD5     # Map + Byte    -> transient byte (the camera-switch flag; reset per load by design)
+GLOB_BYTE = 0xD4      # Global + Byte -> SAVE-BACKED single byte: writes ONLY gEventGlobal[idx] (one byte),
+                      # unlike GLOB_UINT16 which spans [idx, idx+1] and zeroes the neighbour. The engine
+                      # reads e.g. the Pandemonium lift-config bytes 361/362 this way (token 0xF4 =
+                      # 0xD4 | the long-index bit). Use this to seed ONE byte without clobbering the next.
+GLOB_UINT16 = 0xDC    # Global + UInt16 -> save-backed 16-bit word. Read via the EXPRESSION path it is
+                      # UNSIGNED (0..65535, no sign-extension -- EBin.GetVariableValueInternal), so it
+                      # holds a choice availability mask without the 0xFFFF->-1 sign trap of a literal.
+MAP_INT16 = 0xD9      # Map + Int16 -> transient SIGNED 16-bit (wiped per field load). The navigable
+                      # ladder's per-frame climb-target scratch (field 706 uses MAP.I16[2]); re-derived
+                      # from the player's height every frame so its transient value never matters.
+GLOB_INT16 = 0xD8     # Global + Int16. Idx 2 (D8:2) is the engine's ARRIVAL-ENTRANCE var: set it right
+                      # before Field()/WorldMap() and the destination field's player-init switches on it.
+VAR_CLASSES = {"glob_bool": GLOB_BOOL, "map_bool": MAP_BOOL, "glob_uint8": GLOB_UINT8, "glob_byte": GLOB_BYTE}
+
+# A scratch word high in gEventGlobal (byte offset; vars index BYTES, bits index BITS -- so byte 2040
+# is bits 16320+, clear of base-game vars [low offsets] AND the kit's 8000+ bit-flags [bytes ~1000]).
+# Rebuilt every time a choice opens (set_var -> or_var), so its transient value never matters across
+# opens; F10's gEventGlobal reset is harmless to it.
+MASK_SCRATCH_IDX = 2040
+
+# --- expression opcodes / tokens ---
+EXPR_OP = 0x05        # expression statement (its single operand is a token stream)
+T_CONST = 0x7D        # 0x7D <i16>
+T_NOT = 0x0E
+T_EQ = 0x20
+T_ASSIGN = 0x2C       # B_LET ('=')
+T_OR_ASSIGN = 0x3F    # B_OR_LET ('|='); real-field verified (Dali/Storage 407: `VAR |= 2` = 05 .. 3F 7F)
+T_LT = 0x18           # B_LT ('<')
+T_ITEMCOUNT = 0x64    # GetItemCount: unary fn token -- pops an item-id const, pushes the held count
+                      # (real-field verified, Dali/Storage 407 chest guard `GetItemCount(236) < 99`)
+T_SYSVAR = 0x7A       # push GetSysvar(<code>) -- EBin.B_SYSVAR (122); reads the next byte as the code
+T_END = 0x7F
+
+# Arithmetic / comparison / input operator tokens -- the engine's binary-op opcodes, verified
+# byte-for-byte against field 706's navigable vine climb (see content.ladder.navigable_climb_body).
+T_MULT = 0x11         # B_MULT '*'
+T_DIV = 0x12          # B_DIV  '/'
+T_MOD = 0x13          # B_MOD  '%'  (the ladder anim window: (animFrame+1) % frames)
+T_PLUS = 0x14         # B_PLUS '+'
+T_MINUS = 0x15        # B_MINUS '-'
+T_GT = 0x19           # B_GT '>'
+T_LE = 0x1A           # B_LE '<='
+T_GE = 0x1B           # B_GE '>='
+T_ANDAND = 0x27       # B_ANDAND '&&'
+T_OROR = 0x28         # B_OROR '||'
+T_KEY = 0x59          # B_KEY: pop a button-mask const, push (mask & held-inputs ? 1 : 0) -- HELD input
+T_KEYON = 0x4F        # B_KEYON: pop a button-mask const, push (mask & pressed-THIS-FRAME ? 1 : 0) -- the
+                      # press EDGE. The ATE "press SELECT" trigger (field 552 [11667]: `1 B_KEYON` with
+                      # SELECT=EventInput.Select=1u). Edge (not held) so one tap = one open.
+T_OBJVAR = 0x78       # B_OBJSPECA: read an object var -> 78 <uid> <field> (uid 255 = self)
+
+# Field-event input button masks (EventInput.cs): the const a B_KEY/B_KEYON token tests against.
+KEY_SELECT = 1        # EventInput.Select (1u) -- the ATE menu trigger
+KEY_START = 8         # EventInput.Start (8u)
+
+# A couple of useful system-variable codes (EventEngine.GetSysvar switch): 2 = usercontrol
+# (IsMovementEnabled), 9 = ETb.GetChoose() = the index the player picked in the last choice window.
+SYSVAR_USERCONTROL = 2
+SYSVAR_CHOICE = 9
+JMP_FALSE = 0x02      # jump-if-false  02 <skip:i16>
+JMP_TRUE = 0x03       # jump-if-true   03 <skip:i16>
+SETREGION_OP = 0x29
+REGION_ENTRY_TYPE = 1
+RANGE_TAG = 2         # the player-in-region (tread) trigger func -- runs EVERY frame in the quad
+INTERACT_TAG = 3      # the press-action-while-in-quad func -- fires on the action button (a lever/sign)
+
+
+def _cls(var_class) -> int:
+    if isinstance(var_class, str):
+        return VAR_CLASSES[var_class]
+    return int(var_class) & 0xFF
+
+
+def _i16(v: int) -> bytes:
+    return struct.pack("<h", int(v))
+
+
+def _push_var(var_class, idx: int) -> bytes:
+    """Encode a variable reference token. Index <= 0xFF -> ``<cls> <idx>``; a larger index sets the
+    long-index bit (0x20) on the class byte and uses a 2-byte little-endian index, exactly as the
+    engine encodes it (EBin.getVarOperation: ``index << 8``, ``| 0x20`` when index > 0xFF). This lets
+    flags live high in gEventGlobal (clear of base-game flags) and still decode correctly."""
+    c = _cls(var_class)
+    if 0 <= idx <= 0xFF:
+        return bytes([c, idx])
+    return bytes([c | 0x20]) + struct.pack("<H", idx & 0xFFFF)
+
+
+# --- expression statements (opcode 0x05 + token stream) ---
+def set_var(var_class, idx: int, value: int) -> bytes:
+    """``set VAR = value`` -> ``05 <var> 7D <value:i16> 2C 7F``."""
+    return bytes([EXPR_OP]) + _push_var(var_class, idx) + bytes([T_CONST]) + _i16(value) + bytes([T_ASSIGN, T_END])
+
+
+FIELD_ENTRANCE_IDX = 2     # D8:2 = the arrival-entrance var the next Field()/WorldMap() arrives through
+
+
+def set_field_entrance(ent: int) -> bytes:
+    """``D8:2 = ent`` -- set the entrance the next ``Field()``/``WorldMap()`` arrives through (the
+    destination field's player-init switches on it to place the player). ``05 D8 02 7D <ent:i16> 2C 7F``
+    (verified vs field 70's warp + field 380/404/706 ladder tops)."""
+    return set_var(GLOB_INT16, FIELD_ENTRANCE_IDX, ent)
+
+
+def or_var(var_class, idx: int, value: int) -> bytes:
+    """``VAR |= value`` -> ``05 <var> 7D <value:i16> 3F 7F`` (B_OR_LET). Used to OR a bit into a mask
+    scratch (real-field verified: Dali/Storage builds its moogle-mail availability mask this way)."""
+    return bytes([EXPR_OP]) + _push_var(var_class, idx) + bytes([T_CONST]) + _i16(value) + bytes([T_OR_ASSIGN, T_END])
+
+
+def var_expr(var_class, idx: int) -> bytes:
+    """A BARE variable read for use as an opcode EXPRESSION-arg (no leading ``0x05`` statement byte):
+    ``<var-token> 7F``. Pass with ``arg_flags`` bit set so the engine evaluates it (``getv`` -> CalcExpr).
+    Real-field verified (Dali/Storage 407: a CHOOSEPARAM arg is ``d6 09 7f`` = bare var + END)."""
+    return _push_var(var_class, idx) + bytes([T_END])
+
+
+def cond_truthy(var_class, idx: int) -> bytes:
+    """``if (VAR)`` condition expr -> ``05 <var> 7F``."""
+    return bytes([EXPR_OP]) + _push_var(var_class, idx) + bytes([T_END])
+
+
+def cond_not(var_class, idx: int) -> bytes:
+    """``if (!VAR)`` condition expr -> ``05 <var> 0E 7F``."""
+    return bytes([EXPR_OP]) + _push_var(var_class, idx) + bytes([T_NOT, T_END])
+
+
+def cond_eq(var_class, idx: int, value: int) -> bytes:
+    """``if (VAR == value)`` condition expr -> ``05 <var> 7D <value:i16> 20 7F``."""
+    return bytes([EXPR_OP]) + _push_var(var_class, idx) + bytes([T_CONST]) + _i16(value) + bytes([T_EQ, T_END])
+
+
+def cond_item_count_lt(item_id: int, limit: int = 99) -> bytes:
+    """``if (GetItemCount(item) < limit)`` condition expr -> ``05 7D <item:i16> 64 7D <limit:i16> 18 7F``.
+    The FF9 treasure-chest space guard: don't open/give if the player can't carry it (default cap 99).
+    Real-field verified (Dali/Storage 407: ``05 7d ec 00 64 7d 63 00 18 7f`` = ``GetItemCount(236) < 99``)."""
+    return (bytes([EXPR_OP, T_CONST]) + _i16(item_id) + bytes([T_ITEMCOUNT, T_CONST])
+            + _i16(limit) + bytes([T_LT, T_END]))
+
+
+def push_sysvar(code: int) -> bytes:
+    """A system-variable read token: ``7A <code>`` -> push ``GetSysvar(code)`` (EBin.B_SYSVAR). The
+    movement gate is exactly this for code 2 (``05 7A 02 7F`` = IsMovementEnabled), so it's proven."""
+    return bytes([T_SYSVAR, code & 0xFF])
+
+
+def obj_var(uid: int, field: int) -> bytes:
+    """An object-variable read token: ``78 <uid> <field>`` (uid 255 = self / the current object).
+    getvobj field codes: 0=X, 1=world-Y-up (=-pos.y), 2=Z, 3=angle, 4=flags, 5=uid, 6=level,
+    7=animFrame. Verified vs field 706's vine climb (``78 FF 01`` = self world-Y, ``78 FF 07`` =
+    self animFrame)."""
+    return bytes([T_OBJVAR, uid & 0xFF, field & 0xFF])
+
+
+def cond_sysvar_eq(code: int, value: int) -> bytes:
+    """``if (GetSysvar(code) == value)`` condition expr -> ``05 7A <code> 7D <value:i16> 20 7F``.
+
+    With ``code`` = :data:`SYSVAR_CHOICE` (9) this is the dialogue-choice test: branch on which row the
+    player picked in the preceding choice window (``ETb.GetChoose()``)."""
+    return bytes([EXPR_OP]) + push_sysvar(code) + bytes([T_CONST]) + _i16(value) + bytes([T_EQ, T_END])
+
+
+def cond_ate_select(avail_class, avail_idx: int, select_mask: int = KEY_SELECT) -> bytes:
+    """The real ATE menu-open gate, byte-for-byte as field 552 [11667]:
+    ``if ( usercontrol==1  AND  <avail>==1  AND  B_KEYON(SELECT) )``.
+
+    RPN: ``usercontrol==1 , <avail>==1 , && , (SELECT B_KEYON) , &&``. Returns the full condition expr
+    (``EXPR_OP ... T_END``) for :func:`if_block`. ``<avail>`` is the author's own availability flag (set
+    in Main_Init alongside ``ATE(mode)``), so the menu opens ONLY while the ATE is offered and the player
+    taps SELECT this frame. Decoded from the Lindblum Main-St hub (Small-Town Knight ATE)."""
+    toks = (push_sysvar(SYSVAR_USERCONTROL) + bytes([T_CONST]) + _i16(1) + bytes([T_EQ])
+            + _push_var(avail_class, avail_idx) + bytes([T_CONST]) + _i16(1) + bytes([T_EQ])
+            + bytes([T_ANDAND])
+            + bytes([T_CONST]) + _i16(select_mask) + bytes([T_KEYON])
+            + bytes([T_ANDAND]))
+    return bytes([EXPR_OP]) + toks + bytes([T_END])
+
+
+# --- control flow ---
+# 'ifnot (IsMovementEnabled) { return }' -- the verbatim region-trigger prologue (gates the body on
+# usercontrol, exactly like every real exit/switch region). 7a 02 = IsMovementEnabled builtin.
+MOVEMENT_GATE = bytes([EXPR_OP, 0x7A, 0x02, T_END, JMP_TRUE, 0x01, 0x00, opcodes.RETURN[0]])
+
+
+JMP_UNCOND = 0x01    # the undocumented UNCONDITIONAL relative jump (operand = signed i16 skip), CLAUDE.md s7.
+                     # The engine is uniformly IP-relative, so 0x01 <i16> skips <i16> bytes unconditionally --
+                     # the hop the two-arm if/else uses to jump over the else-body after the then-body.
+
+
+def jump(skip: int) -> bytes:
+    """An unconditional relative jump over ``skip`` bytes -> ``01 <skip:i16>``."""
+    return bytes([JMP_UNCOND]) + _i16(skip)
+
+
+def if_block(cond: bytes, body: bytes) -> bytes:
+    """``if (cond) { body }`` -> cond + ``02 <len(body):i16>`` (jump-if-false past body) + body."""
+    return cond + bytes([JMP_FALSE]) + _i16(len(body)) + body
+
+
+def if_else(cond: bytes, then_body: bytes, else_body: bytes) -> bytes:
+    """``if (cond) { then_body } else { else_body }`` -- the explicit TWO-ARM branch.
+
+    Emits ``cond + 02 <len(then)+3> + then_body + 01 <len(else)> + else_body``: the JMP_FALSE skips the
+    then-body AND the 3-byte unconditional hop (landing on else); when cond is true the then-body runs and
+    the hop jumps over else. Byte-grounded on the real treasure-chest Init pose branch (fields 200/407:
+    ``05{flag} 02 <7> SetStandAnimation(open) 01 <4> SetStandAnimation(closed)`` -- the savable open/closed
+    pose). The kit had only single-jump ``if_block``/``if_not_block``; this is the missing else arm."""
+    hop = jump(len(else_body))
+    return cond + bytes([JMP_FALSE]) + _i16(len(then_body) + len(hop)) + then_body + hop + else_body
+
+
+def if_not_block(cond: bytes, body: bytes) -> bytes:
+    """``if (!cond) { body }`` -> cond + ``03 <len(body):i16>`` (jump-if-TRUE past body) + body."""
+    return cond + bytes([JMP_TRUE]) + _i16(len(body)) + body
+
+
+def flag_gate(var_class, idx: int, *, require_set: bool = True) -> bytes:
+    """A story-flag PROLOGUE: ``ifnot (flag matches) { return }``. Prepend it to a function so the
+    function only proceeds when the flag is in the required state (the way real FF9 gates NPCs /
+    triggers by scenario). ``require_set`` True -> proceed only when the flag is SET; False -> only
+    when CLEAR. Same shape as :data:`MOVEMENT_GATE` (push flag, conditional jump over an early
+    ``return``)."""
+    cond = cond_truthy(var_class, idx)               # pushes the flag's truth
+    jmp = JMP_TRUE if require_set else JMP_FALSE      # skip the 'return' when the flag is in-state
+    return cond + bytes([jmp]) + _i16(1) + opcodes.RETURN
+
+
+# --- region entry assembly ---
+def set_region(points) -> bytes:
+    """``SetRegion`` polygon op: ``29 00 <count> <(x,z) i16 pairs>``. 4 convex corners is the
+    real-field norm (the engine's IsInQuad fans consecutive triplets; a convex quad is safe)."""
+    pts = [tuple(p) for p in points]
+    if len(pts) < 3:
+        raise ValueError("a region needs at least 3 points")
+    out = bytes([SETREGION_OP, 0x00, len(pts) & 0xFF])
+    for x, z in pts:
+        out += _i16(x) + _i16(z)
+    return out
+
+
+def gated_set_region(zone, var_class, idx: int) -> bytes:
+    """An Init body that defines the region quad ONLY while flag ``idx`` is CLEAR (else nothing) + a
+    return. So a spent one-shot trigger sets up no quad on a later visit -> no leftover interaction
+    prompt / tread. ``if (flag) skip SetRegion`` == :func:`if_not_block` over :func:`cond_truthy`."""
+    return if_not_block(cond_truthy(var_class, idx), set_region(zone)) + opcodes.RETURN
+
+
+def build_region_entry(zone, range_body: bytes, *, init_extra: bytes = b"", tag: int = RANGE_TAG,
+                       init_body: bytes | None = None) -> bytes:
+    """Assemble a type-1 region entry: Init (tag 0 = SetRegion(zone) + ``init_extra``; return) + a
+    trigger func at ``tag`` (default :data:`RANGE_TAG` 2 = tread, every frame in the quad;
+    :data:`INTERACT_TAG` 3 = press-action-in-quad, a lever/sign). ``init_extra`` runs once on field
+    load (when InitRegion arms the region) -- e.g. a ``set flag = 0`` to re-arm a once-per-visit
+    tread trigger each visit. ``init_body`` overrides the Init body entirely (e.g.
+    :func:`gated_set_region` for a one-shot trigger that vanishes once spent)."""
+    ib = init_body if init_body is not None else (set_region(zone) + init_extra + opcodes.RETURN)
+    funcs = [(0, ib), (tag, range_body)]
+    table_len = len(funcs) * 4
+    table = bytearray()
+    pos = table_len
+    for tag, body in funcs:
+        table += struct.pack("<HH", tag, pos)
+        pos += len(body)
+    return bytes([REGION_ENTRY_TYPE, len(funcs)]) + bytes(table) + b"".join(b for _, b in funcs)
+
+
+def prepend_range_gate(data, slot: int, gate_bytes: bytes) -> bytes:
+    """Insert ``gate_bytes`` at the start of the region in ``slot``'s Range (tag 2) function, so the
+    trigger only runs when the gate passes. Safe via :func:`edit.insert_bytes`: Range is the entry's
+    LAST function, so the gate just becomes its first bytes and no func-table ``fpos`` needs fixing."""
+    eb = EbScript.from_bytes(data)
+    rng = eb.entry(slot).func_by_tag(RANGE_TAG)
+    if rng is None:
+        raise ValueError(f"entry {slot} has no Range (tag {RANGE_TAG}) to gate")
+    if rng.abs_end != eb.entry(slot).abs_end:
+        raise ValueError(f"Range is not the last function of entry {slot}; cannot prepend safely")
+    return edit.insert_bytes(data, rng.abs_start, gate_bytes)
+
+
+def inject_region(data, zone, range_body: bytes, *, slot: int | None = None, activate: bool = True,
+                  spawn_wait_n: int = 2, spawn_wait_occurrence: int = 0, init_extra: bytes = b"",
+                  tag: int = RANGE_TAG, init_body: bytes | None = None, reserve_party_band: bool = False):
+    """Append a conditional region (Init=SetRegion(zone) + ``init_extra``, Range=range_body) into a
+    free slot.
+
+    Returns ``(new_bytes, slot)``. If ``activate`` (default), the region is turned on at field load
+    by overwriting a Main_Init ``Wait(n)`` filler with ``InitRegion(slot, 0)`` -- shift-free. Pass
+    ``activate=False`` for a zone that another zone enables at runtime (the switch-pair toggle).
+    ``init_extra`` runs in the region's Init on each load (e.g. a flag reset for once-per-visit).
+    ``reserve_party_band`` (the VERBATIM-fork path): seat the region BELOW the engine's reserved
+    party-character band instead of into a free slot (else it lands in an unused character slot)."""
+    from . import object as _object             # local: object imports region -> avoid the top-level cycle
+    entry = build_region_entry(zone, range_body, init_extra=init_extra, tag=tag, init_body=init_body)
+    out, slot = _object.seat_entry(data, entry, reserve_party_band=reserve_party_band, slot=slot)
+    if activate:
+        out = edit.activate(out, opcodes.init_region(slot, 0), spawn_wait_n=spawn_wait_n,
+                            spawn_wait_occurrence=spawn_wait_occurrence)
+    return out, slot

ff9mapkit/content/reinit.py

@@ -0,0 +1,59 @@
+"""Add the after-battle handler (entry-0 tag-10 "Main_Reinit") a custom field needs.
+
+After a random battle, EventEngine restores the field then calls Request(entry0, 0, 10).
+``EnterBattleEnd`` has suspended every object; only when the tag-10 handler RETURNS at level
+0 does ``ExitBattleEnd`` un-suspend them. Battle fields ship a Main_Reinit; fields cloned
+from a cutscene field (like our blank) have none, so the player stays frozen after battle.
+
+Minimal handler: ``EnableMove ; return``. With ``with_fade=True`` it is prefixed with a quick
+``FadeFilter`` fade-in, because the battle-return fade is a 256-frame *timed* fade that only a
+field-issued FadeFilter overrides (Main_Init issues one, but after battle the field runs
+tag-10, not Main_Init).
+
+Re-layout: entry-0's function table grows by one 4-byte slot (existing funcs' fpos += 4); the
+new function body is appended after entry-0's code; every later entry shifts in the file so
+its entry-table offset += growth. entryCount is unchanged.
+"""
+
+from __future__ import annotations
+
+import struct
+
+from ..binutils import set_u16, u16
+from ..eb import EbScript, opcodes
+
+REINIT_TAG = 10
+
+
+def add_reinit(eb_bytes, *, with_fade: bool = True, fade_frames: int = 16,
+               tag: int = REINIT_TAG) -> bytes:
+    """Add an entry-0 tag-10 handler (EnableMove; return), optionally with a fast fade-in."""
+    body = b""
+    if with_fade:
+        body += opcodes.fade_filter(2, fade_frames, 0, 0, 0, 0)   # SUB => fade-IN over N frames
+    body += opcodes.ENABLE_MOVE + opcodes.RETURN
+
+    b = bytearray(eb_bytes)
+    entry_count = b[3]
+    off0, sz0 = u16(b, 128), u16(b, 130)
+    es = 128 + off0
+    etype, fc = b[es], b[es + 1]
+    fbase = es + 2
+    funcs = [[u16(b, fbase + i * 4), u16(b, fbase + i * 4 + 2)] for i in range(fc)]
+    if any(t == tag for t, _ in funcs):
+        raise ValueError(f"entry 0 already has a function with tag {tag}")
+    code = bytes(b[fbase + fc * 4: es + sz0])
+    new_funcs = [[t, fp + 4] for t, fp in funcs] + [[tag, (fc + 1) * 4 + len(code)]]
+    new_entry = bytearray([etype, fc + 1])
+    for t, fp in new_funcs:
+        new_entry += struct.pack("<HH", t, fp)
+    new_entry += code + body
+    growth = len(new_entry) - sz0
+
+    out = bytearray(bytes(b[:es]) + bytes(new_entry) + bytes(b[es + sz0:]))
+    set_u16(out, 130, len(new_entry))                          # entry-0 size
+    for i in range(1, entry_count):                             # relocate later entries
+        slot = 128 + i * 8
+        if u16(out, slot + 2) > 0 and u16(out, slot) > off0:
+            set_u16(out, slot, u16(out, slot) + growth)
+    return bytes(out)

ff9mapkit/content/savepoint.py

@@ -0,0 +1,90 @@
+"""Save-point synthesis -- a functional FF9 save point as a press-to-interact region.
+
+The FUNCTIONAL save is a single opcode: ``Menu(4, 0)`` (0x75) -> ``EventService.StartMenu`` ->
+``OpenSaveMenu`` (``SaveLoadUI.SerializeType.Save``). Verified byte-exact (``75 00 04 00``) against the
+real Dali save moogle (field 122 entry 5 tag 3). The real moogle's full act -- jump out of the barrel,
+the Save/Shop dialogue choice, the player-pose ``RunScriptAsync`` surgery -- is COSMETIC; none of it is
+needed to save the game. So instead of grafting that un-graftable 7-entry-ish cluster, the kit SYNTHESIZES
+the save: a press-action region whose interact func opens the save menu.
+
+It is the navigable cousin of :mod:`content.jump`'s ``action`` region -- same Init ``SetRegion`` / tread
+``Bubble`` ("!") / action shape -- but the action dispatch is ``DisableMove; Menu(4, 0); EnableMove``
+instead of a player-arc ``RunScriptSync`` (so, unlike a jump, NO player-function graft is required; the
+save is a self-contained engine call). The optional visible barrel/moogle set-dressing + the cosmetic
+jump-out are a separate, later layer (place a ``[[prop]]``/``[[npc]]`` over the zone); this is the
+functional core.
+"""
+from __future__ import annotations
+
+import struct
+
+from ..eb import EbScript, edit, opcodes
+from . import region as _region
+
+SAVE_MENU_ID = 4          # EventService.FF9Menu_Command case 4u -> OpenSaveMenu
+SAVE_SUB_ID = 0           # OpenSaveMenu requires sub_id == 0
+
+
+def save_dispatch() -> bytes:
+    """The interact body: ``DisableMove; Menu(4, 0); EnableMove; RETURN``. Locks control while the save
+    UI is up (so the player can't walk under it) and restores it after -- mirrors the jump action's
+    ``DisableMove ... EnableMove`` bracket, with the save menu in place of the arc."""
+    return (opcodes.DISABLE_MOVE
+            + opcodes.menu(SAVE_MENU_ID, SAVE_SUB_ID)
+            + opcodes.ENABLE_MOVE + opcodes.RETURN)
+
+
+def _assemble_entry(funcs) -> bytes:
+    """Assemble a type-1 (region) entry from ``[(tag, body), ...]`` -- the func table (4 bytes/func:
+    ``<tag:u16><fpos:u16>``) then the concatenated bodies. Same layout as :func:`content.jump`."""
+    table = b""
+    pos = len(funcs) * 4
+    for tag, body in funcs:
+        table += struct.pack("<HH", tag, pos)
+        pos += len(body)
+    return bytes([_region.REGION_ENTRY_TYPE, len(funcs)]) + table + b"".join(b for _, b in funcs)
+
+
+def savepoint_region(zone, *, bubble: bool = True) -> bytes:
+    """A type-1 region entry for a save point: Init ``SetRegion(zone)`` / tread (tag 2) ``Bubble(1)`` (the
+    floating "!" prompt, if ``bubble``) / action (tag 3) :func:`save_dispatch`. Both trigger funcs are
+    gated by :data:`content.region.MOVEMENT_GATE` (fire only while ``usercontrol == 1``), exactly like
+    every real exit/switch/jump region."""
+    init = _region.set_region([tuple(p) for p in zone]) + opcodes.RETURN
+    tread = _region.MOVEMENT_GATE + (opcodes.bubble(1) if bubble else b"") + opcodes.RETURN
+    action = _region.MOVEMENT_GATE + save_dispatch()
+    funcs = [(0, init), (_region.RANGE_TAG, tread), (_region.INTERACT_TAG, action)]
+    return _assemble_entry(funcs)
+
+
+def inject_savepoint(data, zone, *, bubble: bool = True, activate: bool = True):
+    """Inject one save point: append a save-point region at the next free slot and arm it (``InitRegion``
+    in Main_Init). Returns ``(new_bytes, region_slot)``. ``zone`` is a 4- or 5-point quad (the press
+    area); ``bubble=False`` hides the "!" prompt (e.g. when a visible model already signals the save)."""
+    eb = EbScript.from_bytes(data)
+    slot = eb.first_free_slot()
+    data = edit.append_entry(data, slot, savepoint_region(zone, bubble=bubble))
+    if activate:
+        data = edit.activate(data, opcodes.init_region(slot, 0))
+    return data, slot
+
+
+def inject_savepoints(data, savepoints, *, activate: bool = True):
+    """Inject every ``[[savepoint]]`` (each a dict with ``zone`` + optional ``bubble``). Returns
+    ``(new_bytes, [slot, ...])``."""
+    slots = []
+    for sp in savepoints:
+        data, slot = inject_savepoint(data, sp["zone"], bubble=sp.get("bubble", True), activate=activate)
+        slots.append(slot)
+    return data, slots
+
+
+def graft_director(data, director_body):
+    """Graft the save-sequence DIRECTOR (the donor field's entry-0 tag-1, from
+    :func:`eventscan.extract_savepoint_director`) into the fork's EMPTY entry-0 tag-1, so it puppeteers the
+    carried save Moogle. The director references no entries -- it drives the Moogle through shared transient
+    MAP vars only -- so it grafts VERBATIM (replace the empty system-loop body with it). The carried Moogle +
+    carried cask + this director then reconstitute the source field's exact state machine over those shared
+    vars: the Moogle lowers into the barrel, pops out on a cask push, and runs the save flourish. The fork's
+    entry-0 tag-1 is empty in a blank field, so this is a clean swap (docs/SAVEPOINT.md)."""
+    return edit.replace_function_body(data, 0, 1, bytes(director_body))