ff9mapkit 1.0.0b3__py3-none-any.whl

ff9mapkit/content/event.py

@@ -0,0 +1,191 @@
+"""One-shot field EVENTS -- walk-into-a-zone triggers that fire authored logic, optionally once.
+
+This is the conditional-region primitive (:mod:`ff9mapkit.content.region`) cashed in as authorable
+content. An event is a region whose ``_Range`` runs a composed sequence -- show a message, give an
+item / gil, set a story flag -- gated by a GlobBool so an ``once`` event (a looted chest, a one-time
+line, an ATE) never re-fires. Same shape the real game uses for treasure (decoded from a real chest
+handler: ``AddItem`` + a "received X" ``WindowSync``) and the same flag-gated ``if (!done){..;
+done=1}`` the camera-switch zones use.
+
+Compose a body from the part builders (:func:`message` / :func:`give_item` / :func:`give_gil` /
+:func:`set_flag`); :func:`inject_events` adds any number of events through a SINGLE arming entry (so
+they don't each consume a Main_Init ``Wait`` filler).
+"""
+
+from __future__ import annotations
+
+import struct
+
+from .. import items as _items
+from ..eb import EbScript, edit, opcodes
+from . import region as _region
+
+# 'once' flags live in the SAVE-PERSISTENT Global bool (region.GLOB_BOOL) so a looted chest / one-time
+# event stays done across field reloads + saves. The base is high in gEventGlobal (byte ~1000) to stay
+# clear of the base game's flags (which sit low); override per event with `flag = N`.
+EVENT_FLAG_CLASS = _region.GLOB_BOOL
+EVENT_FLAG_BASE = 8000
+
+
+def message(text_id: int, *, window: int = 1, flags: int = 128) -> bytes:
+    """Body part: open a dialogue window (WindowSync) showing text ``text_id``."""
+    return opcodes.window_sync(window, flags, text_id)
+
+
+def give_item(item_id, count: int = 1) -> bytes:
+    """Body part: AddItem(item, count). ``item_id`` may be a numeric id OR a name ("Potion") --
+    resolved via :mod:`ff9mapkit.items` so authors don't have to memorize ids. Works for ANY item,
+    including weapons/armor ("Excalibur") -- the engine renders the name in the "Received X" box."""
+    return opcodes.add_item(_items.resolve(item_id), count)
+
+
+def take_item(item_id, count: int = 1) -> bytes:
+    """Body part: RemoveItem(item, count) -- the symmetric counterpart of :func:`give_item` (a trade,
+    a quest-item consume). ``item_id`` may be a numeric id OR a name; the engine clamps to what's held."""
+    return opcodes.remove_item(_items.resolve(item_id), count)
+
+
+def give_gil(amount: int) -> bytes:
+    """Body part: change the party's gil by ``amount`` -- positive ADDS (AddGil), negative SUBTRACTS
+    (RemoveGil). The two opcodes both take an unsigned amount, so we pick by sign here (a negative
+    ``amount`` would otherwise wrap to a huge ADD and max out gil)."""
+    return opcodes.add_gil(amount) if amount >= 0 else opcodes.remove_gil(-amount)
+
+
+def set_flag(flag_idx: int, value: int = 1, *, flag_class=EVENT_FLAG_CLASS) -> bytes:
+    """Body part: set a GlobBool story flag (gate other content on it)."""
+    return _region.set_var(flag_class, flag_idx, value)
+
+
+def reveal_object(slot: int) -> bytes:
+    """Body part: re-run an object's Init (``InitObject``). Used after :func:`set_flag` to make a
+    flag-gated NPC appear (or vanish) LIVE in the same room -- its Init re-evaluates the gate with the
+    flag's new value (without this, a gated NPC only updates on field re-entry, since Init runs once
+    at spawn)."""
+    return opcodes.init_object(slot, 0)
+
+
+# RunSoundCode(265, 65535): the field-transition whoosh present byte-identically in EVERY real warp
+# (verified in the airship 455<->457, the Dali innkeeper 351->352, Gargan Roo 950->914 talk handlers).
+WARP_SOUND = (265, 65535)
+
+
+# The proven field-transition fade-out, byte-identical to what ladders + gateways emit (and what the
+# engine itself does on a worldmap entry): FadeFilter(mode 6 = SUB, 24f, target colour white) drives the
+# screen to BLACK (SUB shows `screen - colour`, so colour=white => black), then Wait(25) holds until the
+# fade has fully finished. Confirmed against SceneDirector.InitFade/ServiceFade + content.ladder.
+WARP_FADE = (6, 24, 0, 255, 255, 255)
+
+
+def warp(target: int, entrance: "int | None" = None, *, fade: bool = False) -> bytes:
+    """Body part: warp the player to ``Field(target)``. Grounded in real *talk-handler* warps -- a Field
+    op TRANSITIONS directly from an event / tag-3 _SpeakBTN context (unlike a bare Field in Main_Init,
+    which no-ops -- see memory project_ff9_field_warp_pattern); 14+ shipping fields warp the player from a
+    tag-3 handler this way (the Dali innkeeper, the airship, Gargan Roo...). Plays the transition sound,
+    then warps. The warp TRANSITIONS AWAY, so this MUST be the LAST part of a body (anything after is
+    unreachable).
+
+    ``fade`` (default False) prepends the proven transition FADE-OUT (:data:`WARP_FADE` + ``Wait(25)``).
+    This is what fixes the World-Hub "static screen on spawn": a bare ``Field()`` warp transitions with the
+    SOURCE field still fully drawn, so the destination loads *in the clear* and you SEE its camera-init
+    frames (the smooth-cam needs ~0.8s to wire up player-tracking -- ``FieldMap.SceneService3DScroll`` --
+    during which the camera sits on the bare scene centre with the player off in a corner). Every real
+    gateway/ladder/worldmap entry fades to black FIRST, so the destination loads black and its own reveal
+    fade (and any ``[camera] entry_settle``) hides the wire-up. ``fade=True`` makes the choice-warp do the
+    same. (The destination's reveal LERPs the SUB layer from white->black; if the source never set it to
+    white, that reveal is a no-op and nothing is hidden -- which is exactly the bug.)
+
+    ``entrance`` (when set) writes the ARRIVAL-ENTRANCE var (D8:2) before the warp, like a gateway
+    (:func:`ff9mapkit.content.region.set_field_entrance`) -- the destination's player-init may switch on it
+    to place the player. NOTE it is NOT a camera fix and is silently overridden by destinations whose
+    Main_Init rewrites D8:2 on entry (e.g. the forked Ice Cavern sets D8:2=10000 up front); the fade is the
+    camera fix. Default None = no entrance write."""
+    pre = opcodes.fade_filter(*WARP_FADE) + opcodes.wait(25) if fade else b""
+    if entrance is not None:
+        pre += _region.set_field_entrance(int(entrance))
+    return pre + opcodes.run_sound_code(*WARP_SOUND) + opcodes.field(int(target))
+
+
+def set_scenario(value: int) -> bytes:
+    """Body part: set the ScenarioCounter (the story beat) -- the save-backed gEventGlobal UInt16 @0.
+    Reuses :func:`ff9mapkit.content.startup.startup_body` (story_flags' lever) so an event/choice can
+    advance the beat (e.g. a hub journey-pick seeds the destination's beat before the warp)."""
+    from . import startup as _startup
+    return _startup.startup_body([], scenario=int(value))
+
+
+def event_range_body(body: bytes, once_flag: int | None, flag_class=EVENT_FLAG_CLASS,
+                     requires_flag: int | None = None, requires_set: bool = True,
+                     space_item: int | None = None) -> bytes:
+    """The region ``_Range`` body for an event: a movement gate, an optional ``requires_flag`` story
+    gate (the event only fires when that flag is in-state), then ``body`` -- gated
+    ``if (!flag) { flag = 1; body }`` when ``once_flag`` is set, so it fires once. The once-flag is set
+    BEFORE the body, matching FF9's treasure-chest convention (``if(!opened){ opened=1; reward; msg }``):
+    the dedup flag lands the instant the event fires, before any (movement-unblocking) reward message --
+    so it can't double-fire even if the reward window is left open.
+
+    ``space_item`` (a chest nicety) wraps everything in ``if (GetItemCount(item) < 99) { ... }`` so the
+    reward is skipped (and the once-flag NOT set -> retryable) when the bag is full -- exactly FF9's
+    item-chest guard, with the space check OUTERMOST."""
+    parts = [_region.MOVEMENT_GATE]
+    if requires_flag is not None:
+        parts.append(_region.flag_gate(flag_class, requires_flag, require_set=requires_set))
+    if once_flag is not None:
+        core = _region.if_block(_region.cond_not(flag_class, once_flag),
+                                _region.set_var(flag_class, once_flag, 1) + body)
+    else:
+        # No once flag = the raw region trigger: tag 2 is LEVEL-triggered (the engine fires it every
+        # frame the player treads the quad -- TreadQuad is a pure position test, no edge detection), so
+        # a `once=false` message re-fires as soon as it closes while still inside. Correct for a
+        # continuous effect; edge-triggered "once per visit" would need a leave-detecting re-arm zone.
+        core = body
+    if space_item is not None:                       # FF9 chest: only give if there's room (space outermost)
+        core = _region.if_block(_region.cond_item_count_lt(space_item), core)
+    parts.append(core)
+    parts.append(opcodes.RETURN)
+    return b"".join(parts)
+
+
+def inject_event(data, *, zone, body: bytes, once_flag: int | None = None,
+                 requires_flag: int | None = None, requires_set: bool = True,
+                 flag_class=EVENT_FLAG_CLASS, slot=None, spawn_wait_n: int = 2,
+                 spawn_wait_occurrence: int = 0, reserve_party_band: bool = False):
+    """Inject ONE walk-in event region (armed at load via InitRegion-over-Wait). Returns
+    ``(new_bytes, slot)``. For several events prefer :func:`inject_events` (one shared arm entry)."""
+    range_body = event_range_body(body, once_flag, flag_class, requires_flag, requires_set)
+    return _region.inject_region(data, zone, range_body, slot=slot, activate=True,
+                                 spawn_wait_n=spawn_wait_n, spawn_wait_occurrence=spawn_wait_occurrence,
+                                 reserve_party_band=reserve_party_band)
+
+
+def inject_events(data, events, *, flag_class=EVENT_FLAG_CLASS, spawn_wait_n: int = 2,
+                  spawn_wait_occurrence: int = 0, reserve_party_band: bool = False) -> bytes:
+    """Inject many events through a single arming entry. ``events`` is a list of dicts with keys
+    ``zone`` (corners), ``body`` (composed action bytes), ``once_flag`` (int or None).
+
+    Each event becomes a region (appended, not auto-armed); one type-0 code entry then ``InitRegion``s
+    them all and is activated once via ``InitCode`` over a Main_Init ``Wait`` filler -- so N events
+    cost ONE filler, not N. ``reserve_party_band`` (the VERBATIM-fork path): every region AND the arm
+    entry are seated BELOW the reserved party-character band. The arm's ``InitRegion`` targets the region
+    SLOTS, which sit below the band and so are never shifted by a later below-band insert -> stay valid.
+    Returns new .eb bytes."""
+    events = list(events)
+    if not events:
+        return data if isinstance(data, (bytes, bytearray)) else data.to_bytes()
+    out = data if isinstance(data, (bytes, bytearray)) else data.to_bytes()
+    region_slots = []
+    for ev in events:
+        rb = event_range_body(ev["body"], ev.get("once_flag"), flag_class,
+                              ev.get("requires_flag"), ev.get("requires_set", True),
+                              space_item=ev.get("space_item"))
+        out, slot = _region.inject_region(out, ev["zone"], rb, activate=False,
+                                          reserve_party_band=reserve_party_band)
+        region_slots.append(slot)
+
+    arm = b"".join(opcodes.init_region(s, 0) for s in region_slots) + opcodes.RETURN
+    arm_entry = bytes([0x00, 0x01]) + struct.pack("<HH", 0, 4) + arm
+    from . import object as _object             # local: object imports region -> avoid the top-level cycle
+    out, arm_slot = _object.seat_entry(out, arm_entry, reserve_party_band=reserve_party_band)
+    out = edit.activate(out, opcodes.init_code(arm_slot, 0), spawn_wait_n=spawn_wait_n,
+                        spawn_wait_occurrence=spawn_wait_occurrence)
+    return out

