ff9mapkit 1.0.0b3__py3-none-any.whl

ff9mapkit/config.py

@@ -0,0 +1,360 @@
+"""Path resolution + the FF9/Memoria mod-folder layout.
+
+This module is the single place that knows where things live on disk, replacing the
+absolute paths hardcoded into a dozen of the original bespoke scripts. Game-path
+resolution is, in priority order:
+
+    1. an explicit path passed in code / via the CLI ``--game`` flag
+    2. the ``FF9_GAME_PATH`` environment variable
+    3. a ``game_path`` key in the user config file ``~/.ff9mapkit.toml``
+    4. a small list of common Steam install locations (best-effort fallback)
+
+Nothing here touches the game install; these are pure path computations. A ``ModLayout``
+wraps a *mod root* (e.g. ``<game>/FF9CustomMap``) and yields the canonical sub-paths the
+builder writes to. The same layout works whether the mod root is the live game folder or
+a scratch/staging directory — that decoupling is what lets the builder be validated
+offline (build into a temp dir, diff against the deployed assets).
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+try:
+    import tomllib  # Python 3.11+
+except ModuleNotFoundError:  # pragma: no cover - we require 3.11 but fail soft
+    tomllib = None  # type: ignore[assignment]
+
+# The seven shipped language folders. Field event scripts (.eb) and dialogue (.mes) are
+# stored per-language; in practice the bytecode is identical across all seven and only the
+# text differs, but we always write all seven so no locale loses the field.
+LANGS: tuple[str, ...] = ("us", "uk", "fr", "gr", "it", "es", "jp")
+
+# The mod folder Memoria reads first (highest override priority) on this project's install.
+DEFAULT_MOD_FOLDER = "FF9CustomMap"
+
+# User config file (TOML) — optional convenience so users set their game path once.
+USER_CONFIG = Path.home() / ".ff9mapkit.toml"
+
+# Best-effort fallbacks for a Steam install (Windows). Only used if nothing else resolves.
+_COMMON_STEAM_PATHS = (
+    r"C:\Program Files (x86)\Steam\steamapps\common\FINAL FANTASY IX",
+    r"C:\Program Files\Steam\steamapps\common\FINAL FANTASY IX",
+    r"D:\SteamLibrary\steamapps\common\FINAL FANTASY IX",
+)
+
+
+class ConfigError(RuntimeError):
+    """Raised when a required path cannot be resolved or does not exist."""
+
+
+def _read_user_config() -> dict:
+    if tomllib is None or not USER_CONFIG.is_file():
+        return {}
+    try:
+        with USER_CONFIG.open("rb") as fh:
+            return tomllib.load(fh)
+    except (OSError, ValueError):
+        return {}
+
+
+def find_game_path(explicit: str | os.PathLike | None = None) -> Path:
+    """Resolve the Final Fantasy IX install folder.
+
+    Order: explicit arg > $FF9_GAME_PATH > ~/.ff9mapkit.toml(game_path) > common Steam dirs.
+    Raises ConfigError with actionable guidance if none of them point at a real folder.
+    """
+    candidates: list[Path] = []
+    if explicit:
+        candidates.append(Path(explicit))
+    env = os.environ.get("FF9_GAME_PATH")
+    if env:
+        candidates.append(Path(env))
+    cfg = _read_user_config().get("game_path")
+    if cfg:
+        candidates.append(Path(cfg))
+    candidates.extend(Path(p) for p in _COMMON_STEAM_PATHS)
+
+    for c in candidates:
+        if c.is_dir():
+            return c.resolve()
+
+    raise ConfigError(
+        "Could not locate the Final Fantasy IX install folder.\n"
+        "Set it one of these ways:\n"
+        "  - pass --game \"<path>\" on the command line\n"
+        "  - export FF9_GAME_PATH=\"<path>\"\n"
+        f"  - add  game_path = \"<path>\"  to {USER_CONFIG}\n"
+        "The folder should contain FF9_Launcher.exe and a StreamingAssets directory."
+    )
+
+
+def find_mod_root(game_path: Path, mod_folder: str = DEFAULT_MOD_FOLDER) -> Path:
+    """The mod root inside the game install (created by the builder if absent)."""
+    return (game_path / mod_folder).resolve()
+
+
+@dataclass(frozen=True)
+class ModLayout:
+    """Canonical sub-paths within a Memoria mod root.
+
+    `root` may be the live ``<game>/FF9CustomMap`` or any staging directory. All methods are
+    pure path joins (they neither read nor create anything) except ``ensure_dirs``.
+    """
+
+    root: Path
+
+    # --- top-level registration files Memoria reads from the mod root ---
+    @property
+    def dictionary_patch(self) -> Path:
+        return self.root / "DictionaryPatch.txt"
+
+    @property
+    def battle_patch(self) -> Path:
+        return self.root / "BattlePatch.txt"
+
+    @property
+    def text_patch(self) -> Path:
+        """Item/ability/card NAME + DESCRIPTION overrides (``TextPatch.txt``, a ``>DATABASE`` find/replace
+        patch -- ``Memoria.TextPatcher``). A per-mod-folder drop-in like the dictionary/battle patches,
+        read once at ``DataPatchers.Initialize`` -> a text change needs a RELAUNCH (not F6 Reload)."""
+        return self.root / "TextPatch.txt"
+
+    @property
+    def mod_description(self) -> Path:
+        return self.root / "ModDescription.xml"
+
+    # --- field background scene (camera/overlays + walkmesh + PNGs) ---
+    @property
+    def fieldmaps_dir(self) -> Path:
+        return self.root / "StreamingAssets" / "assets" / "resources" / "FieldMaps"
+
+    def fieldmap_dir(self, fbg_name: str) -> Path:
+        """Folder holding ``<fbg>.bgx``, ``<fbg>.bgi.bytes`` and the overlay PNGs."""
+        return self.fieldmaps_dir / fbg_name
+
+    # --- battle background (BBG): a loose FBX + image#.png the engine loads instead of the bundle ---
+    @property
+    def battlemap_all_dir(self) -> Path:
+        # NOTE: the capitalized "Assets/Resources/BattleMap" segments are VERBATIM -- this exact casing
+        # round-tripped in-game (2026-06-09); do NOT lowercase it to match fieldmaps_dir above.
+        return (self.root / "StreamingAssets" / "Assets" / "Resources"
+                / "BattleMap" / "BattleModel" / "battleMap_all")
+
+    def battlemap_dir(self, bbg: str) -> Path:
+        """Folder holding ``<bbg>.fbx`` + its ``image#.png`` textures (the loose-FBX override slot)."""
+        return self.battlemap_all_dir / bbg
+
+    # --- minted battle SCENE assets (tier c). Paths VERBATIM-proven in-game (C1/C2, 2026-06-09);
+    #     casing matches battlemap_all_dir above (capitalized BattleMap), not the lowercase field tree. ---
+    @property
+    def _battle_resources(self) -> Path:
+        return self.root / "StreamingAssets" / "Assets" / "Resources"
+
+    def battle_scene_dir(self, scene_name: str) -> Path:
+        """``…/BattleMap/BattleScene/EVT_BATTLE_<NAME>`` — holds ``dbfile0000.raw16.bytes`` (gameplay) +
+        ``<scene_id>.raw17.bytes`` (btlseq + camera)."""
+        return self._battle_resources / "BattleMap" / "BattleScene" / f"EVT_BATTLE_{scene_name}"
+
+    @property
+    def battle_info_dir(self) -> Path:
+        """``…/BattleMap/BattleInfo`` — holds ``INB_B<N>.inb.bytes`` (BBGINFO: bbgnumber + anim flags)."""
+        return self._battle_resources / "BattleMap" / "BattleInfo"
+
+    def battle_eb_path(self, lang: str, scene_name: str) -> Path:
+        """``…/CommonAsset/EventEngine/EventBinary/Battle/<lang>/EVT_BATTLE_<NAME>.eb.bytes`` (battle AI)."""
+        return (self._battle_resources / "CommonAsset" / "EventEngine" / "EventBinary"
+                / "Battle" / lang / f"EVT_BATTLE_{scene_name}.eb.bytes")
+
+    def battle_text_dir(self, lang: str) -> Path:
+        """``<root>/FF9_Data/embeddedasset/text/<lang>/battle`` — holds ``<scene_id>.mes`` (battle text)."""
+        return self.root / "FF9_Data" / "embeddedasset" / "text" / lang / "battle"
+
+    # --- field event scripts (.eb), one folder per language ---
+    @property
+    def eventbinary_field_dir(self) -> Path:
+        return (
+            self.root
+            / "StreamingAssets" / "assets" / "resources" / "commonasset"
+            / "eventengine" / "eventbinary" / "field"
+        )
+
+    def eb_path(self, lang: str, evt_name: str) -> Path:
+        """``<root>/.../eventbinary/field/<lang>/<evt_name>`` (evt_name includes .eb.bytes)."""
+        return self.eventbinary_field_dir / lang / evt_name
+
+    def mapconfig_path(self, evt_name: str) -> Path:
+        """``<root>/.../commonasset/mapconfigdata/<evt_name>.bytes`` -- the field's 3D-model LIGHTING config
+        (per-floor lights + shadows + per-object colors), loaded at field setup by the SAME event name as
+        the ``.eb`` (``MapConfiguration.LoadMapConfigData`` / ``fldmcf.cs``). Not per-language."""
+        return (self.root / "StreamingAssets" / "assets" / "resources" / "commonasset"
+                / "mapconfigdata" / f"{evt_name}.bytes")
+
+    # --- dialogue text (.mes), one folder per language ---
+    def text_field_dir(self, lang: str) -> Path:
+        return self.root / "FF9_Data" / "embeddedasset" / "text" / lang / "field"
+
+    def mes_path(self, lang: str, mes_id: int) -> Path:
+        return self.text_field_dir(lang) / f"{mes_id}.mes"
+
+    # --- item / character DATA CSVs (mod-global; the engine merges/overrides them across FolderNames at
+    #     new-game). Written at the mod-write stage from the entry field's [start_inventory]/[equipment]. ---
+    @property
+    def initial_items_csv(self) -> Path:
+        """The new-game starting bag (``Data/Items/InitialItems.csv``). HIGHEST-priority-wins -> a mod must
+        write the FULL bag, and a stacked folder SHADOWS it (lint)."""
+        return self.root / "StreamingAssets" / "Data" / "Items" / "InitialItems.csv"
+
+    @property
+    def default_equipment_csv(self) -> Path:
+        """Per-character starting equipment (``Data/Characters/DefaultEquipment.csv``). MERGED low->high by
+        the engine -> a partial delta (only the characters you change) works."""
+        return self.root / "StreamingAssets" / "Data" / "Characters" / "DefaultEquipment.csv"
+
+    @property
+    def shop_items_csv(self) -> Path:
+        """Custom shop inventories (``Data/Items/ShopItems.csv``). MERGED by id low->high by the engine -> a
+        partial delta (only the custom shops, ids >= 32) works; the base supplies shops 0-31."""
+        return self.root / "StreamingAssets" / "Data" / "Items" / "ShopItems.csv"
+
+    @property
+    def synthesis_csv(self) -> Path:
+        """Custom synthesis recipes (``Data/Items/Synthesis.csv`` = FF9MIX_DATA: Shops/Price/Result/Ingredients).
+        MERGED by id low->high (whole-row, ff9mix.LoadSynthesis) -> a partial delta works; the kit MINTS recipe
+        ids above the base max so it only ADDS recipes. A shop id opens as Synthesis iff it is absent from
+        ShopItems.csv (ff9buy.FF9Buy_GetType); a recipe shows at every shop id in its ``Shops`` list."""
+        return self.root / "StreamingAssets" / "Data" / "Items" / "Synthesis.csv"
+
+    @property
+    def weapons_csv(self) -> Path:
+        """Weapon combat data (``Data/Items/Weapons.csv``: Power/Elements/Category...). MERGED by id low->high
+        (WHOLE-ROW replace) -> a partial delta (the base header + only the rows you tune) works."""
+        return self.root / "StreamingAssets" / "Data" / "Items" / "Weapons.csv"
+
+    @property
+    def armors_csv(self) -> Path:
+        """Armor defence data (``Data/Items/Armors.csv``: P.Def/P.Eva/M.Def/M.Eva). MERGED by id low->high
+        (whole-row replace) -> a partial delta works."""
+        return self.root / "StreamingAssets" / "Data" / "Items" / "Armors.csv"
+
+    @property
+    def items_csv(self) -> Path:
+        """Item info (``Data/Items/Items.csv``: Price/SellingPrice/equip...). MERGED by id low->high (whole-row
+        replace) -> a partial delta works. (NOT InitialItems.csv -- that's the new-game bag, highest-wins.)"""
+        return self.root / "StreamingAssets" / "Data" / "Items" / "Items.csv"
+
+    @property
+    def stats_csv(self) -> Path:
+        """Equip stat bonuses + elemental affinity (``Data/Items/Stats.csv`` = ItemStats, keyed by BonusId).
+        MERGED by id low->high (whole-row replace, ff9equip.cs:26) -> a partial delta works; new minted bonus
+        rows just add entries. The input the level-up stat-growth accumulator reads (ff9play.cs:302-305)."""
+        return self.root / "StreamingAssets" / "Data" / "Items" / "Stats.csv"
+
+    @property
+    def item_effects_csv(self) -> Path:
+        """Consumable use-effects (``Data/Items/ItemEffects.csv`` = ItemEffect, keyed by EffectId). MERGED by id
+        low->high (whole-row replace, ff9item.LoadItemEffects) -> a partial delta works; EffectId is 1:1 with a
+        usable item (no shared Empty row), so a row is edited in place. Power/Rate/Element/Status/Dead are the
+        gameplay knobs; the ScriptId (the behaviour) stays."""
+        return self.root / "StreamingAssets" / "Data" / "Items" / "ItemEffects.csv"
+
+    @property
+    def actions_csv(self) -> Path:
+        """Shared player abilities (``Data/Battle/Actions.csv``). MERGED by id low->high (whole-row replace) ->
+        a partial delta (only the abilities you change) works; the base supplies the other 192 rows."""
+        return self.root / "StreamingAssets" / "Data" / "Battle" / "Actions.csv"
+
+    @property
+    def status_data_csv(self) -> Path:
+        """Status definitions (``Data/Battle/StatusData.csv``). MERGED by id low->high (whole-row replace) ->
+        a partial delta (only the statuses you change) works; the base supplies the other 33 rows."""
+        return self.root / "StreamingAssets" / "Data" / "Battle" / "StatusData.csv"
+
+    @property
+    def status_sets_csv(self) -> Path:
+        """Named multi-status BUNDLES (``Data/Battle/StatusSets.csv``) an action's ``status_index`` points at.
+        MERGED by id low->high -> a partial works (ids 0-38 are the base sets; use >=39 for a custom one)."""
+        return self.root / "StreamingAssets" / "Data" / "Battle" / "StatusSets.csv"
+
+    @property
+    def magic_sword_sets_csv(self) -> Path:
+        """Combo-unlock sets (``Data/Battle/MagicSwordSets.csv``): a Supporter's abilities unlock a Beneficiary's
+        (Vivi -> Steiner's Magic Sword). MERGED by id low->high -> a partial (only the author's sets) works."""
+        return self.root / "StreamingAssets" / "Data" / "Battle" / "MagicSwordSets.csv"
+
+    @property
+    def base_stats_csv(self) -> Path:
+        """Per-character base combat stats (``Data/Characters/BaseStats.csv``). MERGED by CharacterId low->high
+        -> a partial delta (only the characters you change) works; the base supplies the other 11."""
+        return self.root / "StreamingAssets" / "Data" / "Characters" / "BaseStats.csv"
+
+    @property
+    def character_parameters_csv(self) -> Path:
+        """Per-character identity (``Data/Characters/CharacterParameters.csv``): row / category / menu-preset /
+        equip-set. MERGED by CharacterId low->high -> a partial delta works (the base supplies the rest)."""
+        return self.root / "StreamingAssets" / "Data" / "Characters" / "CharacterParameters.csv"
+
+    @property
+    def command_sets_csv(self) -> Path:
+        """Per-character battle-menu command LAYOUTS (``Data/Characters/CommandSets.csv``), keyed by preset 0-19.
+        MERGED low->high -> a partial delta (only the presets you re-point) works."""
+        return self.root / "StreamingAssets" / "Data" / "Characters" / "CommandSets.csv"
+
+    @property
+    def leveling_csv(self) -> Path:
+        """The 99-row growth curve (``Data/Characters/Leveling.csv``). HIGHEST-priority-wins (WHOLE-FILE, gated at
+        >=99 rows) -> a mod must emit the FULL 99-row file, and a stacked folder SHADOWS it (lint)."""
+        return self.root / "StreamingAssets" / "Data" / "Characters" / "Leveling.csv"
+
+    @property
+    def ability_gems_csv(self) -> Path:
+        """Support-ability gem COSTS (``Data/Characters/Abilities/AbilityGems.csv``). MERGED per-SupportAbility
+        low->high -> a partial delta (only the abilities you re-cost) works; the base supplies the other 63."""
+        return self.root / "StreamingAssets" / "Data" / "Characters" / "Abilities" / "AbilityGems.csv"
+
+    def abilities_csv(self, preset_name: str) -> Path:
+        """A per-preset learn list (``Data/Characters/Abilities/<CharacterPresetId>.csv``, e.g. ``Vivi.csv``).
+        WHOLE-FILE highest-priority-wins -> the kit re-emits the complete list. A METHOD (not a property): the
+        Abilities learn lists are a FILE SET (one per preset), like ``battle_eb_path(lang, scene)``."""
+        return self.root / "StreamingAssets" / "Data" / "Characters" / "Abilities" / f"{preset_name}.csv"
+
+    @property
+    def ability_features_txt(self) -> Path:
+        """The ability-EFFECT DSL (``Data/Characters/Abilities/AbilityFeatures.txt``). MERGED per-ability
+        low->high (accumulator) -> a partial file (only the abilities you change) works; the base supplies the
+        rest. Authored from ``[[ability_feature]]`` (:mod:`battle.abilityfeatures`)."""
+        return self.root / "StreamingAssets" / "Data" / "Characters" / "Abilities" / "AbilityFeatures.txt"
+
+    def ensure_dirs(self, fbg_name: str | None = None, *, bbg: str | None = None,
+                    langs: tuple[str, ...] = LANGS) -> None:
+        """Create the directory skeleton a field (and/or battle-map) write needs."""
+        self.root.mkdir(parents=True, exist_ok=True)
+        if fbg_name:
+            self.fieldmap_dir(fbg_name).mkdir(parents=True, exist_ok=True)
+        if bbg:
+            self.battlemap_dir(bbg).mkdir(parents=True, exist_ok=True)
+        for lang in langs:
+            (self.eventbinary_field_dir / lang).mkdir(parents=True, exist_ok=True)
+            self.text_field_dir(lang).mkdir(parents=True, exist_ok=True)
+
+
+# ---- FBG (background scene) naming -------------------------------------------------------
+
+MIN_AREA = 10  # the area id must be >= 10: the FieldScene parser builds "FBG_N"+area with no
+#                zero-padding and the asset loader reads exactly 2 chars, so 00-09 black-screen.
+
+
+def fbg_name(area: int, name: str) -> str:
+    """Build the canonical background-scene folder/key name, e.g. (11, 'HUT_EXT') -> 'FBG_N11_HUT_EXT'.
+
+    Raises ConfigError for single-digit areas (the zero-padding gotcha from the field plumbing).
+    """
+    if area < MIN_AREA:
+        raise ConfigError(
+            f"area id must be >= {MIN_AREA} (got {area}). The FieldScene directive builds the "
+            f"background name as 'FBG_N{{area}}' with no zero-padding and the loader reads exactly "
+            f"two characters, so single-digit areas (00-09) fail to resolve and black-screen."
+        )
+    return f"FBG_N{area}_{name}"

