ff9mapkit 1.0.0b3__py3-none-any.whl

ff9mapkit/content/shop.py

@@ -0,0 +1,178 @@
+"""``[[shop]]`` -- author a custom shop: its INVENTORY (a ``ShopItems.csv`` delta) + an OPENER.
+
+Two channels, like every item feature on this branch:
+
+* **Inventory (data).** A custom shop's stock is a row in ``<mod>/StreamingAssets/Data/Items/ShopItems.csv``
+  -- ``Comment;Id;item1, item2, ...``. The engine **MERGES** these by id low->high (``ff9buy.LoadShopItems``
+  via ``EnumerateCsvFromLowToHigh`` -> ``result[shop.Id] = shop``), so a PARTIAL delta (just the custom shops)
+  works: the base file supplies shops 0-31 (the engine's ``>= 32`` guard is satisfied by the base), and our
+  delta adds the new ids. ★ A custom shop id must be **>= 32** (0-31 are the base shops; a clash OVERRIDES the
+  vanilla shop -- allowed but lint-warned). The id is also the ``Menu`` sub-id (one byte), so it is **<= 255**.
+
+* **Opener (.eb).** A shop opens with ``Menu(2, shopId)`` (0x75 -> ``EventService.FF9Menu_Command`` case 2u ->
+  ``OpenShopMenu``) -- the same opcode family as the save point (``Menu(4, 0)``). Two shapes:
+
+    - a **shopkeeper NPC** -- ``[[npc]] opens_shop = N`` builds a tag-3 talk body that (optionally greets, then)
+      opens the shop; reuses :mod:`content.npc`'s ``speak_body`` slot. ``opens_shop`` may point at a VANILLA shop
+      (0-31) too (e.g. open Dali's weapon shop). This is the authentic "talk to the merchant" UX.
+    - a **standalone press-region** -- ``[[shop]] zone = [...]`` mints a press-to-interact region (the save-point
+      shape: Init ``SetRegion`` / tread ``Bubble`` / action ``DisableMove; Menu(2, id); EnableMove``) so you can
+      walk up to a counter and open the shop with no NPC. Place a cosmetic ``[[npc]]``/``[[prop]]`` over it for the
+      visible merchant, exactly like the save moogle.
+
+The inventory CSV is mod-global (one ``ShopItems.csv`` per mod, collected across every built field's ``[[shop]]``
+blocks); the opener is per-field ``.eb``. (memory project-ff9-items-equipment / project-ff9-branch-lanes.)
+
+    [[shop]]
+    id = 40
+    comment = "Hut Item Shop"
+    sells = ["Potion", "Hi-Potion", "Phoenix Down", "Tent", "Ether"]
+    # optional standalone opener (else open it from an NPC):
+    zone = [[-400, -900], [400, -900], [400, -500], [-400, -500]]
+
+    [[npc]]
+    name = "Shopkeeper"
+    pos = [0, -700]
+    dialogue = "Welcome! Care to buy something?"
+    opens_shop = 40
+"""
+from __future__ import annotations
+
+import struct
+
+from .. import items as _items
+from ..eb import EbScript, edit, opcodes
+from . import region as _region
+
+SHOP_MENU_ID = 2          # FF9Menu_Command case 2u -> EventService.OpenShopMenu
+FIRST_CUSTOM_SHOP = 32    # base game ships shops 0-31; a custom shop must be >= 32 (0-31 are vanilla)
+MAX_SHOP_ID = 255         # the Menu sub-id is a single byte, so a shop id is <= 255
+NO_ITEM = 255             # terminates a shop's item list (ShopItems.ParseEntry stops at NoItem)
+
+
+# --- opener bodies ---------------------------------------------------------------------------------
+
+def open_shop(shop_id: int) -> bytes:
+    """The single op that opens shop ``shop_id``: ``Menu(2, shop_id)``."""
+    return opcodes.menu(SHOP_MENU_ID, int(shop_id))
+
+
+def shop_speak_body(shop_id: int, *, greeting_txid: int | None = None) -> bytes:
+    """A shopkeeper NPC's tag-3 talk body: (optional greeting window ->) open the shop -> RETURN. The talk
+    already halts the player, so -- unlike the press-region -- no ``DisableMove`` bracket is needed."""
+    body = b""
+    if greeting_txid is not None:
+        body += opcodes.window_sync(1, 128, int(greeting_txid))
+    return body + open_shop(shop_id) + opcodes.RETURN
+
+
+def shop_dispatch(shop_id: int) -> bytes:
+    """The press-region action body: ``DisableMove; Menu(2, id); EnableMove; RETURN`` -- locks control while
+    the shop UI is up (so the player can't walk out from under it) and restores it after. Mirrors
+    :func:`content.savepoint.save_dispatch`, with the shop menu in place of the save menu."""
+    return (opcodes.DISABLE_MOVE
+            + open_shop(shop_id)
+            + opcodes.ENABLE_MOVE + opcodes.RETURN)
+
+
+def _assemble_entry(funcs) -> bytes:
+    """Assemble a type-1 (region) entry from ``[(tag, body), ...]`` -- the func table (``<tag:u16><fpos:u16>``
+    each) then the concatenated bodies. Same layout as :func:`content.savepoint._assemble_entry`."""
+    table = b""
+    pos = len(funcs) * 4
+    for tag, body in funcs:
+        table += struct.pack("<HH", tag, pos)
+        pos += len(body)
+    return bytes([_region.REGION_ENTRY_TYPE, len(funcs)]) + table + b"".join(b for _, b in funcs)
+
+
+def shop_region(zone, shop_id: int, *, bubble: bool = True) -> bytes:
+    """A type-1 region entry that opens a shop: Init ``SetRegion(zone)`` / tread (tag 2) ``Bubble(1)`` (the
+    floating "!" prompt, if ``bubble``) / action (tag 3) :func:`shop_dispatch`. Both trigger funcs are gated
+    by :data:`content.region.MOVEMENT_GATE` (fire only while ``usercontrol == 1``), like every real region."""
+    init = _region.set_region([tuple(p) for p in zone]) + opcodes.RETURN
+    tread = _region.MOVEMENT_GATE + (opcodes.bubble(1) if bubble else b"") + opcodes.RETURN
+    action = _region.MOVEMENT_GATE + shop_dispatch(shop_id)
+    funcs = [(0, init), (_region.RANGE_TAG, tread), (_region.INTERACT_TAG, action)]
+    return _assemble_entry(funcs)
+
+
+def inject_shop_region(data, zone, shop_id: int, *, bubble: bool = True, activate: bool = True):
+    """Inject one standalone shop opener: append a shop region at the next free slot and arm it
+    (``InitRegion`` in Main_Init). Returns ``(new_bytes, region_slot)``."""
+    eb = EbScript.from_bytes(data)
+    slot = eb.first_free_slot()
+    data = edit.append_entry(data, slot, shop_region(zone, shop_id, bubble=bubble))
+    if activate:
+        data = edit.activate(data, opcodes.init_region(slot, 0))
+    return data, slot
+
+
+def inject_shop_regions(data, shops, *, activate: bool = True):
+    """Inject a standalone press-region for every ``[[shop]]`` that carries a ``zone``. Returns
+    ``(new_bytes, [slot, ...])``. Shops without a ``zone`` (opened from an NPC instead) are skipped."""
+    slots = []
+    for sh in shops:
+        if not sh.get("zone"):
+            continue
+        data, slot = inject_shop_region(data, sh["zone"], int(sh["id"]),
+                                        bubble=bool(sh.get("bubble", True)), activate=activate)
+        slots.append(slot)
+    return data, slots
+
+
+# --- inventory CSV ---------------------------------------------------------------------------------
+
+def safe_comment(text: str, sid: int) -> str:
+    """Make the CSV column-0 label delimiter-safe. The comment is free author text but column 0 of a
+    semicolon-delimited row whose Id is column 1, so a stray delimiter mis-parses or DROPS the shop:
+    a ``;`` splits the row (the engine reads the wrong Id column), a leading ``#`` makes the engine's
+    CsvReader skip the whole line (the shop silently never loads), and a newline breaks the row. We
+    neutralise all three (``;`` -> ``,``, newlines -> space, strip a leading ``#``); the label is cosmetic
+    (the shop is keyed by Id), so this is lossless to behaviour. Empty -> the default ``Shop NNNN`` label."""
+    text = str(text).replace("\r", " ").replace("\n", " ").replace(";", ",").strip().lstrip("#").strip()
+    return text or f"Shop {sid:04d}"
+
+
+def shop_rows(shops) -> list:
+    """``[{id, sells, comment}, ...]`` -> ``[(id, [item_id, ...], comment), ...]`` sorted by id.
+
+    Item names/ids resolved via :func:`items.resolve`; ``NoItem`` (255) dropped (it would terminate the
+    shop's list); duplicate items within a shop collapsed (order-preserving, first wins). A duplicate SHOP id
+    keeps the last definition (last wins -- the engine's own merge rule); the build lints the duplicate."""
+    by_id: dict = {}
+    for sh in shops:
+        sid = int(sh["id"])
+        seen, ids = set(), []
+        for entry in sh.get("sells", []):
+            iid = _items.resolve(entry)
+            if iid == NO_ITEM or iid in seen:
+                continue
+            seen.add(iid)
+            ids.append(iid)
+        by_id[sid] = (ids, safe_comment(sh.get("comment") or "", sid))
+    return [(sid, ids, comment) for sid, (ids, comment) in sorted(by_id.items())]
+
+
+def render_shop_items(shops) -> str:
+    """The ``ShopItems.csv`` delta text (legend + one ``Comment;Id;items;# names`` row per custom shop). A
+    partial delta -- the engine merges it over the base by id, so only the custom shops are listed."""
+    lines = [
+        "# ff9mapkit [[shop]] -- custom shop inventories (ShopItems.csv delta; the engine MERGES by id over the",
+        "# base, which supplies shops 0-31). Custom shop ids are >= 32.",
+        "# Comment;Id;Items",
+        "# ;Int32;Int32[]",
+    ]
+    for sid, ids, comment in shop_rows(shops):
+        names = ", ".join(_items.name_of(i) or str(i) for i in ids)
+        items_csv = ", ".join(str(i) for i in ids)
+        lines.append(f"{comment};{sid};{items_csv}" + (f";# {names}" if names else ""))
+    return "\n".join(lines) + "\n"
+
+
+def write_shop_items(layout, shops) -> None:
+    """Pure writer: emit the shop-inventory delta into ``layout``'s mod root
+    (``Data/Items/ShopItems.csv``)."""
+    path = layout.shop_items_csv
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(render_shop_items(shops), encoding="utf-8", newline="\n")

