ff9mapkit 1.0.0b3__py3-none-any.whl

ff9mapkit/abilities.py

@@ -0,0 +1,225 @@
+"""Character ABILITY data -- the AP/ability-mastery half of the #5 save editor.
+
+Two pieces, both provenance-clean (ship/commit nothing -- the same live-read pattern as :mod:`ff9mapkit.itemstats`
+and :mod:`ff9mapkit.keyitems`):
+
+* a mod-agnostic **id<->token codec** (``AA:X`` active / ``SA:X`` support <-> the integer ``abil_id`` the save
+  stores in ``players[].pa_extended[].id``), mirroring Memoria's ``CsvParser.AnyAbility`` / ``ff9abil``; and
+* a best-effort **name + AP-requirement** lookup, read LIVE from the install's per-character pool CSVs
+  ``<install>/StreamingAssets/Data/Characters/Abilities/<Preset>.csv`` (rows ``AA:101;40;# Flee`` --
+  token ; AP-to-master ; ``# name``).
+
+★ The codec ALWAYS works (pure arithmetic). The name/AP lookup is BEST-EFFORT: it reads the base-game CSVs, so
+an id that a mod (e.g. Moguri) introduced -- not present in the base pool -- resolves to ``None`` and the editor
+falls back to the raw ``AA:X``/``SA:X`` token. The save's own ``pa_extended`` is the source of truth for which
+abilities a character has; this module only enriches it with names + the master threshold.
+
+The id<->token math (Memoria ``ff9abil``/``CsvParser.AnyAbility``): each ability has a global integer ``abil_id``;
+``mod = abil_id % 256`` is < 192 for ACTIVE (``AA``) and >= 192 for SUPPORT (``SA``); ``pool = abil_id // 256``.
+For ``AA:X`` -> ``abil_id = (X // 192) * 256 + X % 192``; for ``SA:X`` -> ``(X // 64) * 256 + X % 64 + 192``.
+
+Usage::
+
+    from ff9mapkit import abilities
+    abilities.encode_token("AA:108")          # -> 108
+    abilities.decode_token(192)               # -> "SA:0"
+    abilities.name_of(108)                    # -> "Thievery"  (or None if the install isn't reachable)
+    abilities.ap_required(0, 108)             # -> 100  (Zidane preset=0; or None)
+    abilities.resolve(0, "Thievery")          # -> 108
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+# CharacterPresetId (Memoria.Data.Characters.CharacterPresetId) -> the per-pool CSV basename. menu_type in the
+# save == this preset id. Only 0-15 ship a pool CSV (16+ are stage doubles with no learnable set).
+PRESET_NAMES = {0: "Zidane", 1: "Vivi", 2: "Garnet", 3: "Steiner", 4: "Freya", 5: "Quina", 6: "Eiko",
+                7: "Amarant", 8: "Cinna1", 9: "Cinna2", 10: "Marcus1", 11: "Marcus2", 12: "Blank1",
+                13: "Blank2", 14: "Beatrix1", 15: "Beatrix2"}
+
+_AP_MAX = 255                                              # the old-format `pa` cell is a Byte; AP-to-master <= 255
+_ROW_RE = re.compile(r"#\s*(.+?)\s*$")                     # the trailing `# Name` comment on a pool-CSV row
+
+_POOL_CACHE: dict = {}      # menu_type -> [Ability, ...] (or False = tried + unavailable)
+_GLOBAL_NAMES = None        # None = not built; dict {abil_id: name} unioned across every preset pool
+
+
+# --- the mod-agnostic id <-> token codec (pure arithmetic; always available) ----------------------
+
+def kind_of(abil_id: int) -> str:
+    """``"AA"`` (active) if ``abil_id % 256 < 192`` else ``"SA"`` (support) -- the engine's split (ff9abil)."""
+    return "AA" if abil_id % 256 < 192 else "SA"
+
+
+def decode_token(abil_id: int) -> str:
+    """An integer ``abil_id`` -> its ``"AA:X"`` / ``"SA:X"`` token (the inverse of :func:`encode_token`)."""
+    if isinstance(abil_id, bool) or not isinstance(abil_id, int):
+        raise TypeError(f"abil_id must be an int (got {type(abil_id).__name__})")
+    pool, mod = divmod(abil_id, 256)
+    if mod < 192:
+        return f"AA:{pool * 192 + mod}"
+    return f"SA:{pool * 64 + (mod - 192)}"
+
+
+def encode_token(token) -> int:
+    """An ``"AA:X"`` / ``"SA:X"`` token (or a plain integer / digit string) -> the integer ``abil_id``. Mirrors
+    Memoria ``CsvParser.AnyAbility``. Raises ValueError on a malformed token."""
+    if isinstance(token, bool):
+        raise ValueError("ability cannot be a boolean")
+    if isinstance(token, int):
+        if token < 0:
+            raise ValueError(f"abil_id cannot be negative (got {token})")
+        return token
+    s = str(token).strip()
+    m = re.fullmatch(r"(AA|SA):(-?\d+)", s, re.IGNORECASE)
+    if m:
+        kind, x = m.group(1).upper(), int(m.group(2))
+        if x < 0:
+            raise ValueError(f"ability index cannot be negative in {token!r}")
+        if kind == "AA":
+            return (x // 192) * 256 + x % 192
+        return (x // 64) * 256 + x % 64 + 192
+    if re.fullmatch(r"\d+", s):
+        return int(s)
+    raise ValueError(f"not an ability token: {token!r} (expected AA:X, SA:X, or a numeric abil_id)")
+
+
+def is_token(ability) -> bool:
+    """True if ``ability`` is token-SHAPED -- an ``AA:``/``SA:``-prefixed string or a numeric id (NOT a NAME) --
+    so it can be validated WITHOUT the install's name pools: :func:`resolve` / :func:`encode_token` either decode
+    it or REJECT it with a clear error, offline. A real ability name never contains a colon, so an ``AA:``/``SA:``
+    prefix is unambiguously a token -- even a malformed one (``AA:nope``), which ``resolve`` then rejects (so a
+    typo'd token is caught by lint with no install, not silently skipped)."""
+    if isinstance(ability, bool):
+        return False
+    if isinstance(ability, int):
+        return True
+    s = str(ability).strip()
+    return bool(re.match(r"(?:AA|SA):", s, re.IGNORECASE)) or bool(re.fullmatch(r"\d+", s))
+
+
+# --- best-effort name + AP-requirement, read live from the install's pool CSVs ---------------------
+
+@dataclass(frozen=True)
+class Ability:
+    """One row of a character's learnable-ability pool CSV."""
+    index: int                                            # row position (== the old-format `pa` array index)
+    abil_id: int                                          # the global integer id stored in pa_extended
+    token: str                                            # "AA:X" / "SA:X"
+    kind: str                                             # "AA" | "SA"
+    ap_req: int                                           # AP needed to master (the row's 2nd column)
+    name: "str | None"                                    # the row's `# comment` name (None if absent)
+
+
+def _norm(s) -> str:
+    return "".join(c for c in str(s).lower() if c.isalnum())
+
+
+def pool_for_preset(menu_type: int, game=None) -> list:
+    """The ordered learnable-ability pool for a preset (``menu_type``), read live from
+    ``<install>/.../Abilities/<Preset>.csv`` and cached. ``[]`` if the install/file isn't reachable or the preset
+    has no pool (16+)."""
+    if menu_type is None:                                 # no preset known (e.g. a save missing info.menu_type)
+        return []                                         # -> no base pool; callers fall back to token/AP_CAP
+    if menu_type in _POOL_CACHE:
+        return _POOL_CACHE[menu_type] or []
+    name = PRESET_NAMES.get(int(menu_type))
+    if name is None:
+        _POOL_CACHE[menu_type] = False
+        return []
+    try:
+        from .config import find_game_path
+        p = find_game_path(game) / "StreamingAssets" / "Data" / "Characters" / "Abilities" / f"{name}.csv"
+        text = p.read_text(encoding="utf-8-sig", errors="replace")
+    except Exception:                                      # noqa: BLE001 -- install not reachable -> degrade
+        _POOL_CACHE[menu_type] = False
+        return []
+    out = []
+    for line in text.splitlines():
+        s = line.strip()
+        if not s or s.startswith("#"):
+            continue
+        parts = s.split(";")
+        if len(parts) < 2:
+            continue
+        try:
+            abil_id = encode_token(parts[0].strip())
+            ap_req = int(parts[1].strip())
+        except ValueError:
+            continue
+        m = _ROW_RE.search(s)
+        nm = m.group(1).strip() if m else None
+        out.append(Ability(index=len(out), abil_id=abil_id, token=decode_token(abil_id),
+                            kind=kind_of(abil_id), ap_req=ap_req, name=nm or None))
+    _POOL_CACHE[menu_type] = out or False
+    return out
+
+
+def _pool_index(menu_type: int, game=None) -> dict:
+    """``{abil_id: Ability}`` for a preset (last row wins on a dup id)."""
+    return {a.abil_id: a for a in pool_for_preset(menu_type, game)}
+
+
+def _global_names(game=None) -> dict:
+    """``{abil_id: name}`` unioned across every preset pool (for naming an id when the preset is unknown)."""
+    global _GLOBAL_NAMES
+    if _GLOBAL_NAMES is not None:
+        return _GLOBAL_NAMES
+    names: dict = {}
+    for mt in PRESET_NAMES:
+        for a in pool_for_preset(mt, game):
+            if a.name and a.abil_id not in names:
+                names[a.abil_id] = a.name
+    _GLOBAL_NAMES = names
+    return names
+
+
+def name_of(abil_id: int, menu_type=None, game=None) -> "str | None":
+    """The display name for an ``abil_id`` -- from the given preset's pool if ``menu_type`` is set, else from the
+    global union. ``None`` if unknown (a modded id not in the base pools, or the install isn't reachable)."""
+    if menu_type is not None:
+        a = _pool_index(menu_type, game).get(int(abil_id))
+        if a is not None and a.name:
+            return a.name
+    return _global_names(game).get(int(abil_id))
+
+
+def ap_required(menu_type, abil_id: int, game=None) -> "int | None":
+    """The AP needed to master ``abil_id`` for a preset, or ``None`` if that id isn't in the (base) pool."""
+    a = _pool_index(menu_type, game).get(int(abil_id))
+    return a.ap_req if a is not None else None
+
+
+def resolve(menu_type, ability, game=None) -> int:
+    """An ability NAME / ``AA:X`` / ``SA:X`` / numeric id -> the integer ``abil_id``. A token / id is decoded
+    directly (mod-agnostic, no install needed). A NAME is matched case/space/punct-insensitively against the
+    preset's pool first, then the global union. Raises ValueError on an unknown name."""
+    if isinstance(ability, bool):
+        raise ValueError("ability cannot be a boolean")
+    if isinstance(ability, int):
+        return encode_token(ability)
+    s = str(ability).strip()
+    if re.match(r"(?:AA|SA):", s, re.IGNORECASE) or re.fullmatch(r"\d+", s):
+        return encode_token(s)                             # token-SHAPED -> decode, or raise a clear token error
+    key = _norm(s)
+    if menu_type is not None:
+        for a in pool_for_preset(menu_type, game):
+            if a.name and _norm(a.name) == key:
+                return a.abil_id
+    for aid, nm in _global_names(game).items():           # then any character's pool
+        if _norm(nm) == key:
+            return aid
+    raise ValueError(f"unknown ability {ability!r} (use an AA:X / SA:X token or a numeric id, or run "
+                     "`ff9mapkit items --abilities` to list names)")
+
+
+def available(game=None) -> bool:
+    """True if at least one preset pool CSV could be read (so ability NAMES/AP are live)."""
+    return any(pool_for_preset(mt, game) for mt in (0, 1, 2))
+
+
+def _reset_cache():                                       # for tests
+    global _GLOBAL_NAMES
+    _POOL_CACHE.clear()
+    _GLOBAL_NAMES = None

ff9mapkit/animations.py

@@ -0,0 +1,120 @@
+"""Author-facing character animation catalog for cutscenes.
+
+Pick a gesture by NAME -- ``animation = "glad"`` -- instead of hunting a numeric id. Backed by
+:mod:`ff9mapkit._animdb` (FF9 anim id <-> name, from Memoria's open-source ``AnimationDB``). An anim
+name encodes its model + action: ``ANH_MAIN_F0_VIV_TALK_3_1`` -> character ``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 -- proven
+in-game with Vivi 7302 (= ``TALK_3_1``).
+
+Usage::
+
+    from ff9mapkit import animations
+    animations.resolve("vivi", "glad")        # -> 1234  (action by name on Vivi's model)
+    animations.resolve("vivi", "idle")        # -> 148   (a universal CORE gesture)
+    animations.resolve("vivi", 7302)          # -> 7302  (a raw id passes through)
+    animations.actions("vivi")                # -> [("angry", 111), ("angry_2", ...), ...]
+
+Only the 8 playable characters are covered (the cutscene presets); see ``_animdb``.
+"""
+
+from __future__ import annotations
+
+import difflib
+
+from ._animdb import MAIN_ANIMATIONS
+
+# preset / friendly name -> the character's anim-name TOKEN.
+TOKENS = {
+    "vivi": "VIV", "zidane": "ZDN",
+    "garnet": "GRN", "dagger": "GRN", "princess": "GRN",
+    "steiner": "STN", "freya": "FRJ", "quina": "KUI", "eiko": "EIK",
+    "amarant": "SLM", "salamander": "SLM",
+}
+_VALID_TOKENS = set(TOKENS.values())
+
+# Universal gestures that exist for every playable character (friendly alias -> action label). These
+# are the standard field-movement clips the engine itself uses; safe on any main-character model.
+CORE = {
+    "idle": "IDLE", "stand": "IDLE",
+    "walk": "WALK", "run": "RUN",
+    "turn_left": "TURN_L", "turn_l": "TURN_L",
+    "turn_right": "TURN_R", "turn_r": "TURN_R",
+}
+
+
+def _token(model) -> str:
+    """Normalize a preset name / friendly name / raw token to a character TOKEN (e.g. 'VIV')."""
+    if model is None:
+        raise ValueError("no character given -- pass a preset like 'vivi' or a token like 'VIV'")
+    key = str(model).strip()
+    if key.upper() in _VALID_TOKENS:
+        return key.upper()
+    if key.lower() in TOKENS:
+        return TOKENS[key.lower()]
+    raise ValueError(f"unknown character {model!r}; known: "
+                     f"{', '.join(sorted(set(TOKENS) | {t.lower() for t in _VALID_TOKENS}))}")
+
+
+def _split(name: str):
+    """(form_number, token, action_label_lower) for an anim name, or None if it isn't a MAIN anim."""
+    p = name.split("_")                       # ANH MAIN F0 VIV TALK 3 1
+    if len(p) < 5 or p[0] != "ANH" or p[1] != "MAIN":
+        return None
+    form = int(p[2][1:]) if p[2][:1] == "F" and p[2][1:].isdigit() else 99
+    return form, p[3], "_".join(p[4:]).lower()
+
+
+def catalog(model) -> dict:
+    """``{action_label: anim_id}`` for one character, preferring the canonical F0 form when an action
+    appears in more than one form (F0 is the field model)."""
+    token = _token(model)
+    best = {}                                  # action -> (form_number, id)
+    for anim_id, name in MAIN_ANIMATIONS.items():
+        s = _split(name)
+        if not s or s[1] != token:
+            continue
+        form, _, action = s
+        if action not in best or form < best[action][0]:
+            best[action] = (form, anim_id)
+    return {action: aid for action, (form, aid) in best.items()}
+
+
+def actions(model) -> list:
+    """Sorted ``[(action_label, anim_id), ...]`` for a character (for display / the CLI)."""
+    return sorted(catalog(model).items())
+
+
+def resolve(model, action) -> int:
+    """Resolve an ``animation`` value to a numeric anim id. ``action`` may be:
+      * an int (or digit string) -> passed through unchanged (a raw id, even if not in the catalog);
+      * a CORE alias ('idle' / 'walk' / 'run' / 'turn_left' / 'turn_right');
+      * an action label from this character's catalog (case-insensitive, '-'/space -> '_').
+    Raises ValueError (with near-miss suggestions) on an unknown name."""
+    if isinstance(action, bool):
+        raise ValueError("animation cannot be a boolean")
+    if isinstance(action, int):
+        return action
+    s = str(action).strip()
+    if s.isdigit():
+        return int(s)
+    key = s.lower().replace("-", "_").replace(" ", "_")
+    if key in CORE:
+        key = CORE[key].lower()
+    cat = catalog(model)
+    if key in cat:
+        return cat[key]
+    hints = difflib.get_close_matches(key, cat, n=6, cutoff=0.4)
+    extra = f" Did you mean: {', '.join(hints)}?" if hints else \
+        f" Run `ff9mapkit animations {model}` to list gestures."
+    raise ValueError(f"unknown animation {action!r} for {model!r}.{extra}")
+
+
+def name_of(anim_id: int):
+    """The full anim name for an id (e.g. 7302 -> 'ANH_MAIN_F0_VIV_TALK_3_1'), or None."""
+    return MAIN_ANIMATIONS.get(int(anim_id))
+
+
+def characters() -> list:
+    """The preset/friendly character names that have a catalog (for the CLI / docs)."""
+    return sorted(TOKENS)

ff9mapkit/archetypes.py

@@ -0,0 +1,218 @@
+"""Named NPC archetypes -- the Info Hub's "place a common NPC with one word".
+
+A thin curated layer over the model->animation auto-resolution (:func:`catalog.npc_anims`): a friendly
+name (``"garnet"``, ``"black_mage"``, ``"moogle"``) maps to a model whose gestures auto-resolve. Use it
+as ``[[npc]] archetype = "garnet"`` (``preset`` is an accepted alias). For anything not curated here,
+name the model directly: ``[[npc]] model = "GEO_NPC_F0_BAR"`` (browse with ``ff9mapkit models``).
+
+Provenance-clean: only references Memoria model IDENTIFIERS (GEO names), never game bytes. The curated
+set is intentionally small + high-confidence (the playable cast, plus NPC types confirmed in-game) and
+grows as more models are identified -- a wrong name is worse than none.
+"""
+from __future__ import annotations
+
+from . import catalog as _catalog
+from .content.npc import PRESETS as _CHAR_PRESETS   # vivi / zidane: explicit anims, byte-golden
+
+# friendly name -> a curated spec. ``model`` is a GEO name (resolved via the catalog); the model's
+# gestures auto-resolve unless ``anims`` is given; ``animset`` (head height) + ``dialogue`` (a default
+# line) are optional. vivi/zidane are NOT here -- they come from _CHAR_PRESETS (explicit, byte-golden).
+ARCHETYPES: dict = {
+    # -- the playable cast: place any party member as a field NPC --
+    "garnet": {"model": "GEO_MAIN_F0_GRN"},
+    "dagger": {"model": "GEO_MAIN_F0_GRN"},        # alias for garnet
+    "steiner": {"model": "GEO_MAIN_F0_STN"},
+    "freya": {"model": "GEO_MAIN_F0_FRJ"},
+    "quina": {"model": "GEO_MAIN_F0_KUI"},
+    "eiko": {"model": "GEO_MAIN_F0_EIK"},
+    "amarant": {"model": "GEO_MAIN_F0_SLM"},
+    # -- main-character alt-forms (a specific scripted version of a hero) --
+    "zidane_npc": {"model": "GEO_MAIN_F0_ZDN"},          # ZDN -- Zidane's own field model placed as an NPC (vs "zidane" = the cloned player)
+    "steiner_carrying_dagger": {"model": "GEO_MAIN_F0_STD"},  # STD -- "STeiner + Dagger": Steiner carrying Princess Garnet (Evil Forest)
+    "zidane_carrying_dagger": {"model": "GEO_MAIN_F0_ZDD"},   # ZDD -- "ZiDane + Dagger": Zidane carrying Princess Garnet
+    # -- common NPC types (grow this as models are confirmed in-game) --
+    "black_mage": {"model": "GEO_NPC_F0_BMG"},     # verified in-game
+    "moogle": {"model": "GEO_NPC_F0_MOG"},         # the FF moogle code
+    # -- identified via the in-game gallery (token -> what the model actually is) --
+    "townswoman": {"model": "GEO_NPC_F0_APF"},       # APF "Adult Person Female"
+    "woman": {"model": "GEO_NPC_F0_APF"},            # alias of townswoman
+    "townsman": {"model": "GEO_NPC_F0_APM"},         # APM "Adult Person Male"
+    "man": {"model": "GEO_NPC_F0_APM"},              # alias of townsman
+    "bartender": {"model": "GEO_NPC_F0_BAR"},        # BAR
+    "old_woman": {"model": "GEO_NPC_F0_BBA"},        # BBA (JP "baba" = granny)
+    "granny": {"model": "GEO_NPC_F0_BBA"},           # alias of old_woman
+    "oglop": {"model": "GEO_NPC_F0_BRI"},            # BRI (JP "burimushi" = the Oglop bug)
+    "burmecian_child": {"model": "GEO_NPC_F0_BUC"},  # BUC
+    "burmecian_woman": {"model": "GEO_NPC_F0_BUF"},  # BUF
+    "cat": {"model": "GEO_NPC_F0_CAT"},              # CAT
+    "bird": {"model": "GEO_NPC_F0_CCB"},             # CCB (pigeon-ish)
+    "chocobo_child": {"model": "GEO_NPC_F0_CHC"},    # CHC (tentative -- a Black Mage Vil. chocobo)
+    "fat_chocobo": {"model": "GEO_NPC_F0_CHD"},      # CHD (JP "Choco Debu")
+    "chocobo": {"model": "GEO_NPC_F0_CHO"},          # CHO (the common field chocobo)
+    "high_priest": {"model": "GEO_NPC_F0_CLD"},      # CLD (Cleyra Cathedral, JP "Daikanshu")
+    "cleyran_woman": {"model": "GEO_NPC_F0_CLM"},    # CLM
+    "cook": {"model": "GEO_NPC_F0_COK"},             # COK
+    "engineer": {"model": "GEO_NPC_F0_CSA"},         # CSA (Lindblum engineer, e.g. Zebolt)
+    "zebolt": {"model": "GEO_NPC_F0_CSA"},           # alias (the named Lindblum engineer)
+    "lindblum_man": {"model": "GEO_NPC_F0_CSM"},     # CSM
+    "guard": {"model": "GEO_NPC_F0_CSO"},            # CSO (armed Lindblum guard/soldier)
+    "soldier": {"model": "GEO_NPC_F0_CSO"},          # alias of guard
+    "dali_boy": {"model": "GEO_NPC_F0_DAC"},         # DAC (Dali male child)
+    "dali_girl": {"model": "GEO_NPC_F0_DAF"},        # DAF (Dali female child)
+    "dali_man": {"model": "GEO_NPC_F0_DAL"},         # DAL (Dali male citizen)
+    "dali_woman": {"model": "GEO_NPC_F0_DAW"},       # DAW (Dali female citizen/worker)
+    "dwarf": {"model": "GEO_NPC_F0_DOC"},            # DOC (Conde Petie -- "Rally-ho!")
+    "dwarf_woman": {"model": "GEO_NPC_F0_DOF"},      # DOF
+    "dog": {"model": "GEO_NPC_F0_DOG"},              # DOG (a literal dog)
+    "dwarf_priest": {"model": "GEO_NPC_F0_DOK"},     # DOK (JP "Okashira" = chief/leader)
+    "dwarf_man": {"model": "GEO_NPC_F0_DOM"},        # DOM
+    "sand_oracle": {"model": "GEO_NPC_F0_FLS"},      # FLS (Cleyra's priestesses)
+    "frog": {"model": "GEO_NPC_F0_FRM"},             # FRM (the catchable marsh frog)
+    "burmecian_king": {"model": "GEO_NPC_F0_FUK"},   # FUK (dev humor: FUkkatsu = "Revival/Ruined" King)
+    "noble": {"model": "GEO_NPC_F0_G16"},            # G16 (G = Gentleman; Treno/Lindblum noble)
+    "gentleman": {"model": "GEO_NPC_F0_G16"},        # alias of noble
+    "noblewoman": {"model": "GEO_NPC_F0_G17"},       # G17 (female noble)
+    "noble_man": {"model": "GEO_NPC_F0_G18"},        # G18 (another male-noble variant)
+    "queen_stella": {"model": "GEO_NPC_F0_G19"},     # G19 (the Treno noble Queen Stella)
+    "stella": {"model": "GEO_NPC_F0_G19"},           # alias of queen_stella
+    "aristocrat": {"model": "GEO_NPC_F0_G20"},       # G20 (another male-noble variant)
+    "tour_guide": {"model": "GEO_NPC_F0_GUD"},       # GUD (Alexandria tour guide)
+    "commoner": {"model": "GEO_NPC_F0_HEK"},         # HEK (JP "Heikin" = average/commoner)
+    "bandit": {"model": "GEO_NPC_F0_HTH"},           # HTH (JP "Heikin Thief")
+    "thief": {"model": "GEO_NPC_F0_HTH"},            # alias of bandit
+    "fan_club_member": {"model": "GEO_NPC_F0_HUF"},  # HUF (Lowell's fan club, a woman)
+    "human_male": {"model": "GEO_NPC_F0_HUM"},       # HUM (a generic adult man)
+    "old_man": {"model": "GEO_NPC_F0_JJY"},          # JJY (JP "jijii" = old man)
+    "grandpa": {"model": "GEO_NPC_F0_JJY"},          # alias of old_man
+    "alexandria_child": {"model": "GEO_NPC_F0_KAC"}, # KAC (Alexandria kid, e.g. Hippaul)
+    "hippaul": {"model": "GEO_NPC_F0_KAC"},          # alias (the named Alexandria boy)
+    "bishop": {"model": "GEO_NPC_F0_NAN"},           # NAN (Esto Gaza altar)
+    "alexandria_soldier": {"model": "GEO_NPC_F0_OFF"},  # OFF (Alexandria's female soldiers)
+    "auctioneer": {"model": "GEO_NPC_F0_ORC"},       # ORC (Treno Auction House)
+    "scholar": {"model": "GEO_NPC_F0_OSC"},          # OSC (A. Castle Library)
+    "burmecian_soldier": {"model": "GEO_NPC_F0_RAS"},  # RAS (Gizamaluke bell guards)
+    "red_mage_woman": {"model": "GEO_NPC_F0_RMF"},   # RMF (Red Mage, Female)
+    "red_mage_man": {"model": "GEO_NPC_F0_RMM"},     # RMM (Red Mage, Male)
+    "red_mage": {"model": "GEO_NPC_F0_RMM"},         # alias of red_mage_man
+    "puck": {"model": "GEO_NPC_F0_RTC"},             # RTC ("Rat Child" -- the Burmecian boy-thief Zidane befriends)
+    "lowell": {"model": "GEO_NPC_F0_STR"},           # STR ("star" -- the famous actor; HUF = his fan club)
+    "theater_star": {"model": "GEO_NPC_F0_STR"},     # alias of lowell
+    "tadpole": {"model": "GEO_NPC_F0_TAD"},          # TAD (Qu's Marsh)
+    "little_boy": {"model": "GEO_NPC_F0_TBY"},       # TBY ("Tag Boy" -- Alexandria kid, plays tag with TGR)
+    "boy": {"model": "GEO_NPC_F0_TBY"},              # alias of little_boy
+    "ticket_master": {"model": "GEO_NPC_F0_TCK"},    # TCK ("ticket" -- Alexandria play ticketmaster)
+    "ticketmaster": {"model": "GEO_NPC_F0_TCK"},     # alias of ticket_master
+    "little_girl": {"model": "GEO_NPC_F0_TGR"},      # TGR ("Tag Girl" -- Alexandria kid, chases TBY)
+    "girl": {"model": "GEO_NPC_F0_TGR"},             # alias of little_girl
+    "conductor": {"model": "GEO_NPC_F0_BND"},        # BND ("band" -- the Prima Vista's conductor)
+    "band_member": {"model": "GEO_NPC_F0_BND"},      # alias of conductor (a Tantalus musician)
+    "alexandria_woman": {"model": "GEO_NPC_F0_TMF"}, # TMF (an Alexandria townswoman -- e.g. Hippaul's mother)
+    "hippauls_mom": {"model": "GEO_NPC_F0_TMF"},     # alias (the named Alexandria mother)
+    "innkeeper": {"model": "GEO_NPC_F0_TMM"},        # TMM (Alexandria townsman / the inn keeper, "Fish Man")
+    "fish_man": {"model": "GEO_NPC_F0_TMM"},         # alias of innkeeper (the named Alexandria man)
+    "servant": {"model": "GEO_NPC_F0_TRF"},          # TRF (a noble's servant -- e.g. Queen Stella's, in Treno)
+    "stellas_servant": {"model": "GEO_NPC_F0_TRF"},  # alias of servant
+    "worker": {"model": "GEO_NPC_F0_WRK"},           # WRK ("worker" -- a laborer, e.g. Dante the Alexandria signmaker)
+    "signmaker": {"model": "GEO_NPC_F0_WRK"},        # alias of worker
+    "dante": {"model": "GEO_NPC_F0_WRK"},            # alias (the named Alexandria signmaker)
+    # -- SUB group: the named story cast (a unique character; same model->anim auto-resolve as an NPC) --
+    "hilda": {"model": "GEO_SUB_F0_CDW"},            # CDW -- Cid's Wife (Hilda); seen kidnapped, Lindblum Castle
+    "quale": {"model": "GEO_SUB_F0_KUT"},            # KUT -- Quina's master, in Qu's Marsh (KU = Qu Tribe romaji ク族 + T = Teacher/Top = Master)
+    "qu_master": {"model": "GEO_SUB_F0_KUT"},        # alias of quale
+    "quan": {"model": "GEO_SUB_F0_KUW"},             # KUW -- Vivi's grandfather, Quan's Dwelling (KU = Qu Tribe + W = elder/grandpa suffix, JP おじいさん)
+    "garnets_mother": {"model": "GEO_SUB_F0_MOM"},   # MOM ("mother") -- the woman in Garnet's Memoria recollection (likely her birth mother; user: "Jane"). TENTATIVE
+    "genome": {"model": "GEO_SUB_F0_NTC"},           # NTC -- a genome; the roaming Terra one (normal stand/walk, best as a general placeable)
+    "genome_2": {"model": "GEO_SUB_F0_NTA"},         # NTA -- a Bran Bal genome (distinct idle posture; some are seated)
+    "genome_3": {"model": "GEO_SUB_F0_NTB"},         # NTB -- a Bran Bal genome (distinct idle posture)
+    "genome_4": {"model": "GEO_SUB_F0_NTD"},         # NTD -- a Bran Bal genome (distinct idle posture)
+    # Tantalus -- the theater-troupe thieves (all aboard the Prima Vista)
+    "baku": {"model": "GEO_SUB_F0_BAK"},             # BAK -- Tantalus' boss
+    "blank": {"model": "GEO_SUB_F0_BLN"},            # BLN -- Tantalus thief (Zidane's friend)
+    "marcus": {"model": "GEO_SUB_F0_MRC"},           # MRC -- Tantalus thief
+    "cinna": {"model": "GEO_SUB_F0_CNA"},            # CNA -- Tantalus thief (the hammer)
+    "ruby": {"model": "GEO_SUB_F0_RBY"},             # RBY -- Tantalus' actress
+    "zenero": {"model": "GEO_SUB_F0_ZNR"},           # ZNR -- a Tantalus "Nero family" member (ZNR ~ Zenero); tentative
+    # Alexandria royalty / antagonists
+    "brahne": {"model": "GEO_SUB_F0_BRN"},           # BRN -- Queen Brahne of Alexandria
+    "queen_brahne": {"model": "GEO_SUB_F0_BRN"},     # alias of brahne
+    "beatrix": {"model": "GEO_SUB_F0_BTX"},          # BTX -- General Beatrix of Alexandria
+    "kuja": {"model": "GEO_SUB_F0_KJA"},             # KJA -- the antagonist
+    "zorn": {"model": "GEO_SUB_F0_ZON"},             # ZON -- Brahne's jester (paired with Thorn)
+    "lani": {"model": "GEO_SUB_F0_SBW"},             # SBW -- "Scarlet Bounty Woman": Lani, the bounty hunter
+    "pluto_knight": {"model": "GEO_SUB_F0_SSB"},     # SSB -- "Soldier Steiner Base": a male Alexandrian soldier / Knight of Pluto (e.g. Haagen, Weimar)
+    # other named figures
+    "garland": {"model": "GEO_SUB_F0_GRL"},          # GRL -- Garland of Terra (its field is literally "Invincible/Garland")
+    "cid": {"model": "GEO_SUB_F0_CID"},              # CID -- Regent Cid Fabool IX of Lindblum
+    "regent_cid": {"model": "GEO_SUB_F0_CID"},       # alias of cid
+    "fratley": {"model": "GEO_SUB_F0_FLT"},          # FLT -- Sir Fratley, Burmecian Dragon Knight (Freya's lost love); JP フラットレイ "Furattorei"
+    "doctor_tot": {"model": "GEO_SUB_F0_TOT"},       # TOT -- Doctor Tot, the Treno scholar ("Tot Residence")
+    "tot": {"model": "GEO_SUB_F0_TOT"},              # alias of doctor_tot
+    # Black Waltzes -- Brahne's hunter-mages (No. 2 + Trance Kuja are special boss models with no
+    # standard idle/walk anim, so they're intentionally not archetypes -- place by model id if needed)
+    "black_waltz_1": {"model": "GEO_SUB_F0_BW1"},    # BW1 -- Black Waltz No. 1 (Ice Cavern)
+    "black_waltz_3": {"model": "GEO_SUB_F0_BW3"},    # BW3 -- Black Waltz No. 3 (Cargo Ship)
+}
+
+
+# --- CREATURES (GEO_MON): place a battle monster as a field object by name. The kit's field-RENDERABLE
+# GEO_MON set -- verified in-game via the arena gallery (they render + animate as field objects). Most also
+# appear in shipping field scripts; a few are battle bosses the kit can still place. Identified in-game via
+# the gallery (`tools/build_archetype_gallery.py --arena --group MON`). Names are the canonical FF9 bestiary
+# names; the token decode (where known) is in the comment.
+CREATURES: dict = {
+    "armodullahan": {"model": "GEO_MON_F0_AMD"},  # AMD -- the Fossil Roo boss (headless armored rider)
+    "amdusias": {"model": "GEO_MON_F0_AMS"},      # AMS -- Treno weapon-shop duel + Pandemonium enemy
+    "bandersnatch": {"model": "GEO_MON_F0_BAN"},  # BAN -- Queen Brahne's hunting hounds (Alexandria)
+    "zaghnol": {"model": "GEO_MON_F0_BFF"},       # BFF "Beast Festival Foe" -- the Festival of the Hunt boar
+    "red_dragon": {"model": "GEO_MON_F0_CDR"},    # CDR "Chocobo Dragon" -- Mount Gulug boss; reuses the chocobo quadruped rig (the dev trick for many large quadrupeds)
+    "antlion": {"model": "GEO_MON_F0_CLB"},       # CLB "CLeyra Boss" -- the Cleyra sandpit Antlion
+    "taharka": {"model": "GEO_MON_F0_DAH"},       # DAH -- Ipsen's Castle boss; JP ダハカ "Dahaka", localized to Taharka
+    "dahaka": {"model": "GEO_MON_F0_DAH"},        # alias of taharka (the JP name + the DAH token origin)
+    "lich": {"model": "GEO_MON_F0_EEE"},          # EEE -- Lich, the Earth Shrine boss (the Earth elemental fiend; "EEE" = Earth)
+    "prison_cage": {"model": "GEO_MON_F0_EFM"},   # EFM "Evil Forest Monster" -- the Evil Forest miniboss (cage-plant that captures Garnet)
+    "fang": {"model": "GEO_MON_F0_FFG"},          # FFG -- a Fang (dog-like monster), seen all over Lindblum
+    "griffin": {"model": "GEO_MON_F0_GRI"},       # GRI -- Griffin (the Treno Weapon Shop fight)
+    "hedgehog_pie": {"model": "GEO_MON_F0_HHP"},  # HHP -- Hedgehog Pie (the palace hedgehog)
+    "catoblepas": {"model": "GEO_MON_F0_KAT"},    # KAT -- Catoblepas (phonetic: KAToblepas カトブレパス)
+    "mistodon": {"model": "GEO_MON_F0_MKM"},      # MKM "Mist Kaiju Monster" -- the disc-4 Mistodon (swarms Alexandria)
+    "behemoth": {"model": "GEO_MON_F0_MOS"},      # MOS "Monster of Shop" -- Behemoth (the Treno Weapon Shop fight)
+    "mu": {"model": "GEO_MON_F0_MUU"},            # MUU -- Mu (blue cat/fox; Festival of the Hunt); "Mu" padded to 3 letters
+    "ramuh": {"model": "GEO_MON_F0_RAM"},         # RAM -- Ramuh, the Thunder eidolon (Pinnacle Rocks cutscene)
+    "silver_dragon": {"model": "GEO_MON_F0_SDR"}, # SDR "Silver Dragon (Rideable)" -- Kuja's mountable dragon (Iifa Tree)
+    "trick_bird": {"model": "GEO_MON_F0_TBL"},    # TBL "Trick Bird, Lindblum" -- the Lindblum ambient bird
+    "ralvuimago": {"model": "GEO_MON_F0_TOM"},    # TOM "(Tail) Orochi Monster" (Orochi 大蛇 = giant legendary serpent) -- the Gargan Roo snake boss
+    "soulcage": {"model": "GEO_MON_F0_ZZZ"},      # ZZZ "Zonbi Zetsubou Zree" (ゾンビ絶望ツリー = Zombie Despair Tree) -- the Iifa Tree undead boss
+}
+
+
+def names() -> list:
+    """Every archetype name (playable presets + curated NPC types + creatures), sorted."""
+    return sorted(set(_CHAR_PRESETS) | set(ARCHETYPES) | set(CREATURES))
+
+
+def is_archetype(name) -> bool:
+    """True if ``name`` is a known archetype (case-insensitive)."""
+    key = str(name).strip().lower()
+    return key in _CHAR_PRESETS or key in ARCHETYPES or key in CREATURES
+
+
+def resolve(name):
+    """``(model_id|None, animset|None, anims|None, default_dialogue|None)`` for an archetype name.
+
+    ``vivi``/``zidane`` resolve to their byte-golden character preset (explicit anims; zidane keeps the
+    cloned player's model). Every other archetype resolves its model (GEO name -> id) and auto-resolves
+    the model's gestures via :func:`catalog.npc_anims`. Raises ValueError (listing the known names) on an
+    unknown one. Feeding this to ``inject_npc(model=, animset=, anims=)`` reproduces the old
+    ``inject_npc(preset="vivi")`` byte-for-byte, so existing builds are unaffected.
+    """
+    key = str(name).strip().lower()
+    if key in _CHAR_PRESETS:
+        model, animset, anims = _CHAR_PRESETS[key]
+        return model, animset, anims, None
+    spec = ARCHETYPES.get(key) or CREATURES.get(key)
+    if spec is not None:
+        model = _catalog.resolve_model(spec["model"])
+        anims = spec.get("anims") or _catalog.npc_anims(model) or None
+        return model, spec.get("animset"), anims, spec.get("dialogue")
+    raise ValueError(f"unknown archetype {name!r}. Known: {', '.join(names())}. "
+                     f"Or name a model directly with model = \"GEO_...\" (see `ff9mapkit models`).")

ff9mapkit/areatitle.py

@@ -0,0 +1,76 @@
+"""The FF9 area-title overlay manifest -- WHICH scene overlays carry a field's localized "area title"
+card (the big "Ice Cavern" / "Mognet Central" lettering shown on entry).
+
+Engine background: the title is NOT a UI banner and NOT a passive engine fade -- it is a range of scene
+OVERLAYS, listed per-field in the TextAsset ``mapLocalizeAreaTitle.txt`` (columns:
+``mapName, atlasW, atlasH, startOvrIdx, endOvrIdx, hasUK, ...``). The engine only re-textures that range
+from ``atlas_<lang>`` for the 38 fields in ``FieldMap.fieldMapNameWithAreaTitle`` -- it never shows, hides
+or fades them; the DONOR field's own ``.eb`` scripts the show+fade (scenario-gated). A fork / BG-borrow
+that doesn't carry that script leaves the overlays in their default (active) state, so the title sits there
+statically. :mod:`ff9mapkit.content.areatitle` uses these indices to script the lifecycle ourselves.
+
+Offline: reads ``x64/FF9_Data/resources.assets`` via UnityPy (a DIFFERENT source than the kit's usual
+``p0data*.bin`` -- the manifest lives in the main Unity build, not the field bundles). Degrades to ``{}``
+/ ``None`` if UnityPy or the file is absent, so callers no-op cleanly. Provenance-clean: ships nothing,
+reads the user's own install at author time.
+"""
+
+from __future__ import annotations
+
+import functools
+
+from . import config, extract
+
+MANIFEST_NAME = "mapLocalizeAreaTitle"      # the TextAsset's m_Name (matched with/without a .txt suffix)
+
+
+@functools.lru_cache(maxsize=4)
+def _manifest(game_key: str | None = None) -> dict:
+    """``{donor_fbg: (startOvrIdx, endOvrIdx)}`` parsed from resources.assets; ``{}`` if unavailable."""
+    try:
+        UnityPy = extract._unitypy()
+    except Exception:
+        return {}
+    game = config.find_game_path(game_key)
+    if game is None:
+        return {}
+    candidates = [game / "x64" / "FF9_Data" / "resources.assets",
+                  game / "FF9_Data" / "resources.assets",
+                  game / "x86" / "FF9_Data" / "resources.assets"]
+    for res in candidates:
+        if not res.exists():
+            continue
+        try:
+            env = UnityPy.load(str(res))
+        except Exception:
+            continue
+        for obj in env.objects:
+            if obj.type.name != "TextAsset":
+                continue
+            try:
+                data = obj.read()
+            except Exception:
+                continue
+            name = str(getattr(data, "m_Name", None) or getattr(data, "name", ""))
+            if name.rsplit(".", 1)[0] != MANIFEST_NAME:    # m_Name is "mapLocalizeAreaTitle.txt"
+                continue
+            raw = extract._raw_bytes(data)
+            txt = raw.decode("utf-8", "replace") if isinstance(raw, (bytes, bytearray)) else str(raw)
+            out: dict = {}
+            for line in txt.splitlines():
+                cols = [c.strip() for c in line.split(",")]
+                if len(cols) >= 5 and cols[0]:
+                    try:
+                        out[cols[0]] = (int(cols[3]), int(cols[4]))
+                    except ValueError:
+                        continue           # header / malformed row
+            return out
+    return {}
+
+
+def title_range(donor_fbg: str, game=None) -> "tuple[int, int] | None":
+    """The ``(startOvrIdx, endOvrIdx)`` scene-overlay range carrying ``donor_fbg``'s area title, or
+    ``None`` if the field has no area title (the vast majority -- 636 of 674). ``donor_fbg`` is the real
+    field's full FBG name, e.g. ``"FBG_N05_ICCV_MAP085_IC_ENT_0"``."""
+    key = str(game) if game is not None else None
+    return _manifest(key).get(donor_fbg)