ff9mapkit 1.0.0b3__tar.gz

ff9mapkit-1.0.0b3/LICENSE

@@ -0,0 +1,31 @@
+MIT License
+
+Copyright (c) 2026 GameJawnsInc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+The MIT license above covers the ff9mapkit SOURCE CODE only.
+
+It does NOT cover, and ff9mapkit does not grant any rights to, FINAL FANTASY IX
+game data. Any FF9-derived bytes (field scripts, walkmeshes, scene/camera data,
+text, art) belong to Square Enix. ff9mapkit reads such data from the user's own
+legally-owned installation; a clean public distribution should not redistribute
+it (see docs/ENGINE.md). Background art you create is your own.

ff9mapkit-1.0.0b3/PKG-INFO

@@ -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.

ff9mapkit-1.0.0b3/README.md

@@ -0,0 +1,120 @@
+# 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.

ff9mapkit-1.0.0b3/ff9mapkit/__init__.py

@@ -0,0 +1,18 @@
+"""ff9mapkit — author novel custom field maps for Final Fantasy IX (Memoria engine).
+
+The kit compiles a declarative per-field TOML project into a drop-in Memoria mod:
+field background scene (.bgx + overlay PNGs), walkmesh (.bgi), event script (.eb, all
+languages), dialogue text (.mes), and the DictionaryPatch / BattlePatch registration —
+everything a custom field needs at runtime on a *stock* (unmodified) Memoria install.
+
+Public surface is organized as:
+  ff9mapkit.config    — game/mod path resolution + the FF9 mod folder layout
+  ff9mapkit.binutils  — little-endian struct helpers shared by the binary codecs
+  ff9mapkit.eb        — the field event-script (.eb) library (model / edit / disasm / opcodes)
+  ff9mapkit.scene     — camera math, .bgx scene, .bgi walkmesh, paint guides
+  ff9mapkit.content   — generalized script-content injectors (npc/gateway/encounter/...)
+  ff9mapkit.build     — the field.toml -> mod-folder builder
+  ff9mapkit.battle    — the battle.toml -> custom battle-background (BBG) builder (fork/edit/build a 3D battle map)
+"""
+
+__version__ = "1.0.0b3"   # keep in lockstep with [project] version in pyproject.toml

ff9mapkit-1.0.0b3/ff9mapkit/__main__.py

@@ -0,0 +1,36 @@
+"""Enable ``python -m ff9mapkit ...`` (identical to the ``ff9mapkit`` console command).
+
+Handy when the package isn't pip-installed on PATH -- run it from the repo:
+    py -m ff9mapkit build my_room.field.toml --out dist
+
+Robustness: running ``python -m ff9mapkit`` from a directory whose child folder is ALSO named
+``ff9mapkit`` (e.g. the repo *parent* that contains the ``ff9mapkit/`` project) makes Python pick
+up that folder as an empty PEP-420 namespace package, shadowing the real install -- so
+``from . import __version__`` blows up with "cannot import name ... (unknown location)". This file
+lives at the real package's true path, so we detect the shadow and repoint the import there.
+"""
+
+import sys
+from pathlib import Path
+
+
+def _ensure_real_package() -> None:
+    """If ``ff9mapkit`` resolved to a namespace shadow (a folder with no __init__), repoint it at the
+    real package -- the directory holding THIS file -- so the absolute import below loads code."""
+    pkg = sys.modules.get("ff9mapkit")
+    if pkg is not None and getattr(pkg, "__file__", None) is not None:
+        return                                   # already the real, importable package -- nothing to do
+    real_parent = str(Path(__file__).resolve().parent.parent)   # dir that CONTAINS the real ff9mapkit/
+    sys.path.insert(0, real_parent)
+    for name in [m for m in sys.modules if m == "ff9mapkit" or m.startswith("ff9mapkit.")]:
+        if name != __name__:                     # keep this running module
+            del sys.modules[name]
+    import importlib
+    importlib.invalidate_caches()
+
+
+_ensure_real_package()
+from ff9mapkit.cli import main      # noqa: E402  (must follow the sys.path repair above)
+
+if __name__ == "__main__":
+    sys.exit(main())