ff9mapkit 1.0.0b3__py3-none-any.whl

ff9mapkit/content/textcarry.py

@@ -0,0 +1,290 @@
+"""Faithful TEXT carry -- ship a donor field's referenced ``.mes`` text VERBATIM + remap the txids.
+
+The object graft (:mod:`content.object`) and player-function graft (:mod:`content.player`) carry a real
+field's NPCs/props + their interactions byte-for-byte. But a window those grafted bytes open
+(``WindowSync``/``WindowAsync[Ex]``) names a donor ``.mes`` TXID -- and a fork ships its OWN ``.mes`` block
+(authored lines from :func:`build.collect_text`, at a high band), so that donor id resolves to nothing: an
+EMPTY window. This module closes that last gap: it CARRIES the donor's referenced field text (per language,
+verbatim) and REMAPS each grafted window's TXID to a fresh band, so the forked interactions show the real
+words. It is the faithful counterpart to ``import --dialogue`` (which appends EDITABLE ``[[npc]]`` stubs the
+author re-writes); carry ships the donor strings unchanged.
+
+It is IMPORT-ONLY and OPT-IN (the ``import --carry-text`` flag). It never touches the authored-dialogue path
+(:mod:`content.text` / :func:`build.collect_text` stay byte-for-byte; the hut golden is preserved): carried
+text is APPENDED after the authored block, in a disjoint txid band.
+
+Engine / format facts this relies on (verified against the real bytes -- see docs/TEXT_CARRY.md):
+
+  * A window's TXID is a 2-BYTE immediate operand (operand 2 for ``WindowSync``/``WindowAsync`` 0x1F/0x20,
+    operand 3 for the ``...Ex`` variants 0x95/0x96 -- :data:`dialogue.WINDOW_OPS`). Re-emitting at a band
+    >= :data:`CARRY_BASE_TXID` (1000) keeps the new id in 2 bytes -> a SAME-LENGTH in-place patch via
+    :func:`content.object._arg_byte_offset` (the exact primitive the slot/uid remap uses). FF9 NEVER computes
+    a window txid (census: 0/24166 expression txids), so every one is statically remappable.
+  * The carry BAND must clear the base game's real txids (census max = 863, field 1607) AND the fork's own
+    authored band (:data:`content.text.DEFAULT_BASE_TXID` = 500). 1000 is the first unconditionally-safe
+    floor (no real field uses a txid >= 1000) and still a 2-byte immediate (<= 65535).
+  * ``.mes`` text is PER-LANGUAGE (the 7 :data:`config.LANGS`). The carried text is shipped in EVERY language
+    the build ships; a per-language entry is carried VERBATIM -- an empty entry stays empty (field 357 txid
+    470 is empty in us/uk but populated in fr/gr/it/jp -- a us-fallback would WIPE the French/German text).
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Optional
+
+from .. import dialogue as _dialogue
+from ..config import LANGS
+from ..eb import EbScript
+from ..eb.disasm import argsize
+from . import object as _object
+
+# The carried-text txid band: clear of the base game (max real txid 863) AND the fork's authored 500+ band,
+# and still a 2-byte immediate so every window remap is a same-length in-place patch. See the module note.
+CARRY_BASE_TXID = 1000
+
+
+@dataclass(frozen=True)
+class CarriedEntry:
+    """One donor ``.mes`` entry carried per-language. ``texts[lang]`` is the verbatim string for that
+    language (``''`` for an empty/absent donor entry -- carried as-is, never us-filled). ``strt``/``tail``
+    are the donor's window-geometry tags, preserved verbatim from the language the scan was keyed on (they
+    are language-independent geometry, not text)."""
+    donor_txid: int
+    new_txid: int
+    texts: dict                       # lang -> verbatim text (may be "")
+    strt: Optional[str] = None
+    tail: Optional[str] = None
+
+
+# --------------------------------------------------------------- which txids a graft will SHOW ---
+def _grafted_object_windows(donor_eb, specs) -> set:
+    """Every TXID a CARRIED object's grafted bytes will open. For each spec, the carried funcs are its
+    ``carry_tags`` (``None`` = whole entry); we decode the donor entry and collect each window operand's txid
+    in the kept funcs. A REFUSED spec (``graft_safety == "refuse"``) carries nothing -> skipped, matching
+    :func:`content.object.graft_objects`."""
+    eb = donor_eb if isinstance(donor_eb, EbScript) else EbScript.from_bytes(donor_eb)
+    out: set = set()
+    for s in specs:
+        if s.get("graft_safety") == "refuse":
+            continue
+        slot = int(s["donor_idx"])
+        if not 0 <= slot < eb.entry_count:
+            continue
+        keep = s.get("carry_tags")
+        keep = None if keep is None else {int(t) for t in keep}
+        e = eb.entry(slot)
+        if e.empty:
+            continue
+        for f in e.funcs:
+            if keep is not None and f.tag not in keep:
+                continue
+            for ins in eb.instrs(f):
+                opnd = _dialogue.WINDOW_OPS.get(ins.op)
+                if opnd is None:
+                    continue
+                if opnd < len(ins.arg_is_expr) and ins.arg_is_expr[opnd]:
+                    continue                         # computed txid (does not occur in real fields) -- skip
+                txid = ins.imm(opnd)
+                if txid is not None:
+                    out.add(int(txid))
+    return out
+
+
+def _grafted_player_windows(player_specs) -> set:
+    """Every TXID a grafted PLAYER function will open. Only ``clean`` and ``text`` player funcs are carried
+    (a ``text`` func is graftable once its windows are remapped -- the whole point of carry); we decode each
+    grafted body and collect its window txids. Other safety classes are not grafted -> skipped."""
+    out: set = set()
+    for s in player_specs:
+        if s.get("safety") not in ("clean", "text"):
+            continue
+        body = s.get("body")
+        if not body:
+            continue
+        for ins in _object_iter(body):
+            opnd = _dialogue.WINDOW_OPS.get(ins.op)
+            if opnd is None:
+                continue
+            if opnd < len(ins.arg_is_expr) and ins.arg_is_expr[opnd]:
+                continue
+            txid = ins.imm(opnd)
+            if txid is not None:
+                out.add(int(txid))
+    return out
+
+
+def _object_iter(body):
+    from ..eb.disasm import iter_code
+    return iter_code(bytes(body), 0, len(body))
+
+
+# --------------------------------------------------------------- collect the carry plan ---
+def collect_carry(donor_eb, object_specs, player_specs, field, lang_loader) -> list:
+    """Build the carry plan: the donor txids the grafts will SHOW, each assigned a fresh band txid and its
+    per-language text. ``donor_eb`` is the donor field's ``.eb`` bytes; ``object_specs`` /  ``player_specs``
+    are the graft specs (:func:`eventscan.scan_objects_verbatim` / :func:`scan_player_funcs`). ``field`` is
+    the donor field id (for the text loader). ``lang_loader(txids, lang) -> {txid: MesEntry}`` reads the
+    donor's per-language ``.mes`` (injected so this stays install-free + testable -- in the kit it is
+    :func:`_field_text_loader`).
+
+    Returns an ordered ``list[CarriedEntry]`` (sorted by donor txid for determinism), one per distinct
+    referenced txid. ``new_txid`` is :data:`CARRY_BASE_TXID` + i. An empty plan (no grafted windows) returns
+    ``[]`` -- the build then carries no text (byte-identical to no-carry).
+    """
+    wanted = _grafted_object_windows(donor_eb, object_specs) | _grafted_player_windows(player_specs)
+    if not wanted:
+        return []
+    donor_txids = sorted(wanted)
+
+    # per-language text. The geometry tags (strt/tail) are read once from the primary language (us); they
+    # are language-independent window geometry. Each language's TEXT is carried independently (verbatim).
+    per_lang: dict = {}
+    for lang in LANGS:
+        per_lang[lang] = lang_loader(donor_txids, lang) or {}
+    primary = per_lang.get(LANGS[0], {})
+
+    plan = []
+    for i, dt in enumerate(donor_txids):
+        texts = {}
+        for lang in LANGS:
+            e = per_lang[lang].get(dt)
+            texts[lang] = e.text if (e is not None and e.text is not None) else ""
+        pe = primary.get(dt)
+        plan.append(CarriedEntry(donor_txid=dt, new_txid=CARRY_BASE_TXID + i, texts=texts,
+                                 strt=(pe.strt if pe else None), tail=(pe.tail if pe else None)))
+    return plan
+
+
+def _field_text_loader(field, game=None):
+    """The kit's real per-language loader for :func:`collect_carry`: reads the donor field's ``<zone>.mes``
+    block from the install (the authoritative ``eventIDToMESID`` zone), picking the requested language. A
+    thin wrapper over :func:`dialogue._load_field_text` keyed on the field's text zone -- so the SAME block
+    selection :func:`dialogue.read_field_dialogue` proved is used (the want-txids coverage + language score
+    pick the right per-language copy)."""
+    from .._fieldtext import EVENT_ID_TO_MES
+    zone_id = EVENT_ID_TO_MES.get(int(field))
+
+    def _load(txids, lang):
+        return _dialogue._load_field_text(txids, lang, game=game, zone_id=zone_id)
+    return _load
+
+
+# --------------------------------------------------------------- remap the grafted windows ---
+def _remap_windows_in_entry(eb_bytes, entry_index, txid_map, carry_tags=None) -> bytes:
+    """Same-length, in-place remap of every window TXID a grafted entry's CARRIED funcs reference, donor ->
+    carried band, via the decoder-derived 2-byte offset (:func:`content.object._arg_byte_offset`). Only the
+    ``carry_tags`` funcs are patched (``None`` = whole entry), mirroring what was actually grafted. A txid
+    not in ``txid_map`` (e.g. a system window pointing at a base id we chose not to carry) is left
+    untouched. The patch is byte-for-byte length-preserving (2-byte immediate -> 2-byte immediate)."""
+    eb = EbScript.from_bytes(eb_bytes)
+    b = bytearray(eb_bytes)
+    keep = None if carry_tags is None else {int(t) for t in carry_tags}
+    for f in eb.entry(entry_index).funcs:
+        if keep is not None and f.tag not in keep:
+            continue
+        for ins in eb.instrs(f):
+            opnd = _dialogue.WINDOW_OPS.get(ins.op)
+            if opnd is None:
+                continue
+            if opnd < len(ins.arg_is_expr) and ins.arg_is_expr[opnd]:
+                continue
+            txid = ins.imm(opnd)
+            if txid is None or int(txid) not in txid_map:
+                continue
+            new = txid_map[int(txid)]
+            bo = _object._arg_byte_offset(ins, opnd)
+            if bo is None or argsize(ins.op, opnd) != 2:
+                continue                             # only same-length 2-byte window operands are patchable
+            b[ins.off + bo] = new & 0xFF
+            b[ins.off + bo + 1] = (new >> 8) & 0xFF
+    return bytes(b)
+
+
+def remap_object_windows(eb_bytes, object_specs, slot_map, txid_map) -> bytes:
+    """Patch each carried OBJECT's grafted entry (now at its fork slot ``slot_map[donor_idx]``) so its
+    window TXIDs point at the carried band. ``slot_map`` is the donor_idx -> fork-slot map the object graft
+    built; ``txid_map`` is donor_txid -> carried_txid. A refused/un-slotted spec is skipped."""
+    data = eb_bytes
+    for s in object_specs:
+        if s.get("graft_safety") == "refuse":
+            continue
+        slot = slot_map.get(int(s["donor_idx"]))
+        if slot is None:
+            continue
+        data = _remap_windows_in_entry(data, slot, txid_map, s.get("carry_tags"))
+    return data
+
+
+def remap_player_func_windows(eb_bytes, player_entry, tag_map, txid_map) -> bytes:
+    """Patch each grafted PLAYER function (now at its fork tag ``tag_map[donor_tag]`` on the player entry) so
+    its window TXIDs point at the carried band. ``tag_map`` is donor_tag -> fork-tag; only the grafted tags
+    are touched. Same same-length 2-byte patch as the object path."""
+    eb = EbScript.from_bytes(eb_bytes)
+    fork_tags = set(tag_map.values())
+    data = eb_bytes
+    for f in eb.entry(player_entry).funcs:
+        if f.tag not in fork_tags:
+            continue
+        data = _remap_windows_in_entry(data, player_entry, txid_map, [f.tag])
+    return data
+
+
+# --------------------------------------------------------------- emit the carried .mes ---
+def _mes_entry_verbatim(entry: CarriedEntry, lang: str) -> str:
+    """One carried ``.mes`` entry for ``lang``, re-emitted FAITHFULLY at its new txid: the donor's exact STRT
+    (window geometry, kept verbatim) + its TAIL only if the donor had one + the language's verbatim text. NOT
+    :func:`content.text.mes_entry` (which forces a default STRT/TAIL) -- a carried entry must preserve the
+    donor's own geometry tags, else the window resizes."""
+    strt = entry.strt if entry.strt is not None else "10,1"
+    tail = f"[TAIL={entry.tail}]" if entry.tail else ""
+    return f"_[TXID={entry.new_txid}][STRT={strt}]{tail}{entry.texts.get(lang, '')}[ENDN]"
+
+
+def carried_mes_body(plan, lang: str) -> str:
+    """The carried ``.mes`` block for one language: every :class:`CarriedEntry` re-emitted at its new txid,
+    verbatim. Each entry carries its own ``[TXID=]`` re-index (so it is position-independent), letting this
+    block be APPENDED after the fork's authored block without disturbing it. Empty plan -> ``''``."""
+    if not plan:
+        return ""
+    return "\n".join(_mes_entry_verbatim(e, lang) for e in plan) + "\n"
+
+
+# --------------------------------------------------------------- the sidecar (import write / build read) ---
+SIDECAR_VERSION = 1
+
+
+def plan_to_sidecar(plan, *, field=None) -> dict:
+    """Serialise the carry plan to a JSON-able dict (the ``<name>.carrytext.json`` sidecar). One record per
+    carried entry: the donor/new txids, the donor geometry tags, and the per-language verbatim text. The
+    strings are SE-derived, so the sidecar is gitignored (mirrors ``.object*.bin`` / ``.dialogue.json``)."""
+    return {
+        "version": SIDECAR_VERSION,
+        "field": (int(field) if field is not None else None),
+        "base_txid": CARRY_BASE_TXID,
+        "langs": list(LANGS),
+        "entries": [{"donor_txid": e.donor_txid, "new_txid": e.new_txid,
+                     "strt": e.strt, "tail": e.tail, "texts": dict(e.texts)} for e in plan],
+    }
+
+
+def write_sidecar(path, plan, *, field=None) -> None:
+    """Write the carry sidecar to ``path`` (UTF-8 JSON). No-op file is still written for an empty plan so the
+    build's ``[carry_text] bin`` ref always resolves."""
+    from pathlib import Path
+    Path(path).write_text(json.dumps(plan_to_sidecar(plan, field=field), ensure_ascii=False, indent=1),
+                          encoding="utf-8")
+
+
+def load_sidecar(path) -> list:
+    """Read a ``<name>.carrytext.json`` sidecar back into an ordered ``list[CarriedEntry]`` (the build's
+    consume side). Each entry's ``texts`` is filled for every shipped language (missing -> ``''``, so an
+    absent language never errors -- it ships an empty window, harmless)."""
+    from pathlib import Path
+    raw = json.loads(Path(path).read_text(encoding="utf-8"))
+    out = []
+    for rec in raw.get("entries", []):
+        texts = {lang: (rec.get("texts", {}).get(lang) or "") for lang in LANGS}
+        out.append(CarriedEntry(donor_txid=int(rec["donor_txid"]), new_txid=int(rec["new_txid"]),
+                                texts=texts, strt=rec.get("strt"), tail=rec.get("tail")))
+    return out