ff9mapkit/content/gateway.py

@@ -0,0 +1,101 @@
+"""Inject a field-exit gateway (a region trigger that warps to another field).
+
+Clones the proven field-109 exit-region template (a SetRegion polygon ->
+CalculateExitPosition/ExitField -> PreloadField -> FadeFilter -> set FieldEntrance ->
+Field(target)), patches its trigger polygon + target field + arrival entrance, appends it
+into a free entry slot, and activates it by overwriting a Main_Init ``Wait(2)`` filler with
+``InitRegion`` (shift-free).
+
+Zone gotchas (baked into :func:`quad_zone`): the engine's IsInQuad tests a *fan* of
+consecutive vertex triplets, so three collinear points make a dead zone — use a convex quad
+with the **last vertex doubled** (5 points). Point order matters: q0->q1 is the edge the
+player walks out across, so put the front edge first for a natural forward exit.
+"""
+
+from __future__ import annotations
+
+import struct
+
+from .. import data
+from ..eb import EbScript, edit, opcodes
+from . import region as _region
+
+# offsets within the 272-byte region template
+REL_PTS, REL_ENTRANCE, REL_FIELD = 13, 263, 269
+
+
+def quad_zone(corners) -> list:
+    """Make a 5-point IsInQuad-safe zone from 4 (x, z) corners (doubles the last vertex)."""
+    pts = [tuple(c) for c in corners]
+    if len(pts) != 4:
+        raise ValueError("quad_zone needs 4 corners")
+    return pts + [pts[-1]]
+
+
+def inject_gateway(eb_bytes, target: int, *, entrance: int = 0, zone, slot: int | None = None,
+                   spawn_wait_n: int = 2, spawn_wait_occurrence: int = 0,
+                   gate_flag: int | None = None, gate_require_set: bool = True,
+                   on_exit_body: bytes = b"", reserve_party_band: bool = False) -> bytes:
+    """Inject an exit gateway to ``Field(target)`` arriving at ``entrance``. Returns new bytes.
+
+    ``gate_flag`` (a GlobBool index) locks the exit behind a story flag: the region's trigger returns
+    early unless the flag is in the required state (``gate_require_set`` True = open when SET, e.g. a
+    door that unlocks once a switch flag is set; False = open when CLEAR).
+
+    ``on_exit_body`` (raw ``set_var`` bytes -- e.g. from :func:`ff9mapkit.content.startup.startup_body`)
+    ADVANCES story state when the player TAKES this exit: it is prepended to the Range trigger behind a
+    ``usercontrol`` guard, so the writes fire only on an actual walk-out (not while the player is puppeted
+    through with control disabled) and -- when the exit is also ``gate_flag``-locked -- only when the gate
+    passes (the flag gate sits ahead of the writes). The byte sequence runs just before the template's own
+    warp path, so the ScenarioCounter / story bits commit to the save-backed gEventGlobal before the
+    transition. Empty -> no change (the gateway builds byte-identically to before)."""
+    zone = list(zone)
+    if len(zone) != 5:
+        raise ValueError("zone must be 5 points (convex quad + doubled last vertex); see quad_zone()")
+    tpl = bytearray(data.region_template())
+    for i, (x, z) in enumerate(zone):
+        struct.pack_into("<hh", tpl, REL_PTS + i * 4, int(x), int(z))
+    struct.pack_into("<H", tpl, REL_ENTRANCE, entrance)
+    struct.pack_into("<H", tpl, REL_FIELD, target)
+
+    from . import object as _object             # local: object imports region -> avoid the top-level cycle
+    out, slot = _object.seat_entry(eb_bytes, bytes(tpl), reserve_party_band=reserve_party_band, slot=slot)
+    out = edit.activate(out, opcodes.init_region(slot, 0), spawn_wait_n=spawn_wait_n,
+                        spawn_wait_occurrence=spawn_wait_occurrence)
+    # Order matters: prepend the on-exit writes first, then the flag gate, so the final Range reads
+    # [flag gate] -> [usercontrol guard + writes] -> [template warp]. (Each prepend goes to Range's start.)
+    if on_exit_body:
+        out = _region.prepend_range_gate(out, slot, _region.MOVEMENT_GATE + on_exit_body)
+    if gate_flag is not None:
+        out = _region.prepend_range_gate(out, slot, _region.flag_gate(
+            _region.GLOB_BOOL, gate_flag, require_set=gate_require_set))
+    return out
+
+
+def graft_gateway_entry(eb_bytes, entry_bytes, *, retarget=None, slot=None):
+    """Graft a story-gated door's region entry VERBATIM (preserving its whole conditional state machine), then
+    arm it -- the faithful counterpart to :func:`inject_gateway`'s re-synthesis. A real story-gated door
+    (``eventscan.scan_gateway_entries`` ``story_gated``) checks GLOB save flags in a complex conditional the
+    declarative rebuild can't reproduce; carrying the entry whole keeps that logic, and its GLOB conditions
+    then read the ``[startup]``-preset story state (docs/FORK_FIDELITY.md #2b). Mirrors the object carry.
+
+    ``retarget`` maps a real destination field id -> a new id; each ``Field(id)`` literal whose id is in the
+    map is patched in place (ids NOT in the map are left as live seams, like the import's live-seam doors).
+    ``slot`` defaults to the first free entry. Returns ``(new_bytes, slot)``.
+
+    LIMIT: a door-only carry does NOT reconstruct MAP/transient vars the field's *main* logic sets on entry,
+    so a door whose firing also depends on those may still mis-evaluate (documented; ~30% of gated entries
+    also reference other entries and aren't carried by this path at all)."""
+    eb = EbScript.from_bytes(eb_bytes)
+    if slot is None:
+        slot = eb.first_free_slot()
+    out = edit.append_entry(eb_bytes, slot, bytes(entry_bytes))
+    if retarget:
+        ge = EbScript.from_bytes(out)
+        buf = bytearray(out)
+        for f in ge.entry(slot).funcs:
+            for i in ge.instrs(f):
+                if i.op == 0x2B and i.imm(0) in retarget:          # Field(id) -> retarget[id] (2-byte literal @ +2)
+                    struct.pack_into("<H", buf, i.off + 2, int(retarget[i.imm(0)]) & 0xFFFF)
+        out = bytes(buf)
+    return edit.activate(out, opcodes.init_region(slot, 0)), slot

