ff9mapkit 1.0.0b3__tar.gz → 1.0.0b4__tar.gz

{ff9mapkit-1.0.0b3 → ff9mapkit-1.0.0b4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ff9mapkit
-Version: 1.0.0b3
+Version: 1.0.0b4
 Summary: Author novel custom field maps for Final Fantasy IX (Memoria engine) from a declarative TOML project file.
 Author: GameJawnsInc
 License-Expression: MIT

{ff9mapkit-1.0.0b3 → ff9mapkit-1.0.0b4}/ff9mapkit/__init__.py

@@ -15,4 +15,4 @@ Public surface is organized as:
   ff9mapkit.battle    — the battle.toml -> custom battle-background (BBG) builder (fork/edit/build a 3D battle map)
 """
 
-__version__ = "1.0.0b3"   # keep in lockstep with [project] version in pyproject.toml
+__version__ = "1.0.0b4"   # keep in lockstep with [project] version in pyproject.toml

{ff9mapkit-1.0.0b3 → ff9mapkit-1.0.0b4}/ff9mapkit/build.py

@@ -863,6 +863,22 @@ def validate(project: FieldProject) -> list[str]:
         # on-exit story advance: set_scenario / set_flags fire when the player takes this exit
         _validate_story_writes(gw, "[[gateway]]", story_names, problems,
                                scenario_key="set_scenario", flags_key="set_flags")
+        # forced-ATE warp-in: ate = true flashes the grey banner WARNING before this exit warps (the faithful
+        # grey-ATE trigger -- pair with a plain [cutscene] + exit_warp on the destination, which returns you).
+        if "ate_mode" in gw and not gw.get("ate"):
+            problems.append("[[gateway]] ate_mode is set but ate is not true -- set ate = true to make this "
+                            "exit a forced-ATE warp (grey banner warning, then warp), or drop ate_mode.")
+        if gw.get("ate"):
+            m = gw.get("ate_mode", _cutscene.ATE_DEFAULT_MODE)
+            if not isinstance(m, int) or isinstance(m, bool) or not (0 <= m <= 255):
+                problems.append(f"[[gateway]] ate_mode {m!r} must be an int 0..255 "
+                                f"(6 = grey unskippable ATE banner; ATE 0xD7 mode).")
+        if "ate_title" in gw:
+            if not gw.get("ate"):
+                problems.append("[[gateway]] ate_title is set but ate is not true -- set ate = true (it's the "
+                                "title window the forced-ATE warp-in shows), or drop ate_title.")
+            elif not isinstance(gw["ate_title"], str) or not gw["ate_title"].strip():
+                problems.append("[[gateway]] ate_title must be a non-empty string (the ATE title-window text).")
     for ev in project.raw.get("event", []):
         z = ev.get("zone", [])
         if len(z) not in (4, 5):
@@ -2475,7 +2491,9 @@ def _gateway_on_exit_body(gw: dict, names: dict) -> bytes:
     """The story-state advance a ``[[gateway]]`` applies when the player TAKES this exit: the raw
     ``set_var`` bytes from ``set_scenario`` (ScenarioCounter) + ``set_flags`` (gEventGlobal bits), built
     with the shared :func:`ff9mapkit.content.startup.startup_body`. ``b""`` when the gateway has neither
-    (so the build is byte-identical to a gateway without on-exit writes)."""
+    (so the build is byte-identical to a gateway without on-exit writes). (NB ``ate = true`` is NOT handled
+    here -- a forced-ATE warp-in routes to :func:`cutscene.inject_forced_ate` instead, because the banner +
+    timed warp must run in a RunScript'd player func, not inline in the region, or the region's Wait freezes.)"""
     sc = gw.get("set_scenario")
     if isinstance(sc, str):
         sc = _flags.resolve_scenario(sc)
@@ -3251,6 +3269,61 @@ def _inject_verbatim_npcs(project: FieldProject, eb: bytes, npc_txids: dict, *,
     return eb, npc_slots
 
 
+def _gen_conductor_walk_tags(project: FieldProject, eb: bytes, steps, npc_slots):
+    """Shared by the synth + verbatim conductor wiring: add the per-actor choreography tags a conductor's
+    ``walk`` beats need. For each ``walk`` step, add a walk tag (20+) to the actor's entry (the conductor
+    ``RunScript``s into it -- base ``Walk`` acts on the executing object, so the walk must run in the actor's
+    own context). For each actor that walks inside a PARALLEL group (``with_prev``), also add ONE bare-RETURN
+    join tag -- the conductor async-forks the walk then ``RunScriptSync``s the join tag to block until the
+    walk frees the actor's script level. ``add_function`` grows an entry but keeps slot INDICES stable, so the
+    conductor's by-uid refs (and any later band insert) stay valid. Returns ``(eb, walk_calls, join_tags)``.
+
+    The PLAYER walks too: ``"player"`` -> the tag goes on the player's OWN entry (``DefinePlayerCharacter``,
+    located by :func:`ff9mapkit.content.player.find_player_entry`), but the conductor addresses it by the
+    control-char sentinel uid 250 (``GetObjUID(250)`` -> the control character) -- so its add-target entry and
+    its conductor uid differ (an NPC's are the same, slot == uid). Same recipe the ladder uses for the player."""
+    walk_calls, join_tags = {}, {}
+    if not any("walk" in s for s in steps):
+        return eb, walk_calls, join_tags
+    from .eb import edit as _eb_edit
+    from .content import player as _player
+    move_reg = _position_registry(project)
+    # the player entry index is stable across add_function (slot indices don't move), so resolve it once
+    player_entry = (_player.find_player_entry(EbScript.from_bytes(eb))
+                    if any(s.get("actor") == "player" and "walk" in s for s in steps) else None)
+
+    def _walk_target(actor):
+        """(entry index to add the tag to, uid the conductor addresses). Player: its own entry, uid 250."""
+        if actor == "player":
+            return player_entry, _conductor.PLAYER_UID
+        slot = npc_slots.get(actor)                        # an NPC: entry index == runtime uid
+        return slot, slot
+
+    next_tag = {}                                          # actor name -> next free walk tag
+    for i, s in enumerate(steps):
+        if "walk" not in s:
+            continue
+        actor = s.get("actor")
+        entry_idx, uid = _walk_target(actor)
+        pt = _resolve_point(s["walk"], move_reg)
+        t = next_tag.get(actor, _conductor.WALK_TAG_BASE)
+        next_tag[actor] = t + 1
+        eb = _eb_edit.add_function(eb, entry_idx, t, _conductor.walk_tag_body(pt[0], pt[1], s.get("speed")))
+        walk_calls[i] = (uid, t)
+    # actors that walk inside a parallel group (>1 member) need a join tag (async-fork + sync-drain)
+    parallel_actors = set()
+    for g in _conductor.group_parallel(steps):
+        if len(g) > 1:
+            parallel_actors |= {s.get("actor") for _i, s in g if "walk" in s and s.get("actor")}
+    for actor in sorted(parallel_actors):
+        entry_idx, uid = _walk_target(actor)
+        if entry_idx is None:
+            continue
+        eb = _eb_edit.add_function(eb, entry_idx, _conductor.PARALLEL_JOIN_TAG, _conductor.join_tag_body())
+        join_tags[uid] = _conductor.PARALLEL_JOIN_TAG
+    return eb, walk_calls, join_tags
+
+
 def _inject_verbatim_conductor(project: FieldProject, eb: bytes, npc_slots: dict, cutscene_txids, *, warnings) -> bytes:
     """Inject a MULTI-ACTOR ``[cutscene]`` conductor into a VERBATIM fork: ONE director code entry, seated
     BELOW the donor's party band (so the 9 characters stay the top slots), that drives the additive ``[[npc]]``
@@ -3263,22 +3336,8 @@ def _inject_verbatim_conductor(project: FieldProject, eb: bytes, npc_slots: dict
         return eb
     steps = _resolve_conductor_steps(cs["steps"], project)
     # walk beats -> a walk-choreography tag on the actor's below-band entry, RunScript'd by the conductor (the
-    # synth path's mechanism; here the actor entries sit below the band). add_function grows the entry but slot
-    # INDICES are stable, so the conductor's by-uid refs (and the later band insert) stay valid.
-    walk_calls = {}
-    if any("walk" in s for s in steps):
-        from .eb import edit as _eb_edit
-        move_reg = _position_registry(project)
-        next_tag = {}
-        for i, s in enumerate(steps):
-            if "walk" not in s:
-                continue
-            slot = npc_slots.get(s.get("actor"))                 # validated to be a real NPC actor (not player)
-            pt = _resolve_point(s["walk"], move_reg)
-            t = next_tag.get(s["actor"], _conductor.WALK_TAG_BASE)
-            next_tag[s["actor"]] = t + 1
-            eb = _eb_edit.add_function(eb, slot, t, _conductor.walk_tag_body(pt[0], pt[1], s.get("speed")))
-            walk_calls[i] = (slot, t)
+    # synth path's mechanism; here the actor entries sit below the band); a parallel walk also gets a join tag.
+    eb, walk_calls, join_tags = _gen_conductor_walk_tags(project, eb, steps, npc_slots)
     auto = _FlagAlloc(getattr(project, "flag_base", None))   # campaign-safe once-flag (matches the other verbatim blocks)
     c_fclass, c_fidx = _cutscene.once_flag_for(cs)
     if auto.base is not None and "flag" not in cs and cs.get("once", True):
@@ -3289,7 +3348,7 @@ def _inject_verbatim_conductor(project: FieldProject, eb: bytes, npc_slots: dict
         warmup=int(cs.get("warmup", _cutscene.DEFAULT_WARMUP)),
         owns_control=bool(cs.get("owns_control", True)),
         exit_warp=(int(cs["exit_warp"]) if cs.get("exit_warp") else None),
-        walk_calls=walk_calls, reserve_party_band=True)
+        walk_calls=walk_calls, join_tags=join_tags, reserve_party_band=True)
 
 
 def _inject_verbatim_props(project: FieldProject, eb: bytes, prop_txids=None, *, warnings) -> bytes:
@@ -3351,6 +3410,11 @@ def _inject_verbatim_gateways(project: FieldProject, eb: bytes, *, warnings) ->
         zone = gw["zone"]
         if len(zone) == 4:
             zone = _gw.quad_zone(zone)
+        if gw.get("ate"):                               # a forced-ATE warp-in, seated below the party band
+            eb = _cutscene.inject_forced_ate(eb, [tuple(p) for p in zone], int(gw["to"]),
+                                             mode=int(gw.get("ate_mode", _cutscene.ATE_DEFAULT_MODE)),
+                                             reserve_party_band=True)
+            continue
         gf, gs = _gate_of(gw)
         eb = _gw.inject_gateway(eb, int(gw["to"]), entrance=int(gw.get("entrance", 0)),
                                 zone=[tuple(p) for p in zone], gate_flag=gf, gate_require_set=gs,
@@ -3391,12 +3455,14 @@ def build_script(project: FieldProject, lang: str, dialogue_txids: dict,
                  control_value: int = -1, event_txids: dict | None = None,
                  cutscene_txids: list | None = None, walkmesh=None,
                  choice_txids: dict | None = None, on_entry_txids: dict | None = None,
-                 ate_txids: dict | None = None, chest_txids: dict | None = None) -> bytes:
+                 ate_txids: dict | None = None, chest_txids: dict | None = None,
+                 gateway_txids: dict | None = None) -> bytes:
     """Build one language's .eb by applying the project's content to the blank field."""
     _auto = _FlagAlloc(getattr(project, "flag_base", None))
     event_txids = event_txids or {}
     cutscene_txids = cutscene_txids or []
     choice_txids = choice_txids or {}
+    gateway_txids = gateway_txids or {}
     on_entry_txids = on_entry_txids or {}
     ate_txids = ate_txids or {}
     chest_txids = chest_txids or {}
@@ -3557,10 +3623,15 @@ def build_script(project: FieldProject, lang: str, dialogue_txids: dict,
 
     # gateways
     gw_names = _story_names(project)                    # [[flag]] name -> index, for set_flags resolution
-    for gw in project.raw.get("gateway", []):
+    for gi, gw in enumerate(project.raw.get("gateway", [])):
         zone = gw["zone"]
         if len(zone) == 4:
             zone = _gw.quad_zone(zone)
+        if gw.get("ate"):                               # a forced-ATE warp-in: grey banner WARNING + title, then warp
+            eb = _cutscene.inject_forced_ate(eb, [tuple(p) for p in zone], int(gw["to"]),
+                                             mode=int(gw.get("ate_mode", _cutscene.ATE_DEFAULT_MODE)),
+                                             title_txid=gateway_txids.get(gi))
+            continue
         gf, gs = _gate_of(gw)
         eb = _gw.inject_gateway(eb, int(gw["to"]), entrance=int(gw.get("entrance", 0)),
                                 zone=[tuple(p) for p in zone], gate_flag=gf, gate_require_set=gs,
@@ -3705,29 +3776,16 @@ def build_script(project: FieldProject, lang: str, dialogue_txids: dict,
         if _auto.base is not None and "flag" not in cs and cs.get("once", True):
             c_fidx = _auto.cutscene()                          # campaign: pack into this member's flag block
         # walk beats can't run inline (base Walk acts on the EXECUTING object; there's no targeted WalkEx),
-        # so generate a per-actor walk-choreography TAG on the actor's own [[npc]] entry and RunScript into
-        # it (animates in the actor's context, blocks until arrival). walk_calls: step index -> (uid, tag).
-        walk_calls = {}
-        if any("walk" in s for s in c_steps):
-            from .eb import edit as _eb_edit
-            move_reg = _position_registry(project)
-            next_tag = {}                                      # actor name -> next free walk tag
-            for i, s in enumerate(c_steps):
-                if "walk" not in s:
-                    continue
-                slot = npc_slots.get(s.get("actor"))           # validated to be a real NPC actor (not player)
-                pt = _resolve_point(s["walk"], move_reg)
-                t = next_tag.get(s["actor"], _conductor.WALK_TAG_BASE)
-                next_tag[s["actor"]] = t + 1
-                eb = _eb_edit.add_function(eb, slot, t, _conductor.walk_tag_body(pt[0], pt[1], s.get("speed")))
-                walk_calls[i] = (slot, t)
+        # so generate a per-actor walk-choreography TAG on the actor's own [[npc]] entry and RunScript into it
+        # (animates in the actor's context, blocks until arrival); a parallel walk also gets a join tag.
+        eb, walk_calls, join_tags = _gen_conductor_walk_tags(project, eb, c_steps, npc_slots)
         eb = _conductor.inject_conductor(
             eb, c_steps, npc_slots, cutscene_txids,
             once_flag=(c_fidx if cs.get("once", True) else None), flag_class=c_fclass,
             warmup=int(cs.get("warmup", _cutscene.DEFAULT_WARMUP)),
             owns_control=bool(cs.get("owns_control", True)),
             exit_warp=(int(cs["exit_warp"]) if cs.get("exit_warp") else None),
-            say_flags=cs_say_flags, walk_calls=walk_calls)
+            say_flags=cs_say_flags, walk_calls=walk_calls, join_tags=join_tags)
 
     # cutscene (narration, no actor): an ordered, control-locked sequence on entry (once), run as a
     # standalone director code entry. Steps = say / wait / set_flag. An ACTOR cutscene was already
@@ -4133,17 +4191,40 @@ def _validate_conductor(project, cs, problems):
                             _animations.resolve(token, a)
                         except ValueError as e:
                             problems.append(f"[cutscene] step {k}: {e}")
-            if act == "walk":
-                if who == "player":                            # player-walk needs a tag on the player entry -- deferred
-                    problems.append(f"[cutscene] step {k}: walk is not yet supported for \"player\" (only [[npc]] "
-                                    f"actors can walk in a cutscene for now); use turn/anim/say on the player.")
-                try:
+            if act == "walk":                                  # walk on "player" runs in the player's own
+                try:                                           # entry (uid 250); an [[npc]] in its slot entry
                     _resolve_point(s["walk"], move_reg)        # [x, z] or a known marker/NPC name
                 except ValueError as e:
                     problems.append(f"[cutscene] step {k}: {e}")
             t = s.get("tail")
             if t is not None and t not in _text.TAIL_CODES:
                 problems.append(f"[cutscene] step {k} tail {t!r} is not a valid TAIL code")
+        # parallel beats (with_prev): a step marked with_prev runs together with the preceding beat. Only
+        # walk/anim/turn can run in parallel (say/wait/set_flag are sequential barriers), the group leader
+        # must be one of those too, and no actor may act twice in a group (it has one execution context).
+        if steps[0].get("with_prev"):
+            problems.append("[cutscene] step 0 can't have with_prev = true (nothing precedes it)")
+        _par_ok = ("walk", "anim", "turn")
+        for g in _conductor.group_parallel(steps):
+            if len(g) < 2:
+                continue
+            lead_k, lead_s = g[0]
+            lead_act = next((key for key in _par_ok if key in lead_s), None)
+            if lead_act is None:
+                problems.append(f"[cutscene] step {lead_k} has a with_prev beat after it but is a "
+                                f"say/wait/set_flag (a sequential barrier) -- only walk/anim/turn run in parallel")
+            seen = {lead_s.get("actor")} if lead_act else set()
+            for k, s in g[1:]:
+                act = next((key for key in _par_ok if key in s), None)
+                if act is None:
+                    problems.append(f"[cutscene] step {k}: only walk/anim/turn can run with_prev "
+                                    f"(say/wait/set_flag are sequential barriers)")
+                    continue
+                who = s.get("actor")
+                if who in seen:
+                    problems.append(f"[cutscene] step {k}: actor {who!r} already acts in this parallel group "
+                                    f"(an actor can't do two things at once)")
+                seen.add(who)
     if "exit_warp" in cs:
         ew = cs["exit_warp"]
         if not (isinstance(ew, int) and not isinstance(ew, bool) and ew > 0):
@@ -4432,8 +4513,9 @@ def _wrap_width(project: FieldProject):
 
 def collect_text(project: FieldProject):
     """Return (mes_body, npc_txids, event_txids, cutscene_txids, choice_txids, on_entry_txids, ate_txids,
-    chest_txids). All field text (NPC dialogue, event messages, cutscene 'say' lines, choice prompts +
-    replies, on-entry messages, the ATE menu, chest "Received X" boxes) shares one .mes block, in that order
+    chest_txids, gateway_txids). All field text (NPC dialogue, event messages, cutscene 'say' lines, choice
+    prompts + replies, on-entry messages, the ATE menu, chest "Received X" boxes, forced-ATE gateway titles)
+    shares one .mes block, in that order
     (so a field with no events/cutscene/choices/on_entry/ate/chests is byte-identical to the old layout).
     ``cutscene_txids`` is a list (one per 'say' step); ``choice_txids[c]`` = ``{"prompt": id, "replies":
     {opt_index: id}}``; ``on_entry_txids[k]`` = the txid of hook ``k``'s message (only for hooks that have
@@ -4521,8 +4603,20 @@ def collect_text(project: FieldProject):
     for k, ch in enumerate(project.raw.get("chest", [])):
         text, strt, tail = _chest_received_box(ch)
         ch_pos[k] = _add_raw(text, ch.get("tail") or tail, strt=strt)
+    # forced-ATE gateway titles: the winATE-captioned, CENTERED "title window" a `[[gateway]] ate = true` shows
+    # as it warps. Geometry verified vs real grey ATEs 956/2211: `[STRT=W,1][IMME][CENT=W]title` -- the engine
+    # auto-centers a system window from its [STRT] width (like the chest box) + [CENT] centers the text + [IMME]
+    # pops it fully drawn. W ~ the rendered text width (real STRT ~= text.measure * 7.2). The default dialogue
+    # geometry (10,1)+TAIL=UPR pins it TOP-RIGHT (the reported bug). Added LAST (after chests) -> byte-identical
+    # for a field without one.
+    gw_pos = {}
+    for gi, gw in enumerate(project.raw.get("gateway", [])):
+        if gw.get("ate") and gw.get("ate_title"):
+            _title = str(gw["ate_title"])
+            _w = max(8, round(_text.measure(_title) * 7.2))   # ~ the FF9 STRT width of the rendered title
+            gw_pos[gi] = _add_raw(f"[IMME][CENT={_w}]{_title}", "", strt=(_w, 1))   # NO tail -> the real ATE's true centre
     if not lines:
-        return "", {}, {}, [], {}, {}, {}, {}
+        return "", {}, {}, [], {}, {}, {}, {}, {}
     body, mapping = _text.build_mes(lines, start_txid=_text.DEFAULT_BASE_TXID, tails=tails, strts=strts)
     npc_txids = {i: mapping[p] for i, p in npc_pos.items()}
     event_txids = {j: mapping[p] for j, p in ev_pos.items()}
@@ -4536,7 +4630,9 @@ def collect_text(project: FieldProject):
                   "replies": {oi: mapping[p] for oi, p in ate_reply_pos.items()}}
                  if ate_prompt_pos is not None else {})
     chest_txids = {k: mapping[p] for k, p in ch_pos.items()}