ff9mapkit/content/verbatim.py

@@ -0,0 +1,86 @@
+"""Verbatim-`.eb` fork -- ship a real field's WHOLE event script instead of re-synthesizing it.
+
+The faithful realization of "entry-0 carry" (docs/FORK_FIDELITY.md): a story field's entry-0 ``Main_Init``
+arms its objects/regions and gates the cast by ScenarioCounter, and the gated doors read MAP vars it sets --
+so the only way those references resolve is to keep the donor's WHOLE entry layout. This mode does exactly
+that: the build ships the donor's `.eb` verbatim (entry-0 + every object + every gateway, slots intact) and
+only **remaps the `Field()` destinations**; the field then runs its real logic. Proven in-game on Dali Inn
+(the gated door opens, the cast gates by story beat).
+
+The declarative content blocks ([[npc]]/[[gateway]]/...) are NOT used in this mode -- the `.eb` is whole, so
+there is nothing to synthesize. Pair with a `[startup]` block to boot a chosen beat. LIMITS (vs a perfect
+clone): the donor `.mes` text is a separate carry (TXIDs may not resolve until then), and a fork reached by
+F6-warp has no entrance fade to mask first-frame model streaming.
+"""
+from __future__ import annotations
+
+import json
+import struct
+
+from ..eb import EbScript
+
+FIELD_OP = 0x2B           # Field(dest) -- the warp; dest is a 2-byte literal at instruction offset +2
+
+
+def remap_fields(eb_bytes: bytes, retarget: dict) -> bytes:
+    """Patch every ``Field(id)`` literal whose id is in ``retarget`` (real destination -> fork id). Ids NOT in
+    the map are left as live seams (the door warps back into the real game). Empty ``retarget`` -> unchanged."""
+    if not retarget:
+        return eb_bytes
+    eb = EbScript.from_bytes(eb_bytes)
+    buf = bytearray(eb_bytes)
+    for e in eb.entries:
+        if e.empty:
+            continue
+        for f in e.funcs:
+            for i in eb.instrs(f):
+                if i.op == FIELD_OP and i.imm(0) in retarget:
+                    struct.pack_into("<H", buf, i.off + 2, int(retarget[i.imm(0)]) & 0xFFFF)
+    return bytes(buf)
+
+
+def render_retarget(dests, id_remap=None):
+    """The ``[verbatim_eb] retarget`` portion for a verbatim fork's ``Field()`` exits, plus the count of
+    exits actually retargeted.
+
+    ``dests`` = the field's distinct ``Field(id)`` destinations (real ids). With ``id_remap`` (a
+    ``{real_id: fork_id}`` map from import-chain) this emits a LIVE ``retarget = {...}`` table for the
+    in-chain destinations and a comment listing the rest (left as live seams back into the real game) --
+    so a forked CHAIN's doors warp into its OWN member forks. Without ``id_remap`` (single-field
+    ``import --verbatim``) it emits the commented-out fill-in template the author edits by hand, BYTE-FOR-BYTE
+    as before (so the single-field golden is unchanged). Returns ``(toml_text, n_retargeted)``."""
+    dests = list(dests)
+    if id_remap:
+        inchain = [(d, int(id_remap[d])) for d in dests if d in id_remap]
+        if inchain:
+            seams = [d for d in dests if d not in id_remap]
+            tbl = "retarget = { " + ", ".join(f"{a} = {b}" for a, b in inchain) + " }\n"
+            note = ("# (the rest are live seams back into the real game -- not in this chain: "
+                    + ", ".join(map(str, seams)) + ")\n") if seams else ""
+            return tbl + note, len(inchain)
+    body = "".join(f"#   {d} = 0\n" for d in dests) or "#   (this field has no Field() exits)\n"
+    return ("# retarget = {\n" + body + "# }\n"), 0
+
+
+def verbatim_eb(project):
+    """The verbatim `.eb` to ship for ``project`` (from its ``[verbatim_eb]`` block, ``bin`` + optional
+    ``retarget``), Field-remapped -- or ``None`` if the project isn't a verbatim fork (the build then
+    synthesizes from the field.toml as usual). The same bytecode ships for every language (it is
+    language-identical; only the cosmetic name field differs, which the donor's already carries)."""
+    spec = project.raw.get("verbatim_eb")
+    if not spec or not spec.get("bin"):
+        return None
+    retarget = {int(k): int(v) for k, v in (spec.get("retarget") or {}).items()}
+    return remap_fields(project.path(spec["bin"]).read_bytes(), retarget)
+
+
+def verbatim_mes(project, lang: str):
+    """The donor field's WHOLE `.mes` text body to ship for ``lang`` (from the ``[verbatim_eb] text`` JSON
+    sidecar, ``{lang: body}``) -- the verbatim `.eb`'s index-txids resolve straight into it. Falls back to the
+    ``us`` body for a language the dialogue reader couldn't distinguish. ``None`` if the fork carries no text."""
+    spec = project.raw.get("verbatim_eb") or {}
+    tf = spec.get("text")
+    if not tf:
+        return None
+    data = json.loads(project.path(tf).read_text(encoding="utf-8"))
+    return data.get(lang) or data.get("us")

