ff9mapkit 1.0.0b3__py3-none-any.whl

ff9mapkit/sjbinary.py

@@ -0,0 +1,285 @@
+"""SimpleJSON BINARY codec -- the format Memoria's ``JSONNode.Serialize`` / ``JSONNode.Deserialize`` use for
+the unencrypted per-slot extra save file ``SavedData_ww_Memoria_{slot}_{save}.dat``.
+
+This is the foundation for the #5 save-side item/equipment/gil editor: the extra file is what the game LOADS
+(it overrides the encrypted main block -- memory project-ff9-save-item-layout), and it stores items/equip/gil
+as a nested SimpleJSON tree, so editing it needs a real parse -> mutate -> re-serialize, NOT an in-place byte
+patch. This module is the parse/serialize half; the editor (a separate ``save_items`` surface) layers on top.
+
+Byte-exact with C# ``BinaryWriter`` (verified by a round-trip test against the real file):
+
+* tags + counts are **Int32 LE** (``BinaryWriter.Write((int)...)``);
+* strings are **.NET 7-bit-length-prefixed UTF-8** (``BinaryWriter.Write(string)`` / ``BinaryReader.ReadString``):
+  a 7-bit-encoded (LEB128) BYTE length then the UTF-8 bytes;
+* leaves are tagged: ``Value=3`` string, ``IntValue=4`` Int32, ``DoubleValue=5`` Double, ``BoolValue=6`` Bool
+  (1 byte), ``FloatValue=7`` Single. (``Array=1`` = count + children; ``Class=2`` = count + key/value pairs.)
+
+★ FIDELITY: ``JSONData.Serialize`` RE-INFERS a leaf's tag from its string value on every write (int->4, float->7,
+double->5, bool->6, else string->3). We instead **preserve each leaf's READ tag** -- which already equals what
+re-inference produces, because C# wrote the on-disk file via that same inference (so no Value(3) on disk ever
+holds a parseable number). Preserving the read tag + the ordered keys means an UNCHANGED tree re-serializes
+byte-for-byte identically; we never reproduce C#'s float/culture formatting. A changed int leaf emits ``IntValue``
+(tag 4) -- exactly what C# does for an int.
+"""
+from __future__ import annotations
+
+import io
+import struct
+
+# JSONBinaryTag (SimpleJSON/JSONBinaryTag.cs)
+ARRAY = 1
+CLASS = 2
+VALUE = 3            # string
+INT = 4             # Int32
+DOUBLE = 5
+BOOL = 6
+FLOAT = 7           # Single
+
+
+class SJData:
+    """A leaf node: a tag (VALUE/INT/DOUBLE/BOOL/FLOAT) + its typed Python value (str/int/float/bool)."""
+    __slots__ = ("tag", "value")
+
+    def __init__(self, tag: int, value):
+        self.tag = tag
+        self.value = value
+
+    def __repr__(self):
+        return f"SJData(tag={self.tag}, value={self.value!r})"
+
+
+class SJArray:
+    """An ordered list of child nodes (JSONArray)."""
+    __slots__ = ("items",)
+
+    def __init__(self, items=None):
+        self.items = list(items) if items is not None else []
+
+    def __len__(self):
+        return len(self.items)
+
+    def __iter__(self):
+        return iter(self.items)
+
+    def __repr__(self):
+        return f"SJArray({len(self.items)} items)"
+
+
+class SJClass:
+    """An ORDERED string->node map (JSONClass). Key order is preserved (C# Dictionary iterates in insertion
+    order for an add-only save tree), which is what makes an unchanged re-serialize byte-identical."""
+    __slots__ = ("_items", "_idx")
+
+    def __init__(self):
+        self._items: list = []          # [(key, node), ...] in on-disk order
+        self._idx: dict = {}            # key -> index in _items
+
+    def add(self, key: str, node) -> None:
+        """Append a key/node in order (used by the parser; a duplicate key replaces in place, mirroring a dict)."""
+        if key in self._idx:
+            self._items[self._idx[key]] = (key, node)
+        else:
+            self._idx[key] = len(self._items)
+            self._items.append((key, node))
+
+    def get(self, key: str):
+        i = self._idx.get(key)
+        return self._items[i][1] if i is not None else None
+
+    def set(self, key: str, node) -> None:
+        """Replace an existing key's node in place (keeps order). Raises KeyError if the key is absent (the
+        editor only mutates existing leaves -- adding a new key would change the layout)."""
+        if key not in self._idx:
+            raise KeyError(f"key {key!r} not in this SJClass (keys: {list(self._idx)})")
+        i = self._idx[key]
+        self._items[i] = (key, node)
+
+    def keys(self):
+        return [k for k, _ in self._items]
+
+    def __contains__(self, key):
+        return key in self._idx
+
+    def __iter__(self):
+        return iter(self._items)                       # (key, node) pairs, in order
+
+    def __len__(self):
+        return len(self._items)
+
+    def __repr__(self):
+        return f"SJClass(keys={self.keys()})"
+
+
+# --- low-level .NET BinaryReader/Writer primitives ------------------------------------------------
+
+def _read_7bit(r) -> int:
+    """.NET ``Read7BitEncodedInt`` -- LEB128 unsigned (low 7 bits per byte, high bit = continue)."""
+    val = 0
+    shift = 0
+    while True:
+        b = r.read(1)
+        if not b:
+            raise ValueError("unexpected EOF reading a 7-bit length")
+        b = b[0]
+        val |= (b & 0x7F) << shift
+        if not (b & 0x80):
+            return val
+        shift += 7
+        if shift > 35:
+            raise ValueError("7-bit length too long (corrupt stream)")
+
+
+def _write_7bit(w, n: int) -> None:
+    if n < 0:
+        raise ValueError("string length cannot be negative")
+    while n >= 0x80:
+        w.write(bytes([(n & 0x7F) | 0x80]))
+        n >>= 7
+    w.write(bytes([n]))
+
+
+def _read_string(r) -> str:
+    n = _read_7bit(r)
+    raw = r.read(n)
+    if len(raw) != n:
+        raise ValueError(f"unexpected EOF reading a {n}-byte string")
+    return raw.decode("utf-8")
+
+
+def _write_string(w, s: str) -> None:
+    raw = s.encode("utf-8")
+    _write_7bit(w, len(raw))
+    w.write(raw)
+
+
+def _read_i32(r) -> int:
+    raw = r.read(4)
+    if len(raw) != 4:
+        raise ValueError("unexpected EOF reading an Int32")
+    return struct.unpack("<i", raw)[0]
+
+
+def _write_i32(w, v: int) -> None:
+    w.write(struct.pack("<i", v))
+
+
+# --- tree (de)serialization (mirrors JSONNode.Deserialize / *.Serialize) --------------------------
+
+def _deserialize(r):
+    tag = _read_i32(r)
+    if tag == ARRAY:
+        n = _read_i32(r)
+        return SJArray([_deserialize(r) for _ in range(n)])
+    if tag == CLASS:
+        n = _read_i32(r)
+        c = SJClass()
+        for _ in range(n):
+            key = _read_string(r)
+            c.add(key, _deserialize(r))
+        return c
+    if tag == VALUE:
+        return SJData(VALUE, _read_string(r))
+    if tag == INT:
+        return SJData(INT, _read_i32(r))
+    if tag == DOUBLE:
+        return SJData(DOUBLE, struct.unpack("<d", r.read(8))[0])
+    if tag == BOOL:
+        return SJData(BOOL, r.read(1)[0] != 0)
+    if tag == FLOAT:
+        return SJData(FLOAT, struct.unpack("<f", r.read(4))[0])
+    raise ValueError(f"unknown SimpleJSON tag {tag} at offset {r.tell() - 4}")
+
+
+def _serialize(node, w) -> None:
+    if isinstance(node, SJArray):
+        _write_i32(w, ARRAY)
+        _write_i32(w, len(node.items))
+        for it in node.items:
+            _serialize(it, w)
+    elif isinstance(node, SJClass):
+        _write_i32(w, CLASS)
+        _write_i32(w, len(node._items))
+        for key, child in node._items:
+            _write_string(w, key)
+            _serialize(child, w)
+    elif isinstance(node, SJData):
+        _write_i32(w, node.tag)
+        if node.tag == VALUE:
+            _write_string(w, node.value)
+        elif node.tag == INT:
+            _write_i32(w, int(node.value))
+        elif node.tag == DOUBLE:
+            w.write(struct.pack("<d", float(node.value)))
+        elif node.tag == BOOL:
+            w.write(b"\x01" if node.value else b"\x00")
+        elif node.tag == FLOAT:
+            w.write(struct.pack("<f", float(node.value)))
+        else:
+            raise ValueError(f"cannot serialize leaf with tag {node.tag}")
+    else:
+        raise TypeError(f"not an SJ node: {type(node).__name__}")
+
+
+# --- public API -----------------------------------------------------------------------------------
+
+def loads(data: bytes):
+    """Parse the SimpleJSON-binary ``data`` into a node tree. Returns ``(root, trailing)`` -- ``trailing`` is
+    any bytes after the single root tree (normally empty; preserved so a re-emit is byte-exact even if Memoria
+    ever pads the file)."""
+    r = io.BytesIO(data)
+    root = _deserialize(r)
+    trailing = r.read()
+    return root, trailing
+
+
+def dumps(root, trailing: bytes = b"") -> bytes:
+    """Serialize ``root`` (+ any preserved ``trailing`` bytes) back to SimpleJSON-binary bytes."""
+    w = io.BytesIO()
+    _serialize(root, w)
+    w.write(trailing)
+    return w.getvalue()
+
+
+def get_path(root, *keys):
+    """Walk a path of string keys (SJClass) / int indices (SJArray) and return the node, or ``None`` if any
+    step is missing. e.g. ``get_path(root, "40000_Common", "players", 0, "equip")``."""
+    node = root
+    for k in keys:
+        if isinstance(k, int) and isinstance(node, SJArray):
+            if k < 0 or k >= len(node.items):
+                return None
+            node = node.items[k]
+        elif isinstance(node, SJClass):
+            node = node.get(k)
+        else:
+            return None
+        if node is None:
+            return None
+    return node
+
+
+def diff_paths(a, b, _prefix=()):
+    """Yield the path (a tuple of string keys / int indices) of every spot where trees ``a`` and ``b`` differ.
+    A *structural* difference -- a different node type, a different SJClass key list, or a different SJArray
+    length -- yields the path of the differing node ITSELF and does not recurse into it; otherwise recursion
+    continues and differing leaves yield their own path. Used to VERIFY a save edit is scoped: an edit may only
+    touch paths under a known prefix (e.g. ``("40000_Common","items")``); anything else changing => abort."""
+    if type(a) is not type(b):
+        yield _prefix
+        return
+    if isinstance(a, SJData):
+        if a.tag != b.tag or a.value != b.value:
+            yield _prefix
+    elif isinstance(a, SJArray):
+        if len(a.items) != len(b.items):
+            yield _prefix                                  # a length change => the array itself changed
+        else:
+            for i, (x, y) in enumerate(zip(a.items, b.items)):
+                yield from diff_paths(x, y, _prefix + (i,))
+    elif isinstance(a, SJClass):
+        if a.keys() != b.keys():
+            yield _prefix                                  # a key added/removed/reordered => the class changed
+        else:
+            for k, _ in a._items:
+                yield from diff_paths(a.get(k), b.get(k), _prefix + (k,))
+    # any other type: treated as equal (the tree only holds SJData/SJArray/SJClass)

