OpenRCT2-ObjectCommon 0.1.0__py3-none-any.whl

openrct2_object_common/__init__.py

@@ -0,0 +1,13 @@
+"""
+Shared scaffolding for OpenRCT2 object generators: config parsing/validation,
+CLI flow, model placement, object.json headers, and `.parkobj` assembly. Sits
+between the renderer (`openrct2-x7-renderer`) and the generators, so the vehicle
+and scenery tools share one config layer and one packaging path.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("OpenRCT2-ObjectCommon")
+except PackageNotFoundError:  # pragma: no cover - source tree without an install
+    __version__ = "0.0.0"

openrct2_object_common/blender/__init__.py

@@ -0,0 +1,9 @@
+"""
+Blender add-on helpers shared by the vehicle and scenery add-ons.
+
+``lights`` has no ``bpy`` dependency (it only reads attribute-bearing items), so
+it imports anywhere. ``modal`` imports ``bpy`` and is meant to run inside Blender
+only -- import it directly (``from openrct2_object_common.blender.modal import
+RenderModalBase``) rather than eagerly here, so ``lights`` stays usable without
+Blender installed.
+"""

openrct2_object_common/blender/lights.py

@@ -0,0 +1,52 @@
+"""
+Build the renderer's lighting rig from add-on UI items.
+
+The default rig is the renderer's own ``default_lights()`` (re-exported here), so
+the add-ons no longer hand-copy the nine-light list -- a single source shared
+with the CLI. ``lights_from_items`` reads any sequence of objects exposing
+``type`` / ``shadow`` / ``direction`` / ``strength`` (a Blender ``PropertyGroup``
+collection, but nothing here imports ``bpy``), falling back to the default rig
+when the collection is empty.
+"""
+
+from collections.abc import Iterable, Sequence
+from typing import Any, Protocol
+
+import numpy as np
+from openrct2_x7_renderer.constants import LightType
+from openrct2_x7_renderer.lights import default_lights
+from openrct2_x7_renderer.types import Light
+
+__all__ = ["LIGHT_TYPE_MAP", "default_lights", "lights_from_items", "normalize_direction"]
+
+# The light types the add-on UI exposes (hemisphere lights are CLI/config only).
+LIGHT_TYPE_MAP = {"diffuse": LightType.DIFFUSE, "specular": LightType.SPECULAR}
+
+
+class _LightItem(Protocol):
+    type: str
+    shadow: bool
+    direction: Any  # 3-element sequence (bpy float vector)
+    strength: float
+
+
+def normalize_direction(v: Sequence[float]) -> np.ndarray:
+    """A light direction as a unit ``(3,)`` float64 vector; a zero vector is
+    returned unchanged (the renderer rejects it later)."""
+    arr = np.array(v, dtype=np.float64)
+    n = np.linalg.norm(arr)
+    return arr / n if n > 0 else arr
+
+
+def lights_from_items(items: Iterable[_LightItem]) -> list[Light]:
+    """Build a light rig from UI items, or the default rig when ``items`` is empty."""
+    rig = [
+        Light(
+            type=LIGHT_TYPE_MAP[item.type],
+            shadow=int(item.shadow),
+            direction=normalize_direction(list(item.direction)),
+            intensity=item.strength,
+        )
+        for item in items
+    ]
+    return rig or default_lights()

openrct2_object_common/blender/modal.py

@@ -0,0 +1,160 @@
+"""Shared modal operator for add-ons that render off the main thread.
+
+The render (the renderer-bound work) is an opaque, blocking call, so it runs in
+a worker thread while a modal timer drives a status-bar readout. The build phase
+(reading bpy data into the core object) stays on the main thread.
+
+NOTE: no ``from __future__ import annotations`` -- subclasses declare bpy
+properties as annotations and PEP 563 would stringify them and break add-on
+registration.
+
+This module imports ``bpy`` and is meant to run inside Blender only; install the
+package's ``blender`` extra (``pip install OpenRCT2-ObjectCommon[blender]``) when
+type-checking or testing it outside Blender.
+"""
+
+import threading
+import time
+import traceback
+from typing import Any
+
+from bpy.types import Operator
+
+_SPINNER_FRAMES = "|/-\\"
+
+
+class RenderModalBase(Operator):
+    """Scaffolding for operators that run a blocking render off the main thread
+    while showing a status-bar readout.
+
+    Subclasses provide the four hooks below. ``_build`` / ``_prepare`` /
+    ``_on_success`` run on the main thread and may touch ``context`` and bpy
+    data; ``_render`` runs in the worker thread and must touch only ``self``
+    (values it needs from ``context`` are stashed in ``_prepare``).
+
+    Progress is *indeterminate* (a cycling spinner) unless ``_render`` reports
+    real units via :meth:`set_progress`, in which case the status line shows a
+    percentage instead.
+
+    Subclass hooks:
+      ``_status_verb``                 label shown in the status bar.
+      ``_clean_error_types``           build-error exception types whose message
+                                       is already user-facing (reported as-is,
+                                       not wrapped with ``_invalid_prefix``).
+      ``_build(context)``              read bpy data into the core object(s);
+                                       returns an opaque payload for the others.
+      ``_prepare(context, payload)``   stash per-run state on ``self`` (lights,
+                                       output paths) -- main thread.
+      ``_render(payload)``             the blocking work -- worker thread.
+      ``_on_success(context)``         post-render UI; returns an operator result.
+    """
+
+    _status_verb = "Working"
+    _invalid_prefix = "Invalid object"
+    _clean_error_types: tuple[type[Exception], ...] = ()
+
+    # -- hooks ---------------------------------------------------------------
+
+    def _build(self, context) -> Any:  # pragma: no cover - subclass hook
+        raise NotImplementedError
+
+    def _prepare(self, context, payload) -> None:  # pragma: no cover - subclass hook
+        pass
+
+    def _render(self, payload) -> None:  # pragma: no cover - subclass hook
+        raise NotImplementedError
+
+    def _on_success(self, context):  # pragma: no cover - subclass hook
+        raise NotImplementedError
+
+    # -- worker-facing -------------------------------------------------------
+
+    def set_progress(self, done: int, total: int) -> None:
+        """Report determinate progress from ``_render`` (worker thread). Plain
+        int writes; the modal timer reads them to repaint. No lock needed for
+        single-word assignments."""
+        self._done_units = done
+        self._total_units = total
+
+    # -- operator flow -------------------------------------------------------
+
+    def execute(self, context):
+        build_start = time.monotonic()
+        try:
+            payload = self._build(context)
+        except self._clean_error_types as e:
+            self.report({"ERROR"}, str(e))
+            return {"CANCELLED"}
+        except Exception as e:
+            self.report({"ERROR"}, f"{self._invalid_prefix}: {e}")
+            return {"CANCELLED"}
+        self._build_secs = int(time.monotonic() - build_start)
+
+        self._prepare(context, payload)
+        self._error: str | None = None
+        self._finished = False
+        self._start_time = time.monotonic()
+        self._spinner_step = 0
+        self._done_units = 0
+        self._total_units = 0
+
+        def worker():
+            try:
+                self._render(payload)
+            except Exception:
+                self._error = traceback.format_exc()
+            finally:
+                self._finished = True
+
+        self._thread = threading.Thread(target=worker, daemon=True)
+        self._thread.start()
+
+        wm = context.window_manager
+        wm.progress_begin(0, 1)
+        context.window.cursor_modal_set("WAIT")
+        self._set_status(context)
+        self._timer = wm.event_timer_add(0.1, window=context.window)
+        wm.modal_handler_add(self)
+        return {"RUNNING_MODAL"}
+
+    def modal(self, context, event):
+        if event.type == "TIMER":
+            if self._finished:
+                return self._finish(context)
+            self._spinner_step += 1
+            self._set_status(context)
+        return {"PASS_THROUGH"}
+
+    def _set_status(self, context) -> None:
+        elapsed = int(time.monotonic() - self._start_time)
+        # Only mention the build time when it was non-trivial (animated / large
+        # builds); a static build is instant and "(build 0s)" would be noise.
+        build = f" (build {self._build_secs}s)" if self._build_secs else ""
+        wm = context.window_manager
+        if self._total_units > 0:
+            pct = int(100 * self._done_units / self._total_units)
+            context.workspace.status_text_set(
+                f"{self._status_verb}... {pct}% {elapsed}s{build}"
+            )
+            wm.progress_update(self._done_units / self._total_units)
+        else:
+            glyph = _SPINNER_FRAMES[self._spinner_step % len(_SPINNER_FRAMES)]
+            context.workspace.status_text_set(
+                f"{glyph} {self._status_verb}... {elapsed}s{build}"
+            )
+            wm.progress_update((self._spinner_step % 20) / 20.0)
+
+    def _finish(self, context):
+        wm = context.window_manager
+        wm.event_timer_remove(self._timer)
+        wm.progress_end()
+        context.window.cursor_modal_restore()
+        context.workspace.status_text_set(None)
+        self._thread.join()
+        if self._error:
+            print(self._error)
+            self.report(
+                {"ERROR"}, f"{self._status_verb} failed; see the system console for details."
+            )
+            return {"CANCELLED"}
+        return self._on_success(context)

openrct2_object_common/cli.py

@@ -0,0 +1,79 @@
+"""
+Shared command-line scaffolding for object generators.
+"""
+
+import argparse
+import sys
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from openrct2_x7_renderer.lights import default_lights, load_lights
+from openrct2_x7_renderer.ray_trace import Context
+from openrct2_x7_renderer.remap import load_remap_overrides
+from openrct2_x7_renderer.types import Light
+
+from .config import LoadError, parse_config
+
+TEST_ZOOM = 0.125
+
+RenderFn = Callable[[argparse.Namespace, dict[str, Any], list[Light]], None]
+
+
+def parse_cli_args(prog: str, argv: list[str] | None) -> argparse.Namespace:
+    """Parse the flags shared by both generators: `--test` / `--skip-render`
+    (mutually exclusive) and a single config-file `input` path."""
+    parser = argparse.ArgumentParser(prog=prog)
+    group = parser.add_mutually_exclusive_group()
+    group.add_argument("--test", action="store_true", help="single-viewpoint render to test/")
+    group.add_argument(
+        "--skip-render", action="store_true", help="reuse previously rendered sprites"
+    )
+    parser.add_argument("input", type=Path)
+    return parser.parse_args(argv)
+
+
+def output_directory_of(root: dict[str, Any]) -> Path:
+    """The config's `output_directory`, or the current directory if unset."""
+    out = root.get("output_directory")
+    return Path(out) if isinstance(out, str) else Path(".")
+
+
+def make_context(
+    lights: list[Light],
+    units_per_tile: float,
+    test: bool,
+    root: dict[str, Any] | None = None,
+) -> Context:
+    """Build a render Context whose camera scale is driven by the object's
+    configured `units_per_tile`. Test mode scales ``upt`` down by ``TEST_ZOOM``
+    (0.125×), zooming in to show material detail in a single-viewpoint preview.
+
+    In test mode, when ``root`` (the parsed config) is supplied, an optional
+    ``test_remap_colors`` block is read and applied to ``render_view`` output so
+    the preview shows repaint colours instead of the raw remap windows. Outside
+    test mode the overrides are ignored, so real renders keep their remap
+    windows intact for OpenRCT2 to repaint."""
+    upt = TEST_ZOOM * units_per_tile if test else units_per_tile
+    overrides = load_remap_overrides(root) if (test and root is not None) else {}
+    return Context(lights=lights, dither=True, upt=upt, remap_overrides=overrides)
+
+
+def run_cli(prog: str, argv: list[str] | None, render: RenderFn) -> int:
+    """Run the shared CLI flow and return a process exit code.
+
+    Parses the args, reads the config, resolves the lights (the config's
+    `lights` block if present, else the default rig), then hands off to
+    `render`. Any failure is reported on stderr and yields exit code 1.
+    """
+    args = parse_cli_args(prog, argv)
+
+    try:
+        root = parse_config(args.input)
+        lights = load_lights(root["lights"]) if "lights" in root else default_lights()
+        render(args, root, lights)
+    except (LoadError, OSError, ValueError, RuntimeError) as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+
+    return 0

