ff9mapkit 1.0.0b3__py3-none-any.whl

ff9mapkit/_regen_animdb.py

@@ -0,0 +1,72 @@
+"""Regenerate ``_animdb.py`` (FF9 main-character animation id -> name) from a Memoria checkout.
+
+A *maintainer* tool, not part of the runtime -- the table is baked into ``_animdb.py`` so the kit can
+offer an author-facing animation catalog (pick a cutscene gesture by name) with no Memoria source at
+runtime. Same provenance category as ``_fieldtable.py``: it's Memoria's OPEN-SOURCE ``AnimationDB``
+mapping (Memoria's reverse-engineered labels for FF9's anim resource ids), not extracted game data.
+
+    python -m ff9mapkit._regen_animdb --memoria "C:/path/to/Memoria"
+
+It reads ``Global/ff9/FF9DBAll.Animation.cs`` -> ``AnimationDB`` (id <-> "ANH_..") and keeps only the
+8 playable characters' anims (the cutscene presets). Anim names encode model + action:
+``ANH_MAIN_F0_VIV_TALK_3_1`` -> model token ``VIV`` (Vivi), form ``F0``, action ``TALK_3_1``. The
+engine loads an anim by name->id onto the matching model on demand (AnimationFactory), so any anim
+tokened to a character's model plays on that model. To widen coverage (NPC/monster models), add their
+tokens to ``MAIN_TOKENS`` below.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+from pathlib import Path
+
+# the 8 playable characters' anim-name tokens (ZDN Zidane, VIV Vivi, GRN Garnet/Dagger, STN Steiner,
+# FRJ Freya, KUI Quina, EIK Eiko, SLM Amarant "Salamander"). Field cutscene presets draw from these.
+MAIN_TOKENS = ("ZDN", "VIV", "GRN", "STN", "FRJ", "KUI", "EIK", "SLM")
+
+_PAIR = re.compile(r'\{\s*(\d+)\s*,\s*"(ANH_[^"]+)"\s*\}')
+
+
+def parse_table(memoria_root: Path) -> dict:
+    src = (memoria_root / "Assembly-CSharp" / "Global" / "ff9" / "FF9DBAll.Animation.cs"
+           ).read_text(encoding="utf-8", errors="replace")
+    keep = re.compile(r"^ANH_MAIN_F\d_(?:" + "|".join(MAIN_TOKENS) + r")_")
+    table = {}
+    for i, name in _PAIR.findall(src):
+        if keep.match(name):
+            table[int(i)] = name
+    return table
+
+
+def render(table: dict) -> str:
+    header = ('"""Auto-generated FF9 main-character animation table: anim id -> name.\n\n'
+              "DO NOT EDIT BY HAND. Regenerate with:  python -m ff9mapkit._regen_animdb --memoria <path>\n"
+              "Source: Memoria Assembly-CSharp/Global/ff9/FF9DBAll.Animation.cs (AnimationDB, open-source).\n\n"
+              "Names encode model + action: ANH_MAIN_F0_VIV_TALK_3_1 -> Vivi ('VIV'), form F0, action\n"
+              "TALK_3_1. Limited to the 8 playable characters (the field cutscene presets). The catalog\n"
+              "in ff9mapkit.animations turns these into pick-by-name gestures.\n"
+              '"""\n')
+    lines = [header, "", "MAIN_ANIMATIONS = {"]
+    for anim_id in sorted(table, key=lambda i: (table[i], i)):   # by name (groups by character), then id
+        lines.append(f'    {anim_id}: {table[anim_id]!r},')
+    lines.append("}")
+    return "\n".join(lines) + "\n"
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description="Regenerate _animdb.py from Memoria source.")
+    ap.add_argument("--memoria", required=True, help="path to a Memoria source checkout")
+    args = ap.parse_args(argv)
+    table = parse_table(Path(args.memoria))
+    target = Path(__file__).with_name("_animdb.py")
+    target.write_text(render(table), encoding="utf-8", newline="\n")
+    per = {}
+    for name in table.values():
+        per[name.split("_")[3]] = per.get(name.split("_")[3], 0) + 1
+    print(f"wrote {target}  ({len(table)} anims: " + ", ".join(f"{t}={per.get(t, 0)}" for t in MAIN_TOKENS) + ")")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ff9mapkit/_regen_animdb_all.py