ff9mapkit/sps/__init__.py

@@ -0,0 +1,17 @@
+"""FF9 field ``.sps`` (Special Particle System) effect authoring -- the particle-effect analogue of the
+field / battle pillars. An ``.sps`` is a multi-frame cloud of 2D textured billboard quads ("prims") sampling
+the shared per-scene ``spt.tcb`` texture; the field ``.eb`` fires ``RunSPSCode`` to load, place, and loop it
+(~15 fps). This package owns the ``.sps`` GEOMETRY/ANIMATION bytes -- the half we fully control.
+
+``codec`` is the lossless parse / serialize / build foundation (proven byte-exact vs the engine source --
+``SPSEffect.LoadSPS`` / ``_GenerateSPSPrims`` -- and a 9-file Ice-Cavern corpus). The texture (``spt.tcb``,
+a PSX-VRAM blit blob) is a SEPARATE format and the real authoring gate; see [[project-ff9-sps-authoring]]
+for the tiered editor plan (catalog browser -> declarative re-skin -> from-scratch creator).
+
+NOTE: the kit already CARRIES a fork's ``.sps`` + ``spt.tcb`` verbatim (``extract.py`` / ``build.py``) so a
+forked field keeps its donor's effects ([[project-ff9-sps-fork]]). This package is the from-scratch AUTHORING
+half that the verbatim byte-copy doesn't cover.
+"""
+from __future__ import annotations
+
+from . import codec  # noqa: F401  (pure, no I/O -- safe to import always)