ff9mapkit/content/__init__.py

@@ -0,0 +1,13 @@
+"""Generalized field-script content injectors (operate on .eb bytes via the eb library).
+
+  npc        - inject an NPC (model/anims/dialogue) + move the player spawn
+  gateway    - inject a field-exit region trigger (warp to another field)
+  encounter  - add random battles
+  reinit     - add the after-battle handler (+ fast fade-in) custom fields need
+  music      - field BGM on entry and after battle
+  text       - author dialogue .mes entries (high-TXID, non-colliding)
+"""
+
+from . import encounter, gateway, music, npc, reinit, text
+
+__all__ = ["npc", "gateway", "encounter", "reinit", "music", "text"]

ff9mapkit/content/areatitle.py

@@ -0,0 +1,36 @@
+"""Suppress a BG-borrowed field's inherited AREA-TITLE overlays -- the big "Ice Cavern" / "Mognet Central"
+card.
+
+The title is a range of scene OVERLAYS (indices from :mod:`ff9mapkit.areatitle`). In the real game the
+DONOR field's own ``.eb`` owns the title's whole lifecycle: ``Main_Init`` hides the overlays at load, and a
+*scenario-gated* block later shows + fades them (and, on a transition field, warps onward). A ``--verbatim``
+fork carries that script byte-for-byte, so a forked field replays the stock show+fade on its own when the
+journey seeds the trigger scenario -- the kit does NOT script the title for forks (doing so would double
+the card and re-fire the donor's warp).
+
+The gap this module fills is the OTHER case: a SYNTHESIZED field that BG-borrows an area-title room (the
+World Hub borrows Mognet Central's room) inherits those overlays Active-by-default, with no donor ``.eb`` to
+retire them -- so the title sits there statically claiming to be that place. :func:`hide` prepends
+``ShowTile(i, 0)`` for the title overlays to ``Main_Init`` (entry-0 tag-0) so it never shows. A tag-0
+prepend (``rel_off == 0``) is shift-safe even on jump-table donors; the injection is language-identical
+and no-ops when the field has no area title. Mirrors :mod:`ff9mapkit.content.entry_settle`.
+"""
+
+from __future__ import annotations
+
+from ..eb import edit, opcodes
+
+SHOWTILE = 0x5B          # ShowTile / BGLACTIVE: ShowTile(overlayIdx, active) -- active 0 = hide, 1 = show
+
+
+def hide(eb_bytes, start, end) -> bytes:
+    """Prepend ``ShowTile(i, 0)`` for every overlay ``i`` in ``[start, end]`` to Main_Init (entry-0 tag-0)
+    so the area-title overlays are suppressed from the first frame. Returns the input unchanged when the
+    field has no title range (``start``/``end`` is ``None``). ``.eb``-language-identical (call once)."""
+    if start is None or end is None:
+        return eb_bytes
+    ovr = list(range(int(start), int(end) + 1))
+    if not ovr:
+        return eb_bytes
+    body = b"".join(opcodes.encode(SHOWTILE, i, 0) for i in ovr)
+    return edit.insert_in_function(eb_bytes, 0, 0, 0, body)