@@ -0,0 +1,66 @@
+"""Regenerate ``_animdb_all.py`` (the FULL FF9 animation id -> name table) from a Memoria checkout.
+
+A *maintainer* tool, not part of the runtime. Same provenance category as ``_animdb.py`` -- it
+transcribes Memoria's OPEN-SOURCE ``AnimationDB`` (id<->"ANH_.." labels), NOT extracted game data; no
+animation binary is read or shipped.
+
+    python -m ff9mapkit._regen_animdb_all --memoria "C:/path/to/Memoria"
+
+This is the COMPREHENSIVE table (every ``ANH_*`` animation, all model groups), used by
+:mod:`ff9mapkit.catalog` to list any model's gestures via the (group, token) join. It is a superset of
+``_animdb.py`` (which keeps only the 8 playable characters for the cutscene author-convenience and is
+what the *build* path imports). They are regenerated independently on purpose so the build's animation
+resolution is untouched by Info-Hub changes; a future cleanup could derive ``_animdb.py`` from this.
+
+An anim name encodes model + action: ``ANH_<group>_<form>_<token>_<action>`` -- e.g.
+``ANH_MAIN_F0_VIV_TALK_3_1`` (Vivi, field form, action TALK_3_1) or ``ANH_NPC_F0_BAR_*``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+from pathlib import Path
+
+_PAIR = re.compile(r'\{\s*(\d+)\s*,\s*"(ANH_[^"]+)"\s*\}')
+
+
+def parse_table(memoria_root: Path) -> dict:
+    src = (memoria_root / "Assembly-CSharp" / "Global" / "ff9" / "FF9DBAll.Animation.cs"
+           ).read_text(encoding="utf-8", errors="replace")
+    return {int(i): name for i, name in _PAIR.findall(src)}
+
+
+def render(table: dict) -> str:
+    header = ('"""Auto-generated FULL FF9 animation table: anim id -> name (all model groups).\n\n'
+              "DO NOT EDIT BY HAND. Regenerate with:  python -m ff9mapkit._regen_animdb_all --memoria <path>\n"
+              "Source: Memoria Assembly-CSharp/Global/ff9/FF9DBAll.Animation.cs (AnimationDB, open-source) --\n"
+              "the same id<->name table Memoria publishes; NOT extracted game data (see docs/PROVENANCE.md).\n\n"
+              "ANIMATIONS[id] = 'ANH_<group>_<form>_<token>_<action>'. Superset of _animdb.py (which is the\n"
+              "8-playable subset used by the build's cutscene path). ff9mapkit.catalog joins these to a\n"
+              "model by (group, token) -> the model's gesture list.\n"
+              '"""\n')
+    lines = [header, "", "ANIMATIONS = {"]
+    for anim_id in sorted(table, key=lambda i: (table[i], i)):   # by name (groups by model), then id
+        lines.append(f"    {anim_id}: {table[anim_id]!r},")
+    lines.append("}")
+    return "\n".join(lines) + "\n"
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description="Regenerate _animdb_all.py from Memoria source.")
+    ap.add_argument("--memoria", required=True, help="path to a Memoria source checkout")
+    args = ap.parse_args(argv)
+    table = parse_table(Path(args.memoria))
+    target = Path(__file__).with_name("_animdb_all.py")
+    target.write_text(render(table), encoding="utf-8", newline="\n")
+    groups = {}
+    for name in table.values():
+        groups[name.split("_")[1]] = groups.get(name.split("_")[1], 0) + 1
+    print(f"wrote {target}  ({len(table)} anims: "
+          + ", ".join(f"{g}={n}" for g, n in sorted(groups.items())) + ")")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ff9mapkit/_regen_fieldtable.py