ff9mapkit/sps/author.py

@@ -0,0 +1,294 @@
+"""``[[sps]]`` -- author a NEW from-scratch field particle effect (Tier 2 creator), NO DLL.
+
+A ``[[sps]]`` block defines a brand-new effect: its GEOMETRY (a clone of an existing donor effect, re-authored;
+or a fully inline quad cloud via :func:`codec.build`) over a REUSED / BORROWED ``spt.tcb`` texture. This is
+**Route A** -- the new effect's ``tpage``/``clut``/UVs index pixels that already exist in some field's texture,
+so it draws purely from the TCB already in VRAM (``CommonSPSSystem.SetupSPSTexture`` falls through to the TCB for
+any id not in the hardcoded ``SPSConst.SPSTexture`` dict). Guaranteed no-DLL.
+
+The build writes ``<id>.sps.bytes`` + supplies the ``spt.tcb`` into ``FieldMaps/<FBG>/`` (``build._write_authored_sps``)
+and emits a ``RunSPSCode`` create+place trigger into the field's ``.eb`` (``content/sps_trigger.py``) so the effect
+spawns on field load. **Route B** (a custom PNG for genuinely NEW art) needs a Memoria patch -- the spsId->texture
+map is a hardcoded engine dict with no data hook -- so a ``texture = { png = ... }`` block is rejected with that
+pointer. -> [[project-ff9-sps-authoring]], docs/SPS.md.
+
+Schema (``field.toml``)::
+
+    # Clone a real donor effect's texture + colours, re-author the animation (the easiest creator primitive).
+    [[sps]]
+    id        = 5000
+    copy_from = { field = "303", sps = 2266 }   # take tpage/clut/uv/rgb/size from Ice-Cavern effect 2266
+    frames    = [ [ {pos=[0,0], uv=0, rgb=1} ], [ {pos=[2,-2], uv=0, rgb=2} ] ]   # optional: new geometry
+    pos       = [120, 30, -40]                  # world x, y, z (engine negates y); or [x, z] + y = N
+    slot      = 15
+    abr       = 1                               # 0=50%add 1=add 2=sub 3=25%add (omit = leave default)
+    framerate = 16                              # 16 = 1x
+
+    # Fully inline (power user): borrow a donor's tcb, author every byte via codec.build.
+    [[sps]]
+    id      = 5001
+    texture = { borrow_tcb = "303", tpage = { tp = 0, tx = 8, ty = 1 }, clut = { cluty = 251, clutx = 20 } }
+    size    = [9, 9]
+    uv      = [[0, 96], [32, 96]]
+    rgb     = [[255, 200, 80], [255, 120, 0]]
+    frames  = [ [ {pos=[0,0], uv=0, rgb=0} ], [ {pos=[2,-1], uv=1, rgb=1} ] ]
+    pos     = [0, 0, 0]
+    slot    = 14
+"""
+from __future__ import annotations
+
+import copy
+
+from . import codec as _codec
+from .lint import lint_sps
+
+# placement defaults: a high SPS slot avoids colliding with a donor's low-slot effects on a verbatim fork
+DEFAULT_SLOT = 15
+DEFAULT_ABR = 1           # ADDITIVE -- particle effects glow; the engine default (ABR_OFF) renders opaque black boxes
+SCALE_ONE = 4096
+FRAMERATE_ONE = 16
+
+
+class SpsAuthorError(ValueError):
+    pass
+
+
+def _block_list(blocks):
+    if not isinstance(blocks, list):
+        raise SpsAuthorError("[[sps]] must be an array of tables ([[sps]], not [sps])")
+    for n, b in enumerate(blocks):
+        if not isinstance(b, dict):
+            raise SpsAuthorError(f"[[sps]] #{n} must be a table, got {type(b).__name__}")
+    return blocks
+
+
+def _int(b, key, ctx):
+    v = b.get(key)
+    if not isinstance(v, int) or isinstance(v, bool):
+        raise SpsAuthorError(f"{ctx}: {key!r} must be an integer, got {v!r}")
+    return v
+
+
+def make_donor_loader(carried_dir=None):
+    """A ``donor_loader`` for :func:`build_sps_from_block`: ``field=None`` -> clone a CARRIED effect (read
+    ``carried_dir/<sps>.sps.bytes`` -- reuses the field's own texture, no tcb conflict); else load from the
+    install. The build passes ``carried_dir = <member>/sps`` so ``copy_from = {{ sps = N }}`` works."""
+    from pathlib import Path
+
+    def loader(field_token, sps_id):
+        if field_token is not None:
+            return _default_donor_loader(field_token, sps_id)
+        if carried_dir is None:
+            raise SpsAuthorError(f"copy_from sps={sps_id} (no field) clones a CARRIED effect, which needs the "
+                                 "field's sps/ sidecar -- not available here")
+        d = Path(carried_dir)
+        p = d / f"{int(sps_id)}.sps.bytes"
+        if not p.is_file():
+            avail = sorted(x.name[: -len('.sps.bytes')] for x in d.glob("*.sps.bytes")) if d.is_dir() else []
+            raise SpsAuthorError(f"copy_from sps={sps_id}: this field carries no {sps_id}.sps.bytes "
+                                 f"(carried effects: {avail or 'none'})")
+        return _codec.parse(p.read_bytes())
+    return loader
+
+
+def _default_donor_loader(field_token, sps_id) -> _codec.Sps:
+    """Load donor ``field``'s effect ``sps_id`` to a codec model, live from the install (for ``copy_from``)."""
+    if field_token is None:
+        raise SpsAuthorError(f"copy_from sps={sps_id} (no field) clones a CARRIED effect -- needs the field's "
+                             "sps/ sidecar (use the build path, not the bare loader)")
+    from . import catalog as _cat
+    rows = _cat.list_field_sps(field_token)
+    entry = next((e for e in rows if e.sps_id == int(sps_id)), None)
+    if entry is None:
+        have = [e.sps_id for e in rows]
+        raise SpsAuthorError(f"copy_from: field {field_token!r} has no SPS effect {sps_id} "
+                             + (f"(has: {have})" if have else "(no install / not readable)"))
+    return _cat.load_sps(entry)
+
+
+def _parse_frames(frames, ctx) -> list:
+    """``[[{pos=[x,y], uv=I, rgb=J}, ...], ...]`` -> ``list[list[codec.Prim]]``."""
+    if not isinstance(frames, list) or not frames:
+        raise SpsAuthorError(f"{ctx}: 'frames' must be a non-empty array of frames")
+    out = []
+    for fi, frame in enumerate(frames):
+        if not isinstance(frame, list):
+            raise SpsAuthorError(f"{ctx}: frame {fi} must be an array of prims")
+        prims = []
+        for pi, p in enumerate(frame):
+            if not isinstance(p, dict):
+                raise SpsAuthorError(f"{ctx}: frame {fi} prim {pi} must be a table {{pos, uv, rgb}}")
+            pos = p.get("pos")
+            if not (isinstance(pos, list) and len(pos) == 2 and all(isinstance(c, int) for c in pos)):
+                raise SpsAuthorError(f"{ctx}: frame {fi} prim {pi} 'pos' must be [x, y] ints, got {pos!r}")
+            uv = p.get("uv", 0)
+            rgb = p.get("rgb", 0)
+            if not all(isinstance(v, int) and not isinstance(v, bool) for v in (uv, rgb)):
+                raise SpsAuthorError(f"{ctx}: frame {fi} prim {pi} uv/rgb must be integer indices")
+            try:
+                prims.append(_codec.prim(pos[0], pos[1], uv, rgb))
+            except _codec.SpsCodecError as ex:
+                raise SpsAuthorError(f"{ctx}: frame {fi} prim {pi}: {ex}") from ex
+        out.append(prims)
+    return out
+
+
+def _texture_words(texture, ctx):
+    """Resolve ``tpage``/``clut`` (raw ints or fielded tables) to the two u16 words."""
+    def word(key, maker):
+        v = texture.get(key)
+        if isinstance(v, int) and not isinstance(v, bool):
+            return v
+        if isinstance(v, dict):
+            return maker(**{k: int(n) for k, n in v.items()})
+        raise SpsAuthorError(f"{ctx}: texture.{key} must be a u16 int or a fielded table, got {v!r}")
+    return word("tpage", _codec.make_tpage), word("clut", _codec.make_clut)
+
+
+def build_sps_from_block(block: dict, *, donor_loader=None) -> _codec.Sps:
+    """Resolve one ``[[sps]]`` block to a :class:`codec.Sps`. ``copy_from`` clones a donor effect (then an
+    optional ``frames``/``rgb``/``size`` override); otherwise an inline ``texture``+``size``+``uv``+``rgb``+
+    ``frames`` is built via :func:`codec.build`. Lints the result (raises :class:`SpsAuthorError` on a problem)."""
+    if "id" not in block:
+        raise SpsAuthorError("[[sps]]: every block needs an integer `id` (the effect id)")
+    sid = _int(block, "id", "[[sps]]")
+    ctx = f"[[sps]] id={sid}"
+    if "png" in (block.get("texture") or {}):
+        raise SpsAuthorError(f"{ctx}: texture.png (Route B, new art) needs a Memoria SPSConst.SPSTexture "
+                             "registration patch -- not yet supported. Use copy_from / texture.borrow_tcb (Route A).")
+    loader = donor_loader or _default_donor_loader
+
+    # A geometry source: a named TEMPLATE or an explicit copy_from -> a (field, sps) donor to clone; else inline.
+    cf = _resolve_clone_source(block, ctx)
+    if cf is not None:
+        if "texture" in block or "uv" in block:
+            raise SpsAuthorError(f"{ctx}: template/copy_from is exclusive with an inline texture/uv "
+                                 "(it reuses the donor's). frames/rgb/size are allowed as overrides.")
+        model = copy.deepcopy(loader(cf.get("field"), cf["sps"]))   # field=None -> a carried-effect clone
+        model.frame_offsets = None                          # re-laid canonically on serialize
+        model.tail = b""
+        if "frames" in block:                               # optional geometry / colour / size overrides
+            model.frames = _parse_frames(block["frames"], ctx)
+        if "rgb" in block:
+            model.rgb_table = [(*_rgb3(c, ctx), 0) for c in block["rgb"]]
+        if "size" in block:
+            model.h_raw, model.w_raw = _size(block["size"], ctx)
+    else:
+        for req in ("texture", "size", "uv", "rgb", "frames"):
+            if req not in block:
+                raise SpsAuthorError(f"{ctx}: inline effect needs {req!r} (or use copy_from)")
+        tpage_raw, clut_raw = _texture_words(block["texture"], ctx)
+        h_raw, w_raw = _size(block["size"], ctx)
+        model = _codec.build(
+            tpage_raw=tpage_raw, clut_raw=clut_raw, h_raw=h_raw, w_raw=w_raw,
+            uv_table=[tuple(_xy(c, ctx)) for c in block["uv"]],
+            rgb_table=[(*_rgb3(c, ctx), 0) for c in block["rgb"]],
+            frames=_parse_frames(block["frames"], ctx),
+        )
+    problems = lint_sps(model)
+    if problems:
+        raise SpsAuthorError(f"{ctx}: invalid effect -- " + "; ".join(problems))
+    return model
+
+
+def _rgb3(c, ctx):
+    if not (isinstance(c, list) and len(c) == 3 and all(isinstance(v, int) and 0 <= v <= 255 for v in c)):
+        raise SpsAuthorError(f"{ctx}: an rgb entry must be [r, g, b] ints 0..255, got {c!r}")
+    return c[0], c[1], c[2]
+
+
+def _xy(c, ctx):
+    if not (isinstance(c, list) and len(c) == 2 and all(isinstance(v, int) and 0 <= v <= 255 for v in c)):
+        raise SpsAuthorError(f"{ctx}: a uv entry must be [x, y] ints 0..255, got {c!r}")
+    return c[0], c[1]
+
+
+def _size(s, ctx):
+    if not (isinstance(s, list) and len(s) == 2 and all(isinstance(v, int) and 1 <= v <= 255 for v in s)):
+        raise SpsAuthorError(f"{ctx}: 'size' must be [h_raw, w_raw] ints 1..255, got {s!r}")
+    return s[0], s[1]
+
+
+def _resolve_clone_source(block: dict, ctx: str):
+    """A ``template`` name / a ``clone_sps`` carried-effect id / an explicit ``copy_from`` -> a donor to clone,
+    or ``None`` for an inline effect. The three are mutually exclusive. ``clone_sps = N`` is the form-friendly
+    flat alias for ``copy_from = {{ sps = N }}`` (clone one of THIS field's carried effects)."""
+    has_t, has_cf = "template" in block, "copy_from" in block
+    has_clone = block.get("clone_sps") is not None
+    if sum((has_t, has_cf, has_clone)) > 1:
+        raise SpsAuthorError(f"{ctx}: use ONE of `template` / `clone_sps` / `copy_from`")
+    if has_clone:
+        v = block["clone_sps"]
+        if not isinstance(v, int) or isinstance(v, bool):
+            raise SpsAuthorError(f"{ctx}: clone_sps must be a carried-effect id (integer), got {v!r}")
+        return {"sps": v}                                   # field=None -> a carried-effect clone
+    if has_t:
+        from . import templates as _tpl
+        try:
+            t = _tpl.resolve(block["template"])
+        except KeyError:
+            raise SpsAuthorError(f"{ctx}: unknown template {block['template']!r} (known: {sorted(_tpl.TEMPLATES)})")
+        return {"field": t.field, "sps": t.sps}
+    if has_cf:
+        cf = block["copy_from"]
+        if not (isinstance(cf, dict) and "sps" in cf):
+            raise SpsAuthorError(f"{ctx}: copy_from must be {{ sps = <id> }} (clone one of THIS field's carried "
+                                 "effects, reusing its texture) or {{ field = <token>, sps = <id> }} (clone a "
+                                 "donor field's effect)")
+        return cf
+    return None
+
+
+def tcb_source(block: dict) -> tuple[str, str | None]:
+    """How to supply the effect's ``spt.tcb``: ``("borrow", donor_token)`` (a ``template`` / ``copy_from`` /
+    ``texture.borrow_tcb``) or ``("reuse", None)`` (use the field's already-carried tcb)."""
+    cf = _resolve_clone_source(block, "[[sps]]")
+    if cf is not None:
+        if cf.get("field") is None:                # a carried-effect clone (copy_from = { sps = N })
+            return "reuse", None                   # reuses the field's already-carried tcb -- no conflict
+        return "borrow", str(cf["field"])
+    tex = block.get("texture") or {}
+    if tex.get("borrow_tcb") is not None:
+        return "borrow", str(tex["borrow_tcb"])
+    return "reuse", None
+
+
+def trigger_spec(block: dict, *, slot: int | None = None) -> dict:
+    """The placement -> the ``RunSPSCode`` create+place spec (consumed by ``content.sps_trigger``)."""
+    sid = _int(block, "id", "[[sps]]")
+    ctx = f"[[sps]] id={sid}"
+    pos = block.get("pos", [0, 0, 0])
+    if not (isinstance(pos, list) and len(pos) in (2, 3) and all(isinstance(c, int) for c in pos)):
+        raise SpsAuthorError(f"{ctx}: 'pos' must be [x, y, z] (or [x, z] with separate y=), got {pos!r}")
+    if len(pos) == 3:
+        x, y, z = pos
+    else:
+        x, z = pos
+        y = int(block.get("y", 0))
+    for k in ("x", "y", "z"):
+        v = {"x": x, "y": y, "z": z}[k]
+        if not -32768 <= v <= 32767:
+            raise SpsAuthorError(f"{ctx}: pos {k}={v} out of the i16 range RunSPSCode carries")
+    spec = {"slot": slot if slot is not None else int(block.get("slot", DEFAULT_SLOT)),
+            "sps_id": sid, "pos": (x, y, z)}
+    # ABR default = ADDITIVE (1): a particle effect should glow (transparent black, additive brights). The
+    # engine's own default is ABR_OFF = OPAQUE, which renders the quads as solid black boxes -- never right for
+    # a flame/smoke/glow. Set abr explicitly for another blend (0=50%add, 2=sub, 3=25%add, >=4/15 = opaque).
+    spec["abr"] = _int(block, "abr", ctx) if "abr" in block else DEFAULT_ABR
+    for key in ("framerate", "scale"):
+        if key in block:
+            spec[key] = _int(block, key, ctx)
+    if not 0 <= spec["slot"] <= 15:
+        raise SpsAuthorError(f"{ctx}: slot {spec['slot']} out of range 0..15 (FIELD_DEFAULT_OBJCOUNT=16)")
+    return spec
+
+
+def validate_sps_block(block: dict, *, donor_loader=None) -> list[str]:
+    """Offline problems for one ``[[sps]]`` block (empty == OK). Never raises (build-safe). The donor read is
+    install-gated, so a copy_from/borrow whose donor can't be read offline degrades to a clean message."""
+    try:
+        build_sps_from_block(block, donor_loader=donor_loader)
+        trigger_spec(block)
+        return []
+    except (SpsAuthorError, _codec.SpsCodecError) as ex:
+        return [str(ex)]