ff9mapkit 1.0.0b3__py3-none-any.whl

ff9mapkit/battle/seqauthor.py

@@ -0,0 +1,220 @@
+"""NET-NEW raw17 sequence authoring -- the LENGTH-CHANGING tier (read = :mod:`seqdis`, same-length = :mod:`seqpatch`).
+The analog of ``battle/aiauthor`` for enemy AI: assemble a whole attack-sequence body from source (:mod:`seqasm`)
+and SPLICE it in, driving the offset-fixup repack (:func:`seqcodec.serialize_repacked`) so every ``seqOffset`` +
+``camOffset`` is recomputed and the camera block re-appends intact.
+
+``[[scene.seq_replace]]`` (seq = sub_no, source = ...) replaces an existing attack's choreography wholesale. A
+brand-NEW attack slot (growing ``seqCount`` + wiring a raw16 ``AA_DATA`` + the ``.eb`` AI to select it) is a further
+step; replace is the keystone primitive it builds on. Authoring is lint-gated on the two per-file cross-references
+the engine doesn't bounds-check: an out-of-range ``Anim`` code (``IndexOutOfRange`` on ``animList``) and a
+``SetCamera``/``RunCamera`` id past the file's camera count (a stuck/black native camera) -- both fail the build,
+not the game.
+"""
+from __future__ import annotations
+
+from . import camera_codec as _cc
+from . import seqasm as _seqasm
+from . import seqcodec as _sc
+
+
+class SeqAuthorError(ValueError):
+    pass
+
+
+_CAMERA_OPS = (0x10, 0x12, 0x20)                         # SetCamera / RunCamera / RunCameraForced (cam id @ operand 0)
+
+
+def lint_seq(raw17: bytes) -> list:
+    """Offline semantic problems of a raw17's sequences (empty => OK). The codec already guarantees decode-to-
+    terminator / opcode in range / no overrun / disjoint bodies; this adds the SEMANTIC cross-references the codec
+    can't see -- the two operands whose safe range is a function of THIS file's own contents:
+    * an ``Anim`` (0x05) code whose ``seqBaseAnim[sub] + code`` indexes past ``animList`` (the engine does no
+      bounds check -> IndexOutOfRange);
+    * a ``SetCamera``/``RunCamera`` ``cam`` id >= the raw17's own camera count (the closed native SFX plugin
+      selects a non-existent camera -> a stuck/black camera).
+    Both are checked for every sub_no pointing at each body (aliases can differ)."""
+    try:
+        model = _sc.parse(raw17)
+    except _sc.SeqCodecError as ex:
+        return [f"unparseable raw17: {ex}"]
+    cam_count = None                                     # the camera block may be absent/garbage on a hand-built
+    try:                                                 # model -> skip the cam check rather than crash the lint
+        cam_count = len(_cc.parse_block(raw17)[1])
+    except Exception:                                    # noqa: BLE001 -- CameraCodecError or a malformed block
+        cam_count = None
+    problems = []
+    n = model.anim_count
+    for sub in range(model.seq_count):
+        body = model.body_for(sub)
+        if body is None:
+            continue
+        base = model.seq_base_anim[sub]
+        for ins in body.instrs:
+            if ins.op == 0x05 and ins.operands[0] != 255:        # Anim, non-idle
+                idx = base + ins.operands[0]
+                if idx >= n:                                     # base+code of two unsigned bytes is always >= 0
+                    problems.append(f"sub {sub}: Anim code {ins.operands[0]} -> animList[{base}+{ins.operands[0]}]"
+                                    f" = {idx} is out of range (animCount {n}) -- would crash the engine")
+            elif ins.op in _CAMERA_OPS and cam_count is not None and ins.operands[0] >= cam_count:
+                problems.append(f"sub {sub}: {ins.name} cam {ins.operands[0]} exceeds the {cam_count} camera(s) "
+                                f"in this raw17 -- no camera entry to play (stuck/black camera)")
+    return problems
+
+
+def replace_sequence(raw17: bytes, sub_no: int, source: str) -> tuple:
+    """Replace sub_no's attack-sequence body with one assembled from ``source`` (a :mod:`seqasm` block ending in a
+    terminator). Returns (new_raw17, warnings). The whole file is repacked (offsets recomputed, camera block kept).
+    Raises SeqAuthorError on a bad sub_no / unassemblable source / a body whose edit would crash (lint)."""
+    try:
+        model = _sc.parse(raw17)
+    except _sc.SeqCodecError as ex:
+        raise SeqAuthorError(f"malformed raw17: {ex}")
+    if not isinstance(sub_no, int) or isinstance(sub_no, bool) or not 0 <= sub_no < model.seq_count:
+        raise SeqAuthorError(f"seq = {sub_no!r} is not a valid sub_no (0..{model.seq_count - 1})")
+    if model.seq_offset[sub_no] == 0:
+        raise SeqAuthorError(f"seq {sub_no} has no sequence (seqOffset 0 sentinel) -- nothing to replace")
+    body = model.body_for(sub_no)
+    try:
+        instrs = _seqasm.assemble(source)
+    except _seqasm.SeqAsmError as ex:
+        raise SeqAuthorError(f"seq {sub_no} source: {ex}")
+    warnings = []
+    others = tuple(s for s in range(model.seq_count) if model.seq_offset[s] == body.offset and s != sub_no)
+    if others:
+        warnings.append(f"seq {sub_no} also shares its body with sub(s) {','.join(str(s) for s in others)} "
+                        f"-- replacing it rewrites ALL of them")
+    body.instrs = [_sc.Instr(i.op, 0, list(i.operands)) for i in instrs]    # offsets are recomputed by the repack
+    try:
+        out = _sc.serialize_repacked(model)                                 # may raise on an i16-overflowing body
+    except _sc.SeqCodecError as ex:
+        raise SeqAuthorError(f"seq {sub_no}: {ex}")
+    problems = lint_seq(out)                                                # the composed result must lint clean
+    if problems:
+        raise SeqAuthorError(f"seq {sub_no} would produce an invalid raw17: {'; '.join(problems)}")
+    return out, warnings
+
+
+def _locate(body, locator, kind: str) -> int:
+    """Resolve a ``before``/``after`` locator -> an instruction INDEX in ``body.instrs``. The locator is an int
+    (instruction index) or a str (an opcode NAME -> its first occurrence)."""
+    if isinstance(locator, bool) or not isinstance(locator, (int, str)):
+        raise SeqAuthorError(f"{kind} must be an instruction index (int) or an opcode name (str)")
+    if isinstance(locator, int):
+        if not 0 <= locator < len(body.instrs):
+            raise SeqAuthorError(f"{kind} = {locator} out of range (0..{len(body.instrs) - 1})")
+        return locator
+    for idx, ins in enumerate(body.instrs):
+        if ins.name == locator:
+            return idx
+    raise SeqAuthorError(f"{kind} = {locator!r}: no such opcode in this sequence "
+                         f"(has {[i.name for i in body.instrs]})")
+
+
+def insert_sequence(raw17: bytes, sub_no: int, source: str, *, before=None, after=None) -> tuple:
+    """Splice an assembled FRAGMENT (no terminator) into sub_no's body at a ``before``/``after`` locator (an
+    instruction index or an opcode name). The body's terminator stays last. Returns (new_raw17, warnings)."""
+    try:
+        model = _sc.parse(raw17)
+    except _sc.SeqCodecError as ex:
+        raise SeqAuthorError(f"malformed raw17: {ex}")
+    if not isinstance(sub_no, int) or isinstance(sub_no, bool) or not 0 <= sub_no < model.seq_count:
+        raise SeqAuthorError(f"seq = {sub_no!r} is not a valid sub_no (0..{model.seq_count - 1})")
+    if model.seq_offset[sub_no] == 0:
+        raise SeqAuthorError(f"seq {sub_no} has no sequence (seqOffset 0 sentinel)")
+    if (before is None) == (after is None):
+        raise SeqAuthorError("give exactly one of before / after (an instruction index or opcode name)")
+    body = model.body_for(sub_no)
+    try:
+        frag = _seqasm.assemble_fragment(source)
+    except _seqasm.SeqAsmError as ex:
+        raise SeqAuthorError(f"seq {sub_no} fragment: {ex}")
+    pos = _locate(body, before, "before") if before is not None else _locate(body, after, "after") + 1
+    if pos >= len(body.instrs):                          # never splice at/after the terminator
+        raise SeqAuthorError(f"seq {sub_no}: insert position {pos} is at/after the terminator -- "
+                             f"insert before the final {body.instrs[-1].name}")
+    warnings = []
+    others = tuple(s for s in range(model.seq_count) if model.seq_offset[s] == body.offset and s != sub_no)
+    if others:
+        warnings.append(f"seq {sub_no} also shares its body with sub(s) {','.join(str(s) for s in others)} "
+                        f"-- the insert applies to ALL of them")
+    new = [_sc.Instr(i.op, 0, list(i.operands)) for i in body.instrs]
+    for k, ins in enumerate(frag):
+        new.insert(pos + k, _sc.Instr(ins.op, 0, list(ins.operands)))
+    body.instrs = new
+    try:
+        out = _sc.serialize_repacked(model)
+    except _sc.SeqCodecError as ex:
+        raise SeqAuthorError(f"seq {sub_no}: {ex}")
+    problems = lint_seq(out)
+    if problems:
+        raise SeqAuthorError(f"seq {sub_no} insert would produce an invalid raw17: {'; '.join(problems)}")
+    return out, warnings
+
+
+def apply_seq_inserts(raw17: bytes, specs) -> tuple:
+    """Apply ``[{seq, source, before|after}, ...]`` fragment inserts in order. Returns (new_raw17, warnings)."""
+    if not isinstance(specs, list):
+        raise SeqAuthorError("[[scene.seq_insert]] must be a list of tables")
+    b = raw17
+    warnings: list = []
+    for n, spec in enumerate(specs):
+        if not isinstance(spec, dict):
+            raise SeqAuthorError(f"[[scene.seq_insert]] #{n} must be a table (got {type(spec).__name__})")
+        unknown = set(spec) - {"seq", "source", "before", "after"}
+        if unknown:
+            raise SeqAuthorError(f"[[scene.seq_insert]] #{n}: unknown key(s) {sorted(unknown)} "
+                                 f"(expected seq / source / before / after)")
+        seq, source = spec.get("seq"), spec.get("source")
+        if not isinstance(seq, int) or isinstance(seq, bool):
+            raise SeqAuthorError(f"[[scene.seq_insert]] #{n} needs an integer seq")
+        if not isinstance(source, str) or not source.strip():
+            raise SeqAuthorError(f"[[scene.seq_insert]] #{n} needs a non-empty source string")
+        try:
+            b, w = insert_sequence(b, seq, source, before=spec.get("before"), after=spec.get("after"))
+        except SeqAuthorError as ex:
+            raise SeqAuthorError(f"[[scene.seq_insert]] #{n}: {ex}")
+        warnings += w
+    return b, warnings
+
+
+def apply_seq_replaces(raw17: bytes, specs) -> tuple:
+    """Apply ``[{seq, source}, ...]`` body replacements in order. Returns (new_raw17, warnings)."""
+    if not isinstance(specs, list):
+        raise SeqAuthorError("[[scene.seq_replace]] must be a list of tables")
+    b = raw17
+    warnings: list = []
+    for n, spec in enumerate(specs):
+        if not isinstance(spec, dict):
+            raise SeqAuthorError(f"[[scene.seq_replace]] #{n} must be a table (got {type(spec).__name__})")
+        unknown = set(spec) - {"seq", "source"}
+        if unknown:
+            raise SeqAuthorError(f"[[scene.seq_replace]] #{n}: unknown key(s) {sorted(unknown)} (expected seq / source)")
+        seq, source = spec.get("seq"), spec.get("source")
+        if not isinstance(seq, int) or isinstance(seq, bool):
+            raise SeqAuthorError(f"[[scene.seq_replace]] #{n} needs an integer seq (the sub_no to replace)")
+        if not isinstance(source, str) or not source.strip():
+            raise SeqAuthorError(f"[[scene.seq_replace]] #{n} needs a non-empty source string")
+        try:
+            b, w = replace_sequence(b, seq, source)
+        except SeqAuthorError as ex:
+            raise SeqAuthorError(f"[[scene.seq_replace]] #{n}: {ex}")
+        warnings += w
+    return b, warnings
+
+
+def validate_replaces(raw17: bytes, specs) -> list:
+    """Offline problems (empty => OK): re-run the replaces on a copy + surface any SeqAuthorError as a message."""
+    try:
+        apply_seq_replaces(raw17, specs)
+        return []
+    except SeqAuthorError as ex:
+        return [str(ex)]
+
+
+def validate_inserts(raw17: bytes, specs) -> list:
+    """Offline problems (empty => OK): re-run the inserts on a copy + surface any SeqAuthorError as a message."""
+    try:
+        apply_seq_inserts(raw17, specs)
+        return []
+    except SeqAuthorError as ex:
+        return [str(ex)]