ff9mapkit/content/sps_trigger.py

@@ -0,0 +1,66 @@
+"""Emit the ``RunSPSCode`` create+place trigger for an authored ``[[sps]]`` effect (Tier 2 creator).
+
+A new effect's ``<id>.sps.bytes`` is inert until the field's ``.eb`` fires ``RunSPSCode(slot, 130, id, 0, 0)``
+to LOAD it, then positions + animates it. This injects that sequence as a standalone ``InitCode`` code-entry
+in Main_Init -- the SAME proven arming as :func:`ff9mapkit.content.onentry.inject_on_entries`, so the effect
+spawns at field load (post-fade) on BOTH the synthesize and verbatim-fork paths.
+
+Op sequence per effect (confirmed against ``CommonSPSSystem.SetObjParm``):
+  ``RunSPSCode(slot, 130, id, 0, 0)``   LOAD (Arg1==0 -> per-scene FieldMaps/<scene>/<id>.sps + the in-VRAM tcb)
+  ``RunSPSCode(slot, 131, 3, 1, 0)``    ATTR set VISIBLE|UPDATE_ANY_FRAME
+  ``RunSPSCode(slot, 135, x, y, z)``    POS -- the engine NEGATES Arg1 (Y) itself, so emit raw +Y
+  ``RunSPSCode(slot, 156, abr, 0, 0)``  ABR blend (optional)        0=50%add 1=add 2=sub 3=25%add
+  ``RunSPSCode(slot, 160, rate, 0, 0)`` FRAMERATE (optional)        16 = 1x
+  ``RunSPSCode(slot, 145, scale, 0, 0)``SCALE (optional)            4096 = 1x
+
+Opcode ``0xB3 RunSPSCode`` (operand widths ``[1,1,2,2,2]`` from ``eb/_optables.py``). Byte-identical when
+no specs. -> [[project-ff9-sps-authoring]], docs/SPS.md.
+"""
+from __future__ import annotations
+
+import struct
+
+from ..eb import EbScript, edit, opcodes
+
+# parmType constants (Global/SPS/SPSConst.cs)
+SPS_LOAD = 130
+SPS_ATTR = 131
+SPS_POS = 135
+SPS_SCALE = 145
+SPS_ABR = 156
+SPS_FRAMERATE = 160
+ATTR_VISIBLE_UPDATE = 3            # ATTR_VISIBLE(1) | ATTR_UPDATE_ANY_FRAME(2)
+_RUN_SPS = 0xB3
+
+
+def sps_trigger_ops(*, slot: int, sps_id: int, pos=(0, 0, 0),
+                    abr: int | None = None, framerate: int | None = None, scale: int | None = None) -> bytes:
+    """The create+place op sequence for one effect (no entry/RETURN wrapper)."""
+    x, y, z = pos
+    ops = opcodes.encode(_RUN_SPS, slot, SPS_LOAD, sps_id, 0, 0)
+    ops += opcodes.encode(_RUN_SPS, slot, SPS_ATTR, ATTR_VISIBLE_UPDATE, 1, 0)
+    ops += opcodes.encode(_RUN_SPS, slot, SPS_POS, x, y, z)          # engine negates Y -> emit raw +Y
+    if scale is not None:
+        ops += opcodes.encode(_RUN_SPS, slot, SPS_SCALE, scale, 0, 0)
+    if abr is not None:
+        ops += opcodes.encode(_RUN_SPS, slot, SPS_ABR, abr, 0, 0)
+    if framerate is not None:
+        ops += opcodes.encode(_RUN_SPS, slot, SPS_FRAMERATE, framerate, 0, 0)
+    return ops
+
+
+def inject_sps_triggers(data, specs, *, spawn_wait_n: int = 2, spawn_wait_occurrence: int = 0):
+    """Inject the create+place triggers for every authored effect as ONE standalone ``InitCode`` code-entry
+    (all specs share one Main_Init arm -- one ``Wait`` filler consumed, vs one per effect). ``specs`` is a list
+    of :func:`sps_trigger_ops` kwarg dicts. Returns new ``.eb`` bytes; a no-op when ``specs`` is empty."""
+    specs = list(specs)
+    out = data if isinstance(data, (bytes, bytearray)) else data.to_bytes()
+    if not specs:
+        return out
+    body = b"".join(sps_trigger_ops(**s) for s in specs) + opcodes.RETURN
+    entry = bytes([0x00, 0x01]) + struct.pack("<HH", 0, 4) + body
+    entry_slot = EbScript.from_bytes(out).first_free_slot()
+    out = edit.append_entry(out, entry_slot, entry)
+    out = edit.activate(out, opcodes.init_code(entry_slot, 0),
+                        spawn_wait_n=spawn_wait_n, spawn_wait_occurrence=spawn_wait_occurrence)
+    return out

