ff9mapkit 1.0.0b3__py3-none-any.whl

ff9mapkit/pack.py

@@ -0,0 +1,175 @@
+"""Field-ID allocation + mod packaging + project scaffolding.
+
+Custom field IDs and FBG names form a shared namespace across all installed mods, so two
+independently-authored mods must not collide. There is no central registry, so the convention
+is: custom fields use ids >= :data:`CUSTOM_ID_MIN`, and a mod claims a contiguous *block*.
+:func:`suggest_base` derives a deterministic per-mod block from the mod name (reducing the odds
+of an accidental clash); for a public release, coordinate the block with the community.
+
+:func:`pack_mod` zips a built mod for distribution; :func:`new_project` scaffolds a fresh
+``field.toml`` project directory.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import zipfile
+from pathlib import Path
+
+CUSTOM_ID_MIN = 4000          # shipped-content custom field ids start here (below this is base-game territory)
+CUSTOM_ID_MAX = 9899          #   ...content blocks live in [CUSTOM_ID_MIN..CUSTOM_ID_MAX]
+BLOCK_SIZE = 100              # ids per mod block
+# HARD engine cap: the live current-field id (engine `FF9StateSystem.Common.FF9.fldMapNo`) is Int16, so a
+# field id above FIELD_ID_MAX overflows and is unreachable -- the DictionaryPatch *key* is Int32, but the
+# runtime current-field variable is 16-bit (FF9Snd.cs:2651), so you can register a higher id yet never
+# navigate to it. Ephemeral dev/test "scratch" slots (per-worktree, gitignored .ff9deploy.toml) sit in
+# [SCRATCH_ID_MIN..SCRATCH_ID_MAX] -- the top of the valid range, clearly ABOVE shipped content.
+FIELD_ID_MAX = 32767
+SCRATCH_ID_MIN = 30000
+SCRATCH_ID_MAX = FIELD_ID_MAX
+
+
+def suggest_base(mod_name: str) -> int:
+    """A deterministic custom-field-id block base for a mod name (e.g. 4300).
+
+    Hashes the name into one of the 100-id blocks in [CUSTOM_ID_MIN, CUSTOM_ID_MAX]. Two
+    different names usually land in different blocks; collisions should be resolved by hand for
+    a public release.
+    """
+    n_blocks = (CUSTOM_ID_MAX - CUSTOM_ID_MIN) // BLOCK_SIZE
+    h = int.from_bytes(hashlib.sha1(mod_name.encode("utf-8")).digest()[:4], "big")
+    return CUSTOM_ID_MIN + (h % n_blocks) * BLOCK_SIZE
+
+
+def suggest_ids(base: int, count: int) -> list[int]:
+    """``count`` consecutive ids from ``base`` (validated to stay in the custom range)."""
+    if base < CUSTOM_ID_MIN or base + count - 1 > CUSTOM_ID_MAX:
+        raise ValueError(f"id block [{base}..{base + count - 1}] outside custom range "
+                         f"[{CUSTOM_ID_MIN}..{CUSTOM_ID_MAX}]")
+    return [base + i for i in range(count)]
+
+
+def pack_mod(mod_root, out_path) -> Path:
+    """Zip a built mod folder for distribution. Returns the zip path.
+
+    The archive contains the mod folder itself (so unzipping next to FF9_Launcher.exe installs
+    it). Skips ``*.bak`` and editor leftovers.
+    """
+    mod_root = Path(mod_root).resolve()
+    if not mod_root.is_dir():
+        raise FileNotFoundError(mod_root)
+    out_path = Path(out_path)
+    with zipfile.ZipFile(out_path, "w", zipfile.ZIP_DEFLATED) as zf:
+        for p in sorted(mod_root.rglob("*")):
+            if p.is_dir() or p.suffix in (".bak",) or p.name.endswith(".prefix.bak"):
+                continue
+            zf.write(p, arcname=str(Path(mod_root.name) / p.relative_to(mod_root)))
+    return out_path
+
+
+_FIELD_TOML_TEMPLATE = '''\
+# {title} — a custom FF9 field. Compile with:  ff9mapkit build {fname}
+#
+# Human-supplied (Hard Constraint): paint the background layer PNGs and (optionally) model the
+# walkmesh in Blender. `ff9mapkit guide --pitch {pitch} ...` prints where the floor lands on
+# the painted canvas so you can paint to match.
+
+[field]
+id = {field_id}          # custom field id (>= 4000; claim a block for your mod, see docs)
+name = "{name}"          # -> FBG_N{area}_{name} (background) + EVT_{name}.eb (script)
+area = {area}            # must be >= 10
+text_block = 1073
+title = "{title}"
+
+[camera]
+pitch = {pitch}          # downward tilt (degrees); real FF9 fields are <= ~48
+distance = 4500
+fov = 42.2
+[camera.frame]
+back = 205               # painted-canvas rows the floor's back/front edges sit on
+front = 432
+
+[walkmesh]
+# The walkmesh is in TRUE world coords = where the painted floor is (frame = "world"): the player
+# renders exactly on it, no fudge (measured in-game, Session 18). `quad` = the floor's 4 corners,
+# matching the placeholder floor below. Swap for an exported Blender mesh with `obj = "walkmesh.obj"`.
+quad = {quad}
+frame = "world"
+
+[[layers]]               # background layers, back-to-front (z = depth; smaller = nearer)
+image = "art/back.png"   # PLACEHOLDER (solid) -- repaint to match your camera
+z = 4000
+[[layers]]
+image = "art/floor.png"  # PLACEHOLDER (checkerboard floor) -- repaint to match your camera
+z = 3000
+
+[player]
+spawn = [0, {spawn_z}]
+
+# [[npc]]
+# name = "Someone"
+# preset = "vivi"
+# pos = [0, -700]
+# dialogue = "Hello there."
+
+# [[gateway]]
+# to = 100               # warp to this field id
+# entrance = 0
+# zone = [[-1100, -2400], [1100, -2400], [1100, -1750], [-1100, -1750]]
+'''
+
+
+_DISTANCE, _FOV, _BACK, _FRONT = 4500.0, 42.2, 205, 432   # template camera defaults (match the toml)
+
+
+def new_project(name: str, dest, *, field_id: int | None = None, area: int = 11,
+                pitch: float = 48.0, title: str | None = None, placeholder_art: bool = True) -> Path:
+    """Scaffold a new field project under ``dest/<name>/``. Returns the project dir.
+
+    With ``placeholder_art`` (default), derives the walkmesh quad from the template camera frame and
+    writes PLACEHOLDER ``art/back.png`` + ``art/floor.png`` (pure stdlib, no PIL) so the project
+    BUILDS and is walkable straight away -- the human then replaces the art with painted layers. If
+    the camera frame can't be solved (an extreme ``pitch``), falls back to a no-art scaffold.
+    """
+    title = title or name
+    if field_id is None:
+        field_id = suggest_base(name)
+    proj_dir = Path(dest) / name
+    (proj_dir / "art").mkdir(parents=True, exist_ok=True)
+    fname = f"{name.lower()}.field.toml"
+
+    quad = [[-1400, -2400], [1400, -2400], [1400, -800], [-1400, -800]]   # fallback
+    spawn_z = -1350
+    wrote_art = False
+    if placeholder_art:
+        try:
+            from .scene import guide, placeholder
+            camera = guide.make_camera(pitch, _DISTANCE, fov_x_deg=_FOV)
+            frame = guide.frame_floor(camera, back_canvas_y=_BACK, front_canvas_y=_FRONT)
+            quad = [[int(x), int(z)] for (x, z) in guide.walkmesh_corners(frame)]
+            spawn_z = int(round((frame.zb + frame.zf) / 2))
+            placeholder.write_placeholders(camera, frame, proj_dir / "art" / "back.png",
+                                           proj_dir / "art" / "floor.png")
+            wrote_art = True
+        except (ValueError, ZeroDivisionError):
+            pass   # extreme camera -> keep the fallback quad + no placeholder art
+
+    quad_toml = "[" + ", ".join(f"[{x}, {z}]" for x, z in quad) + "]"
+    (proj_dir / fname).write_text(
+        _FIELD_TOML_TEMPLATE.format(name=name, area=area, field_id=field_id, pitch=pitch,
+                                    title=title, fname=fname, quad=quad_toml, spawn_z=spawn_z),
+        encoding="utf-8", newline="\n")
+    if wrote_art:
+        readme = (
+            "PLACEHOLDER background art (back.png = solid slate, floor.png = perspective checkerboard)\n"
+            "was generated by `ff9mapkit new` so the project builds + is walkable right away.\n"
+            "REPLACE back.png and floor.png with your painted layers (same size/aspect).\n\n"
+            "Run  ff9mapkit guide --pitch <p> --png guide.png  for a paint guide showing exactly\n"
+            "where the floor + its edges land on the canvas for your camera.\n")
+    else:
+        readme = (
+            "Place your painted background layer PNGs here (back.png, floor.png, ...).\n"
+            "Run  ff9mapkit guide --pitch <p> --png guide.png  to get a paint guide that shows\n"
+            "exactly where the floor and its edges land on the canvas for your camera.\n")
+    (proj_dir / "art" / "README.txt").write_text(readme, encoding="utf-8", newline="\n")
+    return proj_dir

ff9mapkit/playerswap.py

@@ -0,0 +1,231 @@
+"""Swap who you WALK as in a forked field -- patch the player entry's ``SetModel`` + movement anim ids to a
+different rig: one of the 8 PLAYABLES (a proven home-field table) or ANY registered model -- a moogle, an NPC,
+a creature -- resolved through the kit's model->animation join (:func:`catalog.npc_anims`). The latter is the
+field-side bridge toward CUSTOM characters: a custom model would be driven by exactly this path.
+
+Field control (who you walk as) is DECOUPLED from party state (the menu/battle roster), so this changes only
+the field-controlled character; the party is untouched (use a party-membership op for that). It is the
+productionized form of the in-game-proven Tier-A probe: a same-length, width-aware byte patch of the player
+entry's tag-0 Init -- ``.eb``-only, no DLL (memory ``project-ff9-pc-party-system`` / ``project-ff9-non-zidane-donors``).
+
+:data:`CHARACTERS` holds each playable's canonical field player-Init values (model id + eye-height + the
+movement clips), EXTRACTED from that character's own home field. The animation ids are rig-partitioned -- the
+engine does NOT translate a Zidane clip id onto another rig -- so every movement clip the field's player Init
+sets must be repointed to the target rig (else a wrong-skeleton anim / T-pose).
+
+CAVEAT -- free-roam vs cutscene fields: this swaps only the 6 MOVEMENT clips (idle/walk/run/turns), which is
+everything a free-roam field needs (proven clean: walk Quina/Steiner around the Hangar). But a STORY-EVENT
+field can make the PLAYER play scripted GESTURES in a cutscene via ``RunAnimation`` (0x40) with a specific
+clip id -- that id is NOT swapped, so it would try to play the ORIGINAL rig's clip on the new model and
+glitch/T-pose. So ``--swap-player`` is clean on free-roam fields and cosmetic-and-risky on cutscene-heavy
+ones; :func:`scripted_gesture_ops` flags that risk. For STORY fidelity (be a character THROUGH the story),
+the right tool is a verbatim fork at the right beat with the right party, not a model swap.
+"""
+from __future__ import annotations
+
+from .eb import EbScript
+from .eb.disasm import argsize
+
+SETMODEL_OP = 0x2F
+ANIM_OPS = {0x33: "idle", 0x34: "walk", 0x35: "run", 0x7A: "left", 0x7B: "right", 0x52: "inactive"}
+RUN_ANIM_OPS = frozenset({0x40, 0xBD})   # RunAnimation / RunAnimationEx -- scripted gesture plays (rig-specific)
+ZIDANE_LEADER_MODELS = frozenset({98, 532})   # the controllable Zidane FIELD forms (ZDN + ZDD disguise)
+
+
+class NoSwappablePlayer(ValueError):
+    """No player entry has a ``SetModel`` to swap (a benign per-member skip in a chain). A subclass of
+    ValueError so existing handlers still catch it, but distinguishable from a real patch/corruption error."""
+
+# Canonical field player-Init values per playable, read from each character's home field (model, eye-height,
+# movement clips). idle/walk/run/left/right exist for all 8; ``inactive`` (the idle-break) only where the home
+# field set a generic one -- :func:`swap_player` falls back to ``idle`` for a clip the target lacks (a valid
+# clip on that rig). Verified in-game for Steiner (the Tier-A probe).
+CHARACTERS = {
+    "zidane":  {"model": 98,   "eye": 93,  "idle": 200,  "walk": 25,   "run": 38,   "left": 40,   "right": 41,   "inactive": 57},
+    "vivi":    {"model": 8,    "eye": 61,  "idle": 148,  "walk": 571,  "run": 419,  "left": 917,  "right": 918,  "inactive": 912},
+    "steiner": {"model": 5489, "eye": 104, "idle": 2001, "walk": 1996, "run": 2005, "left": 1986, "right": 2010, "inactive": 119},
+    "garnet":  {"model": 185,  "eye": 91,  "idle": 2089, "walk": 2086, "run": 2091, "left": 2088, "right": 2084},
+    "freya":   {"model": 192,  "eye": 94,  "idle": 2556, "walk": 2553, "run": 2558, "left": 2555, "right": 2551},
+    "quina":   {"model": 273,  "eye": 92,  "idle": 3228, "walk": 3237, "run": 3230, "left": 3235, "right": 3227},
+    "eiko":    {"model": 443,  "eye": 63,  "idle": 7503, "walk": 7518, "run": 7506, "left": 7516, "right": 7514},
+    "amarant": {"model": 509,  "eye": 122, "idle": 8307, "walk": 8316, "run": 8312, "left": 8310, "right": 8314},
+}
+ALIASES = {"dagger": "garnet", "salamander": "amarant"}
+
+
+def resolve_char(name):
+    """``(canonical_name, spec)`` for a swap target. A playable name (zidane..amarant; aliases ``dagger``->
+    garnet, ``salamander``->amarant) returns its proven home-field rig table. ANY OTHER registered model -- a
+    ``GEO_..`` name or a numeric id (a moogle, an NPC, a creature) -- returns a spec built from the kit's
+    model->animation join (:func:`catalog.npc_anims`), so you can walk as it: the field-side bridge to custom
+    characters (a custom model would use the same path). ``spec`` always has ``model`` + the movement clips;
+    a playable also carries ``eye`` + ``inactive``. Raises ``ValueError`` on an unknown target or a model with
+    no movement animations (e.g. a static monster)."""
+    k = ALIASES.get(str(name).lower().strip(), str(name).lower().strip())
+    if k in CHARACTERS:
+        return k, CHARACTERS[k]
+    from . import catalog
+    try:
+        mid = catalog.resolve_model(name)
+    except Exception:
+        raise ValueError("unknown swap target %r -- a playable (%s; aliases dagger, salamander) or a model "
+                         "name/id (see `ff9mapkit models`)" % (name, ", ".join(sorted(CHARACTERS))))
+    na = catalog.npc_anims(mid)                          # {stand,walk,run,left,right} via the model->anim join
+    if not na:
+        from ._modeldb import MODELS
+        raise ValueError("model %s has no movement animations -- can't walk as it"
+                         % MODELS.get(mid, mid))
+    from ._modeldb import MODELS
+    spec = {"model": mid, "idle": na["stand"], "walk": na["walk"], "run": na["run"],
+            "left": na["left"], "right": na["right"]}    # no 'eye' (keep the field's) / no 'inactive' (-> idle)
+    return MODELS.get(mid, str(mid)), spec
+
+
+def _arg_off(ins, ai):
+    """Byte offset (relative to ``ins.off``) of literal operand ``ai`` -- opcode head + the argflag byte
+    (ops >= 0x10 with args) + the widths of the preceding operands."""
+    off = 2 if ins.op >= 0x100 else 1
+    if ins.op >= 0x10 and len(ins.args) != 0:
+        off += 1
+    for k in range(ai):
+        off += argsize(ins.op, k)
+    return off
+
+
+def _put_arg(out: bytearray, ins, ai: int, value: int) -> None:
+    """Overwrite literal operand ``ai`` of ``ins`` in ``out`` with ``value`` (little-endian, same width).
+    Raises ``ValueError`` if ``value`` doesn't fit the operand's byte width. Shared by swap_player +
+    neutralize_gestures -- a same-width in-place patch never shifts offsets."""
+    w = argsize(ins.op, ai)
+    if int(value) >= (1 << (8 * w)):
+        raise ValueError("value %d does not fit arg %d (%d byte(s)) of op %#x" % (value, ai, w, ins.op))
+    o = ins.off + _arg_off(ins, ai)
+    out[o:o + w] = int(value).to_bytes(w, "little")
+
+
+def _has_setmodel(eb, p):
+    init = eb.entry(p).func_by_tag(0)
+    return init is not None and any(i.op == SETMODEL_OP for i in eb.instrs(init))
+
+
+def leader_model(eb):
+    """The model of the character you actually CONTROL -- the swap target. On a ZIDANE-PRESENT field control
+    routes through the party SLOT to the Zidane party-leader, NOT the last-``DefinePlayerCharacter`` binder
+    (:func:`forkreport.controlled_player` mispredicts there -- it returns a co-actor on 66/169 such fields), so
+    target a Zidane field form (98/532) when one is defined. On a no-Zidane FIXED-SID field, use the proven
+    binder (Treno -> Garnet). Single-PC -> the one. Returns the model id, or ``None`` if no swappable entry."""
+    from . import eventscan, forkreport
+    pents = eventscan.resolve_player_entries(eb)
+    have = {p: eventscan._player_model(eb, p) for p in pents
+            if eventscan._player_model(eb, p) is not None and _has_setmodel(eb, p)}
+    if not have:
+        return None
+    zid = [m for m in have.values() if m in ZIDANE_LEADER_MODELS]
+    if zid:
+        return zid[0]                                   # Zidane-present -> you control the Zidane party-leader
+    ctrl = forkreport.controlled_player(eb)[0]          # no Zidane -> the proven last-0x2C binder
+    return have.get(ctrl, next(iter(have.values())))
+
+
+def swap_targets(eb):
+    """The player entries the swap patches = ALL entries whose Init ``SetModel`` == the controlled-leader model
+    (so a Zidane-present field hits the real leader -- not a companion -- and a duplicate leader entry is handled
+    too). Empty when no swappable entry exists."""
+    from . import eventscan
+    m = leader_model(eb)
+    if m is None:
+        return []
+    return [p for p in eventscan.resolve_player_entries(eb)
+            if eventscan._player_model(eb, p) == m and _has_setmodel(eb, p)]
+
+
+def _targets(eb, entry):
+    """Normalize the ``entry`` override to a list of player-entry indices: ``None`` -> :func:`swap_targets`,
+    a single int -> ``[int]``, an iterable -> ``list(it)``. Lets a caller PIN the target set computed on the
+    ORIGINAL bytes: ``swap_targets``/``leader_model`` key on the Init ``SetModel`` id, which ``swap_player``
+    MUTATES, so re-deriving the targets on the swapped bytes would drift to a different entry on a
+    Zidane-present multi-PC field (the gesture-neutralize-on-the-wrong-actor bug)."""
+    if entry is None:
+        return swap_targets(eb)
+    if isinstance(entry, int):
+        return [entry]
+    return list(entry)
+
+
+def scripted_gesture_ops(eb_bytes, *, entry=None) -> int:
+    """How many scripted-gesture ops (``RunAnimation``/``RunAnimationEx``) the player entry plays. These
+    reference the ORIGINAL rig's clips (the swap only repoints the 6 movement clips), so any count > 0 means
+    ``--swap-player`` will glitch those gestures on the new model -- i.e. the field is a cutscene-heavy one
+    where the swap is cosmetic-and-risky, not a clean free-roam swap. Used to WARN at swap time."""
+    eb = EbScript.from_bytes(eb_bytes)
+    targets = _targets(eb, entry)
+    return sum(1 for e in targets for f in eb.entry(e).funcs for i in eb.instrs(f) if i.op in RUN_ANIM_OPS)
+
+
+def swap_player(eb_bytes, char, *, entry=None) -> bytes:
+    """Patch the controlled-leader player entr(ies)' Init ``SetModel`` + movement anim ids to ``char``'s rig
+    (same-length, width-aware). ``entry`` overrides the target; otherwise ALL :func:`swap_targets` (every entry
+    matching the controlled-leader model) are patched. Returns new ``.eb`` bytes (round-trip-checked). Raises
+    :class:`NoSwappablePlayer` when no player entry has a ``SetModel``, ``ValueError`` on an unknown char or a
+    patch that would overflow / corrupt the script."""
+    _name, spec = resolve_char(char)
+    eb = EbScript.from_bytes(eb_bytes)
+    targets = _targets(eb, entry)
+    if not targets:
+        raise NoSwappablePlayer("no player entry with a SetModel to swap")
+    out = bytearray(eb_bytes)
+    for tgt in targets:
+        for ins in eb.instrs(eb.entry(tgt).func_by_tag(0)):
+            if any(ins.arg_is_expr):
+                continue
+            if ins.op == SETMODEL_OP and ins.args:
+                _put_arg(out, ins, 0, spec["model"])
+                if "eye" in spec and len(ins.args) >= 2:        # playables carry an eye-height; an arbitrary
+                    _put_arg(out, ins, 1, spec["eye"])          # model keeps the field's (cosmetic dialog anchor)
+            elif ins.op in ANIM_OPS and ins.args:
+                _put_arg(out, ins, 0, spec.get(ANIM_OPS[ins.op], spec["idle"]))
+
+    out = bytes(out)
+    if EbScript.from_bytes(out).to_bytes() != out:                # the patch must not corrupt the structure
+        raise ValueError("player swap produced a non-round-tripping .eb")
+    return out
+
+
+def neutralize_gestures(eb_bytes, char, *, entry=None) -> bytes:
+    """Make a SWAPPED player stand/idle cleanly through a cutscene instead of T-posing on its foreign gesture
+    clips. On every swap-target player entry (ALL funcs -- gestures live in the LOOP/talk funcs, never Init), it
+    rewrites each scripted ``RunAnimation`` (0x40) clip operand to the swapped rig's OWN idle clip, and repoints
+    any LOOP movement re-sets (``ANIM_OPS``: SetStand/Walk/... ) to the rig's matching clips. The paired
+    ``WaitAnimation``/``Wait``/``SetAnimationFlags`` are LEFT INTACT -- the rig's idle is an already-loaded valid
+    clip, so the wait completes normally (no hang; the donor clip would load a foreign-skeleton clip = the glitch).
+
+    Engine-grounded (Memoria ``DoEventCode``/``ProcessAnime``): RunAnimation is NAME-keyed via a global clip dict,
+    so the substitute idle (loaded by ``--swap-player``'s SetStandAnimation) gives a real frame count and clears
+    ``afExec`` at clip end. Pair with :func:`swap_player` (SAME char); run it on the swapped bytes. A same-width
+    2-byte patch (round-trip-checked). Raises :class:`NoSwappablePlayer` / ``ValueError`` like swap_player.
+
+    NOTE on ``RunAnimationEx`` (0xBD): it never targets the player in the surveyed corpus (its clip arg is at
+    index 1 with a separate object arg), so to avoid rewriting a foreign object's animation it is NOT touched;
+    the gesture WARN still flags it if a field ever has one."""
+    from . import eventscan
+    _name, spec = resolve_char(char)
+    eb = EbScript.from_bytes(eb_bytes)
+    targets = _targets(eb, entry)
+    if not targets:
+        raise NoSwappablePlayer("no player entry with a SetModel to neutralize gestures on")
+    out = bytearray(eb_bytes)
+    for tgt in targets:
+        if eventscan._player_model(eb, tgt) != spec["model"]:   # only an entry actually swapped to `char`:
+            continue                                            # never rewrite a foreign rig's gestures (drift/misuse guard)
+        for f in eb.entry(tgt).funcs:
+            for ins in eb.instrs(f):
+                if any(ins.arg_is_expr) or not ins.args:
+                    continue
+                if ins.op == 0x40:                              # RunAnimation: clip arg 0 -> the rig's idle
+                    _put_arg(out, ins, 0, spec["idle"])
+                elif ins.op in ANIM_OPS:                        # a LOOP movement re-set -> the rig's matching clip
+                    _put_arg(out, ins, 0, spec.get(ANIM_OPS[ins.op], spec["idle"]))
+    out = bytes(out)
+    if EbScript.from_bytes(out).to_bytes() != out:
+        raise ValueError("gesture neutralize produced a non-round-tripping .eb")
+    return out