@@ -0,0 +1,95 @@
+"""Regenerate ``_fieldtable.py`` (FBG field-folder -> event-script name) from a Memoria checkout.
+
+This is a *maintainer* tool, not part of the runtime -- the table is baked into ``_fieldtable.py``
+so the kit needs no Memoria source to map an imported field's background folder to its event ``.eb``.
+Run it only when updating to a newer Memoria whose field registry changed:
+
+    python -m ff9mapkit._regen_fieldtable --memoria "C:/path/to/Memoria"
+
+It reads two base (vanilla) registries, both keyed by field id:
+  * ``Global/Event/Engine/EventEngineUtils.cs``  -> ``eventIDToFBGID``  (id -> "FBG_N..")
+  * ``Global/ff9/FF9DBAll.Events.cs``             -> ``EventDB``        (id -> "EVT_..")
+and joins them on field id to emit ``FBG_TO_EVT = {fbg_lower: [field_id, "EVT_.."]}`` -- exactly the
+mapping ``import`` needs (an imported field is named by its FBG background folder; its script is the
+EVT_ event binary in p0data). EventDB also holds battle/world/startup events; the join on FBG ids
+keeps only the field maps.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+from pathlib import Path
+
+_PAIR = re.compile(r'\{\s*(\d+)\s*,\s*"([^"]+)"\s*\}')
+
+
+def _dict_block(src: str, name: str) -> str:
+    """The text of a ``name = new Dictionary<Int32, String> { ... };`` literal (up to the first ``};``)."""
+    m = re.search(re.escape(name) + r"\s*=\s*new\s+Dictionary<Int32,\s*String>\s*\{(.*?)\n\s*\};",
+                  src, re.S)
+    if not m:
+        raise ValueError(f"could not find dictionary {name!r}")
+    return m.group(1)
+
+
+def parse_tables(memoria_root: Path):
+    eng = (memoria_root / "Assembly-CSharp" / "Global" / "Event" / "Engine" / "EventEngineUtils.cs"
+           ).read_text(encoding="utf-8", errors="replace")
+    evt = (memoria_root / "Assembly-CSharp" / "Global" / "ff9" / "FF9DBAll.Events.cs"
+           ).read_text(encoding="utf-8", errors="replace")
+    id_to_fbg = {int(i): name for i, name in _PAIR.findall(_dict_block(eng, "eventIDToFBGID"))}
+    id_to_evt = {int(i): name for i, name in _PAIR.findall(_dict_block(evt, "EventDB"))}
+    table = {}
+    by_id = {}
+    for fid, fbg in id_to_fbg.items():
+        evt_name = id_to_evt.get(fid)
+        if evt_name:                                    # join on field id; skip ids with no event entry
+            # FOLDER-keyed (lossy: several field ids can share ONE background folder -- the same room at
+            # different story beats -- so the LAST wins; fine for the NAME-based `import` resolver).
+            table[fbg.lower()] = [fid, evt_name]
+            # ID-keyed (COMPLETE: every field id kept, so a shared-folder field like 52/3008 isn't dropped).
+            # The chain walk + whole-zone fork key on this so they don't miss ~142 of the 818 real fields.
+            by_id[fid] = [fbg.lower(), evt_name]
+    return table, by_id, len(id_to_fbg), len(id_to_evt)
+
+
+def render(table: dict, by_id: dict) -> str:
+    header = ('"""Auto-generated FF9 field registry: background folder (FBG) <-> event-script name.\n\n'
+              "DO NOT EDIT BY HAND. Regenerate with:  python -m ff9mapkit._regen_fieldtable\n"
+              "Source (both keyed by field id, joined here on id):\n"
+              "  Memoria  Assembly-CSharp/Global/Event/Engine/EventEngineUtils.cs  (eventIDToFBGID)\n"
+              "           Assembly-CSharp/Global/ff9/FF9DBAll.Events.cs            (EventDB)\n\n"
+              "  FBG_TO_EVT[fbg_folder_lowercase] = [field_id, 'EVT_<name>']   -- FOLDER-keyed (NAME import).\n"
+              "  FIELD_BY_ID[field_id]            = [fbg_folder_lowercase, 'EVT_<name>']   -- ID-keyed, COMPLETE.\n\n"
+              "Several field ids can share ONE FBG folder (the same room at different story beats), so the\n"
+              "folder-keyed FBG_TO_EVT drops all but one -- the id-keyed FIELD_BY_ID keeps every field, which\n"
+              "the chain walk + whole-zone fork need (else ~142 of the 818 real fields go missing + their\n"
+              "warps leak to the live game).\n"
+              '"""\n')
+    lines = [header, "", "FBG_TO_EVT = {"]
+    for fbg in sorted(table):
+        fid, evt = table[fbg]
+        lines.append(f'    {fbg!r}: [{fid}, {evt!r}],')
+    lines += ["}", "", "FIELD_BY_ID = {"]
+    for fid in sorted(by_id):
+        fbg, evt = by_id[fid]
+        lines.append(f'    {fid}: [{fbg!r}, {evt!r}],')
+    lines.append("}")
+    return "\n".join(lines) + "\n"
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description="Regenerate _fieldtable.py from Memoria source.")
+    ap.add_argument("--memoria", required=True, help="path to a Memoria source checkout")
+    args = ap.parse_args(argv)
+    table, by_id, n_fbg, n_evt = parse_tables(Path(args.memoria))
+    target = Path(__file__).with_name("_fieldtable.py")
+    target.write_text(render(table, by_id), encoding="utf-8", newline="\n")
+    print(f"wrote {target}  (eventIDToFBGID={n_fbg}, EventDB={n_evt}, folder maps={len(table)}, "
+          f"id maps={len(by_id)})")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ff9mapkit/_regen_fieldtext.py

