ff9mapkit 1.0.0b3__py3-none-any.whl

ff9mapkit/battle/scene_data.py

@@ -0,0 +1,369 @@
+"""Tune a forked battle's gameplay (the BTL_SCENE ``dbfile0000.raw16``) from a battle.toml ``[scene]``.
+
+A tier-c mint forks a donor battle's raw16 verbatim; this module SURGICALLY patches it with author
+overrides -- enemy positions, stats, rewards, and the camera pose -- WITHOUT changing enemy TYPES (so the
+forked raw17 attack sequences + the loaded enemy GEO/models stay valid). Only the edited fields change;
+every other byte is verbatim, so we never risk mis-packing the 116-byte monster struct.
+
+Layout (from Memoria ``BTL_SCENE.ReadBattleScene``):
+  header 8B: Ver(1) PatCount(1) TypCount(1) AtkCount(1) Flags(2) pad(2)
+  pattern i @ 8 + 56*i (56B): Rate(1) MonsterCount(1) Camera(1) Pad0(1) AP(u32) then 4x SB2_PUT(12B)
+    SB2_PUT j @ +8 + 12*j: TypeNo(1) Flags(1) Pease(1) Pad(1) Xpos(i16) Ypos(i16) Zpos(i16) Rot(i16)
+  monster t @ 8 + 56*PatCount + 116*t (116B, SB2_MON_PARM): the fields we edit are
+    ResistStatus@0 AutoStatus@4 InitialStatus@8 (u32 BattleStatus masks)
+    MaxHP@12(u16) MaxMP@14(u16) WinGil@16(u16) WinExp@18(u16) WinItems@20(4B) StealItems@24(4B)
+    Element{Speed@52,Str@53,Mag@54,Spr@55} Null/Absorb/Half/Weak-Element@60/61/62/63(1B each)
+    Level@64 Category@65 HitRate@66 Phys/Mag-Def+Evade@67-70 BlueMagic@71 WinCard@105
+  pattern AP @ pattern+4 (u32) = the GAMEPLAY AP reward (the per-type AP@50 is unused for rewards).
+
+A stat edit targets the slot's TYPE (SB2_MON_PARM is per type), so two slots sharing a type share stats
+(a real FF9 constraint) -- the editor warns when a type is tuned twice. Element/status fields take a list of
+NAMES (or a raw int); see :mod:`battlecsv` for the name<->bit tables and the [PatchableField] note.
+"""
+from __future__ import annotations
+
+import struct
+
+from .. import items
+from . import battlecsv
+
+_HDR = 8
+_PAT = 56
+_MON = 116
+_PUT = 12
+_FLG_TARGETABLE = 1     # SB2_PUT.FLG_TARGETABLE -- the enemy can be selected/attacked (FLG_MULTIPART=2)
+
+# SB2_MON_PARM scalar field -> (offset, struct-fmt). Offsets RELATIVE to the 116-byte monster block; verified
+# vs BTL_SCENE.cs:54-122 + the scene_codec round-trip. All raw17-safe (no model/type bytes).
+_MON_FIELDS = {
+    "hp": (12, "<H"), "mp": (14, "<H"), "gil": (16, "<H"), "exp": (18, "<H"),
+    "speed": (52, "<B"), "strength": (53, "<B"), "magic": (54, "<B"), "spirit": (55, "<B"),
+    "level": (64, "<B"), "category": (65, "<B"), "hit_rate": (66, "<B"),
+    "phys_def": (67, "<B"), "phys_evade": (68, "<B"), "mag_def": (69, "<B"), "mag_evade": (70, "<B"),
+    "blue_magic": (71, "<B"), "win_card": (105, "<B"),
+}
+_MON_INT_MAX = {"<H": 0xFFFF, "<B": 0xFF}
+
+# Element-affinity bytes (a 1-byte EffectElement bitmask each) + status masks (a u32 BattleStatus each),
+# RELATIVE to the monster block. The author value is a list of element/status NAMES (or a raw int) -- see
+# battlecsv.encode_elements / encode_status. `null` = GuardElement (nullified/immune elements).
+_MON_ELEM_FIELDS = {"null": 60, "absorb": 61, "half": 62, "weak": 63}
+_MON_STATUS_FIELDS = {"resist_status": 0, "auto_status": 4, "initial_status": 8}
+
+# Per-enemy MON flags (SB2_MON_PARM.Flags @48, u16 = ENEMY_INFO.flags) -- raw16-ONLY (not a [PatchableField], so
+# BattlePatch can't reach it; this is the one enemy-identity gap the BP surface leaves). Named bits from
+# ENEMY.cs:37-39: die_atk/die_dmg pick the death-animation path; non_dying_boss = the enemy SURVIVES HP=0 (a
+# scripted boss can't be killed by normal damage). The author value is a list of NAMES or a raw int (the high
+# bits are read by some enemies' AI .eb, so a raw int passes them through).
+_MON_FLAGS_OFF = 48
+_MON_FLAG_NAMES = {"die_atk": 1, "die_dmg": 2, "non_dying_boss": 4}
+
+# [scene]-level Flags (the scene header @4, a u16) -- the ENCOUNTER RULES. Named bits from BTL_SCENE scene_flags
+# (scene_codec: preemptive = SpecialStart bit0, back_attack bit1, no_exp bit3, can't-escape = Runaway bit5).
+# Authoring a `[scene] flags` list CLEARS these 4 known bits then ORs the named ones (any OTHER header bit is
+# preserved); a raw int REPLACES the whole word. Absent -> the donor's header flags are kept verbatim.
+_SCENE_FLAGS_OFF = 4
+_SCENE_FLAG_NAMES = {"preemptive": 0x01, "back_attack": 0x02, "no_exp": 0x08, "no_escape": 0x20}
+_SCENE_FLAG_MASK = 0x01 | 0x02 | 0x08 | 0x20
+
+# RE-SKIN: the (offset, length) byte ranges of the MODEL + display fields, copied VERBATIM from a real donor
+# enemy so a forked enemy's BODY looks like a different creature while keeping its own gameplay. The appearance
+# is a self-consistent group: Geo (the model), Mot[6] (six GLOBAL animation ids = the IDLE/DAMAGE/DEATH motions,
+# `BattleUnit.cs:858-878`; the engine resolves them to THAT model's clips, `btl_init.cs:240`/`:521-522`, and a
+# clip that doesn't belong to the loaded model FREEZES the battle), Mesh[2], Radius (-> radius_collision,
+# `btl_init.cs:68`; model-size-attached -- the Geo table only sets radius_effect/height, so Radius@28 is LIVE,
+# keep it), plus the model-ATTACHED cosmetics (bone[4], die/start SFX, status-icon bones + offsets, shadow
+# bones + offsets). Swapping Geo alone leaves the OLD model's Mot ids -> wrong/missing clips, so a re-skin
+# transplants the WHOLE block. The GAMEPLAY fields (status/hp/mp/rewards/stats/elements/level/category/defences/
+# blue_magic/win_card) are deliberately OUTSIDE these ranges -- they stay the target's.
+#
+# SCOPE -- this is a BODY re-skin, NOT a full one (★ IN-GAME PROVEN 2026-06-13: a Goblin re-skinned to the Fang
+# IDLED as a quadruped Fang but ATTACKED Goblin-like). The transplanted Mot[6] DO drive the new model's own idle/
+# damage/death; but the per-ATTACK animation is bound by the donor scene's raw17 btlseq (keyed by Konran@78, the
+# per-type AnmOfsList selector, `btlseq.cs:1150-1151`), which is KEPT -- so the ATTACK plays the TARGET's clip
+# retargeted onto the new mesh (clip-path-by-name, `AnimationFactory.cs:60`, never crashes). DO NOT add Konran@78
+# or MesCnt@79 (the message-count cursor) to these ranges -- both are raw17/text linkage tied to the TARGET scene.
+# Flags@48 (incl. die_atk/die_dmg, which pick the death-anim path) also stays the target's -- it carries gameplay bits.
+_RESKIN_RANGES = (
+    (28, 20),    # Radius(2) Geo(2) Mot[6](12) Mesh[2](4)  -- the model + its 6 idle/damage/death anim ids
+    (72, 6),     # Bone[4](4) DieSfx(2)
+    (80, 18),    # IconBone[6] IconY[6] IconZ[6]           -- status-icon attach (bone indices are model-specific)
+    (98, 6),     # StartSfx(2) ShadowX(2) ShadowZ(2)
+    (104, 1),    # ShadowBone   (NOT WinCard@105 -- a reward)
+    (106, 4),    # ShadowOfsX(2) ShadowOfsZ(2)
+    (110, 1),    # ShadowBone2  (NOT Pad0@111)
+)
+
+
+class SceneEditError(ValueError):
+    pass
+
+
+def parse_counts(raw16: bytes):
+    """(PatCount, TypCount, AtkCount) from the header."""
+    if len(raw16) < _HDR:
+        raise SceneEditError("raw16 too short")
+    return raw16[1], raw16[2], raw16[3]
+
+
+def _mon_base(patcount: int) -> int:
+    return _HDR + _PAT * patcount
+
+
+def mon_block(raw16: bytes, type_no: int) -> bytes:
+    """The verbatim 116-byte SB2_MON_PARM block for enemy ``type_no`` -- the SOURCE of a re-skin transplant
+    (read from a real donor scene). Raises if ``type_no`` is out of range or the block is truncated."""
+    patcount, typcount, _atk = parse_counts(raw16)
+    if not 0 <= type_no < typcount:
+        raise SceneEditError(f"donor type {type_no} out of range (the donor scene has {typcount} type(s))")
+    base = _mon_base(patcount) + _MON * type_no
+    if len(raw16) < base + _MON:
+        raise SceneEditError("donor raw16 truncated -- can't read the monster block")
+    return bytes(raw16[base:base + _MON])
+
+
+def _apply_reskin_block(b: bytearray, mon_off: int, donor_block: bytes, slot=None) -> None:
+    """Copy the :data:`_RESKIN_RANGES` (model + display fields) from a real donor's 116-byte monster block
+    into the target type's block at ``mon_off`` -- the model swap. The gameplay fields are left untouched."""
+    if len(donor_block) != _MON:
+        where = f"slot {slot}: " if slot is not None else ""
+        raise SceneEditError(f"{where}re-skin donor block is {len(donor_block)} bytes, expected {_MON}")
+    for off, ln in _RESKIN_RANGES:
+        b[mon_off + off:mon_off + off + ln] = donor_block[off:off + ln]
+
+
+def apply_scene_edits(raw16: bytes, scene: dict) -> tuple[bytes, list[str]]:
+    """Patch ``raw16`` with a battle.toml ``[scene]`` dict. Returns (patched_bytes, warnings).
+
+    SPAWN COMPOSITION (``monster_count`` set) re-composes a DETERMINISTIC fight: it writes the SAME
+    composition (count + per-slot type/placement) to EVERY pattern, so whichever pattern the engine rolls
+    yields the user's fight -- and ``build.py`` re-authors the battle eb's Main_Init to match (one enemy-AI
+    object per slot), which is what lets a mint exceed the donor's natural enemy count (up to the engine's
+    hard cap of 4) using the scene's existing types. Without ``monster_count`` it only TUNES the one
+    ``pattern`` (positions/stats/rewards/camera), leaving the composition + the eb untouched.
+    """
+    patcount, typcount, _atk = parse_counts(raw16)
+    b = bytearray(raw16)
+    warnings: list[str] = []
+    enemies = scene.get("enemy", [])
+
+    if "flags" in scene:                                    # [scene] ENCOUNTER RULES -> the header Flags u16
+        cur = struct.unpack_from("<H", b, _SCENE_FLAGS_OFF)[0]
+        struct.pack_into("<H", b, _SCENE_FLAGS_OFF, _encode_scene_flags(scene["flags"], cur))
+
+    cam = None
+    if "camera" in scene:
+        cam = int(scene["camera"])
+        if not 0 <= cam <= 255:
+            raise SceneEditError(f"[scene] camera {cam} out of range (0-2 = a fixed PSX pose, >=3 random)")
+    mc = None
+    if "monster_count" in scene:
+        mc = int(scene["monster_count"])
+        if not 1 <= mc <= 4:
+            raise SceneEditError(f"[scene] monster_count {mc} out of range (1-4; engine hard cap)")
+    ap = None
+    if "ap" in scene:
+        ap = int(scene["ap"])
+        if not 0 <= ap <= 0xFFFFFFFF:
+            raise SceneEditError(f"[scene] ap {ap} out of range (0-{0xFFFFFFFF})")
+
+    # spawn composition -> apply to ALL patterns (uniform/deterministic); else tune the one selected pattern
+    if mc is not None:
+        pats = list(range(patcount))
+    else:
+        p = int(scene.get("pattern", 0))
+        if not 0 <= p < patcount:
+            raise SceneEditError(f"[scene] pattern {p} out of range (this scene has {patcount} pattern(s))")
+        pats = [p]
+
+    mon_base = _mon_base(patcount)
+    for pat in pats:
+        pat_off = _HDR + _PAT * pat
+        if cam is not None:
+            b[pat_off + 2] = cam
+        if mc is not None:
+            b[pat_off + 1] = mc
+        for e in enemies:
+            _edit_placement(b, pat_off, e, typcount)
+        count = b[pat_off + 1]                              # every ACTIVE slot must be a valid, hittable type
+        for s in range(count):
+            po = pat_off + 8 + _PUT * s
+            if b[po] >= typcount:
+                raise SceneEditError(f"active slot {s} (monster_count {count}) has enemy type {b[po]} >= "
+                                     f"TypCount {typcount}; give it a 'type' of 0-{typcount - 1}")
+            if not (b[po + 1] & _FLG_TARGETABLE):
+                raise SceneEditError(f"active slot {s} (monster_count {count}) is not targetable -- set its "
+                                     f"'type' so it becomes a normal attackable enemy (else the fight can't end)")
+
+    # the AP reward is per-PATTERN (the gameplay-effective AP, awarded whole) -> write it to EVERY pattern so
+    # whichever formation the engine rolls gives the authored AP.
+    if ap is not None:
+        for pat in range(patcount):
+            struct.pack_into("<I", b, _HDR + _PAT * pat + 4, ap)
+
+    # stats / rewards are per TYPE (one shared block; same-type slots share it) -> apply once (slot types are
+    # uniform across patterns, so resolve each enemy's type from the representative pattern).
+    rep = _HDR + _PAT * pats[0] + 8
+    tuned_types: dict[int, int] = {}
+    for e in enemies:
+        slot = int(e["slot"])
+        stat_keys = [k for k in e if k in _MON_FIELDS or k in _MON_ELEM_FIELDS
+                     or k in _MON_STATUS_FIELDS or k in ("drop", "steal", "flags")]
+        reskin_block = e.get("_reskin_block")              # a resolved real-donor block (build injects it)
+        if not stat_keys and reskin_block is None:
+            continue
+        type_no = b[rep + _PUT * slot]
+        if type_no in tuned_types and tuned_types[type_no] != slot:
+            warnings.append(f"slots {tuned_types[type_no]} and {slot} share enemy type {type_no}; "
+                            f"their stats/model are the SAME data -- slot {slot} wins")
+        tuned_types.setdefault(type_no, slot)
+        if type_no >= typcount:
+            raise SceneEditError(f"slot {slot} references type {type_no} >= TypCount {typcount}")
+        mon_off = mon_base + _MON * type_no
+        if reskin_block is not None:                       # re-skin: transplant the donor's model+display block
+            _apply_reskin_block(b, mon_off, reskin_block, slot)
+        for k in stat_keys:
+            if k in _MON_FIELDS:
+                off, fmt = _MON_FIELDS[k]
+                v = int(e[k])
+                if not 0 <= v <= _MON_INT_MAX[fmt]:
+                    raise SceneEditError(f"slot {slot} {k}={v} out of range (0-{_MON_INT_MAX[fmt]})")
+                struct.pack_into(fmt, b, mon_off + off, v)
+            elif k in _MON_ELEM_FIELDS:                    # null/absorb/half/weak: a 1-byte element bitmask
+                try:
+                    v = battlecsv.encode_elements(e[k])
+                except ValueError as ex:
+                    raise SceneEditError(f"slot {slot} {k}: {ex}")
+                if not 0 <= v <= 0xFF:
+                    raise SceneEditError(f"slot {slot} {k} bitmask {v} out of range (0-255)")
+                b[mon_off + _MON_ELEM_FIELDS[k]] = v
+            elif k in _MON_STATUS_FIELDS:                  # resist/auto/initial: a u32 BattleStatus mask
+                try:
+                    v = battlecsv.encode_status(e[k])
+                except ValueError as ex:
+                    raise SceneEditError(f"slot {slot} {k}: {ex}")
+                struct.pack_into("<I", b, mon_off + _MON_STATUS_FIELDS[k], v & 0xFFFFFFFF)
+            elif k == "flags":                             # per-enemy MON flags @48 (non_dying_boss / die_*)
+                struct.pack_into("<H", b, mon_off + _MON_FLAGS_OFF, _encode_flags(e[k], slot))
+            else:  # drop / steal: 4 item slots (id/name; 255 = none)
+                base = mon_off + (20 if k == "drop" else 24)
+                for i, iid in enumerate(_resolve_items(e[k], slot, k)):
+                    b[base + i] = iid
+    return bytes(b), warnings
+
+
+def _edit_placement(b: bytearray, pat_off: int, e: dict, typcount: int) -> None:
+    """Apply one [[scene.enemy]]'s slot TYPE + placement (pos/y/rot) within a single pattern."""
+    if "slot" not in e:
+        raise SceneEditError("[[scene.enemy]] needs a 'slot' (0-3, the placement in the pattern)")
+    slot = int(e["slot"])
+    if not 0 <= slot < 4:
+        raise SceneEditError(f"[[scene.enemy]] slot {slot} out of range (0-3)")
+    put_off = pat_off + 8 + _PUT * slot
+    if "type" in e:
+        t = int(e["type"])
+        if not 0 <= t < typcount:
+            raise SceneEditError(f"slot {slot} type {t} out of range (0-{typcount - 1}); must be an enemy "
+                                 f"type ALREADY in this scene, so the forked raw17/GEO/AI covers it")
+        b[put_off] = t
+        b[put_off + 1] = _FLG_TARGETABLE                   # normal, targetable, single-part enemy
+        # GROUND it: default an activated slot's height to slot 0's Ypos (a real on-ground enemy). Explicit y wins.
+        struct.pack_into("<h", b, put_off + 6, struct.unpack_from("<h", b, pat_off + 8 + 6)[0])
+    if "pos" in e:
+        pos = list(e["pos"])
+        if len(pos) not in (2, 3):
+            raise SceneEditError(f"[[scene.enemy]] slot {slot}: pos must be [x, z] or [x, y, z]")
+        struct.pack_into("<h", b, put_off + 4, _clamp_i16(int(pos[0])))    # Xpos
+        struct.pack_into("<h", b, put_off + 8, _clamp_i16(int(pos[-1])))   # Zpos
+        if len(pos) == 3:
+            struct.pack_into("<h", b, put_off + 6, _clamp_i16(int(pos[1])))  # Ypos (height)
+    if "y" in e:
+        struct.pack_into("<h", b, put_off + 6, _clamp_i16(int(e["y"])))
+    if "rot" in e:
+        struct.pack_into("<h", b, put_off + 10, _clamp_i16(int(e["rot"])))
+
+
+def _encode_flags(value, slot) -> int:
+    """A ``[[scene.enemy]] flags`` value -> a u16. Accepts a list of NAMES (``_MON_FLAG_NAMES``, OR'd), a single
+    name, or a raw int (passes the unnamed high bits through to the enemy's AI)."""
+    if isinstance(value, bool):
+        raise SceneEditError(f"slot {slot} flags can't be a boolean")
+    if isinstance(value, int):
+        if not 0 <= value <= 0xFFFF:
+            raise SceneEditError(f"slot {slot} flags {value} out of range (0-65535)")
+        return value
+    names = [value] if isinstance(value, str) else value
+    if not isinstance(names, list):
+        raise SceneEditError(f"slot {slot} flags must be a name / list of names {sorted(_MON_FLAG_NAMES)} "
+                             f"or a raw int")
+    if names and all(isinstance(n, int) and not isinstance(n, bool) for n in names):
+        return _or_raw_bits(names, lambda n: f"slot {slot} flags {n} out of range (0-65535)")  # the [9] round-trip of `flags = 9`
+    bits = 0
+    for nm in names:
+        key = str(nm).strip().lower()
+        if key not in _MON_FLAG_NAMES:
+            raise SceneEditError(f"slot {slot} unknown enemy flag {nm!r}; known: {sorted(_MON_FLAG_NAMES)} "
+                                 f"(or pass a raw int)")
+        bits |= _MON_FLAG_NAMES[key]
+    return bits
+
+
+def _or_raw_bits(ints, err) -> int:
+    """OR a list of raw u16 ints into one flag word (the GUI round-trip of a raw-int `flags = N`: a STRLIST
+    re-parses `N` to the one-int list `[N]`, which must mean the same raw word, not a flag NAMED `N`)."""
+    word = 0
+    for n in ints:
+        if not 0 <= n <= 0xFFFF:
+            raise SceneEditError(err(n))
+        word |= n
+    return word
+
+
+def _encode_scene_flags(value, current: int) -> int:
+    """A ``[scene] flags`` value -> the new header Flags u16. A list of NAMES (``_SCENE_FLAG_NAMES``) CLEARS the
+    4 known bits in ``current`` then ORs the named ones (preserving any other header bit); a raw int REPLACES the
+    whole word. The encounter RULES: preemptive / back_attack / no_exp / no_escape (can't-flee)."""
+    if isinstance(value, bool):
+        raise SceneEditError("[scene] flags can't be a boolean (use a name list or a raw int)")
+    if isinstance(value, int):
+        if not 0 <= value <= 0xFFFF:
+            raise SceneEditError(f"[scene] flags {value} out of range (0-65535)")
+        return value
+    names = [value] if isinstance(value, str) else value
+    if not isinstance(names, list):
+        raise SceneEditError(f"[scene] flags must be a name / list of names {sorted(_SCENE_FLAG_NAMES)} or a raw int")
+    if names and all(isinstance(n, int) and not isinstance(n, bool) for n in names):
+        return _or_raw_bits(names, lambda n: f"[scene] flags {n} out of range (0-65535)")  # the [9] round-trip of `flags = 9`
+    bits = current & ~_SCENE_FLAG_MASK
+    for nm in names:
+        key = str(nm).strip().lower()
+        if key not in _SCENE_FLAG_NAMES:
+            raise SceneEditError(f"[scene] unknown flag {nm!r}; known: {sorted(_SCENE_FLAG_NAMES)} (or a raw int)")
+        bits |= _SCENE_FLAG_NAMES[key]
+    return bits
+
+
+def _clamp_i16(v: int) -> int:
+    return max(-32768, min(32767, v))
+
+
+def _resolve_items(value, slot: int, key: str) -> list[int]:
+    if not isinstance(value, list) or len(value) != 4:
+        raise SceneEditError(f"slot {slot} {key} must be a list of exactly 4 items "
+                             f"(name/id; use \"none\" or 255 for an empty slot)")
+    out = []
+    for it in value:
+        if isinstance(it, str) and it.strip().lower() in ("none", "", "-"):
+            out.append(255)
+        else:
+            out.append(items.resolve(it))
+    return out
+
+
+def validate_scene(raw16: bytes, scene: dict) -> list[str]:
+    """Offline problems (empty => OK). Re-runs the edit on a copy to surface any error as a message."""
+    try:
+        _, warnings = apply_scene_edits(raw16, scene)
+        return []
+    except (SceneEditError, ValueError) as e:
+        return [str(e)]