-    return body, npc_txids, event_txids, cutscene_txids, choice_txids, on_entry_txids, ate_txids, chest_txids
+    gateway_txids = {gi: mapping[p] for gi, p in gw_pos.items()}   # forced-ATE title-window txids (by gw index)
+    return (body, npc_txids, event_txids, cutscene_txids, choice_txids, on_entry_txids, ate_txids,
+            chest_txids, gateway_txids)
 
 
 # --------------------------------------------------------------------------- the build
@@ -4717,7 +4813,7 @@ def build_field(project: FieldProject, layout: ModLayout, *, langs=LANGS) -> Fie
 
     _autofill_ladder_landing_y(project, cutscene_wmesh)   # elevated dismount floors get their real Y
     # --- dialogue + per-language script ---
-    mes_body, txids, event_txids, cutscene_txids, choice_txids, on_entry_txids, ate_txids, chest_txids = collect_text(project)
+    mes_body, txids, event_txids, cutscene_txids, choice_txids, on_entry_txids, ate_txids, chest_txids, gateway_txids = collect_text(project)
     control_value = resolve_control_value(project, camera)
     # faithful text carry: the donor's referenced dialogue, shipped VERBATIM per language and APPENDED after
     # the authored block (its own [TXID=>=1000] re-index keeps it disjoint -- authored text + the hut golden