@@ -0,0 +1,66 @@
+"""Regenerate ``_fieldtext.py`` (field map-id -> text-block / MES id) from a Memoria checkout.
+
+A maintainer tool, not part of the runtime -- the table is baked into ``_fieldtext.py`` so the kit
+needs no Memoria source to find which ``<mes-id>.mes`` holds a real field's dialogue. The engine names a
+field's text file by this id (``FF9TextTool.GetFieldTextFileName`` == the id as a string), and looks it up
+exactly here -- ``EventEngineUtils.eventIDToMESID[fldMapNo]`` (used in FF9UIDataTool). Run it only when
+updating to a newer Memoria whose registry changed:
+
+    python -m ff9mapkit._regen_fieldtext --memoria "C:/path/to/Memoria"
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+from pathlib import Path
+
+_PAIR = re.compile(r"\{\s*(\d+)\s*,\s*(\d+)\s*\}")
+
+
+def _dict_block(src: str, name: str) -> str:
+    """The body of a ``name = new Dictionary<Int32, Int32> { ... };`` literal (up to the first ``};``)."""
+    m = re.search(re.escape(name) + r"\s*=\s*new\s+Dictionary<Int32,\s*Int32>\s*\(\s*\)\s*\{(.*?)\n\s*\};",
+                  src, re.S)
+    if not m:
+        m = re.search(re.escape(name) + r"\s*=\s*new\s+Dictionary<Int32,\s*Int32>\s*\{(.*?)\n\s*\};", src, re.S)
+    if not m:
+        raise ValueError(f"could not find dictionary {name!r}")
+    return m.group(1)
+
+
+def parse_table(memoria_root: Path) -> dict:
+    eng = (memoria_root / "Assembly-CSharp" / "Global" / "Event" / "Engine" / "EventEngineUtils.cs"
+           ).read_text(encoding="utf-8", errors="replace")
+    return {int(k): int(v) for k, v in _PAIR.findall(_dict_block(eng, "eventIDToMESID"))}
+
+
+def render(table: dict) -> str:
+    header = ('"""Auto-generated FF9 field text registry: field map-id -> text-block (MES) id.\n\n'
+              "DO NOT EDIT BY HAND. Regenerate with:  python -m ff9mapkit._regen_fieldtext\n"
+              "Source:  Memoria  Assembly-CSharp/Global/Event/Engine/EventEngineUtils.cs  (eventIDToMESID)\n\n"
+              "A field's dialogue lives in ``<mes-id>.mes`` (the engine names it by this id -- see\n"
+              "FF9TextTool.GetFieldTextFileName / EventEngineUtils.eventIDToMESID). EVENT_ID_TO_MES[field_id]\n"
+              "is how `dialogue-import` reads the RIGHT text block for a real field (txids are 0-based\n"
+              "positions shared by every field, so the block can't be found by txid alone).\n"
+              '"""\n')
+    lines = [header, "", "EVENT_ID_TO_MES = {"]
+    for fid in sorted(table):
+        lines.append(f"    {fid}: {table[fid]},")
+    lines.append("}")
+    return "\n".join(lines) + "\n"
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description="Regenerate _fieldtext.py from Memoria source.")
+    ap.add_argument("--memoria", required=True, help="path to a Memoria source checkout")
+    args = ap.parse_args(argv)
+    table = parse_table(Path(args.memoria))
+    target = Path(__file__).with_name("_fieldtext.py")
+    target.write_text(render(table), encoding="utf-8", newline="\n")
+    print(f"wrote {target}  (eventIDToMESID entries={len(table)})")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ff9mapkit/_regen_modeldb.py