ff9mapkit/content/startup.py

@@ -0,0 +1,71 @@
+"""Field-entry STORY-STATE presets -- the ``[startup]`` block.
+
+A forked field boots with a **zero ``gEventGlobal``**, so every story-gated NPC / door / event / dialogue
+takes the not-yet-happened branch and the field plays in its scenario-zero state. ``[startup]`` lets the
+author **assert the story beat the forked field represents**: set the ScenarioCounter and/or specific
+``gEventGlobal`` story bits, unconditionally, at field load. It is the first lever toward "fork a real story
+field and have it boot in the right beat" (see ``docs/FORK_FIDELITY.md`` #1).
+
+The presets run **first in Main_Init** (prepended to entry-0 tag-0) so every gate evaluated afterwards --
+region triggers, gated NPCs/doors, conditional content -- sees the asserted state. They re-assert on **every
+field entry** (idempotent beat assertion): right for a fork that stands for one beat. For a chain, put
+``[startup]`` on the ENTRY field only and advance the story with gateway-side writes (a separate feature).
+
+Grounded entirely in :mod:`ff9mapkit.content.region`'s byte-for-byte primitives: a story bit is
+``set_var(GLOB_BOOL, idx, 0|1)``; the ScenarioCounter is the save-backed UInt16 at ``gEventGlobal`` byte 0
+(the engine's ``SC_COUNTER`` token ``0xDC``), set via ``set_var(GLOB_UINT16, 0, value)``. Author-side only --
+no extraction; the author asserts the beat (they have the game knowledge).
+"""
+from __future__ import annotations
+
+from . import region as _region
+from ..eb import edit
+
+SCENARIO_BYTE = 0          # ScenarioCounter = the save-backed UInt16 at gEventGlobal byte 0 (token 0xDC)
+SCENARIO_MAX = 32767       # set_var packs a signed int16; every real beat (<= 12000) fits with margin
+WORD_BYTE_MAX = 2046       # a UInt16 word at byte N spans gEventGlobal[N..N+1]; the heap is 2048 bytes
+WORD_VALUE_MAX = 0xFFFF
+BYTE_BYTE_MAX = 2047       # a single byte at byte N occupies gEventGlobal[N] only; the heap is 2048 bytes
+BYTE_VALUE_MAX = 0xFF
+
+
+def startup_body(presets, scenario=None, words=(), byte_writes=()) -> bytes:
+    """The Main_Init preset sequence (the bare bytecode, no entry/return wrapper -- it is prepended INTO
+    Main_Init). ``scenario`` (int, or None) sets the ScenarioCounter; ``presets`` is an iterable of
+    ``(bit_index, value)`` story-bit pairs (truthy -> set, falsy -> clear). Two width-distinct word levers:
+
+    - ``words``: ``(byte_index, value)`` pairs writing a save-backed **UInt16** to ``gEventGlobal[byte_index]``
+      -- a 16-bit value spanning bytes ``[N, N+1]`` (the lever for a 16-bit mask the scenario counter doesn't
+      cover, e.g. the **ATE-availability bitmask at byte 236**; see docs/ATE_SYSTEM.md). ⚠ Because it is two
+      bytes, a UInt16 write to ``N`` also sets byte ``N+1`` (to ``value >> 8``) -- so ``value < 256`` ZEROES
+      the neighbour. To set a single byte without touching its neighbour, use ``byte_writes``.
+    - ``byte_writes``: ``(byte_index, value)`` pairs writing a save-backed **single byte** (0..255) to
+      ``gEventGlobal[byte_index]`` ONLY -- no neighbour clobber. The right lever for adjacent independent
+      config bytes (e.g. the Pandemonium lift pair byte361=4 + byte362=6).
+
+    Writes run scenario -> words -> byte_writes -> bits, so a later, narrower write refines an earlier wider
+    one (a ``byte`` can fix one byte of a seeded ``word``; a ``flag`` can refine one bit). Returns ``b""`` when
+    there is nothing to preset (so a field with no ``[startup]`` stays byte-identical)."""
+    out = b""
+    if scenario is not None:
+        out += _region.set_var(_region.GLOB_UINT16, SCENARIO_BYTE, int(scenario))
+    for byte_idx, value in words:
+        out += _region.set_var(_region.GLOB_UINT16, int(byte_idx), int(value) & WORD_VALUE_MAX)
+    for byte_idx, value in byte_writes:
+        out += _region.set_var(_region.GLOB_BYTE, int(byte_idx), int(value) & BYTE_VALUE_MAX)
+    for idx, val in presets:
+        out += _region.set_var(_region.GLOB_BOOL, int(idx), 1 if val else 0)
+    return out
+
+
+def inject_startup(eb, presets, scenario=None, words=(), byte_writes=()) -> bytes:
+    """Prepend the preset sequence to **Main_Init** (entry 0, tag 0) so it runs first at field load.
+
+    Byte-safe: inserting at function offset 0 can never be straddled by one of the function's own jumps,
+    and :func:`ff9mapkit.eb.edit.insert_in_function` fixes every entry/func table offset. A no-op (returns
+    the input bytes unchanged) when there is nothing to preset -- so a field without ``[startup]`` builds
+    byte-for-byte as before."""
+    body = startup_body(presets, scenario, words, byte_writes)
+    if not body:
+        return bytes(eb) if isinstance(eb, (bytes, bytearray)) else eb.to_bytes()
+    return edit.insert_in_function(eb, 0, 0, 0, body)

