ff9mapkit 1.0.0b3__py3-none-any.whl

ff9mapkit/sps/catalog.py

@@ -0,0 +1,88 @@
+"""Live enumeration of a field's ``.sps`` effects from the install (Tier 0 catalog). INSTALL-GATED, like
+``extract.py``: nothing is baked -- the ``.sps``/``spt.tcb`` bytes are Square-Enix game data (gitignored, never
+shipped), and there is no Memoria name-table to transcribe -- so this reads the bundle on demand and degrades to
+``[]`` / ``None`` with no install or UnityPy. Reuses the same enumeration trio ``extract.write_native_project``
+uses: ``find_field`` -> ``env.container`` prefix filter -> ``_raw_bytes``. -> [[project-ff9-sps-authoring]].
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from . import codec
+
+
+@dataclass(frozen=True)
+class SpsEntry:
+    field_token: str    # what import/extract takes (a field id or an FBG/mapid token)
+    folder: str         # the donor FBG folder the effect lives under
+    sps_id: int         # the numeric .sps id (filename stem == the RunSPSCode arg)
+    container_key: str  # the env.container key, for a lazy byte read
+
+
+def _fieldmaps_prefix(folder: str) -> str:
+    return f"assets/resources/fieldmaps/{folder}/"
+
+
+def list_field_sps(field, *, game=None, bundle=None) -> list[SpsEntry]:
+    """Every ``.sps`` effect bin in a field's FBG folder, sorted by id. ``[]`` if the install/UnityPy is absent
+    or the field has no effects."""
+    try:
+        from .. import extract
+        _bundle, folder, _roles, env = extract.find_field(field, game=game, bundle=bundle)
+    except Exception:  # noqa: BLE001 -- no install / no UnityPy / unknown field -> empty catalog
+        return []
+    pref = _fieldmaps_prefix(folder)
+    out: list[SpsEntry] = []
+    for key in env.container:
+        if not key.startswith(pref) or not key.endswith(".sps.bytes"):
+            continue
+        stem = key.rsplit("/", 1)[-1][: -len(".sps.bytes")]
+        try:
+            sid = int(stem)
+        except ValueError:
+            continue
+        out.append(SpsEntry(str(field), folder, sid, key))
+    return sorted(out, key=lambda e: e.sps_id)
+
+
+def load_sps_bytes(entry: SpsEntry, *, game=None, bundle=None) -> bytes:
+    """Raw bytes of one effect bin."""
+    from .. import extract
+    _bundle, _folder, _roles, env = extract.find_field(entry.field_token, game=game, bundle=bundle)
+    return extract._raw_bytes(env.container[entry.container_key].read())
+
+
+def load_sps(entry: SpsEntry, *, game=None, bundle=None) -> codec.Sps:
+    """Parse one effect to its codec model (the detail/preview source)."""
+    return codec.parse(load_sps_bytes(entry, game=game, bundle=bundle))
+
+
+def load_tcb(field, *, game=None, bundle=None) -> bytes | None:
+    """The field's shared ``spt.tcb`` texture bytes (every effect in the field samples it), or ``None``."""
+    try:
+        from .. import extract
+        _bundle, folder, _roles, env = extract.find_field(field, game=game, bundle=bundle)
+    except Exception:  # noqa: BLE001
+        return None
+    from .. import extract
+    key = _fieldmaps_prefix(folder) + "spt.tcb.bytes"
+    for k, obj in env.container.items():            # ContainerHelper has no .get(); iterate items
+        if k == key:
+            return extract._raw_bytes(obj.read())
+    return None
+
+
+def effect_facts(sps: codec.Sps) -> list[tuple[str, str]]:
+    """Human-readable facts about one effect (for the CLI / Info Hub detail pane)."""
+    prims = [len(f) for f in sps.frames]
+    tp = sps.tpage
+    return [
+        ("kind", "SPS field effect"),
+        ("frames", str(sps.frame_count)),
+        ("prims/frame", f"{min(prims)}-{max(prims)}" if prims else "0"),
+        ("quad half-size", f"{sps.half_w}x{sps.half_h}"),
+        ("uv cells", str(len(sps.uv_table))),
+        ("ramp colours", str(len(sps.rgb_table))),
+        ("tpage", f"TP{tp['TP']} TX{tp['TX']} TY{tp['TY']}"),
+        ("clut", f"Y{sps.clut['ClutY']} X{sps.clut['ClutX']}"),
+    ]