ff9mapkit/battle/seqcodec.py

@@ -0,0 +1,300 @@
+"""Lossless codec for the raw17 ``btlseq`` attack-SEQUENCE body -- parse -> model -> re-serialize, the
+foundation the disassembler (``seqdis``) and the same-length patcher (``seqpatch``) read from. The raw17
+opening-CAMERA block (``[camOffset:]``) is a SEPARATE, already-solved codec (``camera_codec``); this module
+owns the choreography BODY (``[bodyStart, camOffset)``) the camera codec slices verbatim.
+
+PROVEN against the engine source (``btlseq.cs``: ``ReadBattleSequence`` :32-68, the ``Sequencer`` interpreter
+:177-243, the 34-entry ``gSeqProg[]`` delegate table :1223-1259, the ``AdvanceSeqCode`` operand-width table
+:1165-1218, and every ``SeqExec*``/``SeqInit*`` handler) and a 562-file / 3814-sequence corpus sweep:
+``serialize(parse(b)) == b`` byte-exact on 562/562 real donors (the raw16/camera-codec golden analog).
+
+Format facts (all little-endian, all offsets absolute file positions):
+
+* Header (8 fixed bytes + 3 variable tables): ``seqBlockOffset i16 @0`` (constant 4; read but unused -- kept
+  verbatim), ``camOffset i16 @2`` (start of the camera block), ``seqCount i16 @4``, ``animCount i16 @6``,
+  then ``seqOffset[seqCount] i16``, ``animList[animCount] i32``, ``seqBaseAnim[seqCount] u8``.
+* ``bodyStart = 8 + 3*seqCount + 4*animCount`` (always even). Sequence body region = ``[bodyStart, camOffset)``.
+* THE +4 SKEW: a ``seqOffset[i]`` value is the file position MINUS 4 -- sequence i's bytes start at
+  ``seqOffset[i] + 4``. ``0`` is a "no sequence" sentinel (absent in the corpus, supported defensively).
+* Each sequence is a flat opcode stream: ``[op u8][operands...]``, terminated by ``0x00`` End or ``0x18``
+  FastEnd. Several ``seqOffset`` slots may ALIAS one body (a verbatim duplicate offset -- attacks that share
+  choreography); bodies never partially overlap. Inter-body + trailing padding is NOT a derivable alignment
+  rule (0/1-byte gaps that can land on odd boundaries; 5 scenes carry a 4-byte trailing pad) -> captured VERBATIM.
+* The interpreter guard is ``op > gSeqProg.Length`` (== ``> 34``), so an opcode byte of exactly ``34`` (0x22)
+  is NOT coerced -- it indexes ``gSeqProg[34]`` out of bounds, a latent engine crash; ``35..255`` coerce to
+  ``0`` End. Valid opcodes are 0..33; this codec rejects a body opcode of ``34..255`` (strict, for safety).
+"""
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass, field as _field
+
+
+class SeqCodecError(ValueError):
+    pass
+
+
+# ----------------------------------------------------------------- the 34-opcode table (gSeqProg[] @1223-1259)
+# Each entry: name, [ (operand_name, rel_offset_from_opcode, width, signed, kind) ... ]. The instruction TOTAL
+# size = 1 + sum(widths) (every byte is covered, incl. the 0x19 discarded-but-present pad). ``kind`` drives the
+# disassembler rendering + the patch-site taxonomy. Widths/signedness transcribed from each SeqExec*/SeqInit*
+# handler's Read* calls AND cross-checked against the AdvanceSeqCode skip table (skip+1 == size for all 34).
+_OPS = {
+    0x00: ("End", []),
+    0x01: ("Wait", [("frames", 1, 1, False, "frames")]),
+    0x02: ("Calc", []),
+    0x03: ("MoveToTarget", [("frames", 1, 1, False, "frames"), ("distance", 2, 2, True, "distance")]),
+    0x04: ("MoveToTurn", [("frames", 1, 1, False, "frames")]),
+    0x05: ("Anim", [("anim_code", 1, 1, False, "anim_code")]),
+    0x06: ("SVfx", [("svfx_no", 1, 2, False, "svfx"), ("param", 3, 1, False, "param"),
+                    ("time", 4, 1, False, "frames")]),
+    0x07: ("WaitAnim", []),
+    0x08: ("Vfx", [("fx_no", 1, 2, False, "vfx"), ("a0", 3, 2, True, "coord"),
+                   ("a1", 5, 2, True, "coord"), ("a2", 7, 2, True, "coord")]),
+    0x09: ("WaitLoadVfx", []),
+    0x0A: ("StartVfx", []),
+    0x0B: ("WaitVfx", []),
+    0x0C: ("Scale", [("factor", 1, 2, True, "scale"), ("frames", 3, 1, False, "frames")]),
+    0x0D: ("MeshHide", [("mask", 1, 2, False, "mesh_mask")]),
+    0x0E: ("Message", [("mess_id", 1, 1, False, "message")]),
+    0x0F: ("MeshShow", [("mask", 1, 2, False, "mesh_mask")]),
+    0x10: ("SetCamera", [("cam", 1, 1, False, "camera")]),
+    0x11: ("DefaultIdle", [("on_off", 1, 1, False, "flag")]),
+    0x12: ("RunCamera", [("cam", 1, 1, False, "camera")]),   # cam read inside a predicate; layout stable
+    0x13: ("MoveToPoint", [("frames", 1, 1, False, "frames"), ("x", 2, 2, True, "coord"),
+                           ("y", 4, 2, True, "coord"), ("z", 6, 2, True, "coord")]),
+    0x14: ("Turn", [("dir", 1, 2, True, "dir"), ("add", 3, 2, True, "angle"), ("time", 5, 1, False, "frames")]),
+    0x15: ("TexAnimPlay", [("tex", 1, 1, False, "tex")]),
+    0x16: ("TexAnimOnce", [("tex", 1, 1, False, "tex")]),
+    0x17: ("TexAnimStop", [("tex", 1, 1, False, "tex")]),
+    0x18: ("FastEnd", []),
+    0x19: ("Sfx", [("sfx_no", 1, 2, False, "sfx"), ("time", 3, 1, False, "frames"),
+                   ("_pad", 4, 1, False, "pad"), ("vol", 5, 1, False, "param")]),  # +4 is a discarded HOLE
+    0x1A: ("VfxContact", [("fx_no", 1, 2, False, "vfx"), ("a0", 3, 2, True, "coord"),
+                          ("a1", 5, 2, True, "coord"), ("a2", 7, 2, True, "coord")]),
+    0x1B: ("MoveToOffset", [("frames", 1, 1, False, "frames"), ("dx", 2, 2, True, "coord"),
+                            ("dy", 4, 2, True, "coord"), ("dz", 6, 2, True, "coord")]),
+    0x1C: ("TargetBone", [("bone", 1, 1, False, "bone")]),
+    0x1D: ("FadeOut", [("frames", 1, 1, False, "fade")]),
+    0x1E: ("MoveToTargetZ", [("frames", 1, 1, False, "frames"), ("distance", 2, 2, True, "distance")]),
+    0x1F: ("Shadow", [("on_off", 1, 1, False, "flag")]),
+    0x20: ("RunCameraForced", [("cam", 1, 1, False, "camera")]),
+    0x21: ("MessageTitle", [("mess_id", 1, 1, False, "message")]),
+}
+TERMINATORS = (0x00, 0x18)
+MAX_OPCODE = 0x21                                   # 33; a body byte of 34 is the latent gSeqProg[34] crash
+
+
+def _size(op: int) -> int:
+    fields = _OPS[op][1]
+    return 1 + sum(w for _n, _o, w, _s, _k in fields)
+
+
+SIZE = {op: _size(op) for op in _OPS}               # opcode -> total instruction size (incl. opcode byte)
+OP_NAME = {op: nm for op, (nm, _f) in _OPS.items()}
+
+
+# ----------------------------------------------------------------- the in-memory model
+@dataclass
+class Instr:
+    op: int
+    offset: int                # absolute file offset of the opcode byte (in the source raw17)
+    operands: list             # decoded ints, parallel to _OPS[op][1] field descriptors
+
+    @property
+    def name(self) -> str:
+        return OP_NAME[self.op]
+
+    @property
+    def fields(self):
+        return _OPS[self.op][1]
+
+
+@dataclass
+class Body:
+    offset: int                # the seqOffset VALUE (file-pos - 4); absolute start = offset + 4
+    gap_before: bytes          # alignment padding immediately before this body (verbatim)
+    instrs: list               # [Instr]
+
+
+@dataclass
+class Raw17:
+    seq_block_offset: int
+    cam_offset: int
+    seq_count: int
+    anim_count: int
+    seq_offset: list           # [int] per sub_no (the seqOffset table; 0 = sentinel)
+    anim_list: list            # [int] global anim ids (i32)
+    seq_base_anim: list        # [int] per sub_no
+    bodies: list               # [Body] in file (ascending-abs-start) order, distinct offsets only
+    final_pad: bytes           # padding between the last body end and cam_offset (verbatim)
+    camera_block: bytes        # raw17[cam_offset:] verbatim (the separate camera codec owns it)
+    seq_block_raw: bytes = _field(default=b"", repr=False)   # original header tables region (unused; reserved)
+
+    @property
+    def body_start(self) -> int:
+        return 8 + 3 * self.seq_count + 4 * self.anim_count
+
+    def body_for(self, sub_no: int):
+        """The Body a sub_no's seqOffset points at (None for the 0 sentinel / out of range)."""
+        if not 0 <= sub_no < self.seq_count:
+            return None
+        off = self.seq_offset[sub_no]
+        if off == 0:
+            return None
+        for b in self.bodies:
+            if b.offset == off:
+                return b
+        return None
+
+
+# ----------------------------------------------------------------- parse
+def _decode_instr(raw: bytes, pos: int) -> Instr:
+    op = raw[pos]
+    if op > MAX_OPCODE:
+        raise SeqCodecError(f"opcode {op} (0x{op:02x}) at offset {pos} is out of range 0..{MAX_OPCODE} "
+                            f"(34 would crash the engine's gSeqProg[34] index)")
+    operands = []
+    for _name, rel, w, signed, _kind in _OPS[op][1]:
+        operands.append(int.from_bytes(raw[pos + rel:pos + rel + w], "little", signed=signed))
+    return Instr(op, pos, operands)
+
+
+def _decode_body(raw: bytes, abs_start: int, limit: int) -> tuple:
+    """Decode one sequence from ``abs_start`` to its terminator. ``limit`` (== cam_offset) bounds the walk.
+    Returns (instrs, end_pos)."""
+    pos = abs_start
+    instrs = []
+    guard = 0
+    while pos < limit:
+        guard += 1
+        if guard > 100000:
+            raise SeqCodecError(f"sequence at {abs_start} runs away (no terminator before offset {limit})")
+        ins = _decode_instr(raw, pos)
+        sz = SIZE[ins.op]
+        if pos + sz > limit:
+            raise SeqCodecError(f"instruction {ins.name} at {pos} overruns the body region (end {pos + sz} "
+                                f"> camOffset {limit})")
+        instrs.append(ins)
+        pos += sz
+        if ins.op in TERMINATORS:
+            return instrs, pos
+    raise SeqCodecError(f"sequence at {abs_start} reached camOffset {limit} with no terminator")
+
+
+def parse(raw17: bytes) -> Raw17:
+    """Parse a raw17 into a lossless :class:`Raw17` model (header + per-body decoded instructions + the verbatim
+    camera block). ``serialize(parse(b)) == b`` byte-exact for valid donors."""
+    if len(raw17) < 8:
+        raise SeqCodecError(f"raw17 too short ({len(raw17)} bytes)")
+    seq_block_offset, cam_offset, seq_count, anim_count = struct.unpack_from("<hhhh", raw17, 0)
+    if seq_count < 0 or anim_count < 0:
+        raise SeqCodecError(f"bad header (seqCount={seq_count}, animCount={anim_count})")
+    if not 0 < cam_offset <= len(raw17):
+        raise SeqCodecError(f"bad camOffset {cam_offset} (file {len(raw17)} bytes)")
+    table_end = 8 + 2 * seq_count + 4 * anim_count + seq_count   # seqOffset[] + animList[] + seqBaseAnim[]
+    if table_end > len(raw17):                                   # bound BEFORE the unpacks so a malformed header
+        raise SeqCodecError(f"header tables (end {table_end}) run past EOF (file {len(raw17)} bytes) -- "
+                            f"seqCount={seq_count}, animCount={anim_count}")   # raises cleanly, never a struct.error
+    off = 8
+    seq_offset = list(struct.unpack_from(f"<{seq_count}h", raw17, off)); off += 2 * seq_count
+    anim_list = list(struct.unpack_from(f"<{anim_count}i", raw17, off)); off += 4 * anim_count
+    seq_base_anim = list(raw17[off:off + seq_count]); off += seq_count
+    body_start = off
+    if body_start != 8 + 3 * seq_count + 4 * anim_count:
+        raise SeqCodecError("header table region length mismatch (internal)")
+    if body_start > cam_offset:
+        raise SeqCodecError(f"header tables (end {body_start}) overrun camOffset {cam_offset}")
+
+    # distinct, nonzero offsets, decoded once in ascending abs-start order (aliases share a body)
+    distinct = sorted(set(o for o in seq_offset if o != 0))
+    bodies = []
+    prev_end = body_start
+    for o in distinct:
+        abs_start = o + 4
+        if abs_start < body_start or abs_start >= cam_offset:
+            raise SeqCodecError(f"seqOffset {o} (abs {abs_start}) outside the body region "
+                                f"[{body_start}, {cam_offset})")
+        if abs_start < prev_end:                          # a DISTINCT offset landing inside an earlier body =
+            raise SeqCodecError(f"seqOffset {o} (abs {abs_start}) overlaps an earlier sequence body that ends "
+                                f"at {prev_end} -- partial overlap (bodies must be disjoint or EXACT aliases; "
+                                f"a re-serialize would double-emit the shared tail)")   # 0 in the corpus
+        gap = bytes(raw17[prev_end:abs_start])
+        instrs, end = _decode_body(raw17, abs_start, cam_offset)
+        bodies.append(Body(o, gap, instrs))
+        prev_end = max(prev_end, end)
+    final_pad = bytes(raw17[prev_end:cam_offset])
+    return Raw17(seq_block_offset, cam_offset, seq_count, anim_count, seq_offset, anim_list,
+                 seq_base_anim, bodies, final_pad, bytes(raw17[cam_offset:]))
+
+
+# ----------------------------------------------------------------- serialize
+def emit_instr(ins: Instr) -> bytes:
+    """One instruction's bytes (opcode + operands), byte-exact (covers the 0x19 discarded-pad byte)."""
+    if ins.op not in _OPS:                             # a directly-built Instr with a bogus opcode -> clean error
+        raise SeqCodecError(f"opcode {ins.op} is not a valid sequence opcode (0..{MAX_OPCODE})")
+    buf = bytearray(SIZE[ins.op])
+    buf[0] = ins.op
+    for (_name, rel, w, signed, _kind), val in zip(_OPS[ins.op][1], ins.operands):
+        buf[rel:rel + w] = int(val).to_bytes(w, "little", signed=signed)
+    return bytes(buf)
+
+
+def serialize(model: Raw17) -> bytes:
+    """Re-serialize the model. GOLDEN PATH (no body length change): header + tables verbatim + each body's
+    captured gap_before + its instruction bytes + final_pad + the verbatim camera block == the original file."""
+    out = bytearray()
+    out += struct.pack("<hhhh", model.seq_block_offset, model.cam_offset, model.seq_count, model.anim_count)
+    out += struct.pack(f"<{model.seq_count}h", *model.seq_offset)
+    out += struct.pack(f"<{model.anim_count}i", *model.anim_list)
+    out += bytes(model.seq_base_anim)
+    if len(out) != model.body_start:
+        raise SeqCodecError("serialized header length mismatch (internal)")
+    for b in model.bodies:
+        out += b.gap_before
+        for ins in b.instrs:
+            out += emit_instr(ins)
+    out += model.final_pad
+    out += model.camera_block
+    return bytes(out)
+
+
+_I16_MAX = (1 << 15) - 1
+
+
+def serialize_repacked(model: Raw17) -> bytes:
+    """Re-serialize with bodies RE-LAID contiguously + every offset recomputed -- the LENGTH-CHANGING path (used
+    after a body replace/insert, when ``serialize``'s preserve-exact-layout invariant no longer holds).
+
+    Only TWO things in the file reference positions: ``camOffset`` (@2) and ``seqOffset[]``. So the repack lays each
+    distinct body back-to-back from ``body_start`` (in model order), sets ``seqOffset[i] = new_body_start − 4`` (the
+    +4 skew; aliases inherit; the 0 sentinel stays 0), sets ``camOffset = align_up(last_body_end, 4)``, and
+    re-appends the camera block VERBATIM (its internal offsets are camOffset-relative, so it floats intact). The
+    result is NOT byte-identical to a donor (different padding) but is functionally equivalent + re-parses to the
+    same logical sequences. Both i16 offsets are range-checked."""
+    body_start = model.body_start
+    new_off_for = {}                                  # old seqOffset value -> new seqOffset value (file-pos - 4)
+    body_bytes = bytearray()
+    for b in model.bodies:
+        new_off_for[b.offset] = (body_start + len(body_bytes)) - 4
+        for ins in b.instrs:
+            body_bytes += emit_instr(ins)
+    last_end = body_start + len(body_bytes)
+    new_cam_offset = (last_end + 3) & ~3              # 4-align (SE convention; not strictly required by the engine)
+    if new_cam_offset > _I16_MAX:
+        raise SeqCodecError(f"repacked camOffset {new_cam_offset} exceeds Int16 ({_I16_MAX}) -- bodies too large")
+    new_seq_offset = [0 if o == 0 else new_off_for[o] for o in model.seq_offset]
+    for sub, o in enumerate(new_seq_offset):
+        if not 0 <= o <= _I16_MAX:
+            raise SeqCodecError(f"repacked seqOffset[{sub}] = {o} exceeds Int16 range -- sequence body too far")
+    out = bytearray()
+    out += struct.pack("<hhhh", model.seq_block_offset, new_cam_offset, model.seq_count, model.anim_count)
+    out += struct.pack(f"<{model.seq_count}h", *new_seq_offset)
+    out += struct.pack(f"<{model.anim_count}i", *model.anim_list)
+    out += bytes(model.seq_base_anim)
+    if len(out) != body_start:
+        raise SeqCodecError("repacked header length mismatch (internal)")
+    out += body_bytes
+    out += b"\x00" * (new_cam_offset - last_end)      # zero pad to the 4-aligned camOffset
+    out += model.camera_block
+    return bytes(out)