ff9mapkit/content/walkmesh_hotfix.py

@@ -0,0 +1,38 @@
+"""Reproduce a real field's LOAD-TIME engine walkmesh hotfix in a fork.
+
+A few real fields rely on a hardcoded Memoria hotfix (keyed on the real ``fldMapNo``) that toggles
+walkmesh-triangle active-state at field load -- e.g. Gulug/Room (2356) deactivates the broken-wall triangles
+so the player can't walk through the gap. A verbatim/native fork runs at a custom id (>= 4000), so that
+``fldMapNo`` guard is false and the hotfix never fires -> the forked walkmesh is wrong there. See the catalog
+and the two tractability classes in :mod:`ff9mapkit.walkmesh_hotfixes`.
+
+This module reproduces the AUTO (load-time, unconditional) class: it prepends ``EnablePathTriangle(tri, state)``
+-- opcode 0x9A, whose engine handler IS ``WalkMesh.BGI_triSetActive`` -- to ``Main_Init`` (entry-0 tag-0), so
+the triangles are in the right state from the first frame, exactly as the engine sets them at load. The
+``.bgi`` stays byte-verbatim (the fix lives in the script layer). A tag-0 prepend (``rel_off == 0``) is
+shift-safe even on a jump-table donor, and ``EnablePathTriangle`` is language-identical. No toggles -> the eb
+is returned unchanged. Mirrors :mod:`ff9mapkit.content.areatitle` / :mod:`ff9mapkit.content.startup`.
+"""
+from __future__ import annotations
+
+from ..eb import edit, opcodes
+
+ENABLE_PATH_TRIANGLE = 0x9A   # EnablePathTriangle(triId, active) -- the engine handler is BGI_triSetActive
+
+
+def toggles_body(toggles) -> bytes:
+    """The bare ``EnablePathTriangle(tri, state)`` sequence for ``toggles`` (an iterable of ``(tri, state)``),
+    or ``b""`` when there are none. ``state`` is coerced to 0/1 (1 = active/walkable)."""
+    out = b""
+    for tri, state in (toggles or ()):
+        out += opcodes.encode(ENABLE_PATH_TRIANGLE, int(tri), 1 if int(state) else 0)
+    return out
+
+
+def apply_tri_toggles(eb_bytes, toggles) -> bytes:
+    """Prepend the load-time triangle toggles to ``Main_Init`` (entry-0 tag-0). Returns ``eb_bytes`` unchanged
+    when ``toggles`` is empty (so a field with no walkmesh hotfix builds byte-for-byte as before)."""
+    body = toggles_body(toggles)
+    if not body:
+        return eb_bytes
+    return edit.insert_in_function(eb_bytes, 0, 0, 0, body)

