ff9mapkit 1.0.0b3__py3-none-any.whl

ff9mapkit/battle/fbx.py

@@ -0,0 +1,223 @@
+"""Battle-map geometry model + ASCII-FBX emitter (PURE — no I/O, no UnityPy; offline-testable).
+
+A battle background ("BBG") is a Unity model whose child meshes are named Group_0/2/4/8 and classified
+by battlebg.getBbgAttr (battlebg.cs:266): Group_0=PLUS(additive), Group_2=GROUND, Group_4=MINUS
+(subtractive), Group_8=SKY. Memoria's ModelImporter/FbxIO loads a loose FBX from the mod folder INSTEAD
+of the bundle, so a custom battle map ships as an ASCII FBX (+ image#.png textures).
+
+Recipe verified in-game 2026-06-09 (a synthetic quad AND a faithful BBG_B013 round-trip):
+  * one FBX Geometry per submesh, named "Geometry::Group_N" (duplicate names are fine — getBbgAttr
+    matches the literal child-name string);
+  * verts / uvs / normals VERBATIM (no axis flip, no scale, no UV V-flip);
+  * triangles use the FBX polygon-end convention (last index of each face = -i-1); native winding kept;
+  * the Model node is typed "Mesh" (NOT LimbNode/Root — else a skeleton NRE in CreateCustomModelFromFbx)
+    with identity transform, so GetVertices applies an identity bone matrix;
+  * the Material's ShadingModel is set DIRECTLY to the group's PSX shader — imported meshes become
+    SkinnedMeshRenderers, which battlebg's MeshRenderer-only shader pass (SetMaterialShader/setBGColor)
+    skips, so the in-FBX shader is what sticks (GetShaderPathFromType passes non-Default/Phong verbatim);
+  * texture via a Texture node RelativeFilename + an "OP" connection; loaded from disc next to the FBX.
+
+`groups` is the canonical geometry structure (also what battle.extract produces):
+    [ { "name": "Group_2",
+        "verts":  [[x,y,z], ...],            # per vertex (Unity space, verbatim)
+        "normals":[[x,y,z], ...] | None,     # per vertex
+        "uvs":    [[u,v], ...],              # per vertex
+        "submeshes": [ {"texture": "image6", "tris": [[a,b,c], ...]} ] },  # tris index into verts
+      ... ]
+"""
+from __future__ import annotations
+
+# Group child-name -> PSX shader (battlebg.SetDefaultShader, battlebg.cs:52-75) and attribute name.
+GROUP_SHADER = {
+    "Group_0": "PSX/BattleMap_Plus",
+    "Group_2": "PSX/BattleMap_Ground",
+    "Group_4": "PSX/BattleMap_Minus",
+    "Group_8": "PSX/BattleMap_Sky",
+}
+GROUP_ATTR = {"Group_0": "PLUS", "Group_2": "GROUND", "Group_4": "MINUS", "Group_8": "SKY"}
+
+
+def validate_groups(groups) -> list[str]:
+    """Return human-readable problems with a `groups` structure (empty => OK)."""
+    problems: list[str] = []
+    if not groups:
+        problems.append("no geometry groups")
+    for g in groups:
+        name = g.get("name")
+        if name not in GROUP_SHADER:
+            problems.append(f"group {name!r} is not one of Group_0/2/4/8 "
+                            f"(getBbgAttr would default it to PLUS)")
+        vc = len(g.get("verts", []))
+        if vc == 0:
+            problems.append(f"group {name!r} has no vertices")
+        if g.get("normals") is not None and len(g["normals"]) != vc:
+            problems.append(f"group {name!r}: normals count ({len(g['normals'])}) != verts count ({vc})")
+        if len(g.get("uvs", [])) != vc:
+            problems.append(f"group {name!r}: uvs count ({len(g.get('uvs', []))}) != verts count ({vc})")
+        for sm in g.get("submeshes", []):
+            if not sm.get("texture"):
+                problems.append(f"group {name!r}: a submesh has no texture")
+            for tri in sm.get("tris", []):
+                if any(i < 0 or i >= vc for i in tri):
+                    problems.append(f"group {name!r}: triangle index out of range (verts={vc})")
+                    break
+    return problems
+
+
+def textures_used(groups) -> list[str]:
+    """Sorted unique texture stems referenced by the geometry (the image#.png siblings to ship)."""
+    return sorted({sm["texture"] for g in groups for sm in g.get("submeshes", []) if sm.get("texture")})
+
+
+def emit_fbx(groups) -> tuple[str, int]:
+    """Render `groups` to ASCII FBX text. Returns (fbx_text, geometry_count).
+
+    One Geometry/Model/Material/Texture per submesh. The Model is typed "Mesh" with no transform, so
+    Memoria reads vertices verbatim; the Material's ShadingModel is the group's PSX shader.
+    """
+    objs: list[str] = []
+    conns: list[str] = []
+    nid = 1000
+    ngeo = 0
+    for g in groups:
+        name = g["name"]
+        shader = GROUP_SHADER.get(name, "PSX/BattleMap_Plus")
+        verts = g["verts"]
+        norms = g.get("normals")
+        uvs = g["uvs"]
+        vc = len(verts)
+        has_n = norms is not None and len(norms) == vc
+        vflat = ",".join(f"{c:g}" for v in verts for c in v)
+        nflat = ",".join(f"{c:g}" for n in norms for c in n) if has_n else ""
+        uflat = ",".join(f"{c:g}" for uv in uvs for c in uv)
+        for sm in g["submeshes"]:
+            gid, mid, matid, texid = nid, nid + 1, nid + 2, nid + 3
+            nid += 10
+            ngeo += 1
+            pvi: list[int] = []
+            for (a, b, c) in sm["tris"]:
+                pvi += [a, b, -c - 1]   # FBX polygon-end convention
+            pviflat = ",".join(str(i) for i in pvi)
+            tex = sm["texture"]
+            geo = [f'\tGeometry: {gid}, "Geometry::{name}", "Mesh" {{']
+            geo.append(f'\t\tVertices: *{vc * 3} {{\n\t\t\ta: {vflat}\n\t\t}}')
+            geo.append(f'\t\tPolygonVertexIndex: *{len(pvi)} {{\n\t\t\ta: {pviflat}\n\t\t}}')
+            if has_n:
+                geo.append(f'\t\tLayerElementNormal: 0 {{\n\t\t\tMappingInformationType: "ByVertex"\n'
+                           f'\t\t\tReferenceInformationType: "Direct"\n'
+                           f'\t\t\tNormals: *{vc * 3} {{\n\t\t\t\ta: {nflat}\n\t\t\t}}\n\t\t}}')
+            geo.append(f'\t\tLayerElementUV: 0 {{\n\t\t\tMappingInformationType: "ByVertex"\n'
+                       f'\t\t\tReferenceInformationType: "Direct"\n'
+                       f'\t\t\tUV: *{vc * 2} {{\n\t\t\t\ta: {uflat}\n\t\t\t}}\n\t\t}}')
+            geo.append('\t}')
+            objs.append("\n".join(geo))
+            objs.append(f'\tModel: {mid}, "Model::{name}", "Mesh" {{\n\t}}')
+            objs.append(f'\tMaterial: {matid}, "Material::{name}_{texid}", "" {{\n'
+                        f'\t\tShadingModel: "{shader}"\n\t}}')
+            objs.append(f'\tTexture: {texid}, "Texture::{tex}", "" {{\n'
+                        f'\t\tRelativeFilename: "{tex}.png"\n\t}}')
+            conns.append(f'\tC: "OO", {gid}, {mid}')        # geometry -> model
+            conns.append(f'\tC: "OO", {matid}, {mid}')      # material -> model
+            conns.append(f'\tC: "OP", {texid}, {matid}, "DiffuseColor"')  # texture -> material
+    return (
+        "; FBX 7.4.0 project file\n\nFBXHeaderExtension:  {\n\tFBXVersion: 7400\n}\n"
+        "Objects:  {\n" + "\n".join(objs) + "\n}\n"
+        "Connections:  {\n" + "\n".join(conns) + "\n}\n"
+    ), ngeo
+
+
+# --------------------------------------------------------------------- parse (inverse of emit_fbx)
+import re as _re
+
+_NODE_RE = _re.compile(r'(Geometry|Model|Material|Texture):\s*(\d+),\s*"([^"]*)",\s*"[^"]*"\s*\{')
+_CONN_RE = _re.compile(r'C:\s*"(OO|OP)",\s*(\d+),\s*(\d+)')
+
+
+def _block(text, start):
+    """The text of the brace-balanced block beginning at the '{' at/after `start`. Tolerant of the
+    nested `{ }` of LayerElement*/array sub-blocks our emitter produces."""
+    depth = 0
+    i = text.index("{", start)
+    j = i
+    while j < len(text):
+        ch = text[j]
+        if ch == "{":
+            depth += 1
+        elif ch == "}":
+            depth -= 1
+            if depth == 0:
+                return text[i + 1:j]
+        j += 1
+    return text[i + 1:]
+
+
+def _floats(s):
+    return [float(x) for x in s.replace("\n", " ").split(",") if x.strip()]
+
+
+def _ints(s):
+    return [int(float(x)) for x in s.replace("\n", " ").split(",") if x.strip()]
+
+
+def parse_fbx(text):
+    """Inverse of :func:`emit_fbx`: parse an FBX WE emitted back to the canonical `groups` structure.
+
+    NOT a general FBX reader -- it understands exactly our emitter's layout (one Geometry/Model/Material/
+    Texture per submesh, the Connections tying texture->material->model<-geometry). Geometries that share a
+    child-name (Group_N) are merged into one group with one submesh each, so
+    ``emit_fbx(parse_fbx(emit_fbx(g))) == emit_fbx(g)`` (round-trip; tested). Lets the Blender add-on load a
+    kit-built/forked BBG_B###.fbx for reshaping, then re-export it through the same emitter.
+    """
+    # 1) index every Objects node by id, capturing its inner block text
+    nodes = {}                                            # id -> (kind, child_name, block_text)
+    for m in _NODE_RE.finditer(text):
+        kind, nid, label = m.group(1), int(m.group(2)), m.group(3)
+        child = label.split("::", 1)[1] if "::" in label else label
+        nodes[nid] = (kind, child, _block(text, m.end() - 1))
+    # 2) connections: geo->model (OO), material->model (OO), texture->material (OP)
+    model_of_geo, mat_of_model, tex_of_mat = {}, {}, {}
+    for ck, src, dst in _CONN_RE.findall(text):
+        src, dst = int(src), int(dst)
+        sk = nodes.get(src, (None,))[0]
+        if ck == "OO" and sk == "Geometry":
+            model_of_geo[src] = dst
+        elif ck == "OO" and sk == "Material":
+            mat_of_model[dst] = src                       # model <- material
+        elif ck == "OP" and sk == "Texture":
+            tex_of_mat[dst] = src                         # material <- texture
+    # 3) per geometry -> its texture stem, via model<-material<-texture
+    groups, by_name = [], {}
+    for gid, (kind, name, body) in nodes.items():
+        if kind != "Geometry":
+            continue
+        verts = [list(v) for v in _chunk(_floats(_named_array(body, "Vertices")), 3)]
+        pvi = _ints(_named_array(body, "PolygonVertexIndex"))
+        tris = [[pvi[i], pvi[i + 1], -pvi[i + 2] - 1] for i in range(0, len(pvi) - 2, 3)]
+        nrm_raw = _named_array(body, "Normals")
+        normals = [list(v) for v in _chunk(_floats(nrm_raw), 3)] if nrm_raw is not None else None
+        uvs = [list(v) for v in _chunk(_floats(_named_array(body, "UV") or ""), 2)]
+        tex = None
+        mid = model_of_geo.get(gid)
+        if mid is not None:
+            matid = mat_of_model.get(mid)
+            if matid is not None:
+                texid = tex_of_mat.get(matid)
+                if texid is not None:
+                    tex = nodes[texid][1]                 # Texture child-name == the stem
+        g = by_name.get(name)
+        if g is None:
+            g = {"name": name, "verts": verts, "normals": normals, "uvs": uvs, "submeshes": []}
+            by_name[name] = g
+            groups.append(g)
+        g["submeshes"].append({"texture": tex, "tris": tris})
+    return groups
+
+
+def _named_array(body, key):
+    """The flat ``a: ...`` payload string of the first ``<key>: *N { a: ... }`` in `body`, or None."""
+    m = _re.search(rf'{key}:\s*\*\d+\s*\{{\s*a:\s*([^}}]*)\}}', body, _re.S)
+    return m.group(1) if m else None
+
+
+def _chunk(flat, n):
+    return [flat[i:i + n] for i in range(0, len(flat) - n + 1, n)]