ff9mapkit/sps/codec.py

@@ -0,0 +1,264 @@
+"""Lossless codec for the FF9 field ``.sps`` (Special Particle System) effect binary -- parse -> model ->
+re-serialize -> build, the foundation a future SPS browser / re-skin / creator reads from. An ``.sps`` is a
+multi-frame cloud of 2D textured billboard quads ("prims"); the PIXELS live in the shared per-scene
+``spt.tcb`` VRAM texture (a SEPARATE format -- the authoring gate), and the field ``.eb`` fires ``RunSPSCode``
+to load + place + animate it. This module owns only the ``.sps`` GEOMETRY/ANIMATION bytes -- the half we
+fully control. -> [[project-ff9-sps-authoring]].
+
+PROVEN against the engine source (``SPSEffect.LoadSPS`` / ``_GenerateSPSPrims`` :148-247, the TPage/Clut
+bitfields in ``TIMUtils``) and a 9-file Ice-Cavern corpus: ``serialize(parse(b)) == b`` byte-exact on 9/9
+real donors, and ``build(...)`` (a from-scratch constructor that recomputes every offset) reproduces all 9
+from high-level fields alone -- so the encoder needs no hand-authored offsets and a synthetic effect is
+well-formed under the same code path the engine uses.
+
+Format facts (all little-endian; frame-table values are ABSOLUTE file offsets):
+
+* Header: ``header0 u16 @0`` -- ``frame_count = header0 & 0x7FFF``; bit 15 = a flag (never set in the corpus,
+  carried opaque). ``tpage_raw u16 @2`` -- the TIM page word; the runtime OR-s the ABR blend bits (5-6) in
+  from the SPS instance, so they are NOT stored here. ``clut_raw u16 @4`` -- the palette word.
+  ``h_raw u8 @6`` / ``w_raw u8 @7`` -- the size byte does DOUBLE DUTY: quad half-size (world) = ``(raw-1)*2``,
+  UV-cell half-size (px) = ``raw-1``.
+* ``frame_offsets`` : ``u16[frame_count] @8`` -- each is the absolute offset of that frame's prim block.
+* ``work_offset = frame_count*2 + 8`` : ``rgb_offset u16`` (== the UV-table entry count). Then
+  ``pt = work_offset + 2`` (UV table base) and ``rgb = pt + rgb_offset*2 + 2`` (RGB table base; the ``+2``
+  skips a constant ``0x0010`` separator word that sits between the two tables).
+* UV table @ ``pt`` : ``rgb_offset`` x ``(u8 uvx, u8 uvy)``; a prim's UV cell = entry ``texpos & 0x0F``.
+* RGB table @ ``rgb`` : stride-4 ``(u8 r, u8 g, u8 b, u8 pad)`` ramp colors; a prim's color = entry
+  ``texpos >> 4`` (the runtime multiplies it by the instance ``fade``). The 4th ``pad`` byte is NOT read by
+  the colour path (stride-4, only r/g/b consumed) -- real files carry 0 or 1; the codec preserves it verbatim.
+* Each frame block @ its offset: ``u8 prim_count`` then ``prim_count`` x 3-byte prim
+  ``(i8 pos_x, i8 pos_y, u8 texpos)`` -- runtime world pos = ``pos << 2`` (so +-508 units), ``texpos`` packs
+  the UV index (low nibble) + RGB index (high nibble).
+* Canonical layout (what the real files use AND what ``build`` emits): header -> frame table -> rgb_offset
+  word -> UV table -> separator -> RGB table -> frame blocks (contiguous, in index order) -> 0..3 tail pad
+  bytes. ``parse`` captures the source frame offsets + tail verbatim, so ``serialize`` stays byte-exact even
+  on an off-canonical layout.
+"""
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass, field as _field
+
+
+class SpsCodecError(ValueError):
+    pass
+
+
+# ----------------------------------------------------------------------------- texpos / size bit helpers
+def pack_texpos(uv_index: int, rgb_index: int) -> int:
+    """Pack a UV-cell index (0..15) + RGB-ramp index (0..15) into a prim ``texpos`` byte."""
+    if not (0 <= uv_index <= 0x0F and 0 <= rgb_index <= 0x0F):
+        raise SpsCodecError(f"uv/rgb index out of nibble range (0..15): {uv_index},{rgb_index}")
+    return (rgb_index << 4) | uv_index
+
+
+def make_tpage(*, tp: int = 0, ty: int = 0, tx: int = 0) -> int:
+    """Build a ``tpage_raw`` word from its fields (TP = color mode 0=4bpp/1=8bpp/2=16bpp, TY*256/TX*64 =
+    VRAM base). ABR (blend) is set at runtime via the ``.eb`` ABR op, not stored, so it is omitted here."""
+    return ((tp & 3) << 7) | ((ty & 1) << 4) | (tx & 0x0F)
+
+
+def make_clut(*, cluty: int = 0, clutx: int = 0) -> int:
+    """Build a ``clut_raw`` word from its fields (ClutY = VRAM row, ClutX*16 = VRAM halfword x)."""
+    return ((cluty & 0x1FF) << 6) | (clutx & 0x3F)
+
+
+def _i8(v: int) -> int:
+    if not -128 <= v <= 127:
+        raise SpsCodecError(f"prim position {v} out of i8 range (-128..127)")
+    return v
+
+
+# ----------------------------------------------------------------------------- the model
+@dataclass
+class Prim:
+    """One textured billboard quad in a frame. ``pos_*`` are signed i8 (runtime ``<<2``); ``texpos`` packs
+    the UV-cell index (low nibble) + RGB-ramp index (high nibble)."""
+    pos_x: int
+    pos_y: int
+    texpos: int
+
+    @property
+    def uv_index(self) -> int:
+        return self.texpos & 0x0F
+
+    @property
+    def rgb_index(self) -> int:
+        return (self.texpos >> 4) & 0x0F
+
+
+def prim(pos_x: int, pos_y: int, uv_index: int, rgb_index: int) -> Prim:
+    """Construct a :class:`Prim` from explicit UV + RGB indices (friendlier than a raw ``texpos`` byte)."""
+    return Prim(pos_x, pos_y, pack_texpos(uv_index, rgb_index))
+
+
+@dataclass
+class Sps:
+    """A parsed / authorable ``.sps`` effect: header + per-frame prim lists + the shared UV + RGB tables."""
+    tpage_raw: int
+    clut_raw: int
+    h_raw: int
+    w_raw: int
+    frames: list[list[Prim]] = _field(default_factory=list)
+    uv_table: list[tuple[int, int]] = _field(default_factory=list)
+    rgb_table: list[tuple[int, int, int, int]] = _field(default_factory=list)
+    flag_bit15: int = 0
+    separator: int = 0x0010
+    tail: bytes = b""
+    # Captured source layout (set by parse). None for a from-scratch model -> serialize lays the frame
+    # blocks out canonically (contiguous, after the RGB table).
+    frame_offsets: list[int] | None = None
+
+    # --- decoded conveniences (mirror SPSEffect) ---
+    @property
+    def frame_count(self) -> int:
+        return len(self.frames)
+
+    @property
+    def half_w(self) -> int:
+        return (self.w_raw - 1) * 2
+
+    @property
+    def half_h(self) -> int:
+        return (self.h_raw - 1) * 2
+
+    @property
+    def tpage(self) -> dict:
+        v = self.tpage_raw
+        return {"TP": (v >> 7) & 3, "ABR": (v >> 5) & 3, "TY": (v >> 4) & 1, "TX": v & 0x0F}
+
+    @property
+    def clut(self) -> dict:
+        v = self.clut_raw
+        return {"ClutY": (v >> 6) & 0x1FF, "ClutX": v & 0x3F}
+
+
+# ----------------------------------------------------------------------------- parse
+def parse(data: bytes) -> Sps:
+    """Decode an ``.sps`` blob into an :class:`Sps`. Captures the frame offsets + trailing pad verbatim so
+    :func:`serialize` round-trips byte-exact."""
+    if len(data) < 8:
+        raise SpsCodecError(f".sps too short: {len(data)} bytes")
+    header0 = struct.unpack_from("<H", data, 0)[0]
+    frame_count = header0 & 0x7FFF
+    work_offset = frame_count * 2 + 8
+    if work_offset + 2 > len(data):
+        raise SpsCodecError(f"frame table ({frame_count} frames) overruns {len(data)}-byte file")
+    s = Sps(
+        tpage_raw=struct.unpack_from("<H", data, 2)[0],
+        clut_raw=struct.unpack_from("<H", data, 4)[0],
+        h_raw=data[6],
+        w_raw=data[7],
+        flag_bit15=(header0 >> 15) & 1,
+    )
+    s.frame_offsets = list(struct.unpack_from("<%dH" % frame_count, data, 8))
+    rgb_offset = struct.unpack_from("<H", data, work_offset)[0]
+    pt = work_offset + 2
+    rgb = pt + rgb_offset * 2 + 2
+    if rgb > len(data):
+        raise SpsCodecError("UV/RGB table overruns file")
+    # UV table = exactly rgb_offset entries, then the separator word.
+    for k in range(rgb_offset):
+        s.uv_table.append((data[pt + (k << 1)], data[pt + (k << 1) + 1]))
+    s.separator = struct.unpack_from("<H", data, pt + rgb_offset * 2)[0]
+    # Frame prim blocks.
+    for fo in s.frame_offsets:
+        prim_count = data[fo]
+        prims: list[Prim] = []
+        p = fo + 1
+        for _ in range(prim_count):
+            pos_x = struct.unpack_from("<b", data, p)[0]
+            pos_y = struct.unpack_from("<b", data, p + 1)[0]
+            prims.append(Prim(pos_x, pos_y, data[p + 2]))
+            p += 3
+        s.frames.append(prims)
+    # RGB table spans rgb -> the first frame block (canonical) or EOF; stride 4.
+    first_frame = min(s.frame_offsets) if s.frame_offsets else len(data)
+    rgb_end = first_frame if first_frame > rgb else len(data)
+    for k in range((rgb_end - rgb) // 4):
+        base = rgb + (k << 2)
+        s.rgb_table.append((data[base], data[base + 1], data[base + 2], data[base + 3]))
+    # Tail = bytes after the last structural element (verbatim alignment padding).
+    last_end = (max(fo + 1 + 3 * len(pr) for fo, pr in zip(s.frame_offsets, s.frames))
+                if s.frames else rgb_end)
+    struct_end = max(last_end, rgb + len(s.rgb_table) * 4, pt + rgb_offset * 2 + 2)
+    s.tail = data[struct_end:]
+    return s
+
+
+# ----------------------------------------------------------------------------- serialize
+def _layout(s: Sps):
+    """Return ``(frame_offsets, work_offset, pt, rgb, struct_end)``. Reuses the captured frame offsets when
+    present + consistent (byte-exact round-trip); else lays the frame blocks out canonically (contiguous,
+    right after the RGB table, in index order)."""
+    nframes = len(s.frames)
+    rgb_offset = len(s.uv_table)
+    work_offset = nframes * 2 + 8
+    pt = work_offset + 2
+    rgb = pt + rgb_offset * 2 + 2
+    rgb_end = rgb + len(s.rgb_table) * 4
+    if s.frame_offsets is not None and len(s.frame_offsets) == nframes:
+        frame_offsets = list(s.frame_offsets)
+    else:
+        frame_offsets = []
+        cur = rgb_end
+        for prims in s.frames:
+            frame_offsets.append(cur)
+            cur += 1 + 3 * len(prims)
+    last_end = (max(fo + 1 + 3 * len(pr) for fo, pr in zip(frame_offsets, s.frames))
+                if s.frames else rgb_end)
+    return frame_offsets, work_offset, pt, rgb, max(last_end, rgb_end)
+
+
+def serialize(s: Sps) -> bytes:
+    """Encode an :class:`Sps` back to ``.sps`` bytes (the inverse of :func:`parse`)."""
+    if len(s.uv_table) > 0xFFFF:
+        raise SpsCodecError("uv_table too large for a u16 rgb_offset")
+    frame_offsets, work_offset, pt, rgb, struct_end = _layout(s)
+    out = bytearray(struct_end + len(s.tail))
+    header0 = (len(s.frames) & 0x7FFF) | ((s.flag_bit15 & 1) << 15)
+    struct.pack_into("<H", out, 0, header0)
+    struct.pack_into("<H", out, 2, s.tpage_raw & 0xFFFF)
+    struct.pack_into("<H", out, 4, s.clut_raw & 0xFFFF)
+    out[6] = s.h_raw & 0xFF
+    out[7] = s.w_raw & 0xFF
+    for i, fo in enumerate(frame_offsets):
+        struct.pack_into("<H", out, 8 + i * 2, fo)
+    struct.pack_into("<H", out, work_offset, len(s.uv_table))
+    for k, (ux, uy) in enumerate(s.uv_table):
+        out[pt + (k << 1)] = ux & 0xFF
+        out[pt + (k << 1) + 1] = uy & 0xFF
+    struct.pack_into("<H", out, pt + len(s.uv_table) * 2, s.separator & 0xFFFF)
+    for k, (r, g, b, pad) in enumerate(s.rgb_table):
+        base = rgb + (k << 2)
+        out[base] = r & 0xFF
+        out[base + 1] = g & 0xFF
+        out[base + 2] = b & 0xFF
+        out[base + 3] = pad & 0xFF
+    for fo, prims in zip(frame_offsets, s.frames):
+        out[fo] = len(prims) & 0xFF
+        p = fo + 1
+        for pr in prims:
+            struct.pack_into("<b", out, p, _i8(pr.pos_x))
+            struct.pack_into("<b", out, p + 1, _i8(pr.pos_y))
+            out[p + 2] = pr.texpos & 0xFF
+            p += 3
+    if s.tail:
+        out[struct_end:struct_end + len(s.tail)] = s.tail
+    return bytes(out)
+
+
+# ----------------------------------------------------------------------------- build (from-scratch)
+def build(*, tpage_raw: int, clut_raw: int, h_raw: int, w_raw: int,
+          uv_table, rgb_table, frames, flag_bit15: int = 0, separator: int = 0x0010,
+          tail: bytes = b"") -> Sps:
+    """Construct a from-scratch :class:`Sps` (no captured layout -> :func:`serialize` emits the canonical
+    contiguous layout, recomputing every offset). ``frames`` is a list of prim lists; ``uv_table`` is
+    ``(x, y)`` pairs; ``rgb_table`` is ``(r, g, b, pad)`` ramp colors."""
+    return Sps(
+        tpage_raw=tpage_raw, clut_raw=clut_raw, h_raw=h_raw, w_raw=w_raw,
+        frames=[list(f) for f in frames],
+        uv_table=[tuple(t) for t in uv_table],
+        rgb_table=[tuple(t) for t in rgb_table],
+        flag_bit15=flag_bit15, separator=separator, tail=tail,
+    )

ff9mapkit/sps/edit.py

@@ -0,0 +1,184 @@
+"""``[[sps_edit]]`` -- declarative re-skin of an EXISTING ``.sps`` effect over its carried texture (Tier 1).
+Mirrors the ``[[logic_edit]]`` lifecycle (single error type, ``_int``/``_req`` guards, ``_edit_list`` container
+guard, an old-guard per op, a re-parse lint gate) but operates on the decoded :class:`codec.Sps` model -- the
+re-skin is semantic (recolour the RGB ramp, tint the whole ramp, rescale the quad/UV size, reposition the prims),
+so model edits are cleaner than byte-offset patches.
+
+NO texture work and NO ``.eb`` change: every op stays inside the ``.sps`` bin geometry/colour we fully control,
+over the donor's already-carried ``spt.tcb``. (The ``.eb``-side levers -- playback FRAMERATE and ABR blend mode --
+are RunSPSCode operands, not bin fields, and are a follow-up.) A bad edit raises :class:`SpsEditError` so it fails
+the BUILD, never the game. -> [[project-ff9-sps-authoring]].
+
+Schema (``field.toml``)::
+
+    [[sps_edit]]
+    kind = "recolor_ramp"   # overwrite one ramp colour
+    sps  = 2266             # REQUIRED selector: targets <sps>.sps.bytes in the field's sps/ sidecar
+    index = 1               # rgb_table row
+    old = [128, 128, 128]   # old-guard (current r,g,b) -> refuse on donor drift
+    new = [200, 40, 40]
+
+    [[sps_edit]]
+    kind = "tint"           # multiply EVERY ramp colour (recolour/brighten the whole effect)
+    sps  = 2266
+    mul  = [0, 0, 512]      # per-channel, 256 == identity (so this makes a grey effect blue)
+
+    [[sps_edit]]
+    kind = "scale"          # resize the quads + UV cells
+    sps  = 2266
+    old_size = [9, 9]       # [h_raw, w_raw] guard
+    new_size = [13, 13]
+
+    [[sps_edit]]
+    kind = "reposition"     # shift prims (one frame, or all)
+    sps  = 2266
+    dx = 4
+    dy = -2
+    # frame = 0             # optional; omit = every frame
+"""
+from __future__ import annotations
+
+from . import codec as _codec
+
+
+class SpsEditError(ValueError):
+    pass
+
+
+_KIND_KEYS = {
+    "recolor_ramp": {"kind", "sps", "index", "old", "new"},
+    "tint": {"kind", "sps", "mul"},
+    "scale": {"kind", "sps", "old_size", "new_size"},
+    "reposition": {"kind", "sps", "dx", "dy", "frame"},
+}
+
+
+def _edit_list(edits):
+    """Guard that ``edits`` is a list of tables (catches the ``[sps_edit]`` vs ``[[sps_edit]]`` mistake)."""
+    if not isinstance(edits, list):
+        raise SpsEditError("[[sps_edit]] must be an array of tables ([[sps_edit]], not [sps_edit])")
+    for n, e in enumerate(edits):
+        if not isinstance(e, dict):
+            raise SpsEditError(f"[[sps_edit]] #{n} must be a table, got {type(e).__name__}")
+    return edits
+
+
+def _int(e, key, ctx):
+    v = e.get(key)
+    if not isinstance(v, int) or isinstance(v, bool):
+        raise SpsEditError(f"{ctx}: {key!r} must be an integer, got {v!r}")
+    return v
+
+
+def _rgb(e, key, ctx):
+    v = e.get(key)
+    if not (isinstance(v, list) and len(v) == 3 and all(isinstance(c, int) and not isinstance(c, bool) for c in v)):
+        raise SpsEditError(f"{ctx}: {key!r} must be a [r, g, b] integer triple, got {v!r}")
+    if not all(0 <= c <= 255 for c in v):
+        raise SpsEditError(f"{ctx}: {key!r} {v} channel out of 0..255")
+    return tuple(v)
+
+
+def _check_keys(e, kind, ctx):
+    allowed = _KIND_KEYS[kind]
+    unknown = set(e) - allowed
+    if unknown:
+        raise SpsEditError(f"{ctx}: unknown key(s) {sorted(unknown)} for kind {kind!r} (allowed: {sorted(allowed)})")
+    for req in allowed - {"frame"}:
+        if req not in e:
+            raise SpsEditError(f"{ctx}: missing required key {req!r} for kind {kind!r}")
+
+
+def _apply_one(model: _codec.Sps, e: dict, ctx: str) -> None:
+    kind = e.get("kind")
+    if kind not in _KIND_KEYS:
+        raise SpsEditError(f"{ctx}: unknown kind {kind!r} (known: {sorted(_KIND_KEYS)})")
+    _check_keys(e, kind, ctx)
+
+    if kind == "recolor_ramp":
+        idx = _int(e, "index", ctx)
+        if not (0 <= idx < len(model.rgb_table)):
+            raise SpsEditError(f"{ctx}: index {idx} out of range (rgb_table has {len(model.rgb_table)})")
+        old = _rgb(e, "old", ctx)
+        cur = model.rgb_table[idx][:3]
+        if cur != old:
+            raise SpsEditError(f"{ctx}: old-guard mismatch at rgb_table[{idx}] -- expected {old}, found {cur}")
+        new = _rgb(e, "new", ctx)
+        model.rgb_table[idx] = (new[0], new[1], new[2], 0)
+
+    elif kind == "tint":
+        mul = e.get("mul")
+        if not (isinstance(mul, list) and len(mul) == 3 and all(isinstance(c, int) and not isinstance(c, bool) for c in mul)):
+            raise SpsEditError(f"{ctx}: 'mul' must be a [r, g, b] integer triple, got {mul!r}")
+        if not all(0 <= c <= 4096 for c in mul):
+            raise SpsEditError(f"{ctx}: 'mul' {mul} channel out of 0..4096 (256 == identity)")
+        for ri, (r, g, b, _pad) in enumerate(model.rgb_table):
+            model.rgb_table[ri] = (
+                min(255, (r * mul[0]) >> 8),
+                min(255, (g * mul[1]) >> 8),
+                min(255, (b * mul[2]) >> 8),
+                0,
+            )
+
+    elif kind == "scale":
+        old_size = e.get("old_size")
+        if not (isinstance(old_size, list) and len(old_size) == 2):
+            raise SpsEditError(f"{ctx}: 'old_size' must be [h_raw, w_raw], got {old_size!r}")
+        cur = [model.h_raw, model.w_raw]
+        if list(old_size) != cur:
+            raise SpsEditError(f"{ctx}: old-guard mismatch -- expected size {list(old_size)}, found {cur}")
+        new_size = e.get("new_size")
+        if not (isinstance(new_size, list) and len(new_size) == 2
+                and all(isinstance(c, int) and not isinstance(c, bool) and 1 <= c <= 255 for c in new_size)):
+            raise SpsEditError(f"{ctx}: 'new_size' must be two ints 1..255 [h_raw, w_raw], got {new_size!r}")
+        model.h_raw, model.w_raw = new_size[0], new_size[1]
+
+    elif kind == "reposition":
+        dx = _int(e, "dx", ctx)
+        dy = _int(e, "dy", ctx)
+        frame = e.get("frame")
+        if frame is not None:
+            if not isinstance(frame, int) or isinstance(frame, bool) or not (0 <= frame < model.frame_count):
+                raise SpsEditError(f"{ctx}: 'frame' {frame!r} out of range 0..{model.frame_count - 1}")
+            targets = [model.frames[frame]]
+        else:
+            targets = model.frames
+        for fr in targets:
+            for p in fr:
+                nx, ny = p.pos_x + dx, p.pos_y + dy
+                if not (-128 <= nx <= 127 and -128 <= ny <= 127):
+                    raise SpsEditError(f"{ctx}: reposition pushes a prim to ({nx},{ny}), out of i8 range (-128..127)")
+                p.pos_x, p.pos_y = nx, ny
+
+
+def apply_sps_edits(sps_bytes: bytes, edits, *, sps_id: int) -> bytes:
+    """Apply every ``[[sps_edit]]`` whose ``sps == sps_id`` to one ``.sps`` blob; return the new bytes.
+    No matching edit (or an empty list) -> byte-identical. Old-guarded; re-parses + lints the result (the SPS
+    analogue of the eblint gate). Raises :class:`SpsEditError` on any unsafe edit."""
+    _edit_list(edits)
+    mine = [e for e in edits if e.get("sps") == sps_id]
+    if not mine:
+        return bytes(sps_bytes)
+    model = _codec.parse(sps_bytes)
+    for n, e in enumerate(mine):
+        _apply_one(model, e, f"[[sps_edit]] sps={sps_id} #{n}")
+    # Structural gate: the result must re-encode and re-parse stably. (We do NOT run the authoring lint here:
+    # real shipping effects can index a nibble past a short table into adjacent data -- valid, deterministic --
+    # and that must remain editable. Each op already guards its own range; serialize's _i8 enforces positions.)
+    try:
+        out = _codec.serialize(model)
+        if _codec.serialize(_codec.parse(out)) != out:
+            raise SpsEditError(f"edited sps {sps_id} did not round-trip stably")
+    except _codec.SpsCodecError as ex:
+        raise SpsEditError(f"edited sps {sps_id} no longer encodes: {ex}") from ex
+    return out
+
+
+def validate_sps_edits(sps_bytes: bytes, edits, *, sps_id: int) -> list[str]:
+    """Offline problems for one bin's edits (empty == OK). Runs :func:`apply_sps_edits` and returns any
+    :class:`SpsEditError`/:class:`codec.SpsCodecError` as a message. NEVER raises (build-safe)."""
+    try:
+        apply_sps_edits(sps_bytes, edits, sps_id=sps_id)
+        return []
+    except (SpsEditError, _codec.SpsCodecError) as ex:
+        return [str(ex)]

ff9mapkit/sps/lint.py

@@ -0,0 +1,58 @@
+"""Offline structural validator for an authored / edited ``.sps`` effect (mirrors ``battle.seqauthor.lint_seq``:
+a bare ``list[str]`` of problems, empty == OK, NEVER raises). The codec guarantees a byte-exact round-trip of a
+PARSED file; this guards an AUTHORED or ``[[sps_edit]]``-edited model BEFORE serialize -> deploy, catching the
+references that would corrupt the bin or crash ``SPSEffect._GenerateSPSPrims`` at runtime. -> [[project-ff9-sps-authoring]].
+"""
+from __future__ import annotations
+
+from . import codec as _codec
+
+
+def lint_sps(model: _codec.Sps) -> list[str]:
+    """Structural problems of an :class:`codec.Sps` (empty list == OK). This is an AUTHORING-quality check
+    (for from-scratch / Tier-0 display): the uv/rgb index-in-table checks flag a prim that samples a cell you
+    never defined. NOTE a few real shipping effects legitimately index a nibble PAST a short table into the
+    adjacent data region (valid, deterministic engine behaviour), so this is NOT asserted clean on every donor
+    and is NOT used as the ``[[sps_edit]]`` gate (``edit.apply_sps_edits`` gates on encodability instead)."""
+    problems: list[str] = []
+    n_uv = len(model.uv_table)
+    n_rgb = len(model.rgb_table)
+
+    if not (1 <= model.frame_count <= 0x7FFF):
+        problems.append(f"frame_count {model.frame_count} out of range 1..32767")
+    if n_uv == 0:
+        problems.append("uv_table is empty -- prims have no UV cell to sample")
+    if n_uv > 0xFFFF:
+        problems.append(f"uv_table has {n_uv} entries (max 65535 for the u16 rgb_offset)")
+    if n_rgb == 0:
+        problems.append("rgb_table is empty -- prims have no ramp colour")
+    if not (1 <= model.w_raw <= 0xFF) or not (1 <= model.h_raw <= 0xFF):
+        problems.append(f"size bytes h_raw={model.h_raw} w_raw={model.w_raw} must be 1..255 "
+                        "(quad/UV half-size = (raw-1)*2 / (raw-1))")
+
+    for fi, frame in enumerate(model.frames):
+        if len(frame) > 0xFF:
+            problems.append(f"frame {fi}: {len(frame)} prims exceeds the 255-prim u8 count")
+        for pi, p in enumerate(frame):
+            if not (0 <= p.uv_index < n_uv):
+                problems.append(f"frame {fi} prim {pi}: uv_index {p.uv_index} out of range (uv_table has {n_uv})")
+            if not (0 <= p.rgb_index < n_rgb):
+                problems.append(f"frame {fi} prim {pi}: rgb_index {p.rgb_index} out of range (rgb_table has {n_rgb})")
+            if not (-128 <= p.pos_x <= 127) or not (-128 <= p.pos_y <= 127):
+                problems.append(f"frame {fi} prim {pi}: pos ({p.pos_x},{p.pos_y}) out of i8 range (-128..127)")
+
+    for ri, entry in enumerate(model.rgb_table):
+        r, g, b, _pad = entry      # the 4th (stride-4) byte is unused by the colour path; real files use 0 or 1
+        if not all(0 <= c <= 255 for c in (r, g, b)):
+            problems.append(f"rgb_table[{ri}]: colour {(r, g, b)} channel out of 0..255")
+    return problems
+
+
+def lint_sps_bytes(data: bytes) -> list[str]:
+    """Lint raw ``.sps`` bytes -- parse then lint, degrading to a problem string on a parse failure
+    (never raises, so a ``validate`` caller is build-safe)."""
+    try:
+        model = _codec.parse(data)
+    except _codec.SpsCodecError as ex:
+        return [f"unparseable .sps: {ex}"]
+    return lint_sps(model)