ff9mapkit/data/__init__.py

@@ -0,0 +1,48 @@
+"""Bundled binary data + accessors.
+
+Contents
+--------
+blank_field/<lang>.eb.bytes
+    The canonical *blank field* event script (956 bytes), one per language. This is the
+    proven minimal playable field used as the starting point for every built field: a clean
+    Main_Init (no stray popups, standard movement) plus a single player object. Content
+    injectors clone/extend it; the builder writes it (with content) per language.
+
+region_template.bin
+    The 272-byte field-exit region body (a SetRegion polygon -> CalculateExitPosition /
+    ExitField -> PreloadField -> set FieldEntrance -> Field(target)). The gateway injector
+    patches its polygon / entrance / target and appends it as a new entry.
+
+Provenance / distribution note
+------------------------------
+These blobs are DERIVED from Final Fantasy IX field data (the blank field is a cleaned clone of a
+base field; the region template is a base field's exit region). To avoid redistributing Square Enix
+game bytes, the public repo ships **none** of them -- they are regenerated from the user's own,
+legally-owned FF9 install by ``ff9mapkit extract-templates`` (see :mod:`ff9mapkit.provision` and
+docs/PROVENANCE.md) into a local, gitignored cache. The accessors below read that cache and raise a
+clear "run extract-templates" message if it isn't present yet.
+"""
+
+from __future__ import annotations
+
+from ..config import LANGS
+from .. import provision
+
+
+def blank_field_bytes(lang: str = "us") -> bytes:
+    """Bytes of the blank field event script for *lang* (defaults to 'us'). Regenerated from the
+    user's FF9 install by ``ff9mapkit extract-templates``; raises if that hasn't been run."""
+    if lang not in LANGS:
+        raise ValueError(f"unknown language {lang!r}; expected one of {LANGS}")
+    p = provision.blank_dir() / f"{lang}.eb.bytes"
+    if not p.is_file():
+        raise FileNotFoundError(provision.MISSING_MSG)
+    return p.read_bytes()
+
+
+def region_template() -> bytes:
+    """The 272-byte field-exit region template (regenerated from the user's install)."""
+    p = provision.region_template_path()
+    if not p.is_file():
+        raise FileNotFoundError(provision.MISSING_MSG)
+    return p.read_bytes()