ff9mapkit/battle/reskin.py

@@ -0,0 +1,149 @@
+"""Resolve a re-skin's DONOR -- a real battle enemy whose model+animation block we transplant.
+
+A re-skin makes a forked enemy's BODY look like a different creature while keeping its own gameplay. The visual
+identity is a self-consistent group of SB2_MON_PARM fields (Geo + the six Mot animation ids + Mesh + Radius +
+the model-attached cosmetics -- see :data:`scene_data._RESKIN_RANGES`), so it can't be set field-by-field: a
+Mot id that doesn't belong to the loaded Geo names a clip the model lacks, and the battle FREEZES
+(`btl_init.cs:240`/`:521-522`). The only safe source is a real enemy that ALREADY uses the target model --
+Square-Enix shipped that whole block together, so it is guaranteed engine-valid.
+
+SCOPE -- this is a BODY re-skin, NOT a full one (★ IN-GAME PROVEN 2026-06-13). The transplanted Mot[6] DO drive
+the new model's OWN idle / damage / death animations (`btl_init.cs:240`); but the per-ATTACK animation is bound
+by the donor SCENE's raw17 btlseq (keyed by the per-type Konran@78 selector, `btlseq.cs:1150-1151`), which a
+re-skin KEEPS -- so the ATTACK plays the TARGET enemy's clip, RETARGETED onto the new mesh (clip load path is by
+clip NAME, `AnimationFactory.cs:60`, so the cross-model retarget never crashes). Proven: a Goblin re-skinned to
+the Fang IDLED as a quadruped Fang but KNIFED / Goblin-Punched with the Goblin's upright animation. So the body
+looks like the new creature at rest / when hit / dying, but its ATTACK gesture stays the target's. A faithful
+FULL re-skin would also need the donor's raw17 attack binding + AA_DATA -- the deferred raw17-sequence work. The
+build warns per re-skinned slot.
+
+This module reads the donor block LIVE from the user's install (provenance: never committed; only the kit's
+open-source name->geo catalog ships). Two donor specs:
+  * ``{"scene": "EF_R007", "type": 0}`` -- an explicit donor battle scene + enemy type (deterministic, the
+    most reliable form: "look like THAT enemy"). Names from ``ff9mapkit battle-list --scenes``.
+  * ``{"name": "GEO_MON_B3_001"}`` -- a battle GEO model name (``GEO_MON_B3_*``) or a numeric geo id; resolved
+    to a geo id, then the install is SCANNED for the first real enemy that uses it (so the copied bytes are
+    always a real, shipped block). NOTE: friendly creature names (e.g. "goblin") are FIELD models
+    (``GEO_MON_F0_*``) and are NOT used by battle enemies -- use a donor scene or a ``GEO_MON_B3_*`` id instead.
+
+The pure byte-copy lives in :mod:`scene_data`; this module only does the install I/O + name resolution.
+"""
+from __future__ import annotations
+
+import re
+
+from . import extract, scene_codec, scene_data
+
+_RX_RAW16 = re.compile(r"battlescene/evt_battle_([^/]+)/dbfile0000\.raw16", re.I)
+# infra failures that mean "can't reach the install" (find_game_path raises ConfigError, a RuntimeError; a
+# missing UnityPy raises RuntimeError) -- caught + re-raised as an ACTIONABLE ReskinError, not a raw traceback.
+_INFRA_ERRORS = (RuntimeError, FileNotFoundError)
+_INSTALL_HINT = ("can't reach the FF9 install to read the donor model -- pass `--game <FF9 dir>`, set "
+                 "$FF9_GAME_PATH, or `pip install UnityPy`")
+
+
+class ReskinError(scene_data.SceneEditError):
+    pass
+
+
+def _geo_for_name(name) -> int | None:
+    """A battle GEO name / numeric id (or a friendly creature name) -> its geo (model) id, or None. Uses the
+    kit's baked, open-source model catalog (``catalog.model`` is the same id ``SetModel``/SB2_MON_PARM.Geo
+    take). Friendly creature names resolve to FIELD-form ids (``GEO_MON_F0_*``) that no battle enemy uses --
+    they'll fail the enemy scan with a clear message; battle enemies are ``GEO_MON_B3_*``."""
+    from .. import archetypes as _arch
+    from .. import catalog as _cat
+    key = str(name).strip()
+    m = _cat.model(key)                                    # exact GEO name or numeric id
+    if m:
+        return m.id
+    spec = _arch.CREATURES.get(key.lower())                # friendly creature name -> a (FIELD) GEO model name
+    if spec:
+        m = _cat.model(spec["model"])
+        if m:
+            return m.id
+    return None
+
+
+def _scan_for_geo(geo_id: int, game=None):
+    """Scan the install's battle scenes for the FIRST enemy whose Geo == ``geo_id``. Loads p0data2 ONCE and
+    parses each scene's raw16. Returns (scene_name, type_no, donor_raw16) or None. (Used by the ``name`` form
+    so the transplanted block is always a real shipped record, even if a name->id map were imperfect.)"""
+    UnityPy = extract._unitypy()
+    from ..extract import _raw_bytes
+    env = UnityPy.load(str(extract._p0data2(game)))
+    for o in env.objects:
+        if o.type.name != "TextAsset":
+            continue
+        mm = _RX_RAW16.search((getattr(o, "container", None) or "").lower())
+        if not mm:
+            continue
+        try:
+            raw16 = _raw_bytes(o.read())
+            scene = scene_codec.parse_scene(raw16)
+        except Exception:                                  # noqa: BLE001 -- a malformed/odd scene just isn't a donor
+            continue
+        for t, mon in enumerate(scene.monsters):
+            if mon.geo == geo_id:
+                return mm.group(1).upper(), t, raw16
+    return None
+
+
+def resolve_donor_block(spec: dict, *, game=None) -> tuple[bytes, str]:
+    """Resolve a donor ``spec`` -> (116-byte monster block, human provenance string). Install-gated.
+
+    ``spec`` is ``{"scene": NAME, "type": N}`` (explicit) or ``{"name": NAME}`` (a friendly/GEO name, scanned).
+    Raises :class:`ReskinError` with an actionable message on an unknown name / no enemy using that model /
+    an out-of-range donor type."""
+    if spec.get("scene"):
+        donor = str(spec["scene"]).upper()
+        t = int(spec.get("type", 0))
+        try:
+            raw16 = extract.read_scene_assets(donor, game)["raw16"]
+        except (ValueError, KeyError) as ex:
+            raise ReskinError(f"re-skin donor scene {donor!r} not readable: {ex}. Use a name from "
+                              f"`ff9mapkit battle-list --scenes`.")
+        except _INFRA_ERRORS as ex:
+            raise ReskinError(f"re-skin donor scene {donor!r}: {_INSTALL_HINT} ({ex})")
+        return scene_data.mon_block(raw16, t), f"{donor} type {t}"
+
+    name = spec.get("name")
+    if not name:
+        raise ReskinError("re-skin spec needs a 'name' (a GEO model name / geo id) or a 'scene' (+ 'type')")
+    geo = _geo_for_name(name)
+    if geo is None:
+        raise ReskinError(f"re-skin model {name!r}: unknown GEO model name / id. Battle enemies use "
+                          f"`GEO_MON_B3_*` names (browse with `ff9mapkit models`), or point at a real donor "
+                          f"enemy with model_scene = \"<SCENE>\" (+ model_type = N).")
+    try:
+        found = _scan_for_geo(geo, game)
+    except _INFRA_ERRORS as ex:
+        raise ReskinError(f"re-skin model {name!r}: {_INSTALL_HINT} ({ex})")
+    if found is None:
+        raise ReskinError(f"re-skin model {name!r} (geo {geo}) is not used by any BATTLE enemy, so there is "
+                          f"no real animation set to transplant. (Friendly creature names are FIELD models, "
+                          f"not battle enemies.) Use a `GEO_MON_B3_*` id, or a donor enemy with "
+                          f"model_scene = \"<SCENE>\" (+ model_type = N).")
+    scene_name, t, donor_raw16 = found
+    return scene_data.mon_block(donor_raw16, t), f"{name} (geo {geo}) from {scene_name} type {t}"
+
+
+def reskin_spec(enemy: dict):
+    """The donor spec for a ``[[scene.enemy]]`` dict, or None if it has no re-skin. ``model_scene`` (+ optional
+    ``model_type``) is the explicit donor; ``model`` is a friendly/GEO name. Raises on a contradictory combo."""
+    has_scene = enemy.get("model_scene") is not None
+    has_name = enemy.get("model") is not None
+    if has_scene and has_name:
+        raise ReskinError(f"slot {enemy.get('slot')}: set EITHER model = \"<name>\" OR model_scene = "
+                          f"\"<SCENE>\" (+ model_type), not both")
+    if has_scene:
+        return {"scene": enemy["model_scene"], "type": int(enemy.get("model_type", 0))}
+    if has_name:
+        if enemy.get("model_type") is not None:
+            raise ReskinError(f"slot {enemy.get('slot')}: model_type only applies with model_scene (the "
+                              f"model = \"<name>\" form auto-finds the donor enemy)")
+        return {"name": enemy["model"]}
+    if enemy.get("model_type") is not None:                 # model_type alone = a typo (meant model_scene); don't drop it silently
+        raise ReskinError(f"slot {enemy.get('slot')}: model_type has no effect without model_scene = "
+                          f"\"<SCENE>\" (the donor battle scene to copy the model from)")
+    return None