ff9mapkit/battle/seqdis.py

@@ -0,0 +1,106 @@
+"""The read-only DISASSEMBLER VIEW for a raw17 ``btlseq`` attack sequence -- the "see the choreography" step,
+the raw17 analog of :mod:`ff9mapkit.battle.battleai` (enemy AI). Decodes via the lossless :mod:`seqcodec`
+parse, then renders each sub-sequence (by ``sub_no`` == attack index) as named instructions with annotated
+operands + the resolved animation ids. Read-only + offline; only the open-source opcode NAMES are committed.
+
+The companion "find the offset to patch" view (``battle-seq --sites``) delegates to :mod:`seqpatch`.
+"""
+from __future__ import annotations
+
+from . import seqcodec as _sc
+
+
+def _anim_note(model: _sc.Raw17, sub_no: int, ins: _sc.Instr) -> str:
+    """For an Anim (0x05) instruction, resolve animCode -> the global anim id, mirroring SeqExecAnim
+    (btlseq.cs:596-618): 255 = default idle; else ``animList[seqBaseAnim[sub_no] + animCode]``."""
+    if ins.op != 0x05:
+        return ""
+    code = ins.operands[0]
+    if code == 255:
+        return "  # default idle"
+    base = model.seq_base_anim[sub_no] if 0 <= sub_no < len(model.seq_base_anim) else 0
+    idx = base + code
+    if 0 <= idx < len(model.anim_list):
+        return f"  # -> animList[{base}+{code}] = anim id {model.anim_list[idx]}"
+    return f"  # -> animList[{base}+{code}] OUT OF RANGE (animCount {len(model.anim_list)})"
+
+
+def _operand_str(ins: _sc.Instr) -> str:
+    parts = []
+    for (name, _rel, _w, _signed, _kind), val in zip(ins.fields, ins.operands):
+        if name == "_pad":
+            continue                                  # the 0x19 discarded hole -- not meaningful to show
+        parts.append(f"{name}={val}")
+    return ", ".join(parts)
+
+
+def _extra_note(ins: _sc.Instr) -> str:
+    if ins.op == 0x02:
+        return "  # commits a damage/effect pass (hit-count = #Calc)"
+    if ins.op in (0x0E, 0x21) and (ins.operands[0] & 0x80):
+        return "  # attack-name/title (bit7)"
+    if ins.op == 0x12:
+        return "  # camera fires only if the alt-camera predicate is true"
+    return ""
+
+
+def disassemble_seq(raw17: bytes) -> str:
+    """Render a raw17's attack sequences as annotated text: header summary, then each ``sub_no`` (== attack
+    index) as one line per instruction (named op + operands + resolved anim ids). Aliased slots are noted."""
+    try:
+        model = _sc.parse(raw17)
+    except _sc.SeqCodecError as ex:
+        return f"<unreadable/malformed raw17: {ex}>"
+    n_bodies = len(model.bodies)
+    lines = [f"btlseq: {model.seq_count} sequence slot(s), {model.anim_count} anim id(s), "
+             f"{n_bodies} distinct body(ies), camOffset {model.cam_offset}, "
+             f"camera block {len(model.camera_block)} B"]
+    seen: dict = {}                                   # offset -> first sub_no (alias detection)
+    for sub in range(model.seq_count):
+        off = model.seq_offset[sub]
+        base = model.seq_base_anim[sub] if sub < len(model.seq_base_anim) else 0
+        if off == 0:
+            lines.append(f"\n  -- sub {sub}  (no sequence / sentinel) --")
+            continue
+        if off in seen:
+            lines.append(f"\n  -- sub {sub}  -> ALIAS of sub {seen[off]} (offset {off}, base-anim {base}) --")
+            continue
+        seen[off] = sub
+        body = model.body_for(sub)
+        lines.append(f"\n  -- sub {sub}  (base-anim {base}, abs {off + 4}, {len(body.instrs)} instr) --")
+        for ins in body.instrs:
+            ops = _operand_str(ins)
+            note = _anim_note(model, sub, ins) or _extra_note(ins)
+            lines.append(f"    [{ins.offset}] {ins.name}({ops}){note}")
+    return "\n".join(lines)
+
+
+# ----------------------------------------------------------------- scene loading (install-gated, like battleai)
+def _scene_raw17(donor: str, game=None) -> bytes:
+    from . import extract as _extract
+    raw17 = _extract.read_scene_assets(donor, game=game).get("raw17")
+    if not raw17:
+        raise FileNotFoundError(f"no btlseq.raw17 found for battle scene {donor!r}")
+    return raw17
+
+
+def analyze_scene_seq(donor: str, game=None) -> str:
+    """Read a real battle scene's ``btlseq.raw17`` LIVE from the install + disassemble its attack sequences.
+    ``donor`` is the scene name after ``EVT_BATTLE_`` (e.g. ``EF_R007``)."""
+    return (f"# attack sequences of scene {donor} (EVT_BATTLE_{donor}.raw17)\n"
+            + disassemble_seq(_scene_raw17(donor, game=game)))
+
+
+def scene_seq_sites(donor: str, game=None) -> str:
+    """List a scene's patchable sequence operands (the ``[[scene.seq_patch]]`` targets): byte offset, width,
+    current value, context. Read-only -- the 'find the offset to patch' companion to the disassembly."""
+    from . import seqpatch as _seqpatch
+    sites = _seqpatch.constant_sites(_scene_raw17(donor, game=game))
+    lines = [f"# patchable sequence operands of scene {donor} ({len(sites)} sites)",
+             "# cite the offset in [[scene.seq_patch]] (seq = <sub_no>, at = <offset>, old = <value>, "
+             "new = <same-width value>)"]
+    for s in sites:
+        shared = f"  (SHARED: also drives sub {','.join(str(x) for x in s.shared_subs if x != s.sub_no)})" \
+            if len(s.shared_subs) > 1 else ""
+        lines.append(f"  sub{s.sub_no:<2} at={s.offset:<6} {s.width}B  {s.kind:<10} = {s.value:<8}  {s.where}{shared}")
+    return "\n".join(lines)