ff9mapkit/content/synthesis.py

@@ -0,0 +1,106 @@
+"""``[[synthesis]]`` -- author a custom SYNTHESIS shop: recipes (a ``Synthesis.csv`` delta) + the SAME
+``Menu(2, id)`` opener as :mod:`content.shop`.
+
+A synthesis shop combines INGREDIENT items + gil -> a RESULT item. Two engine facts make it a pure data patch
+(no DLL), grounded in the Memoria source:
+
+* **A shop id opens as a SYNTHESIS shop iff it is NOT present in ``ShopItems.csv``** (``ff9buy.FF9Buy_GetType``:
+  a missing id returns ``ShopType.Synthesis``; an id in ``ShopItems`` is a Buy shop). So a synth shop reuses the
+  ``[[shop]]`` opener VERBATIM -- ``Menu(2, id)`` (``EventService.OpenShopMenu``) -- and the synth shop id must
+  NOT also be a ``[[shop]]`` id (that would add it to ``ShopItems.csv`` and flip it to a BUY shop).
+* **A shop's recipes = every ``Synthesis.csv`` row whose ``Shops`` list contains the shop id**
+  (``ShopUI.InitializeMixList``). ``Synthesis.csv`` (``FF9MIX_DATA``) = ``Comment;Id;Shops;Price;Result;Ingredients``
+  with ``#! UseShopList`` (so ``Shops`` parses as an ``Int32[]``); MERGED by Id low->high, whole-row
+  (``ff9mix.LoadSynthesis`` via ``EnumerateCsvFromLowToHigh``). The kit MINTS recipe ids ABOVE the base max (63)
+  so a delta only ADDS recipes, never clobbers a base one. Base rows are read LIVE from the install (cp1252),
+  delta generated at build time -> the repo commits NO game data (same stance as :mod:`content.itemdata`).
+
+The recipe CSV is mod-global (one ``Synthesis.csv`` per mod, recipes collected across every built field's
+``[[synthesis]]`` blocks); the opener is per-field ``.eb`` (reused from :mod:`content.shop` -- ``Menu(2, id)`` is
+byte-identical to a buy shop's, the engine decides Buy-vs-Synthesis from the id alone).
+
+    [[synthesis]]
+    shop = 40                       # the synth-shop id (NOT a [[shop]] buy id; 32..255)
+    recipes = [
+      { result = "Butterfly Sword", ingredients = ["Dagger", "Mage Masher"], price = 300 },
+      { result = "The Ogre",        ingredients = ["Mage Masher", "Mage Masher"], price = 700 },
+    ]
+    # optional standalone opener (else open it from an NPC with opens_shop = 40):
+    zone = [[-400, -900], [400, -900], [400, -500], [-400, -500]]
+"""
+from __future__ import annotations
+
+from .. import items as _items
+from . import shop as _shop
+from .itemdata import read_base_csv, _read_text, CSV_ENCODING
+
+PRICE_CAP = 9_999_999       # gil cap (UInt32 Price; a cost above the holdable gil cap is pointless)
+NO_ITEM = 255               # NoItem -- meaningless as a result/ingredient (the engine skips it when counting)
+FIRST_SYNTH_SHOP = _shop.FIRST_CUSTOM_SHOP   # >= 32: ids 0-31 are base BUY shops (in ShopItems) -> never Synthesis
+MAX_SHOP_ID = _shop.MAX_SHOP_ID              # <= 255: the Menu(2, id) sub-id is a single byte
+
+
+def base_max_id(base_text: str) -> int:
+    """The highest recipe Id in the base ``Synthesis.csv`` (so a mint lands ABOVE every base recipe); -1 if none."""
+    _h, _cols, _idc, rows = read_base_csv(base_text)
+    return max(rows, default=-1)
+
+
+def recipe_rows(synth_blocks, base_text) -> list:
+    """``[(id, shop, price, result, [ingredient_id, ...], comment), ...]`` for every recipe across all
+    ``[[synthesis]]`` blocks -- recipe ids MINTED above the base max (deterministic: block order, then recipe
+    order). Result/ingredient names resolved via :func:`items.resolve`; ``NoItem`` dropped from ingredients
+    (it is meaningless); a recipe with no real result or no real ingredient is SKIPPED here (lint flags it)."""
+    mint = base_max_id(base_text) + 1
+    out = []
+    for b in synth_blocks:
+        shop = int(b["shop"])
+        for r in b.get("recipes", []):
+            result = _items.resolve(r["result"])
+            ingredients = []
+            for entry in r.get("ingredients", []):
+                iid = _items.resolve(entry)
+                if iid != NO_ITEM:                       # NoItem ingredient = no-op (skip; keep dups -- need N)
+                    ingredients.append(iid)
+            if result == NO_ITEM or not ingredients:
+                continue
+            price = max(0, min(PRICE_CAP, int(r.get("price", 0))))
+            comment = _shop.safe_comment(_items.name_of(result) or f"Recipe {mint}", mint)
+            out.append((mint, shop, price, result, ingredients, comment))
+            mint += 1
+    return out
+
+
+def render_synthesis(synth_blocks, base_text) -> str:
+    """The ``Synthesis.csv`` delta text: the base header block VERBATIM (so ``#! UseShopList`` + the legend parse
+    identically -> ``Shops`` reads as an ``Int32[]``) + one minted recipe row per recipe. A partial delta -- the
+    engine merges it over the base by Id, so only the new recipes are listed. ``Comment;Id;Shops;Price;Result;
+    Ingredients`` (the Comment cell is the result's name, delimiter-sanitised; no trailing comment -- the base
+    rows have none, and a trailing ``#``-cell would be truncated away by ``CsvReader`` (``Array.Resize`` at the
+    first ``#``-prefixed cell, before ``ParseEntry`` sees the row), so it is pointless rather than harmful)."""
+    header, _cols, _idc, _rows = read_base_csv(base_text)
+    banner = ("# ff9mapkit [[synthesis]] -- custom recipes (Synthesis.csv delta; MERGED by id over the base). "
+              "Minted ids are above the base max; Shops = the synth-shop id you open with Menu(2, id).")
+    lines = [header, banner]
+    for rid, shop, price, result, ingredients, comment in recipe_rows(synth_blocks, base_text):
+        ingr = ", ".join(str(i) for i in ingredients)
+        lines.append(f"{comment};{rid};{shop};{price};{result};{ingr}")
+    return "\n".join(lines) + "\n"
+
+
+def write_synthesis(layout, synth_blocks, *, game=None) -> None:
+    """Emit the synthesis-recipe delta into ``layout``'s mod root (``Data/Items/Synthesis.csv``). Reads the base
+    rows from the install (raises a clear ValueError if it isn't reachable -- the delta needs the base header +
+    max id). No blocks -> nothing written (no base clobber)."""
+    if not synth_blocks:
+        return
+    from ..config import find_game_path, ConfigError
+    try:                                                  # ConfigError (no resolvable install) is a RuntimeError,
+        base = find_game_path(game) / "StreamingAssets" / "Data" / "Items" / "Synthesis.csv"   # NOT OSError --
+        base_text = _read_text(base)                      # catch both so build.py's `except ValueError` warns+skips
+    except (OSError, ConfigError) as e:
+        raise ValueError("synthesis recipes ([[synthesis]]) need your FF9 install to read the base "
+                         f"Synthesis.csv (header + recipe ids): {e}") from e
+    path = layout.synthesis_csv
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(render_synthesis(synth_blocks, base_text), encoding=CSV_ENCODING, newline="\n")