ff9mapkit/battle/scenelint.py

@@ -0,0 +1,125 @@
+"""Offline BALANCE lint for a battle scene -- the "I can't see the game" superpower for battle tuning.
+
+Reads a parsed :class:`~ff9mapkit.battle.scene_codec.Scene` (every enemy's stats / affinities / rewards) and
+flags design problems an actual playthrough would otherwise reveal. The bar is TRUST: it must be quiet on
+well-designed vanilla fights and loud only on real problems -- so every check here was validated against a
+sweep of all ~562 shipped scenes to confirm it does not cry wolf (a noisy lint trains the user to ignore it).
+
+Checks:
+  * no_reward (warn)    -- a real fight that yields NOTHING (0 EXP / gil / AP / no drops or steals).
+  * bad_item (warn)     -- a drop/steal references an item id that isn't a real item.
+  * status_immune (info)-- the enemy resists EVERY common offensive status -> status abilities are dead choices.
+  * element_wall (info) -- the enemy resists/absorbs/halves >=7/8 elements -> almost no element does full damage.
+  * phys_wall / mag_wall (info) -- a defence in the weapon-power band (>=50; real enemies cap ~24, FF9 weapon
+                          power caps ~108) -> attacks are heavily reduced (FF9 defence is SUBTRACTIVE).
+  * level5 (info)       -- the enemy's Level is a multiple of 5 AND it isn't Death-immune -> LV5 Death one-shots it.
+
+Severity: ``warn`` = a likely real problem; ``info`` = design awareness (an intentional choice may be fine).
+
+NOT done here (deferred -- the kit has no live party model): a turns-to-kill / time-to-kill-a-PC estimator and
+an economy-curve-vs-zone check. FF9 physical damage is `Attack(~Strength) * max(1, weaponPower - defence)` with
+3-4 attackers/round, so a single-attacker turns estimate is off by ~1-2 orders of magnitude and flags ~half the
+bestiary as a "sponge" -- it carries no signal without a real party model, so it is intentionally omitted.
+
+Pure + offline; reads only the parsed scene (the offensive-status mask is built at import from committed tables).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .. import items
+from . import battlecsv
+
+# The common statuses a PLAYER tries to inflict -- if an enemy resists ALL of these, status-disabling
+# abilities are dead choices against it. (Buffs like Haste/Protect and odd ones are excluded on purpose.)
+_OFFENSIVE_STATUSES = ["Petrify", "Venom", "Silence", "Blind", "Death", "Confuse", "Berserk", "Stop",
+                       "Poison", "Sleep", "Slow", "Mini"]
+_OFFENSIVE_MASK = battlecsv.encode_status(_OFFENSIVE_STATUSES)
+_DEATH_MASK = battlecsv.encode_status(["Death"])
+
+_N_ELEMENTS = 8
+# A subtractive-defence "wall": FF9 weapon power runs ~40-108 (Excalibur II caps at 108) and real shipped
+# enemies cap at phys_def ~24, so a defence at/above this band is an AUTHORED wall that floors normal attacks.
+_WALL_DEF = 50
+
+
+@dataclass
+class Finding:
+    severity: str           # "warn" | "info"
+    code: str               # a short stable id (e.g. "status_immune")
+    message: str
+
+    def __str__(self) -> str:
+        return f"[{self.severity}] {self.message}"
+
+
+def lint_scene(scene) -> list[Finding]:
+    """Return balance :class:`Finding`s for a parsed Scene (empty => nothing flagged)."""
+    out: list[Finding] = []
+    combat = [m for m in scene.monsters if m.hp > 1]   # hp<=1 => a placeholder / multipart / non-fightable type
+
+    # --- scene-level: does the whole fight reward anything? ---
+    if combat:
+        total_exp = sum(m.exp for m in combat)
+        total_gil = sum(m.gil for m in combat)
+        max_ap = max((p.ap for p in scene.patterns), default=0)
+        has_item = any(i != 255 for m in combat for i in (*m.drop, *m.steal))
+        if total_exp == 0 and total_gil == 0 and max_ap == 0 and not has_item:
+            out.append(Finding("warn", "no_reward",
+                               "this battle yields NOTHING: 0 EXP, 0 gil, 0 AP, no drops/steals"))
+
+    # --- per-enemy-type ---
+    for t, m in enumerate(scene.monsters):
+        if m.hp <= 1:
+            continue
+        lbl = f"enemy type {t} (Lv {m.level}, HP {m.hp})"
+
+        # counter-play: an enemy that resists/absorbs/halves nearly every element (almost no element exploits it)
+        resisted = set(battlecsv.decode_elements(m.guard_element)) \
+            | set(battlecsv.decode_elements(m.absorb_element)) | set(battlecsv.decode_elements(m.half_element))
+        if len(resisted) >= _N_ELEMENTS - 1:
+            out.append(Finding("info", "element_wall",
+                               f"{lbl}: resists/absorbs/halves {len(resisted)}/{_N_ELEMENTS} elements -- almost "
+                               f"no element does full damage"))
+
+        # counter-play: immune to every offensive status -> status abilities are dead choices
+        if (m.resist_status & _OFFENSIVE_MASK) == _OFFENSIVE_MASK:
+            out.append(Finding("info", "status_immune",
+                               f"{lbl}: immune to every common offensive status -- status abilities are dead "
+                               f"choices here"))
+
+        # LV5 Death exploit -- only when it actually lands (the level is a multiple of 5 AND Death isn't resisted)
+        if m.level > 0 and m.level % 5 == 0 and not ((m.resist_status | m.auto_status) & _DEATH_MASK):
+            out.append(Finding("info", "level5",
+                               f"{lbl}: level {m.level} is a multiple of 5 and not Death-immune -- LV5 Death "
+                               f"one-shots it"))
+
+        # rewards: an item id that isn't a real item
+        for kind, ids in (("drop", m.drop), ("steal", m.steal)):
+            for i in ids:
+                if i != 255 and items.name_of(i) is None:
+                    out.append(Finding("warn", "bad_item",
+                                       f"{lbl}: {kind} references item id {i}, which is not a known item"))
+
+        # subtractive-defence walls (a defence in the weapon-power band floors normal attacks)
+        if m.phys_def >= _WALL_DEF:
+            out.append(Finding("info", "phys_wall",
+                               f"{lbl}: phys_def {m.phys_def} -- physical attacks heavily reduced (FF9 weapon "
+                               f"power ~40-108; subtractive defence)"))
+        if m.mag_def >= _WALL_DEF:
+            out.append(Finding("info", "mag_wall",
+                               f"{lbl}: mag_def {m.mag_def} -- magical attacks heavily reduced"))
+
+    return out
+
+
+def format_findings(findings, *, indent: str = "  ") -> str:
+    """A human-readable block (empty findings => an OK line)."""
+    if not findings:
+        return f"{indent}lint: no balance problems flagged."
+    warns = [f for f in findings if f.severity == "warn"]
+    infos = [f for f in findings if f.severity == "info"]
+    lines = [f"{indent}lint: {len(warns)} warning(s), {len(infos)} note(s)"]
+    for f in warns + infos:
+        lines.append(f"{indent}  {f}")
+    return "\n".join(lines)

ff9mapkit/battle/seqasm.py

@@ -0,0 +1,131 @@
+"""The raw17 sequence ASSEMBLER -- the inverse of :mod:`seqdis` (the analog of ``eb/cmdasm`` for enemy AI). Turns
+a textual sequence source into the instruction bytes the engine interprets, so a NET-NEW attack choreography can
+be authored from scratch (then spliced by :mod:`seqauthor` with the length-changing :func:`seqcodec.serialize_repacked`
+repack). A sequence has NO control flow (no jumps/labels) -- it is a flat list of ``Name(field=value, ...)``
+instructions ending in a terminator -- so the assembler is a direct line-by-line transcription, with each operand
+range-checked against its field width/signedness.
+
+Round-trip INVARIANT (proven over the 562-corpus): ``assemble(to_source(instrs)) == instrs`` and
+``to_source(parse_instr(b))`` re-assembles to the original bytes -- the assembler and the codec decoder are exact
+mutual inverses. Only the open-source opcode NAMES are committed.
+"""
+from __future__ import annotations
+
+import re as _re
+
+from . import seqcodec as _sc
+
+
+class SeqAsmError(ValueError):
+    pass
+
+
+_NAME_TO_OP = {nm: op for op, (nm, _f) in _sc._OPS.items()}
+_LINE_RE = _re.compile(r"^\s*(?:\[\d+\]\s*)?([A-Za-z_]\w*)\s*(?:\(([^()]*)\))?\s*$")   # tolerates a [offset] prefix
+
+
+def _parse_int(tok: str) -> int:
+    tok = tok.strip()
+    try:
+        return int(tok, 0)                            # accepts 10, 0x0a, -5
+    except ValueError:
+        raise SeqAsmError(f"operand value {tok!r} is not an integer")
+
+
+def _field_range(width: int, signed: bool):
+    return (-(1 << (8 * width - 1)), (1 << (8 * width - 1)) - 1) if signed else (0, (1 << (8 * width)) - 1)
+
+
+def assemble_instr_text(line: str) -> _sc.Instr:
+    """One ``Name(field=value, ...)`` line -> an :class:`seqcodec.Instr` (offset 0). A leading ``[offset]`` and a
+    trailing ``# comment`` are tolerated (so a disassembly line pastes back in). Every real operand must be given
+    (the 0x19 ``Sfx`` ``_pad`` hole defaults to 0); each is range-checked against its field."""
+    line = line.split("#", 1)[0].strip()
+    m = _LINE_RE.match(line)
+    if not m:
+        raise SeqAsmError(f"cannot parse instruction {line!r} (expected `Name(field=value, ...)`)")
+    name, argstr = m.group(1), (m.group(2) or "").strip()
+    op = _NAME_TO_OP.get(name)
+    if op is None:
+        raise SeqAsmError(f"unknown opcode name {name!r} (see `battle-seq` / the seqcodec opcode table)")
+    fields = _sc._OPS[op][1]
+    provided: dict = {}
+    if argstr:
+        for part in argstr.split(","):
+            if "=" not in part:
+                raise SeqAsmError(f"{name}: operand {part.strip()!r} must be `field=value`")
+            k, v = part.split("=", 1)
+            key = k.strip()
+            if key in provided:
+                raise SeqAsmError(f"{name}: operand {key!r} given more than once")
+            provided[key] = _parse_int(v)
+    fieldnames = {fn for fn, _o, _w, _s, _k in fields}
+    unknown = set(provided) - fieldnames
+    if unknown:
+        raise SeqAsmError(f"{name}: unknown operand(s) {sorted(unknown)} (fields: {sorted(fieldnames) or 'none'})")
+    operands = []
+    for fn, _o, w, signed, _k in fields:
+        if fn in provided:
+            val = provided[fn]
+        elif fn == "_pad":
+            val = 0                                    # the discarded Sfx hole -- default 0 (engine ignores it)
+        else:
+            raise SeqAsmError(f"{name}: missing operand {fn!r}")
+        lo, hi = _field_range(w, signed)
+        if not lo <= val <= hi:
+            raise SeqAsmError(f"{name}.{fn} = {val} is out of range [{lo}, {hi}] "
+                              f"({w}-byte {'signed' if signed else 'unsigned'})")
+        operands.append(val)
+    return _sc.Instr(op, 0, operands)
+
+
+def assemble(source: str) -> list:
+    """A multi-line / ``;``-separated sequence source -> ``[Instr]``. Must end in a terminator (End/FastEnd) and
+    contain NO terminator before the end (an unreachable tail is a likely authoring error). Blank lines + ``#``
+    comments are ignored. The byte form is ``b"".join(seqcodec.emit_instr(i) for i in assemble(src))``."""
+    raw_lines = [ln for chunk in source.replace(";", "\n").splitlines() for ln in [chunk.strip()] if ln]
+    instrs = []
+    for ln in raw_lines:
+        if ln.split("#", 1)[0].strip():               # skip pure-comment / blank lines
+            instrs.append(assemble_instr_text(ln))
+    if not instrs:
+        raise SeqAsmError("empty sequence source (need at least a terminator)")
+    if instrs[-1].op not in _sc.TERMINATORS:
+        raise SeqAsmError(f"a sequence must end in a terminator (End or FastEnd); got {instrs[-1].name}")
+    for i, ins in enumerate(instrs[:-1]):
+        if ins.op in _sc.TERMINATORS:
+            raise SeqAsmError(f"terminator {ins.name} at instruction {i} is not last -- the tail is unreachable")
+    out = assemble_bytes(instrs)                       # SELF-VERIFY: the bytes re-decode to exactly these instrs
+    redec, _end = _sc._decode_body(out, 0, len(out))
+    if [(i.op, tuple(i.operands)) for i in redec] != [(i.op, tuple(i.operands)) for i in instrs]:
+        raise SeqAsmError("internal: assembled bytes did not re-decode to the source instructions")
+    return instrs
+
+
+def assemble_fragment(source: str) -> list:
+    """A sequence FRAGMENT (for a mid-body splice via :func:`seqauthor.insert_sequence`) -> ``[Instr]``. Like
+    :func:`assemble` but with NO terminator: a fragment is inserted INTO a body, so it must NOT contain End/FastEnd
+    (which would truncate the body early)."""
+    raw_lines = [ln for chunk in source.replace(";", "\n").splitlines() for ln in [chunk.strip()] if ln]
+    instrs = [assemble_instr_text(ln) for ln in raw_lines if ln.split("#", 1)[0].strip()]
+    if not instrs:
+        raise SeqAsmError("empty fragment source")
+    for ins in instrs:
+        if ins.op in _sc.TERMINATORS:
+            raise SeqAsmError(f"a fragment must not contain a terminator ({ins.name}) -- it is spliced mid-body")
+    return instrs
+
+
+def assemble_bytes(instrs) -> bytes:
+    return b"".join(_sc.emit_instr(i) for i in instrs)
+
+
+def to_source(instrs, *, multiline: bool = True) -> str:
+    """The canonical (round-trippable) source for an instruction list -- includes EVERY operand (incl. the Sfx
+    ``_pad``), so ``assemble(to_source(x)) == x`` byte-for-byte. (The human ``seqdis`` view hides ``_pad`` + adds
+    notes; this is the machine form.)"""
+    lines = []
+    for ins in instrs:
+        args = ", ".join(f"{fn}={val}" for (fn, _o, _w, _s, _k), val in zip(ins.fields, ins.operands))
+        lines.append(f"{ins.name}({args})" if args else ins.name)
+    return "\n".join(lines) if multiline else "; ".join(lines)