@@ -0,0 +1,67 @@
+"""Regenerate ``_modeldb.py`` (FF9 actor/field model id -> GEO name) from a Memoria checkout.
+
+A *maintainer* tool, not part of the runtime. Same provenance category as ``_fieldtable.py`` /
+``_animdb.py``: it transcribes Memoria's OPEN-SOURCE ``FF9BattleDB.GEO`` id<->name table (Memoria's
+reverse-engineered labels for FF9's model resource ids), NOT extracted game data -- no model geometry
+is ever read or shipped.
+
+    python -m ff9mapkit._regen_modeldb --memoria "C:/path/to/Memoria"
+
+It reads ``Global/ff9/Battle/FF9BattleDB.GEO.cs`` -> ``GEO`` (model id <-> "GEO_<grp>_<form>_<token>").
+A model name encodes group + form + token:
+  * ``GEO_MAIN_F0_VIV`` -> group MAIN (playable), form F0 (field), token VIV (Vivi)
+  * ``GEO_NPC_F0_BAR``  -> an NPC field model;  ``GEO_MON_F0_*`` a monster;  ``GEO_ACC_F0_*`` a prop
+The token ties a model to its animations: an anim ``ANH_<grp>_<form>_<token>_<action>`` plays on the
+model sharing (group, token). That join is what :mod:`ff9mapkit.catalog` uses for "this model's
+gestures" (verified: model id 8 = ``GEO_MAIN_F0_VIV``, whose (MAIN, VIV) anims are 148/571/419/...).
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+from pathlib import Path
+
+_PAIR = re.compile(r'\{\s*(\d+)\s*,\s*"(GEO_[^"]+)"\s*\}')
+
+
+def parse_table(memoria_root: Path) -> dict:
+    src = (memoria_root / "Assembly-CSharp" / "Global" / "ff9" / "Battle" / "FF9BattleDB.GEO.cs"
+           ).read_text(encoding="utf-8", errors="replace")
+    return {int(i): name for i, name in _PAIR.findall(src)}
+
+
+def render(table: dict) -> str:
+    header = ('"""Auto-generated FF9 model registry: actor/field model id -> GEO resource name.\n\n'
+              "DO NOT EDIT BY HAND. Regenerate with:  python -m ff9mapkit._regen_modeldb --memoria <path>\n"
+              "Source: Memoria Assembly-CSharp/Global/ff9/Battle/FF9BattleDB.GEO.cs (GEO, open-source) --\n"
+              "the same id<->name table Memoria publishes; NOT extracted game data (see docs/PROVENANCE.md).\n\n"
+              "MODELS[id] = 'GEO_<group>_<form>_<token>'. group: MAIN playable / NPC townsfolk / MON\n"
+              "monster / ACC prop / SUB sub-character / WEP weapon. form: F* field, B* battle, W* world.\n"
+              "The token links a model to its animations (ANH_<group>_*_<token>_<action>); see\n"
+              "ff9mapkit.catalog.animations_for_model. The model id is the value SetModel() takes.\n"
+              '"""\n')
+    lines = [header, "", "MODELS = {"]
+    for mid in sorted(table, key=lambda i: (table[i], i)):   # by name (groups by category), then id
+        lines.append(f"    {mid}: {table[mid]!r},")
+    lines.append("}")
+    return "\n".join(lines) + "\n"
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description="Regenerate _modeldb.py from Memoria source.")
+    ap.add_argument("--memoria", required=True, help="path to a Memoria source checkout")
+    args = ap.parse_args(argv)
+    table = parse_table(Path(args.memoria))
+    target = Path(__file__).with_name("_modeldb.py")
+    target.write_text(render(table), encoding="utf-8", newline="\n")
+    groups = {}
+    for name in table.values():
+        groups[name.split("_")[1]] = groups.get(name.split("_")[1], 0) + 1
+    print(f"wrote {target}  ({len(table)} models: "
+          + ", ".join(f"{g}={n}" for g, n in sorted(groups.items())) + ")")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ff9mapkit/_regen_npcparams.py

