Skip to content

Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.

11.8 KB
Raw Blame
"""`verse.placement/1` documents: ids, canonical form and validation.

Pure Python (no bpy, no unreal), shared by the Blender export, the static
check `scripts/unreal/check_art_text.py` and pytest. The format is defined in
docs/verse/unreal/contracts/art-pipeline.md section 4; the JSON Schema is
`art/verse/schema/placement.schema.json`. This module adds the rules a schema
cannot express: unique ids, origins inside the zone box, unit quaternions,
room references, level and data-layer names that match the deck, and the
destructible and mobility rules of sections 4.2 and 5.
"""

from __future__ import annotations

import json
import math
import re
from collections.abc import Iterable, Mapping, Sequence
from pathlib import Path
from typing import Any

SCHEMA_ID = "verse.placement/1"
SCHEMA_PATH = Path(__file__).resolve().parents[1] / "schema" / "placement.schema.json"

ID_SNAP_CM = 15.0
ID_SNAP_DEG = 1.0
LOCATION_DIGITS = 3  # 0.001 cm
QUAT_DIGITS = 7
SCALE_DIGITS = 6
MAX_FILE_BYTES = 2 * 1024 * 1024  # art-pipeline 10.4
UNIT_QUAT_TOLERANCE = 1e-4

#: Destructible proxy states every destructible must provide (art-pipeline 5).
REQUIRED_PROXY_STATES = ("Intact", "Holed", "Breached", "Destroyed")
#: Data layers allowed outside `DL_<Deck>_Base` (VerseDecks day/arena switch).
HANGAR_LAYERS = ("DL_Hangar_Day", "DL_Hangar_Arena")

_ID_SAFE = re.compile(r"[^a-z0-9_]+")


def deck_title(deck: str) -> str:
    """`engineering` -> `Engineering`; `ops_deck` -> `OpsDeck` (folder and level case)."""
    return "".join(part.capitalize() for part in deck.split("_"))


def level_path(deck: str) -> str:
    title = deck_title(deck)
    return f"/Game/Verse/Decks/{title}/LV_{title}"


def base_layer(deck: str) -> str:
    return f"DL_{deck_title(deck)}_Base"


def asset_name_of(object_path: str) -> str:
    """`/Game/Verse/Kit/SM_Wall_480.SM_Wall_480` -> `SM_Wall_480`."""
    return object_path.rsplit("/", 1)[-1].split(".", 1)[0]


def sanitize_id(raw: str) -> str:
    """Builder ids become placement ids: lower case, `[a-z0-9_]` only."""
    cleaned = _ID_SAFE.sub("_", raw.lower()).strip("_")
    if not cleaned:
        raise ValueError(f"id {raw!r} has no usable characters")
    return cleaned


def _id_number(value: float) -> str:
    n = int(round(value))
    return f"m{-n}" if n < 0 else str(n)


def auto_id(piece: str, location_cm: Sequence[float], yaw_deg: float) -> str:
    """`<piece lower>_<x>_<y>_<z>_<yaw>`, snapped to 15 cm and 1 degree.

    Negative numbers are written `m<n>` because ids allow `[a-z0-9_]` only.
    """
    snapped = [ID_SNAP_CM * round(float(v) / ID_SNAP_CM) for v in location_cm]
    yaw = (ID_SNAP_DEG * round(float(yaw_deg) / ID_SNAP_DEG)) % 360.0
    parts = [sanitize_id(piece), *(_id_number(v) for v in snapped), _id_number(yaw) or "0"]
    return "_".join(parts)


def unique_ids(ids: Iterable[str]) -> list[str]:
    """Duplicates get `_2`, `_3`, ... in order of appearance."""
    seen: dict[str, int] = {}
    taken = set()
    out = []
    for raw in ids:
        count = seen.get(raw, 0) + 1
        seen[raw] = count
        candidate = raw if count == 1 else f"{raw}_{count}"
        while candidate in taken:
            count += 1
            seen[raw] = count
            candidate = f"{raw}_{count}"
        taken.add(candidate)
        out.append(candidate)
    return out


def yaw_from_quat_xyzw(quat: Sequence[float]) -> float:
    """Yaw in degrees of an [x, y, z, w] quaternion (rotation about Z part)."""
    x, y, z, w = (float(v) for v in quat)
    return math.degrees(math.atan2(2.0 * (w * z + x * y), 1.0 - 2.0 * (y * y + z * z)))


