ff9mapkit 1.0.0b3__py3-none-any.whl

ff9mapkit/scene/bgs.py

@@ -0,0 +1,174 @@
+#!/usr/bin/env python3
+# FF9 field .bgs (BGSCENE_DEF) binary reader -- the BASE-GAME scene container.
+#
+# A real field's background scene ships as <fbg>.bgs.bytes inside StreamingAssets/p0data*.bin.
+# It holds the field's CAMERAS (BGCAM_DEF) + overlays + animations + lights. The kit normally
+# AUTHORS pure-Memoria .bgx scenes; but to IMPORT a real field as an editable base we must READ
+# its native binary .bgs. This module parses the header + the camera list (what camera import
+# needs); overlay/anim parsing can be layered on later for art extraction.
+#
+# Layout -- verified against Memoria source AND byte-exact vs the engine's own .bgx export
+# (offline p0data spike, 2026-06-04: every GRGR camera field matched the FieldCreatorScene .bgx):
+#
+#   BGSCENE_DEF.ExtractHeaderData (BGSCENE_DEF.cs:655), little-endian:
+#     u16 sceneLength, depthBitShift, animCount, overlayCount, lightCount, cameraCount
+#     u32 animOffset, overlayOffset, lightOffset, cameraOffset      # cameraOffset is ABSOLUTE
+#     i16 orgZ,curZ, orgX,orgY, curX,curY, minX,maxX, minY,maxY, scrX,scrY
+#   then cameraCount BGCAM_DEF blocks at cameraOffset, 52 bytes each (BGCAM_DEF.ReadData, cs:17):
+#     u16 proj; i16 r[3][3]; i32 t[3]; i16 centerOffset[2]; i16 w,h;
+#     i16 vrpMinX,vrpMaxX,vrpMinY,vrpMaxY; i32 depthOffset
+#
+# The kit's Cam stores exactly these fields (cam.Cam: proj, r[3][3], t[3], centerOffset, range=[w,h],
+# viewport=[vrpMinX,vrpMaxX,vrpMinY,vrpMaxY], depthOffset), so a parsed camera drops straight into
+# cam.decompose / cam.to_canvas / bgx.format_bgx_camera.
+from collections import namedtuple
+import struct
+
+from .cam import Cam
+
+_HEADER = struct.Struct("<6H4I12h")        # 6 counts (u16) + 4 offsets (u32) + 12 scene bounds (i16) = 52 B
+_CAMERA = struct.Struct("<H9h3i2h2h4hi")   # one BGCAM_DEF block
+HEADER_SIZE = _HEADER.size                  # 52
+CAMERA_SIZE = _CAMERA.size                  # 52
+
+BgsHeader = namedtuple(
+    "BgsHeader",
+    "sceneLength depthBitShift animCount overlayCount lightCount cameraCount "
+    "animOffset overlayOffset lightOffset cameraOffset bounds",
+)
+
+
+def parse_header(data: bytes) -> BgsHeader:
+    f = _HEADER.unpack_from(data, 0)
+    return BgsHeader(*f[:10], bounds=tuple(f[10:22]))
+
+
+def camera_from_block(buf: bytes, off: int = 0) -> Cam:
+    """Decode one 52-byte BGCAM_DEF block into a kit Cam."""
+    f = _CAMERA.unpack_from(buf, off)
+    c = Cam()
+    c.proj = f[0]
+    r = f[1:10]
+    c.r = [[r[0], r[1], r[2]], [r[3], r[4], r[5]], [r[6], r[7], r[8]]]
+    c.t = list(f[10:13])
+    c.centerOffset = list(f[13:15])
+    c.range = [f[15], f[16]]
+    c.viewport = list(f[17:21])            # vrpMinX, vrpMaxX, vrpMinY, vrpMaxY
+    c.depthOffset = f[21]
+    return c
+
+
+def camera_to_block(cam: Cam) -> bytes:
+    """Encode a kit Cam back into a 52-byte BGCAM_DEF block (round-trip of camera_from_block)."""
+    r = cam.r
+    return _CAMERA.pack(
+        cam.proj,
+        r[0][0], r[0][1], r[0][2], r[1][0], r[1][1], r[1][2], r[2][0], r[2][1], r[2][2],
+        cam.t[0], cam.t[1], cam.t[2],
+        cam.centerOffset[0], cam.centerOffset[1],
+        cam.range[0], cam.range[1],
+        cam.viewport[0], cam.viewport[1], cam.viewport[2], cam.viewport[3],
+        cam.depthOffset,
+    )
+
+
+def parse_cameras(data: bytes) -> list:
+    """All cameras from a .bgs byte blob, as kit Cam objects."""
+    h = parse_header(data)
+    return [camera_from_block(data, h.cameraOffset + i * CAMERA_SIZE) for i in range(h.cameraCount)]
+
+
+# --------------------------------------------------------------------------- overlays + sprites (art)
+# A field's background is a stack of OVERLAYS (depth layers); each overlay is a grid of 16-px TILES,
+# each tile sampling a cell of the upscaled atlas.png. Porting BGSCENE_DEF.ExtractOverlayData/
+# ExtractSpriteData + ExtractHeaderData lets us re-composite the real art offline (see scene.bgart).
+_OVERLAY = struct.Struct("<I HH hhhh hhhh hh hh hh I I I I I")   # BGOVERLAY_DEF.ReadData, 56 B
+HEADER12 = struct.Struct("<12h")
+
+
+def _bits(v, start, n):
+    return (v >> start) & ((1 << n) - 1)
+
+
+class Sprite:
+    __slots__ = ("offX", "offY", "depth", "trans", "alpha", "atlasX", "atlasY")
+
+    def __init__(self, offX, offY, depth, trans, alpha, atlasX=0, atlasY=0):
+        self.offX, self.offY, self.depth = offX, offY, depth
+        self.trans, self.alpha = trans, alpha
+        self.atlasX, self.atlasY = atlasX, atlasY
+
+
+class Overlay:
+    __slots__ = ("curZ", "orgZ", "orgX", "orgY", "w", "h", "camNdx",
+                 "spriteCount", "locOffset", "prmOffset", "sprites")
+
+    def __init__(self, **kw):
+        for k, v in kw.items():
+            setattr(self, k, v)
+        self.sprites = []
+
+
+def parse_overlays(data: bytes):
+    """(header, [Overlay]) — overlays with their tile sprites resolved to atlas grid cells.
+
+    Sprite atlas cells follow BGSCENE_DEF's upscale layout: a global tile index laid out
+    `countPerRow = atlasW // (tile_size+4)`, `atlasX = 2 + i%cpr*(tile_size+4)`, y analogous.
+    `tile_size` defaults to 64 (the Steam 4x atlas); pass the real value if it differs."""
+    h = parse_header(data)
+    overlays = []
+    off = h.overlayOffset
+    for _ in range(h.overlayCount):
+        f = _OVERLAY.unpack_from(data, off)
+        off += _OVERLAY.size
+        buf, buf2 = f[0], f[17]
+        # buf2 packs camNdx (low 8 bits) | isXOffset (1) | viewportNdx (7) | spriteCount (high 16)
+        # -- BGOVERLAY_DEF.ReadData. camNdx = which CAMERA paints this overlay (multi-camera fields
+        # split their art across cameras), the key to a per-camera backdrop.
+        overlays.append(Overlay(
+            curZ=_bits(buf, 8, 12), orgZ=_bits(buf, 20, 12),
+            orgX=f[3], orgY=f[4], w=f[1], h=f[2], camNdx=_bits(buf2, 0, 8),
+            spriteCount=_bits(buf2, 16, 16), locOffset=f[18], prmOffset=f[19]))
+    return h, overlays
+
+
+TILE = 16     # one background tile is 16x16 logical (pre-upscale) px (BGSCENE_DEF sprite quad)
+
+
+def tile_box(sprite, mnX, mnY, upscale: int = 4, tile: int = TILE):
+    """The crop rectangle ``(left, top, right, bottom)`` of one tile-sprite inside its overlay's
+    engine-exported ``Overlay{i}.png``.
+
+    The ``[Export] Field=1`` dump writes each overlay as a tight composite whose pixel (0,0) is the
+    overlay's MIN-offset tile (BGSCENE_DEF.cs:570-588), which is exactly where
+    ``extract.compose_background`` places the whole PNG (``(sOrg+org+min(off))*upscale``, no flip), so
+    a tile at ``(offX, offY)`` sits ``(offX-mnX, offY-mnY)`` tiles in -- each ``tile`` px, upscaled.
+    Pure arithmetic so the per-tile occlusion split is unit-testable without art."""
+    x0 = (sprite.offX - mnX) * upscale
+    y0 = (sprite.offY - mnY) * upscale
+    return (x0, y0, x0 + tile * upscale, y0 + tile * upscale)
+
+
+def resolve_sprites(data: bytes, overlays, atlas_w: int, tile_size: int = 64):
+    """Fill each overlay's .sprites (offX/offY/depth + atlas cell). Mutates in place."""
+    cpr = atlas_w // (tile_size + 4)
+    idx = 0
+    for ov in overlays:
+        alpha_trans = []
+        po = ov.prmOffset
+        for _ in range(ov.spriteCount):
+            p1, p2 = struct.unpack_from("<II", data, po)
+            po += 8
+            alpha_trans.append((_bits(p1, 22, 2), _bits(p2, 28, 1)))   # alpha, trans (shader)
+        lo = ov.locOffset
+        for j in range(ov.spriteCount):
+            (L,) = struct.unpack_from("<I", data, lo)
+            lo += 4
+            depth, offY, offX = _bits(L, 0, 12), _bits(L, 12, 10), _bits(L, 22, 10)
+            alpha, trans = alpha_trans[j]
+            ov.sprites.append(Sprite(
+                offX, offY, depth, trans, alpha,
+                atlasX=2 + idx % cpr * (tile_size + 4),
+                atlasY=2 + idx // cpr * (tile_size + 4)))
+            idx += 1
+    return overlays

ff9mapkit/scene/bgx.py

@@ -0,0 +1,185 @@
+"""FF9 pure-Memoria background scene (``.bgx``) text format.
+
+A ``.bgx`` is a small line-oriented text file describing how a field's background renders:
+a sequence of blocks (``OVERLAY`` layers, a ``CAMERA``, optional ``ANIMATION`` /
+``USE_BASE_SCENE`` / ``LANGUAGE``). Memoria parses it whitespace-insensitively (blank and
+``#``/``//`` comment lines are skipped), so this module models blocks structurally and emits
+a canonical form. Two helpers cover the kit's needs:
+
+  * :class:`BgxScene` — parse / serialize / inspect (overlays + camera) / surgically replace.
+  * :func:`build` — assemble a scene from a :class:`~ff9mapkit.scene.cam.Cam` + overlays.
+
+OVERLAY keys: OverlayId? CameraId ViewportId Position(x,y,z) Size(w,h) Image Shader.
+CAMERA keys : ViewDistance CenterOffset Position Range DepthOffset Viewport
+              OrientationMatrix (9) | OrientationAngles (3).
+Overlay Z (Position 3rd value) is the depth: smaller = nearer the camera (drawn in front).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from . import cam as _cam
+
+BLOCK_TYPES = ("LANGUAGE", "USE_BASE_SCENE", "OVERLAY", "ANIMATION", "CAMERA")
+DEFAULT_SHADER = "PSX/FieldMap_Abr_None"
+
+
+@dataclass
+class Overlay:
+    """One background layer."""
+
+    image: str
+    position: tuple = (0, 0, 0)      # x, y, z(depth)
+    size: tuple = (384, 448)         # w, h
+    shader: str = DEFAULT_SHADER
+    camera_id: int = 0
+    viewport_id: int = 0
+    overlay_id: int | None = None
+
+    def to_lines(self) -> list[str]:
+        lines = ["OVERLAY"]
+        if self.overlay_id is not None:
+            lines.append(f"OverlayId: {self.overlay_id}")
+        lines.append(f"CameraId: {self.camera_id}")
+        lines.append(f"ViewportId: {self.viewport_id}")
+        lines.append(f"Position: {self.position[0]}, {self.position[1]}, {self.position[2]}")
+        lines.append(f"Size: {self.size[0]}, {self.size[1]}")
+        lines.append(f"Image: {self.image}")
+        lines.append(f"Shader: {self.shader}")
+        return lines
+
+    @classmethod
+    def from_fields(cls, fields: list[tuple]) -> "Overlay":
+        o = cls(image="")
+        for key, val in fields:
+            args = [a.strip() for a in val.split(",")]
+            if key == "OverlayId":
+                o.overlay_id = int(args[0])
+            elif key == "CameraId":
+                o.camera_id = int(args[0])
+            elif key == "ViewportId":
+                o.viewport_id = int(args[0])
+            elif key == "Position":
+                o.position = (int(args[0]), int(args[1]), int(args[2]))
+            elif key == "Size":
+                o.size = (int(args[0]), int(args[1]))
+            elif key == "Image":
+                o.image = val.strip()
+            elif key == "Shader":
+                o.shader = val.strip()
+        return o
+
+
+def _camera_to_lines(cam: _cam.Cam) -> list[str]:
+    # reuse cam.format_bgx_camera (already validated faithful) minus its trailing newline
+    return _cam.format_bgx_camera(cam).rstrip("\n").split("\n")
+
+
+@dataclass
+class _Block:
+    type: str
+    fields: list = field(default_factory=list)   # ordered (key, value) for non-comment lines
+
+
+class BgxScene:
+    """Structured view of a ``.bgx``: leading comments, ordered blocks (overlays / camera / ...)."""
+
+    def __init__(self):
+        self.header_comments: list[str] = []     # comment lines before the first block
+        self.blocks: list[_Block] = []
+
+    # ---- parse ----
+    @classmethod
+    def parse(cls, text: str) -> "BgxScene":
+        self = cls()
+        cur: _Block | None = None
+        seen_block = False
+        for raw in text.splitlines():
+            s = raw.strip()
+            if not s:
+                continue
+            if s.startswith("#") or s.startswith("//"):
+                if not seen_block:
+                    self.header_comments.append(s)
+                continue
+            if s in BLOCK_TYPES:
+                cur = _Block(s)
+                self.blocks.append(cur)
+                seen_block = True
+                continue
+            if cur is not None and ":" in s:
+                key, _, val = s.partition(":")
+                cur.fields.append((key.strip(), val.strip()))
+        return self
+
+    @classmethod
+    def from_file(cls, path) -> "BgxScene":
+        with open(path, encoding="utf-8", errors="replace") as fh:
+            return cls.parse(fh.read())
+
+    # ---- serialize (canonical) ----
+    def to_text(self) -> str:
+        out: list[str] = list(self.header_comments)
+        for blk in self.blocks:
+            if blk.type == "OVERLAY":
+                out += self.overlay_of(blk).to_lines()
+            elif blk.type == "CAMERA":
+                out += _camera_to_lines(self.camera_of(blk))
+            else:
+                out.append(blk.type)
+                out += [f"{k}: {v}" for k, v in blk.fields]
+            out.append("")  # blank line between blocks
+        return "\n".join(out).rstrip("\n") + "\n"
+
+    # ---- typed views ----
+    @staticmethod
+    def overlay_of(blk: _Block) -> Overlay:
+        return Overlay.from_fields(blk.fields)
+
+    @staticmethod
+    def camera_of(blk: _Block) -> _cam.Cam:
+        text = "CAMERA\n" + "\n".join(f"{k}: {v}" for k, v in blk.fields) + "\n"
+        return _cam.parse_bgx_cameras_text(text)[0]
+
+    @property
+    def overlays(self) -> list[Overlay]:
+        return [self.overlay_of(b) for b in self.blocks if b.type == "OVERLAY"]
+
+    @property
+    def cameras(self) -> list[_cam.Cam]:
+        return [self.camera_of(b) for b in self.blocks if b.type == "CAMERA"]
+
+    # ---- edits ----
+    def set_camera(self, cam: _cam.Cam) -> None:
+        """Replace the (first) CAMERA block's fields from a Cam, preserving everything else."""
+        lines = _camera_to_lines(cam)[1:]  # drop the "CAMERA" header
+        fields = [tuple(s.split(": ", 1)) for s in lines]
+        for blk in self.blocks:
+            if blk.type == "CAMERA":
+                blk.fields = [(k, v) for k, v in fields]
+                return
+        self.blocks.append(_Block("CAMERA", [(k, v) for k, v in fields]))
+
+
+def build(camera, overlays: list[Overlay], *, header_comment: str | None = None,
+          base_scene: str | None = None) -> str:
+    """Assemble a complete ``.bgx`` text from a camera (or list of cameras) + ordered overlays.
+
+    ``camera`` may be a single ``cam.Cam`` (one CAMERA block, unchanged) or a list of Cams for a
+    MULTI-CAMERA field -- N CAMERA blocks in order (camera index = list position). Each overlay's
+    ``camera_id`` selects which camera shows it; the script switches the active camera via
+    SetFieldCamera (see content.camera). The engine reads cameras in file order (camIdx 0..N-1)."""
+    cameras = camera if isinstance(camera, (list, tuple)) else [camera]
+    out: list[str] = []
+    if header_comment:
+        out.append(f"# {header_comment}")
+    if base_scene:
+        out += ["USE_BASE_SCENE", f"Name: {base_scene}", ""]
+    for ov in overlays:
+        out += ov.to_lines()
+        out.append("")
+    for c in cameras:
+        out += _camera_to_lines(c)
+        out.append("")
+    return "\n".join(out).rstrip("\n") + "\n"