@@ -4923,7 +5019,7 @@ def build_field(project: FieldProject, layout: ModLayout, *, langs=LANGS) -> Fie
             eb = build_script(project, lang, txids, control_value, event_txids=event_txids,
                               cutscene_txids=cutscene_txids, walkmesh=cutscene_wmesh,
                               choice_txids=choice_txids, on_entry_txids=on_entry_txids,
-                              ate_txids=ate_txids, chest_txids=chest_txids)
+                              ate_txids=ate_txids, chest_txids=chest_txids, gateway_txids=gateway_txids)
             base = mes_body or ""
             inplace = base
             suffix = ""

{ff9mapkit-1.0.0b3 → ff9mapkit-1.0.0b4}/ff9mapkit/cli.py

@@ -30,6 +30,7 @@ Subcommands are wired up incrementally as the library lands:
     models/scenes/catalog - the Info Hub: browse models (+ their animations), battle scenes, or
                             search every reference catalog by name
     extract-templates - regenerate base assets from the user's own FF9 install (no game data shipped)
+    setup     - one-shot: find the FF9 install, remember it, extract base assets, report Memoria status
 
 Anything not yet implemented prints a clear "coming in Phase N" message rather than failing
 with an import error, so the installed console script is always runnable.
@@ -104,6 +105,80 @@ def _cmd_extract_templates(args: argparse.Namespace) -> int:
     return 0
 
 
