ff9mapkit 1.0.0b3__py3-none-any.whl

ff9mapkit/workspace/style.py

@@ -0,0 +1,105 @@
+"""A Qt Style Sheet (QSS) for the workspace shell, generated from a theme palette.
+
+PySide6-FREE -- a pure ``str``-building function over a palette dict, so it's unit-testable on a headless
+machine (the same discipline as :mod:`..editor.theme`, whose ``LIGHT``/``DARK`` palettes this consumes).
+QSS uses ``{`` / ``}`` heavily, so the template uses ``string.Template``'s ``$name`` placeholders (which
+leave braces alone) rather than ``str.format``.
+"""
+
+from __future__ import annotations
+
+from string import Template
+
+# Every $name below must be a key in the palette (editor.theme LIGHT/DARK provide them all).
+_QSS = Template(
+    """
+    * { outline: 0; }
+    QWidget { background-color: $bg; color: $text; font-family: "Segoe UI"; font-size: 13px; }
+    QMainWindow::separator { background: $border; width: 1px; height: 1px; }
+
+    QToolBar { background: $surface; border: 0; border-bottom: 1px solid $border; padding: 5px 8px; spacing: 8px; }
+    QToolButton, QPushButton {
+        background: $surface_btn; color: $text; border: 1px solid $border;
+        border-radius: 6px; padding: 6px 12px;
+    }
+    QToolButton:hover, QPushButton:hover { background: $hover; }
+    QPushButton:pressed, QToolButton:pressed { background: $pressed; }
+    QPushButton:disabled { color: $muted; background: $bg; }
+    QPushButton#accent { background: $accent; color: $accent_fg; border: 1px solid $accent; }
+    QPushButton#accent:hover { background: $accent_hover; }
+    QPushButton#accent:pressed { background: $accent_pressed; }
+    /* a disabled accent button (e.g. Save with nothing to save) must grey out -- the #accent id
+       selector otherwise out-ranks the generic :disabled rule and would stay blue. */
+    QPushButton#accent:disabled { background: $surface_btn; color: $muted; border: 1px solid $border; }
+
+    /* Indicators MUST be fully specified: once a stylesheet touches a QCheckBox/QRadioButton, Qt stops
+       drawing the native checked dot, so without this the selected state renders INVISIBLE. */
+    QCheckBox, QRadioButton { background: transparent; spacing: 7px; }
+    QCheckBox::indicator, QRadioButton::indicator {
+        width: 15px; height: 15px; border: 1px solid $border; background: $field;
+    }
+    QRadioButton::indicator { border-radius: 8px; }
+    QCheckBox::indicator { border-radius: 4px; }
+    QCheckBox::indicator:hover, QRadioButton::indicator:hover { border: 1px solid $accent; }
+    QCheckBox::indicator:checked, QRadioButton::indicator:checked {
+        background: $accent; border: 1px solid $accent;
+    }
+    QCheckBox::indicator:disabled, QRadioButton::indicator:disabled { border: 1px solid $muted; background: $bg; }
+
+    QLineEdit {
+        background: $field; color: $text; border: 1px solid $border; border-radius: 6px;
+        padding: 6px 9px; selection-background-color: $accent; selection-color: $accent_fg;
+    }
+    QLineEdit:focus { border: 1px solid $accent; }
+    QLineEdit#search { background: $surface; color: $muted; }
+
+    QTreeWidget, QTreeView, QListWidget {
+        background: $surface; border: 1px solid $border; border-radius: 8px; padding: 4px;
+    }
+    QTreeView::item, QListWidget::item { padding: 5px 4px; border-radius: 4px; }
+    QTreeView::item:hover, QListWidget::item:hover { background: $hover; }
+    QTreeView::item:selected, QListWidget::item:selected { background: $accent; color: $accent_fg; }
+    QHeaderView::section { background: $surface_btn; color: $muted; border: 0; padding: 5px; }
+
+    QTabWidget::pane { border: 1px solid $border; border-radius: 8px; top: -1px; }
+    QTabBar::tab {
+        background: $surface_btn; color: $muted; padding: 7px 16px; border: 1px solid $border;
+        border-bottom: 0; border-top-left-radius: 6px; border-top-right-radius: 6px; margin-right: 2px;
+    }
+    QTabBar::tab:selected { background: $bg; color: $text; }
+    QTabBar::tab:hover { color: $text; }
+
+    QPlainTextEdit, QTextEdit {
+        background: $log_bg; color: $log_fg; border: 1px solid $border; border-radius: 8px;
+        font-family: "Cascadia Code", "Consolas", monospace; font-size: 12px; padding: 6px;
+    }
+
+    /* dropdown menus (the toolbar Field / Campaign / Journey buttons) */
+    QMenu { background: $surface; border: 1px solid $border; border-radius: 6px; padding: 4px; }
+    QMenu::item { padding: 6px 22px; border-radius: 4px; }
+    QMenu::item:selected { background: $accent; color: $accent_fg; }
+    QMenu::separator { height: 1px; background: $border; margin: 4px 6px; }
+
+    QDockWidget { color: $muted; }
+    QDockWidget::title { background: $surface; padding: 6px 9px; border-bottom: 1px solid $border; }
+
+    QScrollBar:vertical { background: $bg; width: 12px; margin: 0; }
+    QScrollBar::handle:vertical { background: $scroll; border-radius: 5px; min-height: 28px; }
+    QScrollBar:horizontal { background: $bg; height: 12px; margin: 0; }
+    QScrollBar::handle:horizontal { background: $scroll; border-radius: 5px; min-width: 28px; }
+    QScrollBar::add-line, QScrollBar::sub-line { width: 0; height: 0; }
+    QScrollBar::add-page, QScrollBar::sub-page { background: transparent; }
+
+    QSplitter::handle { background: $border; }
+    QSplitter::handle:horizontal { width: 1px; }
+    QSplitter::handle:vertical { height: 1px; }
+    QLabel { background: transparent; }
+    QStatusBar { background: $surface; color: $muted; border-top: 1px solid $border; }
+    QToolTip { background: $surface; color: $text; border: 1px solid $border; }
+    """
+)
+
+
+def qss(palette: dict) -> str:
+    """Render the workspace stylesheet for ``palette`` (an :mod:`..editor.theme` LIGHT/DARK dict)."""
+    return _QSS.substitute(palette)