@@ -0,0 +1,123 @@
+"""Regenerate ``_npcparams.py`` -- the per-model NPC OBJECT params (animset / head-focus / logical-size /
+movement clips) that :func:`ff9mapkit.content.npc.build_npc_init` uses to emit a byte-faithful standing NPC
+for ANY model, not just moogles.
+
+We scan every real field's ``.eb`` for non-player object entries (those WITHOUT ``DefinePlayerCharacter``),
+read each one's Init -- ``SetModel`` (model + animset), ``SetObjectLogicalSize``, ``SetHeadFocusMask``, and
+the five movement-anim setters (ops 0x33/0x34/0x35/0x7A/0x7B) -- and bake, per model, the MODAL (most common)
+value of each. Only ``GEO_NPC_*`` / ``GEO_MON_*`` models with a COMPLETE set (animset + head-focus +
+logical-size + five clips) are kept: those are the real standing-NPC/creature rigs. Party (``GEO_MAIN``) and
+accessory (``GEO_ACC``) models are excluded -- party characters are the player's job and accessories are
+props (their own ``inject_prop`` path), so they must not drive generic NPC synthesis.
+
+Provenance: the output is DERIVED METADATA (model ids + small ints only -- no Square-Enix bytes), exactly
+like ``_modeldb`` / ``_animdb``. Run with the install reachable (``$FF9_GAME_PATH`` or run from the game dir):
+
+    python -m ff9mapkit._regen_npcparams
+"""
+from __future__ import annotations
+
+from collections import Counter, defaultdict
+from pathlib import Path
+
+# op -> the movement-clip slot it sets (the from-scratch Init's five setters, in ANIM_ORDER)
+_ANIM_OPS = {0x33: "stand", 0x34: "walk", 0x35: "run", 0x7A: "left", 0x7B: "right"}
+_SLOTS = ("stand", "walk", "run", "left", "right")
+
+
+def _scan() -> dict:
+    """``{model: {animset, head_focus, logical_size, anims}}`` -- the modal real-NPC params per model."""
+    from . import extract
+    from .eb import EbScript
+    from ._modeldb import MODELS
+
+    bundle = extract.EventBundle()
+    acc: dict = defaultdict(lambda: {"animset": Counter(), "hf": Counter(), "ls": Counter(), "anims": Counter()})
+    for fid in extract.ID_TO_FBG:
+        eb_bytes = bundle.eb_for_id(fid)
+        if not eb_bytes:
+            continue
+        try:
+            eb = EbScript.from_bytes(eb_bytes)
+        except Exception:                                  # noqa: BLE001 -- a field we can't parse: skip
+            continue
+        for e in eb.entries:
+            if e.empty:
+                continue
+            f0 = e.func_by_tag(0)
+            if f0 is None:
+                continue
+            ins = list(eb.instrs(f0))
+            if any(i.op == 0x2C for i in ins):             # the player (DefinePlayerCharacter) -- not an NPC
+                continue
+            sm = next((i for i in ins if i.op == 0x2F), None)
+            if sm is None:
+                continue
+            model, animset = int(sm.args[0]), int(sm.args[1])
+            a = acc[model]
+            a["animset"][animset] += 1
+            ls = next((tuple(i.args) for i in ins if i.op == 0x4B), None)
+            if ls:
+                a["ls"][ls] += 1
+            hf = next((tuple(i.args) for i in ins if i.op == 0x8B), None)
+            if hf:
+                a["hf"][hf] += 1
+            clips = {}
+            for i in ins:
+                if i.op in _ANIM_OPS and _ANIM_OPS[i.op] not in clips:
+                    clips[_ANIM_OPS[i.op]] = int(i.args[0])
+            if len(clips) == 5:
+                a["anims"][tuple(clips[s] for s in _SLOTS)] += 1
+
+    out = {}
+    for model, c in acc.items():
+        name = MODELS.get(model, "")
+        if not (name.startswith("GEO_NPC") or name.startswith("GEO_MON")):
+            continue                                       # only real NPC / creature rigs (no party / accessory)
+        if not (c["animset"] and c["hf"] and c["ls"] and c["anims"]):
+            continue                                       # incomplete -> the defaults in npc.py cover it
+        anims = c["anims"].most_common(1)[0][0]
+        out[model] = {
+            "animset": c["animset"].most_common(1)[0][0],
+            "head_focus": tuple(c["hf"].most_common(1)[0][0]),
+            "logical_size": tuple(c["ls"].most_common(1)[0][0]),
+            "anims": {s: anims[i] for i, s in enumerate(_SLOTS)},
+        }
+    return out
+
+
+def _render(params: dict) -> str:
+    from ._modeldb import MODELS
+    L = ['"""Auto-generated per-model NPC OBJECT params -- the canonical (modal) animset / head-focus /',
+         "logical-size / movement clips real standing NPCs use, so ``content.npc.build_npc_init`` emits a",
+         "byte-faithful NPC for any GEO_NPC_* / GEO_MON_* model (not just moogles).",
+         "",
+         "DO NOT EDIT BY HAND. Regenerate with:  python -m ff9mapkit._regen_npcparams",
+         "Provenance: derived metadata (model ids + small ints), no Square-Enix bytes.",
+         '"""',
+         "",
+         "NPC_PARAMS = {"]
+    for model in sorted(params):
+        p = params[model]
+        a = p["anims"]
+        L.append(f"    {model}: {{  # {MODELS.get(model, '?')}")
+        L.append(f"        \"animset\": {p['animset']}, \"head_focus\": {p['head_focus']}, "
+                 f"\"logical_size\": {p['logical_size']},")
+        L.append(f"        \"anims\": {{\"stand\": {a['stand']}, \"walk\": {a['walk']}, \"run\": {a['run']}, "
+                 f"\"left\": {a['left']}, \"right\": {a['right']}}},")
+        L.append("    },")
+    L.append("}")
+    L.append("")
+    return "\n".join(L)
+
+
+def main() -> int:
+    params = _scan()
+    dest = Path(__file__).resolve().parent / "_npcparams.py"
+    dest.write_text(_render(params), encoding="utf-8", newline="\n")
+    print(f"wrote {dest}  ({len(params)} models)")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ff9mapkit/_regen_scenedb.py