ff9mapkit/content/text.py

@@ -0,0 +1,183 @@
+"""Author field dialogue text (``.mes``).
+
+Memoria loads field text cumulatively across mods: a mod's
+``FF9_Data/embeddedasset/text/<lang>/field/<mesId>.mes`` is merged over the base block, and
+explicit ``[TXID=n]`` indices let a mod *add* entries without disturbing the base text — as
+long as you use indices the base block doesn't occupy (a high TXID like 500+). That is the
+trick proven in Session 9: drop a ``<mesId>.mes`` with our line at a high index; the base
+text is untouched, our entry is added, and an NPC's WindowSync(... , txid) resolves to it.
+
+Format of one entry::
+
+    _[TXID=500][STRT=10,1][TAIL=UPR]I miss you Zidane[ENDN]
+
+The leading ``_`` (any non-``[STRT=`` character) is required so the parser treats ``[TXID=]``
+as a re-index rather than the start of entry 0.
+"""
+
+from __future__ import annotations
+
+import re
+
+# A safe starting index for mod-added dialogue (base field blocks don't use these).
+DEFAULT_BASE_TXID = 500
+
+# The dialogue window's TAIL — the little pointer that aims at the speaker (FF9's "who's talking"
+# cue; there's no separate name-box). Codes map to Dialog.TailPosition (FFIXTextTag.GetTailPosition):
+#   UPR/UPL upper-right/left · LOR/LOL lower-right/left · UPC/LOC upper/lower-center
+#   ...F variants force that corner · DEFT = engine default/auto-position
+TAIL_CODES = {"UPR", "UPL", "LOR", "LOL", "UPC", "LOC",
+              "UPRF", "UPLF", "LORF", "LOLF", "DEFT"}
+DEFAULT_TAIL = "UPR"
+
+# How a `speaker` name is prefixed onto a line. FF9 has no name-box, so a name is just part of the
+# text; ": " is the common readable form. Use a name-variable tag in the speaker for a renameable
+# party member, e.g. speaker = "[VIVI]" -> renders the player's chosen name for Vivi.
+SPEAKER_SEP = ": "
+
+# Dialogue CHOICE text (one entry holds the prompt + the selectable rows). After the prompt, [CHOO]
+# starts the option list and each subsequent newline is one selectable row; [MOVE=18,0] indents each
+# row so the selection cursor has room (FF9's exact convention -- see Memoria FFIXTextTagCode). So a
+# choice entry's text is:  prompt + CHOICE_OPEN + ("\n" + CHOICE_INDENT).join(options).
+CHOICE_INDENT = "[MOVE=18,0]"
+CHOICE_OPEN = "\n[CHOO]" + CHOICE_INDENT
+# [IMME] = IMMEDIATE display: the window pops fully drawn with NO character-by-character type-on. FF9's own
+# shop/menu choices use it (e.g. the Treno Weapon Shop's "What can I do for you?" Buy/Sell menu ends in
+# [IMME]) so a SELECTOR feels instant, while story dialogue types out. Appended to a choice entry when the
+# [[choice]] sets `instant = true` (the World Hub journey menu turns it on).
+CHOICE_IMME = "[IMME]"
+
+
+def with_speaker(speaker, text: str) -> str:
+    """Prefix ``speaker`` onto a dialogue line (``"Vivi: ...">``), or return ``text`` unchanged when no
+    speaker. ``speaker`` may be a plain name or an FF9 name tag like ``[ZDNE]`` / ``[VIVI]``."""
+    return f"{speaker}{SPEAKER_SEP}{text}" if speaker else text
+
+
+def mes_entry(text: str, txid: int, *, strt: tuple = (10, 1), tail: str = DEFAULT_TAIL) -> str:
+    """One ``.mes`` entry line that ADDS dialogue at ``txid`` without touching base text."""
+    strt_s = ",".join(str(v) for v in strt)
+    return f"_[TXID={txid}][STRT={strt_s}][TAIL={tail}]{text}[ENDN]"
+
+
+def build_mes(lines, *, start_txid: int = DEFAULT_BASE_TXID, tails=None, strts=None) -> tuple[str, dict]:
+    """Build a ``.mes`` file body from an ordered list of dialogue strings.
+
+    Returns ``(text, mapping)`` where ``mapping[i]`` is the TXID assigned to ``lines[i]`` (so a
+    caller can point each NPC's WindowSync at the right id). TXIDs are ``start_txid + i``.
+    ``tails`` (optional) is a per-line list of TAIL codes; ``None``/missing entries use
+    :data:`DEFAULT_TAIL`. ``strts`` (optional) is a per-line ``(x, y)`` window geometry; ``None``/missing
+    entries use ``mes_entry``'s default ``(10, 1)`` -- so existing callers stay byte-identical. (A FF9
+    *system* window like the chest's item-get box auto-CENTERS from its ``[STRT=width,lines]``, so it must
+    pass its real geometry, not the dialogue default.)
+    """
+    entries = []
+    mapping = {}
+    for i, line in enumerate(lines):
+        txid = start_txid + i
+        mapping[i] = txid
+        tail = (tails[i] if tails and i < len(tails) and tails[i] else DEFAULT_TAIL)
+        strt = (strts[i] if strts and i < len(strts) and strts[i] else (10, 1))
+        entries.append(mes_entry(line, txid, strt=strt, tail=tail))
+    return "\n".join(entries) + "\n", mapping
+
+
+# --------------------------------------------------------------------------- proportional auto-wrap
+# FF9 field dialogue does NOT auto-wrap: the window grows to fit the widest line, so an un-broken long
+# line runs off the screen. The original game hand-breaks every line; we reproduce that at build time.
+#
+# Why this is PROPORTIONAL and not pixel-exact (from Memoria source): the field dialogue font is a
+# *runtime dynamic TrueType* font -- EncryptFontManager.InitializeFont ->
+# Font.CreateDynamicFontFromOSFont(Configuration.Font.Names, ...), default the bundled "TBUDGoStd-Bold",
+# overridable in Memoria.ini [Font]. Glyph widths come from Unity's TTF rasterizer at a configurable
+# size, per language (NGUIText.GetGlyphWidth -> mTempChar.advance). So there is NO fixed pixel-width
+# table to ship and exact-per-install wrapping is impossible offline. Instead we model RELATIVE glyph
+# widths for a bold proportional sans ('W'/'m' ~3x 'i'/'l') and wrap at a conservative width budget --
+# accurate where it matters (it respects glyph widths) and erring toward wrapping a hair early so it
+# never overflows. Tune `wrap` per field for fuller lines (one in-game check finds your true max).
+
+# max rendered line width, in "width units" (~ average characters). Conservative by default.
+DEFAULT_WRAP_WIDTH = 28.0
+_DEFAULT_GLYPH_W = 1.0
+
+# relative advances for a bold proportional sans (em-ish; a typical letter ~0.9). Approximate by design.
+_GLYPH_W = {
+    " ": 0.5,
+    "'": 0.3, "|": 0.3, "`": 0.3, ".": 0.4, ",": 0.4, ";": 0.4, ":": 0.4,
+    "!": 0.45, "i": 0.45, "j": 0.45, "l": 0.45, "I": 0.5,
+    "(": 0.5, ")": 0.5, "[": 0.5, "]": 0.5, "/": 0.5, "\\": 0.5,
+    "f": 0.55, "t": 0.55, '"': 0.6, "-": 0.6, "r": 0.6,
+    "s": 0.75, "J": 0.75, "?": 0.9,
+    "m": 1.45, "w": 1.4, "M": 1.6, "W": 1.6, "@": 1.6, "&": 1.25,
+}
+for _c in "abcdeghknopquvxyz":
+    _GLYPH_W.setdefault(_c, 0.9)
+for _c in "ABCDEFGHKLNOPQRSTUVXYZ":
+    _GLYPH_W.setdefault(_c, 1.15)
+for _c in "0123456789":
+    _GLYPH_W.setdefault(_c, 0.95)
+
+_TAG_RE = re.compile(r"\[[^\]]*\]")
+# tags render nothing (color/format/control) EXCEPT name/variable tags, which render text at runtime.
+_NAME_TAGS = {"ZDNE", "VIVI", "DGGR", "STNR", "FRYA", "QUIN", "EIKO", "AMRT",
+              "PTY1", "PTY2", "PTY3", "PTY4"}
+
+
+def _tag_render_width(tag: str) -> float:
+    code = tag[1:-1].split("=", 1)[0].strip().upper()      # "[VIVI]" -> "VIVI"; "[ICON=5]" -> "ICON"
+    if code in _NAME_TAGS:
+        return 6.0          # a (renameable) party name; ~6 characters
+    if code in ("TEXT", "NUMB", "ITEM", "ICON"):
+        return 4.0          # an inserted variable / item name / icon; rough
+    return 0.0              # color / format / page / control tag -> no glyphs
+
+
+def measure(text: str) -> float:
+    """Approximate rendered width of a dialogue line in width units (~average characters). Literal
+    ``[...]`` tag brackets are not counted; their *rendered* content is (a name tag ~ a name, a color
+    tag ~ nothing). Approximate by design -- see the module note on why pixel-exact is impossible."""
+    total, i = 0.0, 0
+    for m in _TAG_RE.finditer(text):
+        total += sum(_GLYPH_W.get(c, _DEFAULT_GLYPH_W) for c in text[i:m.start()])
+        total += _tag_render_width(m.group())
+        i = m.end()
+    total += sum(_GLYPH_W.get(c, _DEFAULT_GLYPH_W) for c in text[i:])
+    return total
+
+
+def wrap_text(text: str, width: float = DEFAULT_WRAP_WIDTH):
+    """Break ``text`` into lines that each fit within ``width`` units, reproducing FF9's hand-broken
+    dialogue. Existing ``\\n`` and ``[PAGE]`` breaks are respected (each page/line wrapped on its own),
+    and a segment that already fits is kept BYTE-IDENTICAL (so short lines never change). Returns
+    ``(wrapped, overflow)`` where ``overflow`` lists single words too wide to fit on a line alone."""
+    overflow = []
+    out_pages = []
+    for page in text.split("[PAGE]"):
+        out_lines = []
+        for seg in page.split("\n"):
+            if measure(seg) <= width:
+                out_lines.append(seg)                      # already fits -> verbatim
+                continue
+            cur = ""
+            for word in seg.split(" "):
+                if measure(word) > width:
+                    overflow.append(word)                  # an unbreakable, over-wide single word
+                cand = f"{cur} {word}" if cur else word
+                if cur and measure(cand) > width:
+                    out_lines.append(cur)
+                    cur = word
+                else:
+                    cur = cand
+            out_lines.append(cur)
+        out_pages.append("\n".join(out_lines))
+    return "[PAGE]".join(out_pages), overflow
+
+
+def overflow_lines(text: str, width: float = DEFAULT_WRAP_WIDTH):
+    """Final wrapped lines that STILL exceed ``width`` -- i.e. an unbreakable over-wide word (a long
+    name/URL). Empty list = everything fits after wrapping. Used to warn at build time."""
+    wrapped, _ = wrap_text(text, width)
+    bad = []
+    for page in wrapped.split("[PAGE]"):
+        bad.extend(ln for ln in page.split("\n") if measure(ln) > width)
+    return bad