+def _cmd_setup(args: argparse.Namespace) -> int:
+    """One-shot post-install setup: find the FF9 install, remember it in the user config, regenerate the
+    base assets, and report the Memoria engine status. ``--install-engine <zip>`` additionally installs the
+    Dream World IX engine bundle (backed up first). Safe to re-run; returns non-zero only so a calling
+    script (e.g. the installer) can tell -- it never needs to block."""
+    from . import memoria, provision
+    from .config import save_game_path
+
+    # 1) resolve the install, and remember it so future commands need no --game/$FF9_GAME_PATH
+    try:
+        game = find_game_path(args.game)
+    except ConfigError as e:
+        print(str(e), file=sys.stderr)
+        print("\nOnce you know the path, run:  ff9mapkit setup --game \"<path>\"", file=sys.stderr)
+        return 2
+    print(f"Found FINAL FANTASY IX:  {game}")
+    try:
+        cfg = save_game_path(game)
+        print(f"  remembered in {cfg}  (future commands won't need --game)")
+    except OSError as e:                                  # noqa: BLE001 - config write is best-effort
+        print(f"  (couldn't save the config: {e})", file=sys.stderr)
+
+    rc = 0
+    # 2) regenerate the base assets (the one-time bring-your-own-install step; reads YOUR install)
+    if not args.no_extract:
+        if provision.templates_present() and not args.force:
+            print("Base assets:  already extracted (use --force to redo).")
+        elif not _has_unitypy():
+            print("Base assets:  SKIPPED -- UnityPy isn't installed (it reads FF9's assetbundles).\n"
+                  "  Install it:  pip install UnityPy   (or reinstall ff9mapkit with the [assets] extra)",
+                  file=sys.stderr)
+            rc = 1
+        else:
+            print("Base assets:  regenerating from your install (ff9mapkit ships no game data)...")
+            try:
+                rep = provision.extract_templates(game=str(game), fixtures=not args.no_fixtures, verbose=True)
+                print(f"  OK -- {len(rep['verified'])} assets regenerated + verified.")
+            except Exception as e:                       # noqa: BLE001
+                print(f"  extract-templates failed: {e}", file=sys.stderr)
+                rc = 1
+
+    # 3) Memoria engine status (forked fields need it; novel/from-scratch fields run on stock Memoria)
+    st = memoria.memoria_status(game)
+    if st["installed"]:
+        print("Memoria engine:  detected -- forked real fields will work.")
+    else:
+        print("Memoria engine:  NOT detected.")
+        print("  From-scratch / BG-borrow fields run on stock Memoria. To play FORKED real fields, install\n"
+              "  Memoria + the Dream World IX engine bundle (dwix-custom-memoria-*.zip) -- see docs/ENGINE.md,\n"
+              "  or re-run:  ff9mapkit setup --install-engine <bundle.zip>")
+
+    # 4) opt-in: install the engine bundle (backed up; never touches Memoria.ini)
+    if args.install_engine:
+        zp = Path(args.install_engine)
+        if not zp.is_file():
+            print(f"--install-engine: file not found: {zp}", file=sys.stderr)
+            return 1
+        import datetime  # noqa: PLC0415
+        stamp = datetime.datetime.now().strftime("%Y%m%d-%H%M%S")
+        print(f"Engine bundle:  installing {zp.name} (backing up the originals first)...")
+        try:
+            rep = memoria.install_engine_bundle(game, zp, stamp=stamp)
+            print(f"  backed up {len(rep['backed_up'])} DLL(s) -> {rep['backup_root']}")
+            print(f"  installed {len(rep['installed'])} DLL(s) into x64 + x86 Managed.")
+            print("  Relaunch FF9 to load it.  (Undo: copy the backup DLLs back over the Managed ones.)")
+        except Exception as e:                           # noqa: BLE001
+            print(f"  engine install failed: {e}", file=sys.stderr)
+            return 1
+
+    if rc == 0:
+        print("\nSetup complete.  Try 'ff9mapkit doctor', or open the GUI with 'ff9mapkit-workspace'.")
+    return rc
+
+
 def _cmd_disasm(args: argparse.Namespace) -> int:
     from .eb import EbScript
 