ff9mapkit/workspace/tuningdialog.py

@@ -0,0 +1,223 @@
+"""A modal editor for a journey's ``[journey.tuning]`` -- the mod-GLOBAL player/ability CSV deltas (BaseStats /
+abilities / leveling / status / ...). It REUSES the battle "Party & abilities" specs verbatim
+(:data:`ff9mapkit.editor.battle_forms.PLAYER_TABLES`) over the shared tk-free form machinery
+(:mod:`ff9mapkit.editor.forms` + :mod:`forms_qt`), so the same tables a battle.toml carries are authored here at
+the journey level -- the placement the user chose (mod-global tuning = journey).
+
+The dialog is self-contained: a left row-list (one per tuning entry, ``<table> · <selector>``), a right form host,
+Add / Remove, and OK/Cancel. ``result_tuning`` holds the edited ``{block: [rows]}`` dict on accept (else None); the
+caller (:meth:`ff9mapkit.workspace.shell.Workspace.on_set_journey_tuning`) writes it back with
+:func:`ff9mapkit.journey.set_journey_tuning`. The nested player tables (``[[learn]]`` / ``[[ability_feature]]`` /
+``[[status_set]]`` / ``[[magic_sword_set]]``) stay hand-authored -- as everywhere else -- and are left untouched.
+"""
+from __future__ import annotations
+
+from PySide6.QtWidgets import (
+    QComboBox, QDialog, QDialogButtonBox, QFrame, QHBoxLayout, QLabel, QListWidget, QPushButton, QScrollArea,
+    QSplitter, QVBoxLayout, QWidget,
+)
+
+from ..editor import battle_forms as bf
+from ..editor import forms
+from .forms_qt import build_form, read
+
+
+class TuningDialog(QDialog):
+    """Edit a journey's ``[journey.tuning]`` player/ability CSV blocks. ``tuning`` is the current ``{block:
+    [rows]}`` (only the KNOWN player-table blocks are editable; unknown/nested ones are preserved by the caller's
+    text writer, untouched here). On accept, :attr:`result_tuning` is the edited dict (blocks with no rows
+    dropped); on cancel it's None."""
+
+    def __init__(self, parent, palette, jid, tuning, *, is_bare=False):
+        super().__init__(parent)
+        self.pal = palette
+        self.jid = jid
+        self.setWindowTitle(f"Tuning — {jid}")
+        self.resize(660, 470)
+        # a working COPY of just the FORM-editable blocks (the 7 PLAYER_SPECS); deep enough that Cancel discards.
+        self.tuning = {k: [dict(r) for r in (tuning.get(k) or []) if isinstance(r, dict)]
+                       for k in bf.PLAYER_SPECS if tuning.get(k)}
+        # the nested blocks this dialog does NOT edit (learn / ability_feature / status_set / magic_sword_set, +
+        # any unknown key) — carried through verbatim so an edit never DESTROYS hand-authored tuning.
+        self._untouched = {k: v for k, v in (tuning or {}).items() if k not in bf.PLAYER_SPECS}
+        self._rows: list = []          # [(block, idx)] parallel to the list widget
+        self._ctx = None               # {block, idx, spec, getters} for the mounted form
+        self.result_tuning = None
+        self._build_ui(is_bare)
+        self._rebuild()
+        if self.rows.count():
+            self.rows.setCurrentRow(0)
+
+    # ------------------------------------------------------------------ UI
+    def _build_ui(self, is_bare):
+        outer = QVBoxLayout(self)
+        intro = QLabel("Mod-GLOBAL player/ability tuning for this journey — the same BaseStats / abilities / "
+                       "leveling deltas a field.toml carries, injected into the entry member at deploy. One CSV "
+                       "per mod (shared across a multi-journey hub).")
+        intro.setWordWrap(True)
+        intro.setStyleSheet(f"color:{self.pal['muted']};")
+        outer.addWidget(intro)
+        if is_bare:
+            warn = QLabel("⚠ This is a BARE single-field journey — tuning is injected into a MULTI-campaign entry "
+                          "member, so it WON'T apply here. Put the deltas on the entry field's own field.toml.")
+            warn.setWordWrap(True)
+            warn.setStyleSheet(f"color:{self.pal['warn']};")
+            outer.addWidget(warn)
+
+        split = QSplitter()
+        left = QWidget()
+        lv = QVBoxLayout(left)
+        lv.setContentsMargins(0, 0, 0, 0)
+        self.rows = QListWidget()
+        self.rows.currentRowChanged.connect(self._on_row)
+        lv.addWidget(self.rows, 1)
+        self.add_btn = QPushButton("Add tuning…")
+        self.add_btn.clicked.connect(self._add)
+        lv.addWidget(self.add_btn)
+        self.del_btn = QPushButton("Remove selected")
+        self.del_btn.clicked.connect(self._remove)
+        self.del_btn.setEnabled(False)
+        lv.addWidget(self.del_btn)
+        split.addWidget(left)
+
+        right = QWidget()
+        rv = QVBoxLayout(right)
+        rv.setContentsMargins(0, 0, 0, 0)
+        self.host_scroll = QScrollArea()
+        self.host_scroll.setWidgetResizable(True)
+        self.host_scroll.setFrameShape(QFrame.Shape.NoFrame)
+        self.host = QWidget()
+        self.host_lay = QVBoxLayout(self.host)
+        self.host_scroll.setWidget(self.host)
+        rv.addWidget(self.host_scroll, 1)
+        split.addWidget(right)
+        split.setSizes([220, 430])
+        outer.addWidget(split, 1)
+
+        bb = QDialogButtonBox(QDialogButtonBox.StandardButton.Ok | QDialogButtonBox.StandardButton.Cancel)
+        bb.accepted.connect(self._accept)
+        bb.rejected.connect(self.reject)
+        outer.addWidget(bb)
+        self._placeholder("Add a tuning row, or pick one to edit.")
+
+    def _clear(self):
+        while self.host_lay.count():
+            it = self.host_lay.takeAt(0)
+            w = it.widget()
+            if w is not None:
+                w.deleteLater()
+
+    def _placeholder(self, text):
+        self._clear()
+        lbl = QLabel(text)
+        lbl.setStyleSheet(f"color:{self.pal['muted']};")
+        lbl.setWordWrap(True)
+        self.host_lay.addWidget(lbl)
+        self.host_lay.addStretch(1)
+
+    # ------------------------------------------------------------------ row list
+    def _all_rows(self):
+        return [(block, i) for block in bf.PLAYER_SPECS for i in range(len(self.tuning.get(block) or []))]
+
+    def _rebuild(self):
+        self.rows.blockSignals(True)
+        self.rows.clear()
+        self._rows = []
+        for block, i in self._all_rows():
+            row = self.tuning[block][i]
+            self.rows.addItem(f"{bf.PLAYER_LABEL[block]}  ·  {row.get(bf.PLAYER_SELECTOR[block], i)}")
+            self._rows.append((block, i))
+        self.rows.blockSignals(False)
+
+    def _on_row(self, r):
+        if not (0 <= r < len(self._rows)):
+            self.del_btn.setEnabled(False)
+            return
+        self._commit()
+        block, idx = self._rows[r]
+        self.del_btn.setEnabled(True)
+        if 0 <= idx < len(self.tuning.get(block) or []):
+            self._mount(block, idx)
+
+    def _mount(self, block, idx):
+        self._clear()
+        spec = bf.PLAYER_SPECS[block]
+        form, getters = build_form(spec, forms.entity_to_values(spec, self.tuning[block][idx]), self.pal)
+        self.host_lay.addWidget(form)
+        self.host_lay.addStretch(1)
+        self._ctx = {"block": block, "idx": idx, "spec": spec, "getters": getters}
+
+    def _fold(self, ctx) -> bool:
+        try:
+            entity = forms.build_entity(ctx["spec"], read(ctx["getters"]))
+        except ValueError:
+            return False
+        lst = self.tuning.get(ctx["block"]) or []
+        if not (0 <= ctx["idx"] < len(lst)):
+            return False                                   # a stale ctx (its row was removed)
+        lst[ctx["idx"]] = entity
+        return True
+
+    def _commit(self) -> bool:
+        return self._fold(self._ctx) if self._ctx else True
+
+    def _select(self, block, idx):
+        for r, node in enumerate(self._rows):
+            if node == (block, idx):
+                self.rows.setCurrentRow(r)
+                return
+
+    # ------------------------------------------------------------------ add / remove
+    def _add(self):
+        self._commit()
+        block = self._pick_table()
+        if not block:
+            return
+        self.tuning.setdefault(block, []).append(dict(bf.PLAYER_DEFAULT[block]))
+        self._rebuild()
+        self._select(block, len(self.tuning[block]) - 1)
+
+    def _pick_table(self):
+        dlg = QDialog(self)
+        dlg.setWindowTitle("Add tuning")
+        lay = QVBoxLayout(dlg)
+        lay.addWidget(QLabel("Tune which player-side table? It's mod-global — applied to the whole journey."))
+        combo = QComboBox()
+        for key, label, *_ in bf.PLAYER_TABLES:
+            combo.addItem(label, key)
+        lay.addWidget(combo)
+        bb = QDialogButtonBox(QDialogButtonBox.StandardButton.Ok | QDialogButtonBox.StandardButton.Cancel)
+        bb.accepted.connect(dlg.accept)
+        bb.rejected.connect(dlg.reject)
+        lay.addWidget(bb)
+        if dlg.exec() != QDialog.DialogCode.Accepted:
+            return None
+        return combo.currentData()
+
+    def _remove(self):
+        r = self.rows.currentRow()
+        if not (0 <= r < len(self._rows)):
+            return
+        block, idx = self._rows[r]
+        lst = self.tuning.get(block) or []
+        if not (0 <= idx < len(lst)):
+            return
+        self._ctx = None                                   # the mounted form's row is going away — don't commit it
+        del lst[idx]
+        if not lst:
+            self.tuning.pop(block, None)
+        self._rebuild()
+        nxt = min(r, self.rows.count() - 1)
+        if 0 <= nxt < self.rows.count():
+            self.rows.setCurrentRow(nxt)
+        else:
+            self._placeholder("Add a tuning row, or pick one to edit.")
+            self.del_btn.setEnabled(False)
+
+    # ------------------------------------------------------------------ accept
+    def _accept(self):
+        if not self._commit():
+            return                                         # an invalid field stays open (the form highlights it)
+        # the edited form blocks OVER the carried-through nested blocks (disjoint keys -> a clean union)
+        self.result_tuning = {**self._untouched, **{b: rows for b, rows in self.tuning.items() if rows}}
+        self.accept()