ff9mapkit/content/ate.py

@@ -0,0 +1,118 @@
+"""``[[ate]]`` -- synthesize an Active Time Event (FF9's optional "Press SELECT" cutscene mechanism).
+
+An ATE has three engine-visible parts (see ``docs/ATE_SYSTEM.md``); this module emits all of them onto
+a custom field, byte-for-byte as the real Lindblum Main-St hub (field 552, the "Small-Town Knight" ATE):
+
+  Main_Init wiring (prepended):
+      ATE(mode)                       # 0xD7 -> EIcon.SetAIcon -> the blinking "Active Time Event" HUD prompt
+      <avail flag> = 1                # the author's own GLOB availability flag
+      InitCode(<menu slot>)           # activate the menu code-entry (its tag-1 func then loops each frame)
+
+  the menu code-entry (appended):
+      func0 (tag 0): RETURN           # trivial init
+      func1 (tag 1): the per-frame LOOP --
+          if ( usercontrol==1  AND  <avail>==1  AND  B_KEYON(SELECT) ) {     # the real gate, field 552 [11667]
+              DisableMove ; EnableDialogChoices ; WindowSync(win, 64=winATE, prompt) ;  # the "Select event" menu
+              <branch on GetChoose -> the picked row's body> ; EnableMove
+          }
+          RETURN
+
+Engine facts grounding every byte (all verified): ``AICON=0xD7`` (the blink HUD), ``winATE=64`` ->
+``CaptionType.ActiveTimeEvent``, ``GetChoose`` = sysvar 9, ``B_KEYON=0x4F`` (press-edge), ``Select=1u``,
+sysvar 2 = ``usercontrol``. The menu + per-row branch reuse :mod:`ff9mapkit.content.choice` (the same
+``GetChoose`` machinery) with ``flags=64`` so the window renders with the ATE caption; each row's body is the
+ordinary event/choice action vocabulary (a narration line, a story-flag set, or a ``warp`` to the cutscene
+field -- the real hub->destination pattern, e.g. Small-Town Knight -> ``Field(555)``).
+"""
+from __future__ import annotations
+
+import struct
+
+from ..eb import EbScript, edit, opcodes
+from . import choice as _choice, region as _region
+
+# Availability-flag band: GLOB bools, clear of events (8000), cutscene (8100), choice (8200). Each [[ate]]
+# on a field claims ATE_FLAG_BASE + i so multiple ATEs don't collide.
+ATE_FLAG_BASE = 8300
+
+# ATE(mode) presets -- the arg is a 3-bit FLAG WORD, not an enum (see opcodes.ate / EIcon.cs:416-454 /
+# docs/ATE_SYSTEM.md): >0 enable (0=off); &3==2 Gray (else Blue); &4 force-show (draw without user control).
+MODE_BLUE = 1     # Blue, no force -- the optional Press-SELECT prompt (shows only with control). The [ate] HUB default.
+MODE_GRAY = 2     # Gray, no force -- NEVER used in the real game (can't show during a no-control beat; use 6 for grey).
+MODE_FORCE = 5    # Blue + force -- field 206's lone real site. AVOID for authoring: re-flashes the SELECT glyph (use 6).
+
+WIN_ATE = 64      # ETb.winATE -> Dialog.CaptionType.ActiveTimeEvent
+
+
+def _build_entry(funcs, etype: int = 0) -> bytes:
+    """Assemble an entry body from ``funcs = [(tag, code_bytes), ...]``: ``[type][func_count]`` + the
+    func table (``tag:u16, fpos:u16`` each; ``fpos`` is relative to entryStart+2) + the concatenated code.
+    Mirrors the layout :class:`ff9mapkit.eb.model.EbScript` parses (so it round-trips)."""
+    fc = len(funcs)
+    fpos = fc * 4                                  # code starts right after the func table
+    table = bytearray()
+    code = bytearray()
+    for tag, c in funcs:
+        table += struct.pack("<HH", tag, fpos)
+        code += c
+        fpos += len(c)
+    return bytes([etype, fc]) + bytes(table) + bytes(code)
+
+
+JMP_OP = 0x01   # the undocumented UNCONDITIONAL jump (op_01): target = instr.end + signed-i16 offset
+
+
+def menu_loop_body(prompt_txid: int, option_bodies, *, avail_idx: int, window: int = 1,
+                   setup: bytes = b"") -> bytes:
+    """The menu entry's tag-1 LOOP body. It must POLL each frame, exactly as the real ATE menu does
+    (field 552 entry-7 tag-1)::
+
+        loop:  if ( usercontrol AND avail AND B_KEYON(SELECT) ) { winATE menu }
+               Wait(1)                 # yield a frame -> one poll per frame (not a busy-spin)
+               JMP loop                # op_01 unconditional jump back to the top; NO RETURN
+
+    The poller lives as long as the field is loaded (no terminate). ``setup`` is the optional
+    ``EnableDialogChoices`` pre-choose opcode (default / cancel / hidden rows), from
+    :func:`ff9mapkit.content.choice.pre_choose`.
+
+    NB the earlier ``if(gate){menu} + RETURN`` form ran ONCE right after ``InitCode`` and never polled
+    again -- so SELECT did nothing. The ``Wait(1)`` + ``op_01`` jump-back is what makes it a real loop."""
+    menu = _choice.region_body(prompt_txid, option_bodies, window=window, flags=WIN_ATE, setup=setup)
+    gate = _region.cond_ate_select(_region.GLOB_BOOL, avail_idx)
+    body = _region.if_block(gate, menu) + opcodes.wait(1)
+    back = -(len(body) + 3)                          # op_01 is 3 bytes; jump back to the loop top (offset 0)
+    return body + bytes([JMP_OP]) + struct.pack("<h", back)
+
+
+def menu_entry(prompt_txid: int, option_bodies, *, avail_idx: int, window: int = 1,
+               setup: bytes = b"") -> bytes:
+    """The complete ATE menu CODE-ENTRY body (ready for :func:`ff9mapkit.eb.edit.append_entry`): a trivial
+    tag-0 init (RETURN) + the tag-1 polling loop (:func:`menu_loop_body`). InitCode'd from Main_Init."""
+    return _build_entry([(0, opcodes.RETURN),
+                         (1, menu_loop_body(prompt_txid, option_bodies, avail_idx=avail_idx,
+                                            window=window, setup=setup))])
+
+
+def main_init_inject(*, avail_idx: int, menu_slot: int, mode: int = MODE_BLUE) -> bytes:
+    """The Main_Init wiring, prepended to entry-0 tag-0: arm the blinking prompt, set the availability
+    flag, and activate the menu entry. ``ATE(mode) ; <avail>=1 ; InitCode(menu_slot)``."""
+    return (opcodes.ate(mode)
+            + _region.set_var(_region.GLOB_BOOL, avail_idx, 1)
+            + opcodes.init_code(menu_slot))
+
+
+def inject_ate(data, prompt_txid: int, option_bodies, *, avail_idx: int = ATE_FLAG_BASE,
+               mode: int = MODE_BLUE, setup: bytes = b"") -> bytes:
+    """Synthesize a complete ATE onto ``data`` (a field ``.eb``): append the SELECT-polling menu entry
+    (:func:`menu_entry`) into a free slot, then PREPEND the Main_Init wiring (:func:`main_init_inject` --
+    ``ATE(mode)`` + set the avail flag + ``InitCode`` the menu slot) to entry-0 tag-0. Returns new ``.eb``
+    bytes. The prepend goes through :func:`ff9mapkit.eb.edit.insert_in_function`, which is boundary-safe even
+    on a Main_Init with a ``0x06`` scenario jump-table. No-op-safe: pass real ``option_bodies`` (one per row).
+    Default ``mode`` is Blue (mode 1, shows while the player has control -- the HUB convention). For a forced
+    auto-play use mode 6 (Gray+force) via ``[cutscene] ate``, not ``MODE_FORCE`` (5, Blue+force) -- a force-shown
+    Blue icon re-flashes the SELECT glyph during auto-play (mode arg = a 3-bit flag word; see EIcon.cs:416-454)."""
+    out = data if isinstance(data, (bytes, bytearray)) else data.to_bytes()
+    entry = menu_entry(prompt_txid, option_bodies, avail_idx=avail_idx, setup=setup)
+    slot = EbScript.from_bytes(out).first_free_slot()
+    out = edit.append_entry(out, slot, entry)
+    return edit.insert_in_function(out, 0, 0, 0, main_init_inject(avail_idx=avail_idx, menu_slot=slot, mode=mode))