openrct2_object_common/config.py

@@ -0,0 +1,188 @@
+"""
+Generic config parsing + validation helpers shared by the generators' loaders.
+"""
+
+__all__ = [
+    "LoadError",
+    "as_array_or_wrap",
+    "load_meshes",
+    "load_preview",
+    "optional_bool",
+    "optional_int",
+    "optional_number",
+    "optional_string",
+    "optional_string_list",
+    "parse_config",
+    "read_vector3",
+    "require_int",
+    "require_number",
+    "require_string",
+]
+
+import json
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+from openrct2_x7_renderer.image import read_png
+from openrct2_x7_renderer.mesh import Mesh, load_mesh
+from openrct2_x7_renderer.types import IndexedImage, LoadError
+
+
+def parse_config(path: Path | str) -> dict[str, Any]:
+    """Parse a JSON or YAML config file into a dict (chosen by extension)."""
+    p = Path(path)
+    text = p.read_text()
+    if p.suffix.lower() in (".yaml", ".yml"):
+        try:
+            import yaml
+        except ImportError:
+            raise LoadError(
+                "PyYAML is required to load .yaml configs (pip install pyyaml)"
+            ) from None
+        root = yaml.safe_load(text)
+    else:
+        root = json.loads(text)
+    if not isinstance(root, dict):
+        raise LoadError("Config root is not an object")
+    return root
+
+
+def require_string(obj: dict[str, Any], key: str) -> str:
+    """Return the string at ``obj[key]``, raising LoadError if absent or not a string."""
+    v = obj.get(key)
+    if not isinstance(v, str):
+        raise LoadError(f'Property "{key}" not found or is not a string')
+    return v
+
+
+def optional_string(obj: dict[str, Any], key: str, default: str = "") -> str:
+    """Return the string at ``obj[key]``, or ``default`` if the key is absent."""
+    v = obj.get(key)
+    if v is None:
+        return default
+    if not isinstance(v, str):
+        raise LoadError(f'Property "{key}" is not a string')
+    return v
+
+
+def optional_string_list(obj: dict[str, Any], key: str) -> list[str]:
+    """Return the value at ``obj[key]`` coerced to a list of strings.
+
+    A single string is wrapped in a list; an absent key returns ``[]``.
+    """
+    v = obj.get(key)
+    if v is None:
+        return []
+    if isinstance(v, str):
+        return [v]
+    if not isinstance(v, list) or any(not isinstance(x, str) for x in v):
+        raise LoadError(f'Property "{key}" is not a string or array of strings')
+    return list(v)
+
+
+def require_int(obj: dict[str, Any], key: str) -> int:
+    """Return the integer at ``obj[key]``, raising LoadError if absent, non-int, or a bool."""
+    v = obj.get(key)
+    if not isinstance(v, int) or isinstance(v, bool):
+        raise LoadError(f'Property "{key}" not found or is not an integer')
+    return v
+
+
+def optional_int(obj: dict[str, Any], key: str, default: int) -> int:
+    """Return the integer at ``obj[key]``, or ``default`` if the key is absent."""
+    v = obj.get(key)
+    if v is None:
+        return default
+    if not isinstance(v, int) or isinstance(v, bool):
+        raise LoadError(f'Property "{key}" is not an integer')
+    return v
+
+
+def require_number(obj: dict[str, Any], key: str) -> float:
+    """Return the number at ``obj[key]`` as float, raising LoadError if absent or non-numeric."""
+    v = obj.get(key)
+    if not isinstance(v, (int, float)) or isinstance(v, bool):
+        raise LoadError(f'Property "{key}" not found or is not a number')
+    return float(v)
+
+
+def optional_number(obj: dict[str, Any], key: str, default: float) -> float:
+    """Return the number at ``obj[key]`` as float, or ``default`` if the key is absent."""
+    v = obj.get(key)
+    if v is None:
+        return default
+    if not isinstance(v, (int, float)) or isinstance(v, bool):
+        raise LoadError(f'Property "{key}" is not a number')
+    return float(v)
+
+
+def optional_bool(obj: dict[str, Any], key: str, default: bool = False) -> bool:
+    """Return the boolean at ``obj[key]``, or ``default`` if the key is absent."""
+    v = obj.get(key)
+    if v is None:
+        return default
+    if not isinstance(v, bool):
+        raise LoadError(f'Property "{key}" is not a boolean')
+    return v
+
+
+def read_vector3(arr: Any) -> np.ndarray:
+    """Parse a 3-element list into a float64 ``(3,)`` array, raising LoadError on bad input."""
+    if not isinstance(arr, list) or len(arr) != 3:
+        raise LoadError("Vector must be an array of 3 numbers")
+    try:
+        return np.array([float(x) for x in arr], dtype=np.float64)
+    except (ValueError, TypeError) as e:
+        raise LoadError(f"Vector element is not a number: {e}") from e
+
+
+def as_array_or_wrap(value: Any) -> list[Any]:
+    """Return ``value`` as-is if it is a non-empty list, or wrap a scalar in a one-element list."""
+    if value is None:
+        raise LoadError("Missing value")
+    if isinstance(value, list):
+        if len(value) == 0:
+            raise LoadError("Empty array")
+        return value
+    return [value]
+
+
+def load_meshes(root: dict[str, Any], base_dir: Path | None = None) -> list[Mesh]:
+    """Load every OBJ listed under the config's `meshes` array.
+
+    Relative mesh paths are resolved against *base_dir* (typically the
+    directory containing the config file).  When *base_dir* is ``None``
+    the paths are used as-is (resolved against CWD).
+    """
+    mesh_paths = root.get("meshes")
+    if not isinstance(mesh_paths, list):
+        raise LoadError('Property "meshes" does not exist or is not an array')
+    meshes: list[Mesh] = []
+    for path in mesh_paths:
+        if not isinstance(path, str):
+            raise LoadError("Mesh path is not a string")
+        resolved = Path(path) if base_dir is None or Path(path).is_absolute() else base_dir / path
+        meshes.append(load_mesh(resolved))
+    return meshes
+
+
+def load_preview(root: dict[str, Any], base_dir: Path | None = None) -> IndexedImage | None:
+    """Load the optional `preview` PNG referenced by the config, if any.
+
+    Relative preview paths are resolved against *base_dir*.
+    """
+    preview_path = root.get("preview")
+    if preview_path is None:
+        return None
+    if not isinstance(preview_path, str):
+        raise LoadError('Property "preview" is not a string')
+    resolved = (
+        Path(preview_path)
+        if base_dir is None or Path(preview_path).is_absolute()
+        else base_dir / preview_path
+    )
+    try:
+        return read_png(resolved)
+    except (OSError, ValueError) as e:
+        raise LoadError(f"Unable to open image file {preview_path}: {e}") from e