ff9mapkit/content/inventory.py

@@ -0,0 +1,59 @@
+"""``[start_inventory]`` -- author the NEW-GAME starting bag (the items the player begins a New Game with).
+
+Writes ``<mod>/StreamingAssets/Data/Items/InitialItems.csv``. ★ The engine reads this
+**HIGHEST-PRIORITY-WINS** (NOT merged -- ``ff9item.LoadInitialItems`` via ``GetCsvWithHighestPriority``), so
+this file **REPLACES the base starting bag entirely**: list the COMPLETE intended inventory. A stacked mod
+folder that also defines ``InitialItems.csv`` SHADOWS this one (the ``text_block`` trap) -> the build lints.
+
+Read ONCE at new-game init, so it only affects a true **New Game** (not an F6 / campaign mid-game entry).
+It is mod-global (one bag per mod) and lives on the ENTRY field's ``field.toml`` -- emitted at the mod-write
+stage, not into any field's ``.eb``. (memory project-ff9-items-equipment / project-ff9-branch-lanes.)
+
+    [start_inventory]
+    items = [["Potion", 20], ["Phoenix Down", 5], ["Tent", 3], ["Ether", 10]]
+"""
+from __future__ import annotations
+
+from .. import items as _items
+
+NO_ITEM = 255          # the empty sentinel -- never a real starting item
+MAX_COUNT = 99         # the per-item inventory cap (UInt8 column; the engine clamps, we clamp too)
+
+
+def inventory_rows(items) -> list:
+    """``[[name, count], ...]`` (or bare names) -> sorted ``[(item_id, count), ...]`` -- names resolved,
+    dup ids summed, counts clamped 1..99, NoItem dropped. Raises ValueError (via :func:`items.resolve`) on an
+    unknown name."""
+    by_id: dict = {}
+    for entry in items:
+        if isinstance(entry, (list, tuple)):
+            name = entry[0]
+            count = int(entry[1]) if len(entry) > 1 else 1
+        else:
+            name, count = entry, 1
+        iid = _items.resolve(name)
+        if iid == NO_ITEM:
+            continue
+        by_id[iid] = min(MAX_COUNT, by_id.get(iid, 0) + max(1, count))
+    return sorted(by_id.items())
+
+
+def render_initial_items(items) -> str:
+    """The FULL ``InitialItems.csv`` text (header + ``id;count;# name`` rows). Replaces the base bag entirely
+    (highest-priority-wins), so this is the complete starting inventory."""
+    lines = [
+        "# ff9mapkit [start_inventory] -- the FULL new-game starting bag (REPLACES the base; highest-priority-wins).",
+        "# ItemID;Count",
+        "# Int32;UInt8",
+    ]
+    for iid, count in inventory_rows(items):
+        nm = _items.name_of(iid)
+        lines.append(f"{iid};{count};" + (f"# {nm}" if nm else ""))
+    return "\n".join(lines) + "\n"
+
+
+def write_initial_items(layout, items) -> None:
+    """Pure writer: emit the starting-bag CSV into ``layout``'s mod root (``Data/Items/InitialItems.csv``)."""
+    path = layout.initial_items_csv
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(render_initial_items(items), encoding="utf-8", newline="\n")