ff9mapkit 1.0.0b3__py3-none-any.whl

ff9mapkit/sps/render.py

@@ -0,0 +1,116 @@
+"""Offline preview of an ``.sps`` effect (Tier 0). Composites each frame's quad cloud over the decoded
+``spt.tcb`` page into a PNG / contact-sheet / GIF -- "see what FF9's effects look like" without launching
+the game (the bespoke analogue of Memoria's in-engine Model Viewer).
+
+The composite is an ADDITIVE approximation: each prim's UV cell is cropped from the page, tinted by its
+RGB-ramp colour, premultiplied by its texel alpha, and added onto a black canvas at the prim's screen
+offset (``pos_x, pos_y``, +Y up). Additive matches fire/smoke/magic (most field SPS are additive-blended);
+pass ``additive=False`` for an alpha-over paste. This is a catalog preview, not the exact engine projection
+(no per-camera GTE transform / depth sort). -> [[project-ff9-sps-authoring]].
+"""
+from __future__ import annotations
+
+from . import texture
+from .codec import Sps
+
+
+def _page_image(sps: Sps, tcb: bytes):
+    from PIL import Image  # noqa: PLC0415 - only the preview path needs PIL
+    w, h, rgba = texture.tcb_page_rgba(tcb, sps.tpage_raw, sps.clut_raw)
+    return Image.frombytes("RGBA", (w, h), rgba)
+
+
+def _frame_bounds(sps: Sps, cell_w: int, cell_h: int, pad: int):
+    """Canvas size + origin covering EVERY frame's prims (so frames align in a strip/GIF)."""
+    xs, ys = [], []
+    for frame in sps.frames:
+        for p in frame:
+            xs.append(p.pos_x)
+            ys.append(p.pos_y)
+    if not xs:
+        return cell_w + 2 * pad, cell_h + 2 * pad, 0.0, 0.0
+    hx, hy = cell_w / 2, cell_h / 2
+    min_x, max_x = min(xs) - hx, max(xs) + hx
+    min_y, max_y = min(ys) - hy, max(ys) + hy
+    w = int(round(max_x - min_x)) + 2 * pad
+    h = int(round(max_y - min_y)) + 2 * pad
+    return max(w, 1), max(h, 1), min_x - pad, max_y + pad  # origin x-left / y-top (Y inverted)
+
+
+def render_frame(sps: Sps, tcb: bytes, frame_index: int = 0, *, scale: int = 3,
+                 additive: bool = True, _page=None, _bounds=None):
+    """Render one frame's quad cloud to a PIL RGBA image (black/transparent where empty)."""
+    from PIL import Image, ImageChops  # noqa: PLC0415
+
+    page = _page if _page is not None else _page_image(sps, tcb)
+    uv_w = max(1, sps.w_raw - 1)
+    uv_h = max(1, sps.h_raw - 1)
+    cell_w, cell_h = uv_w * scale, uv_h * scale
+    if _bounds is not None:
+        W, H, ox, oy = _bounds
+    else:
+        W, H, ox, oy = _frame_bounds(sps, cell_w, cell_h, pad=cell_w)
+
+    acc = Image.new("RGB", (W, H), (0, 0, 0))
+    if not sps.frames:
+        return acc.convert("RGBA")
+    prims = sps.frames[frame_index % len(sps.frames)]
+    for p in prims:
+        ux, uy = sps.uv_table[p.uv_index] if p.uv_index < len(sps.uv_table) else (0, 0)
+        cell = page.crop((ux, uy, ux + uv_w, uy + uv_h)).convert("RGBA")
+        r, g, b, _pad = sps.rgb_table[p.rgb_index] if p.rgb_index < len(sps.rgb_table) else (255, 255, 255, 0)
+        rr, gg, bb, aa = cell.split()
+        tint = lambda band, k: band.point(lambda v, k=k: (v * k) >> 8)  # noqa: E731 (×k/256)
+        rr, gg, bb = tint(rr, r), tint(gg, g), tint(bb, b)
+        if additive:
+            # premultiply by alpha so transparent texels add nothing, then add onto the canvas
+            rgb = Image.merge("RGB", (ImageChops.multiply(rr, aa), ImageChops.multiply(gg, aa),
+                                      ImageChops.multiply(bb, aa)))
+            layer = Image.new("RGB", (W, H), (0, 0, 0))
+            cx = int(round(p.pos_x - ox)) - cell_w // 2
+            cy = int(round(oy - p.pos_y)) - cell_h // 2
+            layer.paste(rgb.resize((cell_w, cell_h), Image.NEAREST), (cx, cy))
+            acc = ImageChops.add(acc, layer)
+        else:
+            rgba = Image.merge("RGBA", (rr, gg, bb, aa)).resize((cell_w, cell_h), Image.NEAREST)
+            cx = int(round(p.pos_x - ox)) - cell_w // 2
+            cy = int(round(oy - p.pos_y)) - cell_h // 2
+            acc = acc.convert("RGBA")
+            acc.alpha_composite(rgba, (cx, cy))
+            acc = acc.convert("RGB")
+    # alpha = per-pixel brightness so the preview overlays cleanly (black -> transparent)
+    rr, gg, bb = acc.split()
+    alpha = ImageChops.lighter(ImageChops.lighter(rr, gg), bb)
+    return Image.merge("RGBA", (rr, gg, bb, alpha))
+
+
+def render_strip(sps: Sps, tcb: bytes, *, scale: int = 3, cols: int = 8, gap: int = 4):
+    """Render every frame into one contact-sheet image (frames share a canvas size, so motion aligns)."""
+    from PIL import Image  # noqa: PLC0415
+
+    page = _page_image(sps, tcb)
+    uv_w, uv_h = max(1, sps.w_raw - 1), max(1, sps.h_raw - 1)
+    bounds = _frame_bounds(sps, uv_w * scale, uv_h * scale, pad=uv_w * scale)
+    W, H = bounds[0], bounds[1]
+    n = max(1, sps.frame_count)
+    cols = max(1, min(cols, n))
+    rows = (n + cols - 1) // cols
+    sheet = Image.new("RGBA", (cols * W + (cols - 1) * gap, rows * H + (rows - 1) * gap), (0, 0, 0, 0))
+    for i in range(n):
+        cell = render_frame(sps, tcb, i, scale=scale, _page=page, _bounds=bounds)
+        sheet.alpha_composite(cell, ((i % cols) * (W + gap), (i // cols) * (H + gap)))
+    return sheet
+
+
+def save_png(image, path) -> None:
+    image.save(path)
+
+
+def save_gif(sps: Sps, tcb: bytes, path, *, scale: int = 3, duration_ms: int = 66) -> None:
+    """Write an animated GIF of the effect (default ~15 fps, the engine tick). Black background."""
+    page = _page_image(sps, tcb)
+    uv_w, uv_h = max(1, sps.w_raw - 1), max(1, sps.h_raw - 1)
+    bounds = _frame_bounds(sps, uv_w * scale, uv_h * scale, pad=uv_w * scale)
+    frames = [render_frame(sps, tcb, i, scale=scale, _page=page, _bounds=bounds).convert("RGB")
+              for i in range(max(1, sps.frame_count))]
+    frames[0].save(path, save_all=True, append_images=frames[1:], duration=duration_ms, loop=0)

ff9mapkit/sps/templates.py

@@ -0,0 +1,47 @@
+"""Curated named SPS effect TEMPLATES -- the friendly starting points for the Tier-2 creator (``[[sps]]
+template = "fire"``). Each template is a ``copy_from`` preset pointing at a known-good donor effect in a
+common, always-present field (the Ice Cavern, disc 1), so it reuses the proven Route-A path (clone a real
+effect's texture + colours + animation, then optionally re-author the geometry). No new art, no DLL.
+
+Picked from an offline preview survey of the donor effects (distinct, recognisable types). The registry is
+just identifiers (field token + sps id) -- the bytes are read from the user's install at build time, like
+``copy_from``; nothing here is Square-Enix data. Browsable (``list_templates``) so the CLI + a future GUI
+creator picker read the same set. Extend freely -- add a row pointing at any donor effect.
+-> [[project-ff9-sps-authoring]], docs/SPS.md.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# common donor fields (Ice Cavern, disc 1 -- every install has them)
+_ICCV_JMP = "fbg_n05_iccv_map088_ic_jmp_0"
+_ICCV_BRI = "fbg_n05_iccv_map089_ic_bri_0"
+
+
+@dataclass(frozen=True)
+class Template:
+    description: str
+    field: str          # donor field token (what copy_from / extract takes)
+    sps: int            # donor effect id to clone
+
+
+# name -> Template. `[[sps]] template = "<name>"` resolves to copy_from {field, sps}.
+TEMPLATES: dict[str, Template] = {
+    "fire":    Template("a small flickering red flame", _ICCV_JMP, 2266),   # the in-game-proven melt-fire
+    "bonfire": Template("a large orange flame", _ICCV_BRI, 2272),
+    "smoke":   Template("a soft white smoke / mist cloud", _ICCV_JMP, 231),
+    "sparkle": Template("twinkling gold sparkle motes", _ICCV_JMP, 180),
+    "embers":  Template("scattered drifting orange embers", _ICCV_BRI, 2273),
+    "glimmer": Template("a soft crystalline glint", _ICCV_BRI, 344),
+}
+
+
+def resolve(name: str):
+    """The :class:`Template` for ``name`` (raises ``KeyError`` if unknown -- the caller maps it to its
+    own error type with the known-names hint)."""
+    return TEMPLATES[name]
+
+
+def list_templates() -> list[tuple[str, str, str, int]]:
+    """``[(name, description, donor_field, donor_sps), ...]`` -- for the CLI / GUI picker."""
+    return [(n, t.description, t.field, t.sps) for n, t in TEMPLATES.items()]

ff9mapkit/sps/texture.py

@@ -0,0 +1,131 @@
+"""Decode the shared ``spt.tcb`` texture an ``.sps`` effect samples -- the read-only half of the SPS picture
+(Tier 0 preview). An ``.sps`` carries only quad positions + UV/RGB indices; the PIXELS live in ``spt.tcb``,
+a PSX-VRAM blit blob. This module replays the blits into a simulated VRAM and decodes a TPage (through its
+CLUT) to RGBA, exactly as the engine does.
+
+PORTED byte-for-byte from the engine (``PSXTextureMgr.LoadTCBInVram`` / ``LoadImageBin`` :109-449 and
+``PSXTexture.CreateBufferColor32`` / ``ConvertABGR16toABGR32`` :42-132). No PIL / UnityPy needed -- pure
+bytes in, RGBA bytes out (``render.py`` adds the PIL compositing for a preview image).
+
+The model: VRAM is ``u16[1024*512]`` addressed ``vram[y*1024 + x]``. ``spt.tcb`` is two batches of
+``(x, y, w, h)`` rectangle blits (BGR555 halfwords) -- both the indexed texture page AND the CLUT (palette)
+rows live in that VRAM. An ``.sps``'s ``tpage_raw`` (TP color-mode / TX*64 / TY*256) selects a 256x256 texel
+window; ``clut_raw`` (ClutX*16 / ClutY) selects the palette row. -> [[project-ff9-sps-authoring]].
+"""
+from __future__ import annotations
+
+import struct
+from array import array
+
+VRAM_W = 1024
+VRAM_H = 512
+VRAM_SIZE = VRAM_W * VRAM_H  # 524288 u16
+
+
+class SpsTextureError(ValueError):
+    pass
+
+
+def _load_image_bin(vram: array, x: int, y: int, w: int, h: int, data: bytes, off: int) -> int:
+    """Blit a w*h rectangle of LE-u16 pixels into VRAM at (x, y). Returns the new read cursor. Mirrors
+    ``PSXTextureMgr.LoadImageBin``."""
+    for i in range(h):
+        base = (y + i) * VRAM_W + x
+        row = base
+        for _ in range(w):
+            lo = data[off]
+            hi = data[off + 1]
+            vram[row] = (hi << 8) | lo
+            row += 1
+            off += 2
+    return off
+
+
+def load_tcb_to_vram(tcb: bytes) -> array:
+    """Replay a ``spt.tcb`` container into a fresh simulated VRAM (``array('H')`` of length 524288).
+    Mirrors ``PSXTextureMgr.LoadTCBInVram``: a header (secondBatchOffset, firstBatchOffset, firstBatchCount)
+    then two batches of rect blits -- the first carries an inline 8-byte rect header before each block's
+    pixels, the second packs the rect headers and pixels in separate running cursors."""
+    if len(tcb) < 12:
+        raise SpsTextureError(f"spt.tcb too short: {len(tcb)} bytes")
+    vram = array("H", bytes(VRAM_SIZE * 2))  # zero-initialised (unblitted texels read as transparent)
+    second_batch_off, first_batch_off, first_batch_count = struct.unpack_from("<IIi", tcb, 0)
+    try:
+        # First batch: rect header is inline, immediately followed by its pixels.
+        off = first_batch_off
+        for _ in range(first_batch_count):
+            x, y, w, h = struct.unpack_from("<hhhh", tcb, off)
+            _load_image_bin(vram, x, y, w, h, tcb, off + 8)
+            off += w * h * 2 + 8
+        # Second batch: rect headers packed from second_batch_off+8, pixels from a separate img cursor.
+        img_off, second_batch_count = struct.unpack_from("<Ii", tcb, second_batch_off)
+        rect_off = second_batch_off + 8
+        for _ in range(second_batch_count):
+            x, y, w, h = struct.unpack_from("<hhhh", tcb, rect_off)
+            img_off = _load_image_bin(vram, x, y, w, h, tcb, img_off)
+            rect_off += 8
+    except (struct.error, IndexError) as ex:
+        raise SpsTextureError(f"malformed spt.tcb: {ex}") from ex
+    return vram
+
+
+def _abgr16_to_rgba(num: int) -> tuple[int, int, int, int]:
+    """Expand a PSX BGR555 halfword to RGBA8. Black (0x0000) is transparent; the 0x8000 STP bit OR any colour
+    bit makes it opaque. Mirrors ``PSXTexture.ConvertABGR16toABGR32``."""
+    r = (num & 0x1F) << 3
+    g = (num & 0x3E0) >> 2
+    b = (num & 0x7C00) >> 7
+    a = 255 if (num & 0x8000) or (num & 0x7FFF) else 0
+    return r, g, b, a
+
+
+def decode_page(vram: array, tpage_raw: int, clut_raw: int, w: int = 256, h: int = 256) -> bytes:
+    """Decode a 256x256 (by default) RGBA texture window from VRAM for an ``.sps``'s ``tpage``/``clut``.
+    Mirrors ``PSXTexture.CreateBufferColor32`` (TP 0=4bpp / 1=8bpp / 2=16bpp-direct). Returns ``w*h*4``
+    bytes, row-major, top row first (the same uniIndex order the engine writes)."""
+    tp = (tpage_raw >> 7) & 3
+    tx = (tpage_raw & 0x0F) << 6   # VRAM x base (halfwords)
+    ty = ((tpage_raw >> 4) & 1) << 8   # VRAM y base
+    clut_x = clut_raw & 0x3F
+    clut_y = (clut_raw >> 6) & 0x1FF
+    clut_base = (clut_x << 4) + (clut_y << 10)
+    out = bytearray(w * h * 4)
+    o = 0
+
+    def put(num: int):
+        nonlocal o
+        r, g, b, a = _abgr16_to_rgba(num)
+        out[o] = r; out[o + 1] = g; out[o + 2] = b; out[o + 3] = a
+        o += 4
+
+    if tp == 0:          # 4bpp: 4 texels per halfword, low nibble first
+        for y in range(h):
+            vi = (ty + y) * VRAM_W + tx
+            for _ in range(w >> 2):
+                pi = vram[vi]
+                put(vram[clut_base + (pi & 0xF)])
+                put(vram[clut_base + ((pi >> 4) & 0xF)])
+                put(vram[clut_base + ((pi >> 8) & 0xF)])
+                put(vram[clut_base + (pi >> 12)])
+                vi += 1
+    elif tp == 1:        # 8bpp: 2 texels per halfword
+        for y in range(h):
+            vi = (ty + y) * VRAM_W + tx
+            for _ in range(w >> 1):
+                pi = vram[vi]
+                put(vram[clut_base + (pi & 0xFF)])
+                put(vram[clut_base + (pi >> 8)])
+                vi += 1
+    else:                # 16bpp direct (no CLUT)
+        for y in range(h):
+            vi = (ty + y) * VRAM_W + tx
+            for _ in range(w):
+                put(vram[vi])
+                vi += 1
+    return bytes(out)
+
+
+def tcb_page_rgba(tcb: bytes, tpage_raw: int, clut_raw: int, w: int = 256, h: int = 256):
+    """Convenience: load ``spt.tcb`` and decode the page an effect samples. Returns ``(w, h, rgba_bytes)``."""
+    vram = load_tcb_to_vram(tcb)
+    return w, h, decode_page(vram, tpage_raw, clut_raw, w, h)

ff9mapkit/walkmesh_hotfixes.py

@@ -0,0 +1,163 @@
+"""Engine WALKMESH HOTFIXES that a fork loses on a minted id -- the catalog.
+
+A handful of real fields rely on a **hardcoded Memoria engine hotfix, keyed on the real ``fldMapNo``**, that
+toggles walkmesh-triangle active-state (``WalkMesh.BGI_triSetActive(triNdx, isActive)``, which flips bit 0 of
+the triangle's ``triFlags`` -- the walkable bit -- both in the loaded ``BGI_DEF`` and the runtime mesh). A
+verbatim/native fork ships the same ``.bgi`` but runs at a CUSTOM id (>= 4000), so every ``mapNo == <real id>``
+guard is false and the hotfix never fires -- the forked walkmesh is subtly wrong at that beat (a wall stays
+walkable, an NPC can't reach its spot, a blocked stair is open). This is the "real-``fldMapNo``-gated engine
+behavior is lost on a mint" residual from ``docs/FORK_FIDELITY.md`` (the carry taxonomy), made concrete for the
+walkmesh dimension.
+
+There are two tractability classes:
+
+* **LOAD-TIME, unconditional** (``FieldMap.BG_init`` / ``DelayedActiveTri``, keyed on ``fldMapNo`` only): the
+  triangle state is asserted at field load with no runtime condition. A fork reproduces it EXACTLY by
+  prepending ``EnablePathTriangle(tri, state)`` -- the same opcode (0x9A) whose handler IS ``BGI_triSetActive``
+  -- to ``Main_Init`` (``content.walkmesh_hotfix.apply_tri_toggles``). The ``.bgi`` stays byte-verbatim; the
+  fix lives in the script layer, exactly as the engine's own opcode would. These carry ``toggles`` and are
+  AUTO-reproduced by the build (``[field] walkmesh_tri_toggles``, auto-emitted by ``import`` for these donors).
+* **EVENT-CODE / DYNAMIC / OPCODE-AUGMENT** (``DoEventCode`` + ``turnOffTriManually``, keyed on ``mapNo`` plus a
+  runtime condition -- an object uid/sid/tag, a position, or a story var): the toggle fires DURING play, so a
+  static prepend can't reproduce it faithfully (e.g. Daguerreo's librarian tris TRACK ``gEventGlobal`` var
+  761060). These are cataloged with a reproduction ``note`` and surfaced by ``fork-report`` as "lost on a mint
+  -> fork in-place on the real id (or accept it)". They are NOT auto-applied -- a per-field bespoke splice
+  (locate the trigger ``.eb`` site, splice the toggle) is a possible follow-up, recorded in each note.
+
+Source (Memoria, ``Assembly-CSharp``, compile-matched to ``6b8bb2d5``):
+``Global/Field/Map/FieldMap.cs`` (load-time), ``Global/Event/Engine/EventEngine.DoEventCode.cs`` (event-code +
+the BGIACTIVE 0x9A handler's own ``mapNo`` augments), ``Global/Event/Engine/EventEngine.turnOffTriManually.cs``
+(dynamic). Read-only reference data -- ships no Square-Enix bytes.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field as _dc_field
+
+
+@dataclass(frozen=True)
+class Hotfix:
+    """One real field's engine walkmesh hotfix.
+
+    ``kind``    : ``load_time`` (auto-reproducible) | ``event_code`` | ``dynamic`` | ``opcode_augment``.
+    ``toggles`` : the load-time ``(tri, state)`` pairs (state 1 = active/walkable, 0 = inactive) -- the AUTO
+                  set, non-empty only for ``load_time``.
+    ``tris``    : every triangle index the hotfix touches (for reporting, incl. the non-auto kinds).
+    ``note``    : what it does + the runtime condition + (for non-auto) the reproduction recipe.
+    ``source``  : the Memoria source location.
+    ``engine_remapped`` : the SHIPPED custom engine already reproduces this hotfix faithfully for a fork (its
+                  ``fldMapNo`` gate is wrapped with ``EffectiveFieldId``, so it fires for the fork id too) WITH the
+                  original timing -- so the kit must NOT also prepend a Main_Init toggle. Set when the engine hotfix
+                  is DELAYED (e.g. 2507's ``DelayedActiveTri`` runs 0.5s after load): the at-load toggle prepend
+                  fires BEFORE the field's own props settle onto those tris, snapping them to the wrong floor (the
+                  Ipsen chests dropped a level). Reproduce delayed hotfixes via the engine remap, not the prepend.
+    """
+
+    field_id: int
+    name: str
+    kind: str
+    note: str
+    source: str
+    toggles: tuple = ()
+    tris: tuple = ()
+    engine_remapped: bool = False
+
+    @property
+    def auto(self) -> bool:
+        """True when the build SHOULD reproduce this hotfix via a Main_Init tri-toggle prepend. False for an
+        ``engine_remapped`` hotfix: the shipped engine already reproduces it for the fork id (correct timing),
+        and the at-load prepend would mis-time it (see ``engine_remapped``)."""
+        return self.kind == "load_time" and bool(self.toggles) and not self.engine_remapped
+
+
+_HOTFIXES = {
+    # --- LOAD-TIME (unconditional at field load; AUTO-reproduced) -------------------------------------------
+    2356: Hotfix(2356, "Gulug/Room (the Red-Dragon-wall room)", "load_time",
+                 "At field load the engine deactivates 3 floor triangles around a 3D treasure-chest prop (entry "
+                 "5, GEO_ACC_F0_TBX @ (-426,1664)). The engine comment '(Red Dragon bursting through wall)' names "
+                 "the ROOM (field 2356), not these tris' job. ★ IN-GAME PROVEN by A/B (2026-06-14): teleporting "
+                 "to the patch EDGE (-543,1667) -- ~120u from the chest, beyond its collision -- is STUCK with the "
+                 "toggle (id 30003) and FREE without it (id 30004), so the toggle (not the chest) blocks that "
+                 "floor. The patch extends ~120u around the chest, so it blocks more than the chest's collision "
+                 "alone -- the hotfix is NOT redundant. (Confound to avoid: the tri-78 CENTER (39u) coincides "
+                 "with the chest collision; test the edge.)",
+                 "FieldMap.cs:112-117", toggles=((78, 0), (79, 0), (80, 0)), tris=(78, 79, 80)),
+    2161: Hotfix(2161, "L. Castle/Guest Room (disc 3)", "load_time",
+                 "At field load the engine deactivates one triangle (a disc-3 room-layout block). Unconditional.",
+                 "FieldMap.cs:119-122", toggles=((69, 0),), tris=(69,)),
+    2507: Hotfix(2507, "I. Castle/Stairwell (ladders + stairs)", "load_time",
+                 "0.5s AFTER load the engine deactivates four stairwell triangles AND drops every non-player NPC's "
+                 "walkmesh collision (DelayedActiveTri). ENGINE-REMAPPED: the s29 fork-donor patch wraps this gate "
+                 "with EffectiveFieldId, so it fires for the fork id too -- with the original 0.5s delay AND the "
+                 "NPC-collision drop. The kit must NOT also prepend an at-load toggle: tris 174/175/177/178 are the "
+                 "FLOOR the two treasure-chest props snap onto, and the real field's 0.5s delay lets them settle "
+                 "FIRST, then removes the tris. An at-load prepend removes them BEFORE the chests place, snapping "
+                 "the chests a floor down (★ caught in-game 2026-06-23). So reproduce via the engine remap only.",
+                 "FieldMap.cs:139-148", toggles=((174, 0), (175, 0), (177, 0), (178, 0)),
+                 tris=(174, 175, 177, 178), engine_remapped=True),
+
+    # --- EVENT-CODE one-shot (locatable trigger; reproducible-but-bespoke; NOT auto-applied) ----------------
+    450: Hotfix(450, "Dali/Field (Grandma's initial position)", "event_code",
+                "When Grandma (sid 3) is created at (363, 88) the engine deactivates one triangle. Reproducible "
+                "by splicing EnablePathTriangle(24,0) after that CreateObject in the fork's .eb (bespoke; not "
+                "auto-applied -- a synth fork's spawn/positions may differ).",
+                "DoEventCode.cs:291-292", tris=(24,)),
+
+    # --- OPCODE-AUGMENT (the BGIACTIVE 0x9A handler itself has mapNo special-cases) ------------------------
+    1753: Hotfix(1753, "(EnablePathTriangle augment)", "opcode_augment",
+                 "When the field's own .eb runs EnablePathTriangle(207, x), the engine ALSO toggles triangle "
+                 "208 to the same state. A fork keeps the donor's EnablePathTriangle(207,x) but loses the paired "
+                 "208 toggle. Reproducible by emitting a paired EnablePathTriangle(208, x) beside it.",
+                 "DoEventCode.cs:2566-2567", tris=(207, 208)),
+    1606: Hotfix(1606, "(EnablePathTriangle augment)", "opcode_augment",
+                 "When the field's own .eb runs EnablePathTriangle(107, x), the engine FORCES x = 1 (always "
+                 "activate). A fork's EnablePathTriangle(107, 0) would deactivate instead. Reproducible by "
+                 "rewriting that toggle's state operand to 1 in the fork's .eb.",
+                 "DoEventCode.cs:2568-2569", tris=(107,)),
+
+    # --- DYNAMIC (toggle tracks runtime story/position state; NOT statically reproducible) -----------------
+    2803: Hotfix(2803, "Daguerreo/2nd Floor (LibrarianB book quest)", "dynamic",
+                 "The librarian's walkable triangles 105/106 are activated when RunScript(uid 20, tag 18) fires "
+                 "AND are continuously re-evaluated against gEventGlobal var 761060 (turnOffTriManually). A "
+                 "static prepend can't track the story var. The interaction also depends on Main_Init shared "
+                 "helpers (the #14-infeasible quest logic) -- fork in-place on 2803, or accept the book-quest "
+                 "geometry is at scenario-zero.",
+                 "DoEventCode.cs:158-162 + turnOffTriManually.cs:39-44", tris=(105, 106)),
+    900: Hotfix(900, "Treno/Pub (Steiner_11)", "dynamic",
+                "Triangle 62 is activated when RunScriptAsync(uid 14, level 2, tag 11) fires, and 56/62 are "
+                "deactivated by turnOffTriManually on later beats. Tracks runtime script/manual-var state -> "
+                "not a static toggle; fork in-place for faithful pub geometry.",
+                "DoEventCode.cs:149-150 + turnOffTriManually.cs:14-31", tris=(56, 62)),
+    1421: Hotfix(1421, "Fossil Roo/Mining Site (Lindblum_Worker)", "dynamic",
+                 "Triangles 109/110 toggle on/off as the worker (sid 5) moves between positions (a moving "
+                 "block). Position-driven during play -> not a static toggle.",
+                 "DoEventCode.cs:296-309", tris=(109, 110)),
+    1900: Hotfix(1900, "(turnOffTriManually, sid 4)", "dynamic",
+                 "Triangle 56 is deactivated by turnOffTriManually when an object with sid 4 triggers it. "
+                 "Object-driven -> not a static load-time toggle.",
+                 "turnOffTriManually.cs:8-12", tris=(56,)),
+    1455: Hotfix(1455, "(turnOffTriManually, sid 5)", "dynamic",
+                 "Triangle 16 is deactivated by turnOffTriManually when an object with sid 5 triggers it. "
+                 "Object-driven -> not a static load-time toggle.",
+                 "turnOffTriManually.cs:32-36", tris=(16,)),
+}
+
+
+def info(field_id) -> "Hotfix | None":
+    """The :class:`Hotfix` record for a real field id, or ``None`` if the field has no engine walkmesh hotfix
+    (the vast majority). ``field_id`` may be an int or a numeric string."""
+    try:
+        return _HOTFIXES.get(int(field_id))
+    except (TypeError, ValueError):
+        return None
+
+
+def load_time_toggles(field_id) -> list:
+    """The ``[(tri, state), ...]`` a fork of ``field_id`` should prepend at load to reproduce its (auto)
+    engine walkmesh hotfix, or ``[]`` when the field has none / its hotfix isn't statically reproducible."""
+    h = info(field_id)
+    return [list(t) for t in h.toggles] if (h and h.auto) else []
+
+
+def all_ids() -> list:
+    """Every real field id with a cataloged engine walkmesh hotfix (sorted)."""
+    return sorted(_HOTFIXES)

ff9mapkit/workspace/__init__.py

@@ -0,0 +1,18 @@
+"""The FF9 Map Kit **workspace** -- a modern PySide6 (Qt) shell for the kit's GUIs.
+
+Phase 3 of the GUI makeover: one dockable window whose left rail IS the journey > campaign > field >
+object hierarchy, a clickable breadcrumb, a central document area, a right inspector, and a bottom
+Output/Problems dock -- the genuinely-modern, scalable replacement for the tkinter ``apps/*.pyw`` suite,
+shipped side-by-side with them.
+
+The shell **reuses the kit's tk-free backends unchanged** -- ``editor.feedback`` (Verdict/Problem),
+``editor.breadcrumb`` (Crumb/trail), ``campaign`` (CampaignPlan/graph), ``editor.forms``/``editor.model``
+-- so only the Qt view layer is new. ``style`` (the QSS builder) is PySide6-FREE and unit-testable; the
+Qt widgets live in ``shell`` (imported lazily by the launcher so this package stays importable headless).
+"""
+
+from __future__ import annotations
+
+from . import style  # noqa: F401  (re-export the PySide6-free QSS builder)
+
+__all__ = ["style"]