ff9mapkit/content/camera.py

@@ -0,0 +1,123 @@
+"""Camera-services / scrolling control (the ``BGCACTIVE`` opcode).
+
+Larger-than-screen fields scroll the view to follow the player. Memoria's 3D scroll
+(``FieldMap.SceneService3DScroll``) runs automatically for a walkable field, but only when the
+field's ``Active`` flag is set — and that flag is set by the field-script opcode
+``EnableCameraServices`` (``BGCACTIVE`` = 0x71, args ``isActive, frameCount, sinusOrLinear``).
+
+A field cloned from a static (non-scrolling) base never calls it, so :func:`enable_camera_services`
+injects ``EnableCameraServices(1, 0, 0)`` at the start of Main_Init. Proven in-game on the 768x448
+scroll spike (field 4003): with the wide ``Range`` + scroll ``Viewport`` (see
+:func:`ff9mapkit.scene.cam.scroll_bounds`) the view then pans + clamps cleanly.
+"""
+
+from __future__ import annotations
+
+import struct
+
+from ..eb import EbScript, edit, opcodes
+from . import region as _region
+
+BGCACTIVE_OP = 0x71      # EnableCameraServices
+
+# The camera-state flag. VAR_GlobUInt8_24 is exactly what the real field (Gargan Roo/Passage) uses;
+# our init entry resets it to 0 on every field load, so it never collides across loads.
+DEFAULT_FLAG = (_region.GLOB_UINT8, 24)
+
+
+def enable_camera_services(eb_bytes, *, frame_count: int = 0, scroll_type: int = 0) -> bytes:
+    """Insert ``EnableCameraServices(1, frame_count, scroll_type)`` at the start of Main_Init.
+
+    ``frame_count`` = duration (frames) of the camera's reposition-to-player when it activates
+    (0 = instant; -1 defaults to 30 in the engine). ``scroll_type`` = 8 for sinusoidal, else linear.
+    Uses :func:`edit.insert_bytes` (relocates jumps/fpos), so it is safe alongside other injectors.
+    """
+    eb = EbScript.from_bytes(eb_bytes)
+    f = eb.entry(0).func_by_tag(0)
+    if f is None:
+        raise ValueError("entry 0 has no Main_Init (tag 0) to enable camera services in")
+    code = opcodes.encode(BGCACTIVE_OP, 1, int(frame_count), int(scroll_type))
+    return edit.insert_bytes(eb_bytes, f.abs_start, code)
+
+
+# --------------------------------------------------------------------------- multi-camera switch
+# Generalizes the real-field convention (decoded byte-for-byte from Gargan Roo/Passage,
+# evt_gargan_gr_lef_0) to N cameras via an AREA model: a state flag holds the CURRENT camera index,
+# and each zone owns the floor area where its camera should be active. Entering a zone for camera K
+# while flag != K switches to camera K, stores K in the flag, and re-tunes movement
+# (SetControlDirection for K's yaw). The flag guard stops re-firing while you stand in a zone;
+# NON-OVERLAPPING zones can't flap. An init code-entry resets the flag to 0 + arms every zone on
+# field load (state is consistent on entry); after a battle (Main_Init doesn't run) the tag-10
+# restore (:func:`add_camera_restore`) re-applies the stored camera + movement.
+
+REINIT_TAG = 10
+
+
+def _zone_body(to_camera: int, control_value: int, flag) -> bytes:
+    """A camera zone's Range body: movement-gate, then `if (flag != to_camera) { SetFieldCamera;
+    set flag = to_camera; SetControlDirection }`."""
+    flag_class, flag_idx = flag
+    actions = (opcodes.set_field_camera(to_camera)
+               + _region.set_var(flag_class, flag_idx, to_camera)
+               + opcodes.set_control_direction(control_value, control_value))
+    return (_region.MOVEMENT_GATE
+            + _region.if_not_block(_region.cond_eq(flag_class, flag_idx, to_camera), actions)
+            + opcodes.RETURN)
+
+
+def inject_camera_zones(data, zones, control_values, *, flag=DEFAULT_FLAG, spawn_wait_n: int = 2,
+                        spawn_wait_occurrence: int = 0) -> bytes:
+    """Inject N camera-switch zones (the area model). Returns new .eb bytes.
+
+    ``zones`` = list of ``(to_camera, [4 (x, z) corners])``; ``control_values[k]`` = the
+    SetControlDirection (TWIST) value for camera ``k`` (derive from its yaw). Each zone owns the floor
+    area where its camera is active; standing in it sets that camera. Zones SHOULD NOT overlap
+    (overlapping zones flap). Needs ``len(zones) + 1`` free entry slots (the zones + one load-time
+    init/arm entry that resets the flag to 0 and arms them all)."""
+    flag_class, flag_idx = flag
+    zones = list(zones)
+    eb = EbScript.from_bytes(data)
+    if len(eb.free_slots()) < len(zones) + 1:
+        raise ValueError(f"need {len(zones) + 1} free entry slots for {len(zones)} camera zones, "
+                         f"have {len(eb.free_slots())}")
+    out = data
+    slots = []
+    for to_camera, corners in zones:
+        body = _zone_body(int(to_camera), int(control_values[int(to_camera)]), flag)
+        out, slot = _region.inject_region(out, [tuple(p) for p in corners], body, activate=False)
+        slots.append(slot)
+    # init/arm entry: reset flag = 0 (camera 0 at load) + arm every zone.
+    init_body = _region.set_var(flag_class, flag_idx, 0)
+    for s in slots:
+        init_body += opcodes.init_region(s, 0)
+    init_body += opcodes.RETURN
+    init_entry = bytes([0x00, 0x01]) + struct.pack("<HH", 0, 4) + init_body
+    init_slot = EbScript.from_bytes(out).first_free_slot()
+    out = edit.append_entry(out, init_slot, init_entry)
+    out = edit.activate(out, opcodes.init_code(init_slot, 0), spawn_wait_n=spawn_wait_n,
+                        spawn_wait_occurrence=spawn_wait_occurrence)
+    return out
+
+
+def add_camera_restore(data, cameras_used, control_values, *, flag=DEFAULT_FLAG) -> bytes:
+    """Add an after-battle camera restore to Main_Reinit (tag 10). Returns new .eb bytes.
+
+    For each non-zero camera ``K`` in ``cameras_used``: ``if (flag == K) { SetFieldCamera(K);
+    SetControlDirection(K) }``. After a battle the field runs tag-10 (NOT Main_Init, so the flag isn't
+    reset) -- this re-applies the camera + movement the player was on. Requires an existing tag-10
+    (``content.reinit.add_reinit`` / an encounter); a no-op if no non-zero camera is used."""
+    flag_class, flag_idx = flag
+    eb = EbScript.from_bytes(data)
+    f = eb.entry(0).func_by_tag(REINIT_TAG)
+    if f is None:
+        raise ValueError("entry 0 has no tag-10 handler (run content.reinit.add_reinit first)")
+    restore = b""
+    for k in sorted({int(c) for c in cameras_used}):
+        if k == 0:
+            continue
+        actions = opcodes.set_field_camera(k) + opcodes.set_control_direction(
+            int(control_values[k]), int(control_values[k]))
+        restore += _region.if_block(_region.cond_eq(flag_class, flag_idx, k), actions)
+    if not restore:
+        return data if isinstance(data, (bytes, bytearray)) else data.to_bytes()
+    return edit.insert_bytes(data, f.abs_start, restore)