def _round_list(values: Sequence[float], digits: int) -> list[float]:
    out = []
    for value in values:
        rounded = round(float(value), digits)
        out.append(0.0 if rounded == 0 else rounded)
    return out


def canonical(doc: Mapping[str, Any]) -> dict[str, Any]:
    """Return a copy with rounded numbers and arrays in stable order (by id)."""
    out = json.loads(json.dumps(doc))
    for item in out.get("placements", []):
        item["location"] = _round_list(item["location"], LOCATION_DIGITS)
        item["rotation"] = _round_list(item["rotation"], QUAT_DIGITS)
        item["scale"] = _round_list(item["scale"], SCALE_DIGITS)
        if "tags" in item:
            item["tags"] = sorted(item["tags"])
    for item in out.get("sockets", []):
        item["location"] = _round_list(item["location"], LOCATION_DIGITS)
        item["rotation"] = _round_list(item["rotation"], QUAT_DIGITS)
    for room in out.get("rooms", []):
        room["polygon_cm"] = [_round_list(p, LOCATION_DIGITS) for p in room["polygon_cm"]]
    bounds = out.get("bounds_cm")
    if isinstance(bounds, dict):
        for key in ("min", "max"):
            if key in bounds:
                bounds[key] = _round_list(bounds[key], LOCATION_DIGITS)
    for key in ("placements", "sockets", "rooms"):
        if isinstance(out.get(key), list):
            out[key].sort(key=lambda entry: str(entry.get("id", "")))
    return out


def dumps(doc: Mapping[str, Any]) -> str:
    """Canonical text: sorted keys, 2-space indent, LF, trailing newline."""
    return json.dumps(canonical(doc), indent=2, sort_keys=True, ensure_ascii=True) + "\n"


def write(path: Path, doc: Mapping[str, Any]) -> bool:
    """Write `doc` canonically; return True when the file changed."""
    text = dumps(doc)
    if path.is_file() and path.read_text(encoding="utf-8") == text:
        return False
    path.parent.mkdir(parents=True, exist_ok=True)
    path.write_bytes(text.encode("utf-8"))
    return True


# --------------------------------------------------------------------------
# Validation
# --------------------------------------------------------------------------


def _schema_validator():
    import jsonschema

    schema = json.loads(SCHEMA_PATH.read_text(encoding="utf-8"))
    jsonschema.Draft202012Validator.check_schema(schema)
    return jsonschema.Draft202012Validator(schema)


def _path_of(error) -> str:
    parts = [str(p) for p in error.absolute_path]
    return "/".join(parts) or "<root>"


def schema_errors(doc: Any) -> list[str]:
    validator = _schema_validator()
    return [
        f"{_path_of(e)}: {e.message}"
        for e in sorted(validator.iter_errors(doc), key=lambda e: list(e.absolute_path))
    ]


def _inside(point: Sequence[float], lo: Sequence[float], hi: Sequence[float]) -> bool:
    return all(a - 1e-6 <= p <= b + 1e-6 for p, a, b in zip(point, lo, hi, strict=True))


def _dupes(values: Sequence[str]) -> list[str]:
    return sorted({v for v in values if values.count(v) > 1})


def _quat_norm_error(quat: Sequence[float]) -> float:
    return abs(math.sqrt(sum(float(v) * float(v) for v in quat)) - 1.0)