openrct2_object_common/objectjson.py

@@ -0,0 +1,34 @@
+"""
+The object.json fields every OpenRCT2 object shares.
+
+`id`, `originalId`, `version`, `authors`, and `objectType` are identical across
+rides and all three scenery kinds; each generator's ``build_*_json`` opens with
+this header, then fills in its kind-specific ``properties`` / ``strings``.
+"""
+
+from collections.abc import Iterable
+from typing import Any
+
+__all__ = ["object_json_header"]
+
+
+def object_json_header(
+    obj_id: str,
+    *,
+    object_type: str,
+    original_id: str = "",
+    version: str = "1.0",
+    authors: Iterable[str] = (),
+) -> dict[str, Any]:
+    """The shared leading object.json fields, in OpenRCT2's canonical key order.
+
+    ``originalId`` is omitted when empty (OpenRCT2 treats it as absent); the
+    caller adds ``properties``/``strings``/``images`` to the returned dict.
+    """
+    out: dict[str, Any] = {"id": obj_id}
+    if original_id:
+        out["originalId"] = original_id
+    out["version"] = version
+    out["authors"] = list(authors)
+    out["objectType"] = object_type
+    return out

openrct2_object_common/parkobj.py

@@ -0,0 +1,88 @@
+"""
+Write ``images.dat``, the object.json, and assemble the ``.parkobj`` ZIP.
+
+Every object kind follows the same packaging path: render sprites into a single
+``images.dat`` blob (or reuse a previous render), write the object.json that
+references it via ``$LGX:``, and zip the two together. The per-kind work is just
+*what* sprites to render and *what* metadata to emit; this module owns the rest.
+"""
+
+import json
+import logging
+import zipfile
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from openrct2_x7_renderer.images_dat import write_images_dat
+from openrct2_x7_renderer.types import IndexedImage
+
+__all__ = ["RenderFn", "assemble_parkobj", "write_images_dat_lgx"]
+
+log = logging.getLogger(__name__)
+
+# Render the object's sprites into ``work_dir`` (writing ``images.dat``) and
+# return the object.json "images" list (the ``$LGX:`` references).
+RenderFn = Callable[[Path], list[str]]
+
+
+def write_images_dat_lgx(
+    images: list[IndexedImage], work_dir: Path, *, note: str = ""
+) -> list[str]:
+    """Write ``images`` to ``work_dir/images.dat`` and return the object.json
+    "images" value referencing it.
+
+    ``note`` is appended to the log line (e.g. ``" for 4 tiles"``). Returns the
+    single-element ``["$LGX:images.dat[0..N-1]"]`` list OpenRCT2 expects.
+    """
+    out_path = work_dir / "images.dat"
+    write_images_dat(images, out_path)
+    log.info(
+        "wrote %s (%d sprites%s, %.1f KB)",
+        out_path,
+        len(images),
+        note,
+        out_path.stat().st_size / 1024,
+    )
+    return [f"$LGX:images.dat[0..{len(images) - 1}]"]
+
+
+def assemble_parkobj(
+    obj_json: dict[str, Any],
+    parkobj_path: Path,
+    work_dir: Path,
+    render: RenderFn,
+    *,
+    skip_render: bool = False,
+) -> None:
+    """Render (or reuse) sprites, write the object.json, and zip the ``.parkobj``.
+
+    Shared by every object kind; callers differ only in ``obj_json`` (the built
+    metadata) and ``render`` (which renders the sprites, writes ``images.dat``,
+    and returns the object.json "images" list -- typically via
+    :func:`write_images_dat_lgx`).
+
+    With ``skip_render`` the "images" list is read back from a previous run's
+    object.json in ``work_dir`` and ``render`` is not called; otherwise the
+    stale object.json / images.dat are removed first so a failed render can't
+    leave a half-written pair behind.
+    """
+    work_dir.mkdir(parents=True, exist_ok=True)
+
+    if skip_render:
+        prev = json.loads((work_dir / "object.json").read_text())
+        images_json = prev.get("images")
+        if not isinstance(images_json, list):
+            raise RuntimeError('Property "images" is not an array')
+    else:
+        for p in (work_dir / "object.json", work_dir / "images.dat"):
+            p.unlink(missing_ok=True)
+        images_json = render(work_dir)
+
+    obj_json["images"] = images_json
+    (work_dir / "object.json").write_text(json.dumps(obj_json, indent=4))
+
+    parkobj_path.parent.mkdir(parents=True, exist_ok=True)
+    with zipfile.ZipFile(parkobj_path, "w", compression=zipfile.ZIP_DEFLATED) as zf:
+        zf.write(work_dir / "object.json", "object.json")
+        zf.write(work_dir / "images.dat", "images.dat")