@@ -3101,6 +3176,17 @@ def build_parser() -> argparse.ArgumentParser:
     xt.add_argument("--no-fixtures", action="store_true", help="skip the test fixtures (templates only)")
     xt.set_defaults(func=_cmd_extract_templates)
 
+    su = sub.add_parser("setup",
+                        help="one-shot post-install setup: find your FF9 install, remember it, extract base "
+                             "assets, report Memoria status (--install-engine ZIP to install the engine bundle)")
+    su.add_argument("--install-engine", metavar="ZIP", default=None,
+                    help="also install the Dream World IX engine bundle (dwix-custom-memoria-*.zip) -- backs "
+                         "up the originals; needed only to play FORKED real fields")
+    su.add_argument("--force", action="store_true", help="re-extract the base assets even if already present")
+    su.add_argument("--no-extract", action="store_true", help="skip the base-asset extraction step")
+    su.add_argument("--no-fixtures", action="store_true", help="skip test fixtures during extraction")
+    su.set_defaults(func=_cmd_setup)
+
     return p
 
 

{ff9mapkit-1.0.0b3 → ff9mapkit-1.0.0b4}/ff9mapkit/config.py

@@ -19,6 +19,7 @@ offline (build into a temp dir, diff against the deployed assets).
 from __future__ import annotations
 
 import os
