ff9mapkit 1.0.0b3__py3-none-any.whl

ff9mapkit/battle/seqpatch.py

@@ -0,0 +1,137 @@
+"""SAME-LENGTH raw17 ``btlseq`` operand patches -- the first sequence *authoring* step (read = :mod:`seqdis`).
+
+The safest sequence edit is a *literal* one: change one operand in place without moving any bytes -- retime a
+``Wait``/``MoveTo*`` frame count, swap an ``Anim`` code or a ``SetCamera`` id, tweak a ``Scale``/``FadeOut``
+value. No length change means no ``seqOffset``/``camOffset`` repack and no risk of mis-packing -- byte-accurate by
+construction (the seqcodec identity holds), exactly like :mod:`aipatch` (enemy AI) and ``scene_data`` (raw16).
+
+Addressing is by BYTE OFFSET (from ``battle-seq --sites``) + a required OLD-value guard: the patch only applies
+if the operand at that offset currently equals ``old`` (a stale/wrong offset fails LOUD instead of corrupting a
+byte), and ``new`` must fit the SAME field (width + signedness). raw17 bytecode is language-independent, so a
+forked scene ships one raw17 for all languages -- the patch applies once.
+
+This reaches OPERAND LITERALS only (frame counts, ids, masks, coords). Length-changing edits (inserting/removing
+instructions, a new sequence) are the deferred assembler/codec-repack tier (:mod:`seqcodec` provides the model).
+The 0x19 ``Sfx`` discarded-pad byte is NOT a site (the engine ignores it); the Move ``Next`` advance is not in the
+bytes at all (hard-coded in the engine) so there is no Next site to patch.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from . import seqcodec as _sc
+
+
+class SeqPatchError(ValueError):
+    pass
+
+
+@dataclass(frozen=True)
+class Site:
+    """One patchable operand in a sequence body."""
+    sub_no: int        # the canonical sub_no (attack index) owning this body (shared bodies: the first slot)
+    offset: int        # absolute byte offset of the operand's first byte (the ``at`` you cite)
+    width: int         # 1 or 2
+    signed: bool
+    kind: str          # frames | anim_code | camera | vfx | svfx | sfx | mesh_mask | message | coord | ...
+    value: int         # the current decoded value (signed per the field)
+    where: str         # human context, e.g. "sub0 Anim anim_code"
+    shared_subs: tuple = ()   # ALL sub_nos whose seqOffset aliases this body (>1 => a SHARED body: a patch here
+    #                           rewrites every one of them; 289/562 real scenes alias one body across several slots)
+
+    @property
+    def vmin(self) -> int:
+        return -(1 << (8 * self.width - 1)) if self.signed else 0
+
+    @property
+    def vmax(self) -> int:
+        return (1 << (8 * self.width - 1)) - 1 if self.signed else (1 << (8 * self.width)) - 1
+
+
+def _canonical_sub(model: _sc.Raw17, body: _sc.Body) -> int:
+    for sub in range(model.seq_count):
+        if model.seq_offset[sub] == body.offset:
+            return sub
+    return -1
+
+
+def constant_sites(raw17: bytes) -> list:
+    """Every patchable operand in a raw17's sequence bodies, in byte order. The ``offset`` of each is the ``at``
+    you cite in a ``[[scene.seq_patch]]``; ``battle-seq --sites`` prints them. The 0x19 discarded-pad byte and
+    terminator/no-operand opcodes contribute no sites."""
+    try:
+        model = _sc.parse(raw17)
+    except _sc.SeqCodecError as ex:
+        raise SeqPatchError(f"malformed raw17: {ex}")
+    out = []
+    for body in model.bodies:
+        sub = _canonical_sub(model, body)
+        shared = tuple(s for s in range(model.seq_count) if model.seq_offset[s] == body.offset)
+        for ins in body.instrs:
+            for (name, rel, w, signed, kind), val in zip(ins.fields, ins.operands):
+                if kind == "pad":
+                    continue
+                out.append(Site(sub, ins.offset + rel, w, signed, kind, val,
+                                f"sub{sub} {ins.name} {name}", shared))
+    return out
+
+
+_PATCH_KEYS = {"at", "old", "new", "seq"}
+
+
+def apply_seq_patches(raw17: bytes, patches) -> tuple:
+    """Apply ``[{at, old, new, seq?}, ...]`` same-length operand patches to ``raw17``. Each ``at`` must be a real
+    operand site whose current value == ``old`` (the guard) and whose field fits ``new``. Returns (patched, warns).
+    Raises SeqPatchError on a bad offset / old-mismatch / range-overflow -- so a wrong patch fails the build,
+    never the game."""
+    if not isinstance(patches, list):
+        raise SeqPatchError("[[scene.seq_patch]] must be a list of tables")
+    sites = {s.offset: s for s in constant_sites(raw17)}
+    b = bytearray(raw17)
+    warnings: list = []
+    seen: dict = {}
+    for n, p in enumerate(patches):
+        if not isinstance(p, dict):
+            raise SeqPatchError(f"[[scene.seq_patch]] #{n} must be a table (got {type(p).__name__})")
+        unknown = set(p) - _PATCH_KEYS
+        if unknown:
+            raise SeqPatchError(f"[[scene.seq_patch]] #{n}: unknown key(s) {sorted(unknown)} "
+                                f"(expected at / old / new / seq) -- typo?")
+        at, old, new = p.get("at"), p.get("old"), p.get("new")
+        for k, v in (("at", at), ("old", old), ("new", new)):
+            if not isinstance(v, int) or isinstance(v, bool):
+                raise SeqPatchError(f"[[scene.seq_patch]] #{n} needs integer {k} (at = offset, old/new = values)")
+        site = sites.get(at)
+        if site is None:
+            raise SeqPatchError(f"[[scene.seq_patch]] #{n}: no patchable operand at offset {at} "
+                                f"(cite an offset from `battle-seq --sites`)")
+        seq = p.get("seq")
+        if seq is not None and seq not in site.shared_subs:                  # a wrong seq number (typo), NOT an alias
+            owners = "/".join(str(s) for s in site.shared_subs)
+            warnings.append(f"[[scene.seq_patch]] #{n}: seq={seq} does not own offset {at} (owned by sub {owners}) "
+                            f"-- check the seq/at numbers")
+        if len(site.shared_subs) > 1:                                        # a genuinely SHARED body: the edit hits
+            owners = ",".join(str(s) for s in site.shared_subs)              # every aliasing attack, regardless of seq
+            warnings.append(f"[[scene.seq_patch]] #{n}: offset {at} drives a SHARED sequence body (subs {owners}) "
+                            f"-- this edit changes the choreography of ALL of them")
+        if at in seen:
+            warnings.append(f"[[scene.seq_patch]] #{n} and #{seen[at]} both patch offset {at} -- the later wins")
+        seen[at] = n
+        if site.value != old:
+            raise SeqPatchError(f"[[scene.seq_patch]] #{n}: expected old = {old} at offset {at}, but the raw17 has "
+                                f"{site.value} ({site.where}) -- wrong offset, or already patched?")
+        if not site.vmin <= new <= site.vmax:
+            raise SeqPatchError(f"[[scene.seq_patch]] #{n}: new = {new} does not fit the {site.width}-byte "
+                                f"{'signed' if site.signed else 'unsigned'} {site.kind} operand at offset {at} "
+                                f"({site.vmin}..{site.vmax}) -- a same-length patch can't widen it")
+        b[at:at + site.width] = int(new).to_bytes(site.width, "little", signed=site.signed)
+    return bytes(b), warnings
+
+
+def validate_patches(raw17: bytes, patches) -> list:
+    """Offline problems (empty => OK): re-run the patch on a copy and surface any SeqPatchError as a message."""
+    try:
+        apply_seq_patches(raw17, patches)
+        return []
+    except SeqPatchError as ex:
+        return [str(ex)]

ff9mapkit/battle_bgm.py

@@ -0,0 +1,133 @@
+"""Donor battle BGM, read LIVE from the install (provenance-clean): the ``(field, scene) -> song`` map.
+
+FF9 chooses a field battle's song by ``(originMap, battleId)`` == ``(fldMapNo, entered-scene)`` from
+``EmbeddedAsset/Manifest/Sounds/BtlEncountBgmMetaData.txt`` (``FF9SndMetaData.GetMusicForBattle`` /
+``BattleSwirl.RequestPlayBattleEncounterSongForField``). ``fldMapNo`` is the FIELD id; ``battleId`` is the
+``nextMapNo`` the field actually ENTERS -- for a RANDOM encounter that's the chosen ``SetRandomBattles``
+scene, for a SCRIPTED battle it's the explicit ``Battle(0x2A)`` scene. A field forked to a custom id
+(>= 4000) is NOT in the map, the donor song is lost (``GetMusicForBattle`` returns ``-1``), and the kit's
+forced ``Music: 0`` then pins the encounter to the generic Battle Theme. The kit reproduces a song by
+emitting a ``Music: <song>`` BattlePatch line: that populates ``FF9SndMetaData.BtlBgmPatcherMapper[scene]``,
+which is keyed on the SCENE id the fork KEEPS (not the field id), so it wins regardless of the custom
+origin. This is the same id-gated-table-lost-on-a-mint family as the walkmesh hotfixes and the narrow-map
+width table, but reproducible because the override is scene-keyed.
+
+★ SCOPE: the live map's NON-zero songs (e.g. the boss/special theme 35) ALL belong to SCRIPTED-battle
+scenes; every random-encounter field maps to song 0. So ``import`` prefilling ``[encounter] battle_music``
+from the donor's RANDOM primary scene (``extract._donor_battle_song``) is correct but inert for the shipping
+game -- it can only ever read a 0. Carrying a donor's SPECIAL battle theme means looking up the donor's
+SCRIPTED ``Battle(0x2A)`` scene id (decoded from the carried ``.eb`` of a ``--verbatim`` fork), which the
+declarative ``[encounter]`` block never sees -- a separate follow-up (docs/FORK_FIDELITY.md #6).
+
+The metadata is a Square-Enix ``TextAsset`` inside ``FF9_Data/resources.assets`` (NOT Memoria source), so it
+is read LIVE from the install and cached in-memory, **shipping/committing NOTHING** -- the same
+provenance-clean live pattern as :mod:`ff9mapkit.keyitems` / :mod:`ff9mapkit.itemstats`. If the asset isn't
+reachable (no install, no UnityPy, asset moved/renamed), every accessor returns ``None`` and the caller
+degrades gracefully (``battle_music`` stays unset -> the build's default 0).
+"""
+from __future__ import annotations
+
+import json
+
+ASSET_NAME = "BtlEncountBgmMetaData.txt"        # the field-map encounter-BGM TextAsset in resources.assets
+
+_CACHE = None                                   # {int field_id: {int scene_id: int song_id}}, or the _MISS sentinel
+_MISS = object()                                # distinguishes "tried, unreachable" from "not yet loaded" (None)
+
+
+def _resources_assets(game=None):
+    """Path to the install's ``resources.assets`` (the Unity data file holding the BGM TextAsset), or ``None``.
+    The 64-bit build's data lives under ``x64/FF9_Data``; fall back to ``x86`` then a flat ``FF9_Data``."""
+    from .config import find_game_path
+    try:
+        root = find_game_path(game)
+    except Exception:                            # noqa: BLE001 -- install not resolvable -> degrade
+        return None
+    for sub in ("x64", "x86", ""):
+        p = (root / sub / "FF9_Data" / "resources.assets") if sub else (root / "FF9_Data" / "resources.assets")
+        if p.exists():
+            return p
+    return None
+
+
+def _read(game=None):
+    """Parse the BtlEncountBgmMetaData TextAsset from ``resources.assets`` -> ``{field: {scene: song}}``, or
+    ``None`` if anything is unavailable. Lazy UnityPy import (kept out of the core kit's hot path)."""
+    p = _resources_assets(game)
+    if p is None:
+        return None
+    try:
+        import UnityPy                            # noqa: PLC0415 -- only import/extract needs it
+    except ImportError:
+        return None
+    from .extract import _raw_bytes               # the canonical TextAsset byte reader (UnityPy-version-safe)
+    try:
+        env = UnityPy.load(str(p))
+        for obj in env.objects:
+            if obj.type.name != "TextAsset":
+                continue
+            data = obj.read()
+            name = getattr(data, "m_Name", None) or getattr(data, "name", "")
+            if name != ASSET_NAME:
+                continue
+            body = _raw_bytes(data)
+            if body is None:
+                continue
+            return parse(body.decode("utf-8", "replace"))
+    except Exception:                             # noqa: BLE001 -- any UnityPy/parse failure -> degrade
+        return None
+    return None
+
+
+def parse(text):
+    """``{"field": {"scene": "song"}}`` JSON -> ``{int field: {int scene: int song}}`` (malformed JSON or
+    non-numeric keys/values are skipped, never raised on -- the file is data, never trusted to be perfectly
+    formed; an unparseable blob yields ``{}``)."""
+    try:
+        root = json.loads(text)
+    except (ValueError, TypeError):               # JSONDecodeError (empty/garbled) -> empty map, never raise
+        return {}
+    out: dict = {}
+    for fk, scenes in (root or {}).items():
+        try:
+            fid = int(fk)
+        except (TypeError, ValueError):
+            continue
+        row: dict = {}
+        for sk, song in (scenes or {}).items():
+            try:
+                row[int(sk)] = int(song)
+            except (TypeError, ValueError):
+                continue
+        out[fid] = row
+    return out
+
+
+def _load(game=None):
+    """``{field: {scene: song}}`` (cached), or ``None`` if the install/asset can't be read."""
+    global _CACHE
+    if _CACHE is None:
+        parsed = _read(game)
+        _CACHE = _MISS if parsed is None else parsed
+    return None if _CACHE is _MISS else _CACHE
+
+
+def song(field_id, scene_id, game=None):
+    """The donor field's real battle song for ``scene_id`` (the akao song-play id, e.g. 35), or ``None`` when
+    the ``(field, scene)`` pair isn't in the map (the engine plays no special song -> the field BGM bleeds
+    into the battle) or the install can't be read. ``0`` is a REAL value (the standard Battle Theme), so it is
+    returned as ``0`` and is DISTINCT from ``None`` ("unknown / no mapping")."""
+    if field_id is None:
+        return None
+    table = _load(game)
+    if not table:
+        return None
+    row = table.get(int(field_id))
+    if not row:
+        return None
+    return row.get(int(scene_id))
+
+
+def available(game=None) -> bool:
+    """True if the install's BtlEncountBgmMetaData could be read (so donor battle songs are live)."""
+    return _load(game) is not None

ff9mapkit/binutils.py

@@ -0,0 +1,60 @@
+"""Little-endian struct helpers shared by every binary codec in the kit.
+
+The original tools each redefined some variant of these (``u16``, ``i16``, ``w16``, inline
+``struct.pack_into``); they are collected here so the ``.eb`` / ``.bgi`` / ``.bgx`` codecs
+share one tested implementation. All multi-byte values in FF9 field binaries are
+little-endian.
+"""
+
+from __future__ import annotations
+
+import struct
+
+# --- read (from bytes/bytearray at an offset) ---
+
+def u8(b: bytes, o: int) -> int:
+    return b[o]
+
+
+def u16(b: bytes, o: int) -> int:
+    """Unsigned 16-bit little-endian."""
+    return b[o] | (b[o + 1] << 8)
+
+
+def i16(b: bytes, o: int) -> int:
+    """Signed 16-bit little-endian."""
+    return struct.unpack_from("<h", b, o)[0]
+
+
+def u32(b: bytes, o: int) -> int:
+    return struct.unpack_from("<I", b, o)[0]
+
+
+def i32(b: bytes, o: int) -> int:
+    return struct.unpack_from("<i", b, o)[0]
+
+
+# --- pack (to bytes) ---
+
+def pu16(v: int) -> bytes:
+    """Pack an unsigned 16-bit little-endian value."""
+    return struct.pack("<H", v & 0xFFFF)
+
+
+def pi16(v: int) -> bytes:
+    """Pack a signed 16-bit little-endian value."""
+    return struct.pack("<h", v)
+
+
+def pu32(v: int) -> bytes:
+    return struct.pack("<I", v & 0xFFFFFFFF)
+
+
+# --- write (in place on a bytearray at an offset) ---
+
+def set_u16(b: bytearray, o: int, v: int) -> None:
+    struct.pack_into("<H", b, o, v & 0xFFFF)
+
+
+def set_i16(b: bytearray, o: int, v: int) -> None:
+    struct.pack_into("<h", b, o, v)