ff9mapkit/data/_regen_provenance.py

@@ -0,0 +1,142 @@
+"""MAINTAINER tool: regenerate the provenance artifacts (patches + manifest) from a vanilla FF9
+install, so the public repo can ship ZERO Square Enix bytes.
+
+Run from a repo checkout with $FF9_GAME_PATH set (or --game), against an UNMODIFIED install:
+
+    python -m ff9mapkit.data._regen_provenance
+
+It writes ff9mapkit/data/provenance/{manifest.json, blank.<lang>.patch, region_template.patch}
+-- all OURS (copy/insert diffs + hashes + source field names; no game bytes) -- and verifies that
+`ff9mapkit extract-templates` would reproduce the current on-disk blobs byte-for-byte. The actual
+game-derived blobs (blank_field/, region_template.bin, the binary test fixtures) are NOT committed;
+end users regenerate them locally from their own install.
+
+This is the inverse bookend of provision.extract_templates: this AUTHORS the patches; that APPLIES them.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import sys
+from pathlib import Path
+
+from .. import provision
+from ..config import LANGS
+
+HERE = Path(__file__).resolve().parent
+PROV = HERE / "provenance"
+
+# --- the base fields the kit's assets are derived from (all present in a vanilla install) ----------
+BLANK_SRC = "fbg_n11_ldbm_map203_lb_hng_0"     # field 1357 (L.Castle/Hangar) -> the cleaned blank field
+REGION_SRC = "fbg_n01_alxt_map031_at_wpn_0"    # ALEX3_AT_WEAPON -> the exit-region template
+ALEX_SRC = "fbg_n01_alxt_map016_at_msa_0"      # ALEX1_AT_STREET_A (vanilla field 100) -> eventscan oracle
+GRGR_SRC = "fbg_n21_grgr_map420_gr_cen_0"      # Gargan Roo centre -> camera fixture
+MULTIFLOOR_SRC = "fbg_n00_tshp_map008_th_upr_0"  # Prima Vista upper deck (3 floors) -> multi-floor walkmesh
+#   (chosen because its real .bgi round-trips byte-exact through the kit's codec AND is seam-clean:
+#    fully walk-reachable, strands on obj re-export, reconciles -- so it exercises the seam machinery.)
+
+# the Session-12 Alexandria door, re-injected onto the vanilla field so the eventscan oracle keeps its
+# "3 real exits + 1 injected door" shape without redistributing AlternateFantasy's modified bytes.
+ALEX_DOOR = {"target": 4000, "entrance": 0,
+             "zone": [[-700, 2200], [200, 2200], [200, 3400], [-700, 3400]]}
+
+sha = lambda b: hashlib.sha256(b).hexdigest()
+
+
+def main(argv=None) -> int:
+    import argparse
+    from .. import extract
+    ap = argparse.ArgumentParser(description="regenerate ff9mapkit provenance patches + manifest")
+    ap.add_argument("--game", help="FF9 install path (else $FF9_GAME_PATH / config)")
+    args = ap.parse_args(argv)
+    game = args.game
+
+    PROV.mkdir(parents=True, exist_ok=True)
+    manifest: dict = {
+        "_note": ("ff9mapkit ships NO Final Fantasy IX game data. These entries describe how to "
+                  "regenerate the small set of base assets the kit needs from YOUR OWN install via "
+                  "`ff9mapkit extract-templates`. The .patch files contain only our edits + copy "
+                  "offsets (never game bytes). See docs/PROVENANCE.md."),
+    }
+
+    # 1) blank field: per-language copy/insert patch (1357 -> our cleaned blank)
+    blank_sha = {}
+    for lang in LANGS:
+        src = extract.extract_event_script(BLANK_SRC, game=game, lang=lang)
+        dst = (HERE / "blank_field" / f"{lang}.eb.bytes").read_bytes()   # current on-disk blank
+        patch = provision.make_patch(src, dst)
+        (PROV / f"blank.{lang}.patch").write_text(json.dumps(patch), encoding="utf-8")
+        assert provision.apply_patch(src, patch) == dst, f"blank {lang} patch round-trip failed"
+        bad = provision.patch_game_runs(src, patch)
+        assert not bad, f"blank {lang}: patch would ship game-byte runs {bad}"
+        blank_sha[lang] = sha(dst)
+        print(f"  blank.{lang}.patch  insert={patch['insert_bytes']}B (no game runs)  -> reproduces blank OK")
+    manifest["blank"] = {"source_fbg": BLANK_SRC, "patch": "blank.{lang}.patch", "sha256": blank_sha}
+
+    # 2) region template: single patch (ALEX3_AT_WEAPON -> our 272B exit-region template)
+    src = extract.extract_event_script(REGION_SRC, game=game, lang="us")
+    dst = (HERE / "region_template.bin").read_bytes()
+    patch = provision.make_patch(src, dst)
+    (PROV / "region_template.patch").write_text(json.dumps(patch), encoding="utf-8")
+    assert provision.apply_patch(src, patch) == dst, "region patch round-trip failed"
+    assert not provision.patch_game_runs(src, patch), "region patch would ship game-byte runs"
+    manifest["region_template"] = {"source_fbg": REGION_SRC, "lang": "us",
+                                   "patch": "region_template.patch", "sha256": sha(dst)}
+    print(f"  region_template.patch  insert={patch['insert_bytes']}B  -> reproduces template OK")
+
+    # 3) test fixtures, regenerated from the install (sha recorded so extract-templates self-verifies)
+    fixtures = {}
+    fix_dir = HERE.parent.parent / "tests" / "fixtures"
+
+    #   alex100: vanilla field 100 + the kit's own door injection (no AlternateFantasy bytes)
+    from ..content import gateway as _gw
+    van = extract.extract_event_script(ALEX_SRC, game=game, lang="us")
+    door = _gw.inject_gateway(van, ALEX_DOOR["target"], entrance=ALEX_DOOR["entrance"],
+                              zone=_gw.quad_zone(ALEX_DOOR["zone"]))
+    fixtures["alex100-us.eb.bytes"] = {"source_fbg": ALEX_SRC, "kind": "event_with_gateway",
+                                       "lang": "us", "gateway": ALEX_DOOR, "sha256": sha(door)}
+    if fix_dir.is_dir():
+        (fix_dir / "alex100-us.eb.bytes").write_bytes(door)
+
+    #   grgr.bgx: the real GRGR camera (extracted as a borrowable .bgx)
+    #   multifloor.bgi.bytes: a real 3-floor walkmesh that round-trips byte-exact (codec + seam tests)
+    import tempfile
+    tg = Path(tempfile.mkdtemp())
+    extract.extract_field(GRGR_SRC, tg, game=game)
+    grgr_bgx = (tg / "camera.bgx").read_bytes()
+    tm = Path(tempfile.mkdtemp())
+    extract.extract_field(MULTIFLOOR_SRC, tm, game=game)
+    mf_bgi = (tm / "walkmesh.bgi").read_bytes()
+    fixtures["grgr.bgx"] = {"source_fbg": GRGR_SRC, "kind": "camera_bgx", "sha256": sha(grgr_bgx)}
+    fixtures["multifloor.bgi.bytes"] = {"source_fbg": MULTIFLOOR_SRC, "kind": "walkmesh_verbatim",
+                                        "sha256": sha(mf_bgi)}
+    if fix_dir.is_dir():
+        (fix_dir / "grgr.bgx").write_bytes(grgr_bgx)
+        (fix_dir / "multifloor.bgi.bytes").write_bytes(mf_bgi)
+    manifest["fixtures"] = fixtures
+    print(f"  fixtures: alex100-us({len(door)}B) grgr.bgx({len(grgr_bgx)}B) "
+          f"multifloor.bgi({len(mf_bgi)}B)")
+
+    # 4) build goldens: the hut example's build outputs are DERIVATIVE (embed the blank), so we ship a
+    #    hash, not the bytes. The build test compares fresh build output's hash to this.
+    manifest["goldens"] = _golden_hashes(game)
+    print(f"  goldens (hash-only): {list(manifest['goldens'])}")
+
+    (PROV / "manifest.json").write_text(json.dumps(manifest, indent=2), encoding="utf-8")
+    print(f"\nwrote {PROV/'manifest.json'} + patches")
+    return 0
+
+
+def _golden_hashes(game) -> dict:
+    """SHA-256 of the hut example's build outputs (the independent build-golden reference)."""
+    import tempfile
+    from ..build import FieldProject, build_mod, ModLayout
+    example = HERE.parent.parent / "examples" / "vivi-hut" / "hut_int.field.toml"
+    out = Path(tempfile.mkdtemp())
+    build_mod([FieldProject.load(example)], out, mod_name="GoldenCheck")
+    L = ModLayout(out)
+    return {"EVT_HUT_INT.eb.bytes/us": sha(L.eb_path("us", "EVT_HUT_INT.eb.bytes").read_bytes())}
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ff9mapkit/data/provenance/blank.es.patch