+import re
 from dataclasses import dataclass
 from pathlib import Path
 
@@ -60,6 +61,25 @@ def _read_user_config() -> dict:
         return {}
 
 
+def save_game_path(game_path: str | os.PathLike) -> Path:
+    """Persist ``game_path`` into the user config (``~/.ff9mapkit.toml``) so later commands resolve the
+    install without ``--game`` / ``$FF9_GAME_PATH``. Surgical: rewrites only the ``game_path`` line and
+    preserves any other keys/comments. Stores the path with forward slashes so the TOML basic string can
+    never trip a backslash escape on Windows (``Path`` reads forward slashes fine). Returns the config path.
+    """
+    p = str(Path(game_path).resolve()).replace("\\", "/")
+    line = f'game_path = "{p}"'
+    existing = USER_CONFIG.read_text(encoding="utf-8") if USER_CONFIG.is_file() else ""
+    if re.search(r"(?m)^[ \t]*game_path[ \t]*=", existing):
+        new = re.sub(r"(?m)^[ \t]*game_path[ \t]*=.*$", line, existing)
+    elif existing.strip():
+        new = existing.rstrip("\n") + "\n" + line + "\n"
+    else:
+        new = line + "\n"
+    USER_CONFIG.write_text(new, encoding="utf-8")
+    return USER_CONFIG
+
+
 def find_game_path(explicit: str | os.PathLike | None = None) -> Path:
     """Resolve the Final Fantasy IX install folder.