openrct2_object_common/placement.py

@@ -0,0 +1,57 @@
+"""
+Place a Model's meshes into a render scene.
+
+Both generators turn a ``Model`` (a list of placements, each carrying one
+``MeshFrame`` per animation frame) into Embree scene geometry the same way:
+convert the frame's degree orientation to a rotation matrix and add the
+referenced mesh at its position. The only difference is how out-of-range frame
+indices are handled (vehicles index exactly; scenery clamps to a placement's
+last pose), which is the ``clamp_frame`` flag.
+"""
+
+import math
+
+import numpy as np
+from openrct2_x7_renderer.geometry import rotate_x, rotate_y, rotate_z
+from openrct2_x7_renderer.mesh import Mesh
+from openrct2_x7_renderer.ray_trace import SceneBuilder
+from openrct2_x7_renderer.types import Model
+
+__all__ = ["add_model_to_scene", "orientation_to_matrix"]
+
+
+def orientation_to_matrix(orientation_deg: np.ndarray) -> np.ndarray:
+    """A MeshFrame orientation ``(angle_y, angle_z, angle_x)`` in degrees as a
+    ``(3, 3)`` rotation matrix, applied as ``rotate_y @ rotate_z @ rotate_x``."""
+    rx, ry, rz = orientation_deg * (math.pi / 180.0)
+    return rotate_y(rx) @ rotate_z(ry) @ rotate_x(rz)
+
+
+def add_model_to_scene(
+    builder: SceneBuilder,
+    meshes: list[Mesh],
+    model: Model,
+    *,
+    frame: int = 0,
+    mask: int = 0,
+    clamp_frame: bool = False,
+) -> None:
+    """Add ``model``'s placed meshes to an open ``SceneBuilder`` at pose ``frame``.
+
+    Placements whose ``mesh_index`` is ``-1`` (an empty slot) are skipped. With
+    ``clamp_frame=True`` a placement with fewer frames falls back to its last
+    frame (scenery's animated poses); with ``False`` the frame is indexed exactly
+    (vehicle frames are uniform across placements). ``mask`` is the per-model
+    ``MeshFlag`` bitmask (e.g. ghost / mask geometry).
+    """
+    for mesh_frames in model.meshes:
+        idx = min(frame, len(mesh_frames) - 1) if clamp_frame else frame
+        mf = mesh_frames[idx]
+        if mf.mesh_index == -1:
+            continue
+        builder.add_model(
+            meshes[mf.mesh_index],
+            orientation_to_matrix(mf.orientation),
+            mf.position.astype(np.float64),
+            mask,
+        )