def semantic_errors(
    doc: Mapping[str, Any],
    *,
    path: Path | None = None,
    known_assets: set[str] | None = None,
) -> list[str]:
    """Rules beyond the schema. Assumes `schema_errors(doc)` is empty."""
    errors: list[str] = []
    deck, zone = doc["deck"], doc["zone"]
    if path is not None:
        if path.name != f"{zone}.placement.json":
            errors.append(f"file name must be {zone}.placement.json")
        if path.parent.name != deck:
            errors.append(f"file must live in Placements/{deck}/")
        size = path.stat().st_size if path.is_file() else 0
        if size > MAX_FILE_BYTES:
            errors.append(f"file is {size} bytes, budget {MAX_FILE_BYTES} (art-pipeline 10.4)")
    if doc["level"] != level_path(deck):
        errors.append(f"level must be {level_path(deck)}")
    lo, hi = doc["bounds_cm"]["min"], doc["bounds_cm"]["max"]
    if not all(a < b for a, b in zip(lo, hi, strict=True)):
        errors.append("bounds_cm: min must be below max on every axis")

    rooms = [room["id"] for room in doc["rooms"]]
    errors += [f"rooms: duplicate id {rid!r}" for rid in _dupes(rooms)]
    room_set = set(rooms)
    allowed_layers = {base_layer(deck)}
    if deck == "hangar":
        allowed_layers.update(HANGAR_LAYERS)

    ids = [p["id"] for p in doc["placements"]]
    errors += [f"placements: duplicate id {i!r}" for i in _dupes(ids)]
    for item in doc["placements"]:
        where = f"placements/{item['id']}"
        if asset_name_of(item["asset"]) != item["piece"]:
            errors.append(f"{where}: asset {item['asset']} is not the piece {item['piece']}")
        object_name = item["asset"].rsplit(".", 1)[-1]
        if object_name != item["piece"]:
            errors.append(f"{where}: object path must end in .{item['piece']}")
        if known_assets is not None and item["asset"] not in known_assets:
            errors.append(f"{where}: unknown asset {item['asset']} (no import record)")
        if not _inside(item["location"], lo, hi):
            errors.append(f"{where}: origin {item['location']} outside bounds_cm")
        if _quat_norm_error(item["rotation"]) > UNIT_QUAT_TOLERANCE:
            errors.append(f"{where}: rotation is not a unit quaternion")
        if item["room"] is not None and item["room"] not in room_set:
            errors.append(f"{where}: room {item['room']!r} is not in rooms[]")
        if item["data_layer"] not in allowed_layers:
            layers = sorted(allowed_layers)
            errors.append(f"{where}: data_layer {item['data_layer']} not in {layers}")
        destructible = item["destructible"]
        if destructible is not None:
            if item["mobility"] != "movable":
                errors.append(f"{where}: a destructible must be movable")
            if item["collision"] != "Verse_Destructible":
                errors.append(f"{where}: a destructible uses collision Verse_Destructible")
            missing = [s for s in REQUIRED_PROXY_STATES if s not in destructible["proxies"]]
            if missing:
                errors.append(f"{where}: destructible proxies missing {missing}")
            states = set(destructible["states"])
            for state in REQUIRED_PROXY_STATES:
                if state not in states:
                    errors.append(f"{where}: destructible states missing {state}")
        elif item["collision"] == "Verse_Destructible":
            errors.append(f"{where}: collision Verse_Destructible needs a destructible block")
        if item["piece"].startswith("GC_") and destructible is None:
            errors.append(f"{where}: a geometry collection placement must be destructible")

    socket_ids = [s["id"] for s in doc["sockets"]]
    errors += [f"sockets: duplicate id {i!r}" for i in _dupes(socket_ids)]
    for socket in doc["sockets"]:
        where = f"sockets/{socket['id']}"
        if not _inside(socket["location"], lo, hi):
            errors.append(f"{where}: location outside bounds_cm")
        if _quat_norm_error(socket["rotation"]) > UNIT_QUAT_TOLERANCE:
            errors.append(f"{where}: rotation is not a unit quaternion")
        if socket["room"] is not None and socket["room"] not in room_set:
            errors.append(f"{where}: room {socket['room']!r} is not in rooms[]")
    return errors


def validate(
    doc: Any, *, path: Path | None = None, known_assets: set[str] | None = None
) -> list[str]:
    """All errors of one placement document (schema first, then semantics)."""
    errors = schema_errors(doc)
    if errors:
        return errors
    return semantic_errors(doc, path=path, known_assets=known_assets)


def validate_file(path: Path, *, known_assets: set[str] | None = None) -> list[str]:
    raw = path.read_bytes()
    errors: list[str] = []
    if b"\r\n" in raw:
        errors.append("line endings must be LF")
    try:
        doc = json.loads(raw.decode("utf-8"))
    except (UnicodeDecodeError, json.JSONDecodeError) as error:
        return [f"not valid JSON: {error}"]
    errors += validate(doc, path=path, known_assets=known_assets)
    if not errors and raw.decode("utf-8") != dumps(doc):
        errors.append(
            "not in canonical form (sorted keys, 2-space indent, arrays by id);"
            " rewrite it with lib.placement.write"
        )
    return errors