@@ -0,0 +1 @@
+{"src_sha256": "b536766f4e15836b9e83851bae513512be410b291829de3187d8345ef45c28b2", "out_len": 956, "out_sha256": "eb6ac7333a273333b9d7e296408a2cfad41b059acd06679c3fb2a50b815234ac", "insert_bytes": 16, "ops": [["c", 0, 4], ["i", "826b"], ["c", 12, 4], ["c", 4, 8], ["c", 26, 3], ["i", "85"], ["c", 32, 12], ["i", "82928294816682938140"], ["c", 44, 86], ["i", "6c"], ["c", 131, 302], ["i", "ffff"], ["c", 435, 29], ["c", 532, 105], ["c", 68, 60], ["c", 68, 8], ["c", 637, 319]]}

ff9mapkit/data/provenance/blank.fr.patch

@@ -0,0 +1 @@
+{"src_sha256": "2ccd924b63800c95703ce7e766dde0036a9d6dd94b619d0bcfeb848ce1a7c49e", "out_len": 956, "out_sha256": "b06d7768c8485ee4c48443e2384730a0d447d2af8e84d87a20a3ee2a23c45f6b", "insert_bytes": 22, "ops": [["c", 0, 4], ["i", "826b"], ["c", 22, 5], ["i", "62828182938294828c8285815e"], ["c", 4, 12], ["i", "8294"], ["c", 16, 1], ["i", "66"], ["c", 18, 1], ["i", "93"], ["c", 24, 2], ["c", 44, 86], ["i", "6c"], ["c", 131, 302], ["i", "ffff"], ["c", 435, 29], ["c", 532, 105], ["c", 68, 60], ["c", 68, 8], ["c", 637, 319]]}