@@ -0,0 +1,57 @@
+"""Regenerate ``_scenedb.py`` (FF9 battle-scene name -> encounter id) from a Memoria checkout.
+
+A *maintainer* tool, not part of the runtime. Same provenance category as ``_fieldtable.py``: it
+transcribes Memoria's OPEN-SOURCE ``FF9BattleDB.SceneData`` name<->id table, NOT extracted game data
+(no battle binary, enemy stats, or roster bytes are read or shipped -- only the id<->name labels).
+
+    python -m ff9mapkit._regen_scenedb --memoria "C:/path/to/Memoria"
+
+It reads ``Global/ff9/Battle/FF9BattleDB.SceneData.cs`` -> ``SceneData`` ("BSC_<region>_<n>" <-> id).
+A scene id is what a field encounter points at (``SetRandomBattles`` slots); the name encodes the
+region (BSC_AC_* = Alexandria Castle, BSC_B3_* = a disc-3 battle, ...). This is a *reference* catalog
+for picking/identifying encounter ids by name; enemy rosters/stats are NOT here (they live in p0data).
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+from pathlib import Path
+
+_PAIR = re.compile(r'\{\s*"(BSC_[^"]+)"\s*,\s*(\d+)\s*\}')
+
+
+def parse_table(memoria_root: Path) -> dict:
+    src = (memoria_root / "Assembly-CSharp" / "Global" / "ff9" / "Battle" / "FF9BattleDB.SceneData.cs"
+           ).read_text(encoding="utf-8", errors="replace")
+    return {name: int(i) for name, i in _PAIR.findall(src)}
+
+
+def render(table: dict) -> str:
+    header = ('"""Auto-generated FF9 battle-scene registry: scene name -> encounter id.\n\n'
+              "DO NOT EDIT BY HAND. Regenerate with:  python -m ff9mapkit._regen_scenedb --memoria <path>\n"
+              "Source: Memoria Assembly-CSharp/Global/ff9/Battle/FF9BattleDB.SceneData.cs (SceneData,\n"
+              "open-source) -- the same id<->name table Memoria publishes; NOT extracted game data.\n\n"
+              "SCENES['BSC_<region>_<n>'] = encounter_id. A field's encounter points SetRandomBattles at\n"
+              "these ids; the name encodes the region. Enemy rosters/stats are NOT here (they're in p0data).\n"
+              '"""\n')
+    lines = [header, "", "SCENES = {"]
+    for name in sorted(table):
+        lines.append(f"    {name!r}: {table[name]},")
+    lines.append("}")
+    return "\n".join(lines) + "\n"
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description="Regenerate _scenedb.py from Memoria source.")
+    ap.add_argument("--memoria", required=True, help="path to a Memoria source checkout")
+    args = ap.parse_args(argv)
+    table = parse_table(Path(args.memoria))
+    target = Path(__file__).with_name("_scenedb.py")
+    target.write_text(render(table), encoding="utf-8", newline="\n")
+    print(f"wrote {target}  ({len(table)} battle scenes)")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())