ff9mapkit-1.0.0b3.dist-info/METADATA

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: ff9mapkit
+Version: 1.0.0b3
+Summary: Author novel custom field maps for Final Fantasy IX (Memoria engine) from a declarative TOML project file.
+Author: GameJawnsInc
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/GameJawnsInc/Dream-World-IX
+Project-URL: Repository, https://github.com/GameJawnsInc/Dream-World-IX
+Project-URL: Issues, https://github.com/GameJawnsInc/Dream-World-IX/issues
+Keywords: final-fantasy-ix,ff9,memoria,modding,field,map
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Pillow>=9.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-xdist>=3; extra == "dev"
+Provides-Extra: save
+Requires-Dist: pycryptodome>=3.10; extra == "save"
+Provides-Extra: assets
+Requires-Dist: UnityPy; extra == "assets"
+Provides-Extra: gui
+Requires-Dist: PySide6-Essentials>=6.5; extra == "gui"
+Dynamic: license-file
+
+# FF9 Map Kit (`ff9mapkit`)
+
+Author **novel custom field maps** for *Final Fantasy IX* (Steam, via the
+[Memoria engine](https://github.com/Albeoris/Memoria)) from a single declarative
+`field.toml`, compiled into a drop-in Memoria mod.
+
+> Part of the **[Dream World IX](../README.md)** project — `ff9mapkit` is the toolkit/package name
+> (unchanged), `pip install`ed and imported as `ff9mapkit`.
+
+> **Feature-complete and in-game-verified.** The productized form of a proven
+> pipeline for minting brand-new playable FF9 fields, end to end. A **novel** field runs on a
+> **stock, unmodified Memoria install**; a **forked** field needs the small bundled engine patch
+> set for fork fidelity (see [`docs/ENGINE.md`](docs/ENGINE.md)).
+
+**Headline capabilities:** author **any camera angle** from scratch (single / scrolling / multi-camera)
+with a pixel-accurate paint guide · **fork any of ~674 real fields** — camera, walkmesh, art, *and* its
+exits/encounters/music · NPCs, dialogue, gateways, encounters, events, story branching, and cutscenes from
+one `field.toml`. Author it in TOML, a **form-based editor**, or a **[Blender add-on](blender/README.md)**.
+
+> **Full capability list & command reference → [`docs/FEATURES.md`](docs/FEATURES.md)** (with a before/now
+> comparison) and [`SETUP.md`](../SETUP.md) (the 59-command CLI reference). [`docs/gallery/`](docs/gallery/)
+> collects screenshots/GIFs as they're captured.
+
+## What it does
+
+Given a `field.toml` describing one field — its camera, painted background layers, walkmesh,
+NPCs, dialogue, gateways, encounter, and music — `ff9mapkit build` emits everything a custom
+field needs:
+
+- the background scene (`.bgx` camera + overlay PNGs) and walkmesh (`.bgi`),
+- the field event script (`.eb`) for all seven languages,
+- dialogue text (`.mes`),
+- and the `DictionaryPatch` / `BattlePatch` registration + `ModDescription.xml`.
+
+## What stays a human task — the way the originals were made
+
+FF9's backgrounds are **pre-rendered**: the original artists built each room as a 3D scene, shot it
+through a fixed camera to bake a 2D plate, and the game projects the live 3D characters back onto that
+plate through the *same* camera. `ff9mapkit` deliberately follows that pipeline instead of hiding it.
+You place the camera; the kit hands you a **pixel-accurate paint guide** — the floor and walls
+projected onto the canvas, the modern stand-in for the layout render the original artists painted over
+— and you paint the background to match. Your hand-modeled `.obj` walkmesh is converted to the
+engine's `.bgi` and projected through that identical camera, so characters stand exactly where the art
+says they should. Painting the art and (optionally) modeling the geometry stay yours; everything in
+between is the kit.
+
+## Quickstart
+
+```powershell
+pip install -e .                                 # from the ff9mapkit\ package dir
+py -m ff9mapkit doctor                           # verify it found your FF9 install
+py -m ff9mapkit import <field> --out myroom --verbatim   # fork a real field — or `new` for original art
+```
+
+> **Full setup → [`SETUP.md`](../SETUP.md)**: extras (`gui`/`save`/`dev`), game-path resolution, the
+> one-time `extract-templates` (the kit ships no game data — see [Provenance](docs/PROVENANCE.md)),
+> `doctor`, the dev loop, and a guided first-field walkthrough.
+
+**Prefer not to touch TOML?** Author the *logic* (dialogue, events, story flags, encounters, music,
+cutscenes) in the form-based editor — `ff9mapkit edit <field.toml>`. The visual side has a front-end too:
+the [**Blender add-on**](blender/README.md) poses the camera, models the walkmesh, places markers, and
+writes a `scene.toml`. So the suite splits cleanly — **Blender = where things are, the editor = what they
+do** — and `build` compiles both. There's also a one-window [PySide6 Workspace GUI](../SETUP.md#6-the-gui-workspace-optional).
+
+## Commands
+
+59 subcommands — run `ff9mapkit -h` (or `py -m ff9mapkit -h`) for the full list. A taste of the families:
+
+- **Author** — `new` (scaffold) · `guide` (paint guide for your camera) · `walkmesh` · `edit` (form editor)
+- **Build & ship** — `build` · `lint` · `pack` · `export-art`
+- **Fork a real field** — `import` (`--editable`/`--native`/`--verbatim`) · `import-chain` · `fork-report`
+- **Campaigns & journeys** — `new-campaign` / `build-all` · `gen-hub` / `assemble-journey`
+- **Battle maps & tuning** — `battle-import` / `battle-build` · `battle-scene` / `battle-ai`
+- **Dialogue, catalogs & saves** — `dialogue` · `catalog` / `models` / `archetypes` · `flags-inspect` · `items-inspect`
+
+> **The full grouped command reference (all 59, with flags) is in [`SETUP.md` §7](../SETUP.md#7-cli-command-reference).**
+
+## Docs
+
+- [`SETUP.md`](../SETUP.md) — **start here:** install, configure, the dev loop, and your first field (setup + quickstart).
+- [`docs/TUTORIAL.md`](docs/TUTORIAL.md) — the focused ~10-minute first-field walkthrough.
+- [`docs/FEATURES.md`](docs/FEATURES.md) — **the full capability list** (+ before/now comparison).
+- [`docs/gallery/`](docs/gallery/) — collects screenshots/GIFs as they're captured.
+- [`docs/FORMAT.md`](docs/FORMAT.md) — the `field.toml` schema.
+- [`docs/PIPELINE.md`](docs/PIPELINE.md) — the full authoring workflow.
+- [`docs/ENGINE.md`](docs/ENGINE.md) — engine requirements (stock Memoria) + provenance notes.
+- [`docs/PROVENANCE.md`](docs/PROVENANCE.md) — **the kit ships no game data**: how the base assets are
+  regenerated from your own FF9 install (`extract-templates`), and why that's legally clean.
+- [`docs/TECHNICAL.md`](docs/TECHNICAL.md) — the hard problems solved (camera math, `.eb` format, import).
+- [`docs/GLOSSARY.md`](docs/GLOSSARY.md) — terms used across the docs (walkmesh, gateway, fork, GLOB flag…).
+- [`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md) — common first-run failures → fixes.
+- [`docs/KNOWN_ISSUES.md`](docs/KNOWN_ISSUES.md) — beta limitations + the Workspace GUI gaps.
+- [`examples/vivi-hut/`](examples/vivi-hut) — a complete worked example.
+- [`blender/`](blender/README.md) — the **Blender add-on**: visually author the camera + walkmesh,
+  then export a `field.toml` for `build` (Blender 4.2+/5.x).
+
+## How it's built / trusted
+
+The library is split into `eb` (the event-script codec + content injectors), `scene`
+(camera math, `.bgx`, `.bgi` walkmesh, paint guides), `build` (the `field.toml` compiler),
+and `pack`. Correctness is proven by an **offline golden-master test suite**: every codec
+round-trips your install's field assets byte-for-byte (regenerated locally via `extract-templates`
+— the kit ships none), and compiling the example reproduces an in-game-verified field's script exactly.
+
+```bash
+pip install -e ".[dev]" && pytest      # the full suite
+```
+
+## About
+
+I make games — including an FFIX-inspired RPG of my own — so this started as the tool I wanted while
+learning how FF9's fields actually work, not a drive-by experiment. The aim was to build a new room
+the way the game's creators did: paint a background against a 3D-derived guide, then walk on geometry
+projected through the same camera — so authoring a field feels like level design rather than blind
+byte-hacking. Months of reverse-engineering the field format, the projection math, and the event
+bytecode went into making that the easy path. If you're poking at FF9's internals too, I hope it
+saves you the same dig.
+
+Built on (and grateful for) the [Memoria engine](https://github.com/Albeoris/Memoria) — none of this
+is possible without it.