ff9mapkit/data/provenance/blank.gr.patch

@@ -0,0 +1 @@
+{"src_sha256": "08b0cba27ddafe91062b7d565e4aece258c6b51d0fa82bfc2a999b14caa0fd09", "out_len": 956, "out_sha256": "5676ef381393767a4fef715cdfe1eca947fef10b1d0ec80dd247a0301fa66a34", "insert_bytes": 21, "ops": [["c", 0, 5], ["i", "6b81448140"], ["c", 6, 1], ["i", "62"], ["c", 8, 1], ["i", "8182938294"], ["c", 10, 3], ["i", "85"], ["c", 24, 2], ["c", 28, 13], ["i", "948166"], ["c", 42, 1], ["i", "938140"], ["c", 44, 86], ["i", "6c"], ["c", 131, 302], ["i", "ffff"], ["c", 435, 29], ["c", 532, 105], ["c", 68, 60], ["c", 68, 8], ["c", 637, 319]]}

ff9mapkit/data/provenance/blank.it.patch

@@ -0,0 +1 @@
+{"src_sha256": "251dfb52f8c962a0cc5868c5c7723066c445058cc09acf187b48c99fa8262569", "out_len": 956, "out_sha256": "d968b0d1bafe3b2c60ee02c91a435986f71c23b4afb1e78fa65a67294c5b290b", "insert_bytes": 15, "ops": [["c", 0, 5], ["i", "6b"], ["c", 6, 5], ["i", "62"], ["c", 12, 1], ["i", "81"], ["c", 14, 1], ["i", "93"], ["c", 16, 1], ["i", "94"], ["c", 20, 3], ["i", "85"], ["c", 26, 15], ["i", "948166"], ["c", 42, 1], ["i", "938140"], ["c", 44, 86], ["i", "6c"], ["c", 131, 302], ["i", "ffff"], ["c", 435, 29], ["c", 532, 105], ["c", 70, 58], ["c", 70, 10], ["c", 637, 319]]}