openrct2_objectcommon-0.1.0.dist-info/METADATA

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: OpenRCT2-ObjectCommon
+Version: 0.1.0
+Summary: Shared config, CLI, .parkobj, and object.json scaffolding for OpenRCT2 object generators.
+Project-URL: Homepage, https://github.com/alex-parisi/OpenRCT2-ObjectCommon
+Project-URL: Repository, https://github.com/alex-parisi/OpenRCT2-ObjectCommon
+Author-email: Alex Parisi <alex@atparisi.com>
+License-Expression: GPL-3.0-or-later
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.26
+Requires-Dist: openrct2-x7-renderer>=0.3.0
+Requires-Dist: pillow>=10.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: blender
+Requires-Dist: bpy>=4.0; extra == 'blender'
+Description-Content-Type: text/markdown
+
+# OpenRCT2 Object Common
+
+Shared scaffolding for the OpenRCT2 object generators. This package sits between
+the renderer and the generators, so the vehicle and scenery tools share one
+config layer, one CLI flow, and one `.parkobj` packaging path instead of each
+re-implementing them.
+
+```
+openrct2-x7-renderer        the Embree-backed iso renderer (meshes -> sprites)
+        ▲
+OpenRCT2-ObjectCommon        config, CLI, placement, object.json, .parkobj  ← you are here
+        ▲
+   ┌────┴─────┐
+Vehicle      Scenery         the generators (+ their Blender add-ons)
+```
+
+Rendering is handled by the external
+[`openrct2-x7-renderer`](https://pypi.org/project/openrct2-x7-renderer/) package
+(an Embree-backed ray tracer shipping prebuilt, vendored wheels), so this repo is
+pure Python, with no compiler or Embree needed.
+
+> Part of the **OpenRCT2-Tools** family — the
+> [renderer](https://github.com/alex-parisi/OpenRCT2-X7-Renderer),
+> [VehicleGenerator](https://github.com/alex-parisi/OpenRCT2-VehicleGenerator),
+> and [SceneryGenerator](https://github.com/alex-parisi/OpenRCT2-SceneryGenerator)
+> all build on this package.
+
+## Requirements
+
+- Python ≥ 3.11
+- [uv](https://docs.astral.sh/uv/) (recommended); `uv sync` pulls everything,
+  including the renderer wheel from PyPI.
+
+## Develop
+
+```bash
+uv sync
+uv run pytest        # coverage is enabled by default via pyproject.toml
+uv run ruff check .
+uv run mypy
+```
+
+## What's here
+
+| Module | What it provides |
+|---|---|
+| `config` | `parse_config` (JSON/YAML) and the `require_*` / `optional_*` validation helpers; `load_meshes` / `load_preview` |
+| `cli` | `run_cli` (parse args → read config → resolve lights → render), `make_context`, `parse_cli_args`, `output_directory_of` |
+| `objectjson` | `object_json_header` — the `id` / `originalId` / `version` / `authors` / `objectType` block every object shares |
+| `placement` | `add_model_to_scene` and `orientation_to_matrix` — turn a `Model` into render-scene geometry |
+| `parkobj` | `assemble_parkobj` (render-or-reuse → write object.json → zip) and `write_images_dat_lgx` |
+| `blender.lights` | `lights_from_items` / `default_lights` — build the renderer's light rig from add-on UI items |
+| `blender.modal` | `RenderModalBase` — the off-main-thread modal render operator the add-ons subclass |
+
+## Usage
+
+### CLI scaffolding
+
+A generator's `__main__` wires its loader/exporter into the shared flow:
+
+```python
+from openrct2_object_common.cli import make_context, output_directory_of, run_cli
+
+
+def _render(args, root, lights):
+    obj = build_object(root)                       # generator-specific
+    context = make_context(lights, obj.units_per_tile, args.test)
+    export(obj, context, output_directory_of(root), skip_render=args.skip_render)
+
+
+def main(argv=None):
+    return run_cli("openrct2-my-generator", argv, _render)
+```
+
+### Packaging a `.parkobj`
+
+```python
+from openrct2_object_common.objectjson import object_json_header
+from openrct2_object_common.parkobj import assemble_parkobj, write_images_dat_lgx
+
+
+def export_to(obj, context, parkobj_path, work_dir, skip_render=False):
+    obj_json = object_json_header(obj.id, object_type="scenery_small", authors=obj.authors)
+    obj_json["properties"] = build_properties(obj)
+    assemble_parkobj(
+        obj_json, parkobj_path, work_dir,
+        lambda wd: write_images_dat_lgx(render_sprites(obj, context), wd),
+        skip_render=skip_render,
+    )
+```
+
+### Blender helpers
+
+The `blender` subpackage imports `bpy` (only `blender.modal` — `blender.lights`
+does not), so install the extra when working with it outside Blender:
+
+```bash
+pip install "OpenRCT2-ObjectCommon[blender]"
+```
+
+## License
+
+GPL-3.0-or-later.

openrct2_objectcommon-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+openrct2_object_common/__init__.py,sha256=adMVCDhNCiMIj-ROK9PV5QK0CihG5bTAWobjFVAq8NE,537
+openrct2_object_common/cli.py,sha256=uIBd_P4Wg7jXgDjLsO3l4DpJKq8KkBdO--YES8sGGvU,3072
+openrct2_object_common/config.py,sha256=P3Bqxz6apMmrMnpYuPxib3IM-sahEqkjJCO-HetHd2M,6445
+openrct2_object_common/objectjson.py,sha256=SNqcBifrj3lFHLhy27Pn4g4ERqI9h1ISlrizxMoUHnA,1030
+openrct2_object_common/parkobj.py,sha256=wEGNUugh3jDAPKmjO0AfnqjE9I3pBOOR9sRanksoWto,3214
+openrct2_object_common/placement.py,sha256=syzOUd7lEjGngkx1QGcm-zwgvgmHy9s5BBxjgAC8XSE,2152
+openrct2_object_common/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+openrct2_object_common/blender/__init__.py,sha256=jAlI1-klUzZN9r4jA5VTH6ywIWrlZXFMvYFFS-kiasY,416
+openrct2_object_common/blender/lights.py,sha256=5pDbYeLjWChgx-_TmVg3v_yRQTWvhWsGQoYpq0_U4Cs,1885
+openrct2_object_common/blender/modal.py,sha256=AY5D2eUE3UN_jtSJpHTi7IEWoo9k2ezhSwXy8jyMMlc,6382
+openrct2_objectcommon-0.1.0.dist-info/METADATA,sha256=kBALGxpPvA5oLydMtmSJC390K-PvxvM05VwaGlvVoEY,4421
+openrct2_objectcommon-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+openrct2_objectcommon-0.1.0.dist-info/licenses/LICENSE,sha256=gXf5dRMhNSbfLPYYTY_5hsZ1r7UU1OaKQEAQUhuIBkM,18092
+openrct2_objectcommon-0.1.0.dist-info/RECORD,,

openrct2_objectcommon-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

openrct2_objectcommon-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,339 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 2, June 1991
+
+ Copyright (C) 1989, 1991 Free Software Foundation, Inc.,
+ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The licenses for most software are designed to take away your
+freedom to share and change it.  By contrast, the GNU General Public
+License is intended to guarantee your freedom to share and change free
+software--to make sure the software is free for all its users.  This
+General Public License applies to most of the Free Software
+Foundation's software and to any other program whose authors commit to
+using it.  (Some other Free Software Foundation software is covered by
+the GNU Lesser General Public License instead.)  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it
+if you want it, that you can change the software or use pieces of it
+in new free programs; and that you know you can do these things.
+
+  To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must give the recipients all the rights that
+you have.  You must make sure that they, too, receive or can get the
+source code.  And you must show them these terms so they know their
+rights.
+
+  We protect your rights with two steps: (1) copyright the software, and
+(2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.
+
+  Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software.  If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.
+
+  Finally, any free program is threatened constantly by software
+patents.  We wish to avoid the danger that redistributors of a free
+program will individually obtain patent licenses, in effect making the
+program proprietary.  To prevent this, we have made it clear that any
+patent must be licensed for everyone's free use or not licensed at all.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                    GNU GENERAL PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. This License applies to any program or other work which contains
+a notice placed by the copyright holder saying it may be distributed
+under the terms of this General Public License.  The "Program", below,
+refers to any such program or work, and a "work based on the Program"
+means either the Program or any derivative work under copyright law:
+that is to say, a work containing the Program or a portion of it,
+either verbatim or with modifications and/or translated into another
+language.  (Hereinafter, translation is included without limitation in
+the term "modification".)  Each licensee is addressed as "you".
+
+Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope.  The act of
+running the Program is not restricted, and the output from the Program
+is covered only if its contents constitute a work based on the
+Program (independent of having been made by running the Program).
+Whether that is true depends on what the Program does.
+
+  1. You may copy and distribute verbatim copies of the Program's
+source code as you receive it, in any medium, provided that you
+conspicuously and appropriately publish on each copy an appropriate
+copyright notice and disclaimer of warranty; keep intact all the
+notices that refer to this License and to the absence of any warranty;
+and give any other recipients of the Program a copy of this License
+along with the Program.
+
+You may charge a fee for the physical act of transferring a copy, and
+you may at your option offer warranty protection in exchange for a fee.
+
+  2. You may modify your copy or copies of the Program or any portion
+of it, thus forming a work based on the Program, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+    a) You must cause the modified files to carry prominent notices
+    stating that you changed the files and the date of any change.
+
+    b) You must cause any work that you distribute or publish, that in
+    whole or in part contains or is derived from the Program or any
+    part thereof, to be licensed as a whole at no charge to all third
+    parties under the terms of this License.
+
+    c) If the modified program normally reads commands interactively
+    when run, you must cause it, when started running for such
+    interactive use in the most ordinary way, to print or display an
+    announcement including an appropriate copyright notice and a
+    notice that there is no warranty (or else, saying that you provide
+    a warranty) and that users may redistribute the program under
+    these conditions, and telling the user how to view a copy of this
+    License.  (Exception: if the Program itself is interactive but
+    does not normally print such an announcement, your work based on
+    the Program is not required to print an announcement.)
+
+These requirements apply to the modified work as a whole.  If
+identifiable sections of that work are not derived from the Program,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works.  But when you
+distribute the same sections as part of a whole which is a work based
+on the Program, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Program.
+
+In addition, mere aggregation of another work not based on the Program
+with the Program (or with a work based on the Program) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+  3. You may copy and distribute the Program (or a work based on it,
+under Section 2) in object code or executable form under the terms of
+Sections 1 and 2 above provided that you also do one of the following:
+
+    a) Accompany it with the complete corresponding machine-readable
+    source code, which must be distributed under the terms of Sections
+    1 and 2 above on a medium customarily used for software interchange; or,
+
+    b) Accompany it with a written offer, valid for at least three
+    years, to give any third party, for a charge no more than your
+    cost of physically performing source distribution, a complete
+    machine-readable copy of the corresponding source code, to be
+    distributed under the terms of Sections 1 and 2 above on a medium
+    customarily used for software interchange; or,
+
+    c) Accompany it with the information you received as to the offer
+    to distribute corresponding source code.  (This alternative is
+    allowed only for noncommercial distribution and only if you
+    received the program in object code or executable form with such
+    an offer, in accord with Subsection b above.)
+
+The source code for a work means the preferred form of the work for
+making modifications to it.  For an executable work, complete source
+code means all the source code for all modules it contains, plus any
+associated interface definition files, plus the scripts used to
+control compilation and installation of the executable.  However, as a
+special exception, the source code distributed need not include
+anything that is normally distributed (in either source or binary
+form) with the major components (compiler, kernel, and so on) of the
+operating system on which the executable runs, unless that component
+itself accompanies the executable.
+
+If distribution of executable or object code is made by offering
+access to copy from a designated place, then offering equivalent
+access to copy the source code from the same place counts as
+distribution of the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+  4. You may not copy, modify, sublicense, or distribute the Program
+except as expressly provided under this License.  Any attempt
+otherwise to copy, modify, sublicense or distribute the Program is
+void, and will automatically terminate your rights under this License.
+However, parties who have received copies, or rights, from you under
+this License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+  5. You are not required to accept this License, since you have not
+signed it.  However, nothing else grants you permission to modify or
+distribute the Program or its derivative works.  These actions are
+prohibited by law if you do not accept this License.  Therefore, by
+modifying or distributing the Program (or any work based on the
+Program), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Program or works based on it.
+
+  6. Each time you redistribute the Program (or any work based on the
+Program), the recipient automatically receives a license from the
+original licensor to copy, distribute or modify the Program subject to
+these terms and conditions.  You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties to
+this License.
+
+  7. If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Program at all.  For example, if a patent
+license would not permit royalty-free redistribution of the Program by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Program.
+
+If any portion of this section is held invalid or unenforceable under
+any particular circumstance, the balance of the section is intended to
+apply and the section as a whole is intended to apply in other
+circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system, which is
+implemented by public license practices.  Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+  8. If the distribution and/or use of the Program is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Program under this License
+may add an explicit geographical distribution limitation excluding
+those countries, so that distribution is permitted only in or among
+countries not thus excluded.  In such case, this License incorporates
+the limitation as if written in the body of this License.
+
+  9. The Free Software Foundation may publish revised and/or new versions
+of the General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+Each version is given a distinguishing version number.  If the Program
+specifies a version number of this License which applies to it and "any
+later version", you have the option of following the terms and conditions
+either of that version or of any later version published by the Free
+Software Foundation.  If the Program does not specify a version number of
+this License, you may choose any version ever published by the Free Software
+Foundation.
+
+  10. If you wish to incorporate parts of the Program into other free
+programs whose distribution conditions are different, write to the author
+to ask for permission.  For software which is copyrighted by the Free
+Software Foundation, write to the Free Software Foundation; we sometimes
+make exceptions for this.  Our decision will be guided by the two goals
+of preserving the free status of all derivatives of our free software and
+of promoting the sharing and reuse of software generally.
+
+                            NO WARRANTY
+
+  11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
+FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
+OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
+OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
+TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
+PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
+REPAIR OR CORRECTION.
+
+  12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
+OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
+TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
+YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
+PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software; you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation; either version 2 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License along
+    with this program; if not, write to the Free Software Foundation, Inc.,
+    51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+Also add information on how to contact you by electronic and paper mail.
+
+If the program is interactive, make it output a short notice like this
+when it starts in an interactive mode:
+
+    Gnomovision version 69, Copyright (C) year name of author
+    Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, the commands you use may
+be called something other than `show w' and `show c'; they could even be
+mouse-clicks or menu items--whatever suits your program.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a "copyright disclaimer" for the program, if
+necessary.  Here is a sample; alter the names:
+
+  Yoyodyne, Inc., hereby disclaims all copyright interest in the program
+  `Gnomovision' (which makes passes at compilers) written by James Hacker.
+
+  <signature of Ty Coon>, 1 April 1989
+  Ty Coon, President of Vice
+
+This General Public License does not permit incorporating your program into
+proprietary programs.  If your program is a subroutine library, you may
+consider it more useful to permit linking proprietary applications with the
+library.  If this is what you want to do, use the GNU Lesser General
+Public License instead of this License.