ff9mapkit/data/provenance/blank.jp.patch

@@ -0,0 +1 @@
+{"src_sha256": "89ef1de34133a8b8e22a1502cf4fb65ab2c77237a80ef63d9b5548066c40edf7", "out_len": 956, "out_sha256": "e5595df0fcd0685bf8702b2286ac28bc0f8c54169e4c881e61ff5c0ec09c1219", "insert_bytes": 39, "ops": [["c", 0, 4], ["i", "826b814481408262828182"], ["c", 7, 1], ["i", "8294828c828581"], ["c", 19, 1], ["i", "82678281828e8287828182928294816682"], ["c", 23, 1], ["c", 26, 1], ["i", "40"], ["c", 44, 86], ["i", "6c"], ["c", 131, 302], ["i", "ffff"], ["c", 435, 29], ["c", 532, 105], ["c", 64, 64], ["c", 28, 4], ["c", 637, 319]]}

ff9mapkit/data/provenance/blank.uk.patch

@@ -0,0 +1 @@
+{"src_sha256": "ccb9439159f288a85b231bff945e52dac7b5dc01662f09484479a06d0c627df1", "out_len": 956, "out_sha256": "2289085a5dc1030d8cd1541619e34a0bd722a0957d0849bfaf077c7e30e90452", "insert_bytes": 3, "ops": [["c", 0, 130], ["i", "6c"], ["c", 131, 302], ["i", "ffff"], ["c", 435, 29], ["c", 532, 105], ["c", 70, 58], ["c", 70, 10], ["c", 637, 319]]}

ff9mapkit/data/provenance/blank.us.patch

@@ -0,0 +1 @@
+{"src_sha256": "ccb9439159f288a85b231bff945e52dac7b5dc01662f09484479a06d0c627df1", "out_len": 956, "out_sha256": "2289085a5dc1030d8cd1541619e34a0bd722a0957d0849bfaf077c7e30e90452", "insert_bytes": 3, "ops": [["c", 0, 130], ["i", "6c"], ["c", 131, 302], ["i", "ffff"], ["c", 435, 29], ["c", 532, 105], ["c", 70, 58], ["c", 70, 10], ["c", 637, 319]]}