structura-render 0.1.0__py3-none-any.whl

structura_render/__init__.py

@@ -0,0 +1,6 @@
+"""Minecraft Structure NBT renderers and reusable mesh construction."""
+
+from .textures import TextureBank, tint_for
+
+__all__ = ["TextureBank", "tint_for"]
+__version__ = "0.1.0"

structura_render/assets.py

@@ -0,0 +1,82 @@
+"""Minecraft client-asset discovery without a repository-relative import."""
+
+import hashlib
+import os
+import sys
+import zipfile
+from pathlib import Path
+
+_VERSION_MARKER_BLOCK = "heavy_core"
+
+
+def _cache_root() -> Path:
+    configured = os.environ.get("XDG_CACHE_HOME")
+    base = Path(configured).expanduser() if configured else Path.home() / ".cache"
+    return base / "structura-render" / "jar-assets"
+
+
+def _extract_jar_assets(jar_path: Path) -> Path:
+    stat = jar_path.stat()
+    key = hashlib.sha1(
+        f"{jar_path.resolve()}:{stat.st_mtime_ns}:{stat.st_size}".encode(),
+    ).hexdigest()[:16]
+    dest = _cache_root() / key
+    marker = dest / ".extracted"
+    target = dest / "assets" / "minecraft"
+    if marker.is_file() and target.is_dir():
+        return target
+
+    with zipfile.ZipFile(jar_path) as archive:
+        members = [
+            name for name in archive.namelist()
+            if name.startswith("assets/minecraft/") and not name.endswith("/")
+        ]
+        if not members:
+            raise FileNotFoundError(
+                f"{jar_path} has no assets/minecraft/ entries; "
+                "is this a real Minecraft client jar?",
+            )
+        dest.mkdir(parents=True, exist_ok=True)
+        archive.extractall(dest, members=members)
+    marker.touch()
+    return target
+
+
+def _warn_if_version_mismatch(assets_root: Path) -> None:
+    marker = assets_root / "models" / "block" / f"{_VERSION_MARKER_BLOCK}.json"
+    if not marker.is_file():
+        print(
+            f"structura_render: WARNING: {assets_root} has no "
+            f"{_VERSION_MARKER_BLOCK} model (added in Minecraft 1.21) -- "
+            "these assets look older than the datapack's target version; "
+            "renders may not match what actually spawns in-game.",
+            file=sys.stderr,
+        )
+
+
+def minecraft_assets_root() -> Path:
+    configured = os.environ.get("STRUCTURA_MINECRAFT_ASSETS")
+    if configured:
+        path = Path(configured).expanduser().resolve()
+        if path.is_dir():
+            _warn_if_version_mismatch(path)
+            return path
+        if path.is_file() and path.suffix == ".jar":
+            extracted = _extract_jar_assets(path)
+            _warn_if_version_mismatch(extracted)
+            return extracted
+        raise FileNotFoundError(
+            f"STRUCTURA_MINECRAFT_ASSETS does not exist: {path} "
+            "(point it at an assets/minecraft directory or a client .jar)",
+        )
+
+    candidates = [Path.cwd(), *Path(__file__).resolve().parents]
+    for root in candidates:
+        path = root / "assets" / "minecraft"
+        if path.is_dir():
+            _warn_if_version_mismatch(path)
+            return path
+    return Path.cwd() / "assets" / "minecraft"
+
+
+ASSETS = minecraft_assets_root()

structura_render/block_model.py

@@ -0,0 +1,255 @@
+"""Resolve vanilla blockstate/model JSON into textured quads."""
+import json
+import math
+from functools import wraps
+
+from .assets import ASSETS
+
+BLOCKSTATES = ASSETS / "blockstates"
+MODELS = ASSETS / "models/block"
+
+DIRECTIONS = ("up", "down", "north", "south", "east", "west")
+AXIS_VEC = {
+    "up": (0, 1, 0), "down": (0, -1, 0),
+    "north": (0, 0, -1), "south": (0, 0, 1),
+    "east": (1, 0, 0), "west": (-1, 0, 0),
+}
+VEC_AXIS = {v: k for k, v in AXIS_VEC.items()}
+
+FACE_CORNERS = {
+    "up": (4, 5, 6, 7), "down": (0, 1, 2, 3),
+    "north": (1, 0, 4, 5), "south": (3, 2, 6, 7),
+    "east": (2, 1, 5, 6), "west": (0, 3, 7, 4),
+}
+FACE_UV_BASIS = {
+    "up": ((1, 0, 0), (0, 0, 1)), "down": ((1, 0, 0), (0, 0, 1)),
+    "north": ((-1, 0, 0), (0, 1, 0)), "south": ((1, 0, 0), (0, 1, 0)),
+    "east": ((0, 0, -1), (0, 1, 0)), "west": ((0, 0, 1), (0, 1, 0)),
+}
+FACE_UV_PLANE = {
+    "up": (0, 2), "down": (0, 2),
+    "north": (0, 1), "south": (0, 1),
+    "east": (2, 1), "west": (2, 1),
+}
+
+_blockstate_cache = {}
+_model_cache = {}
+_RESOLUTION_ERRORS = (KeyError, IndexError, TypeError, ValueError, json.JSONDecodeError)
+
+
+def safe(fn):
+    @wraps(fn)
+    def wrapper(*args, **kwargs):
+        try:
+            return fn(*args, **kwargs)
+        except _RESOLUTION_ERRORS:
+            return None
+    return wrapper
+
+
+def strip_ns(name):
+    name = name.split(":", 1)[-1]
+    return name[len("block/"):] if name.startswith("block/") else name
+
+
+def load_blockstate(name):
+    name = strip_ns(name)
+    if name not in _blockstate_cache:
+        path = BLOCKSTATES / f"{name}.json"
+        _blockstate_cache[name] = json.loads(path.read_text()) if path.exists() else None
+    return _blockstate_cache[name]
+
+
+def load_model(name):
+    name = strip_ns(name)
+    if name not in _model_cache:
+        path = MODELS / f"{name}.json"
+        _model_cache[name] = json.loads(path.read_text()) if path.exists() else None
+    return _model_cache[name]
+
+
+def resolve_model(name, depth=0):
+    if depth > 10:
+        return {"elements": None, "textures": {}}
+    data = load_model(name)
+    if data is None:
+        return {"elements": None, "textures": {}}
+    parent = data.get("parent")
+    base = resolve_model(parent, depth + 1) if parent else {"elements": None, "textures": {}}
+    return {
+        "elements": data.get("elements", base["elements"]),
+        "textures": {**base["textures"], **data.get("textures", {})},
+    }
+
+
+def resolve_texture(ref, textures, depth=0):
+    if ref is None or depth > 10:
+        return None
+    if isinstance(ref, dict):
+        return resolve_texture(ref.get("sprite"), textures, depth + 1)
+    key = ref[1:] if ref.startswith("#") else ref
+    if key in textures:
+        return resolve_texture(textures[key], textures, depth + 1)
+    return strip_ns(ref) if not ref.startswith("#") else None
+
+
+def matching_variant(variants, props):
+    parsed = []
+    for key, value in variants.items():
+        pairs = tuple(pair.split("=", 1) for pair in key.split(",")) if key else ()
+        parsed.append((dict(pairs), value))
+    matches = [
+        (len(wanted), value)
+        for wanted, value in parsed
+        if all(props.get(k) == v for k, v in wanted.items())
+    ]
+    return max(matches, key=lambda item: item[0])[1] if matches else (parsed[0][1] if parsed else None)
+
+
+def condition_matches(condition, props):
+    if "OR" in condition:
+        return any(condition_matches(part, props) for part in condition["OR"])
+    if "AND" in condition:
+        return all(condition_matches(part, props) for part in condition["AND"])
+    return all(props.get(key) in str(wanted).split("|") for key, wanted in condition.items())
+
+
+def selected_models(blockstate, props):
+    if "variants" in blockstate:
+        entries = [matching_variant(blockstate["variants"], props)]
+    else:
+        entries = [
+            part["apply"] for part in blockstate.get("multipart", ())
+            if "when" not in part or condition_matches(part["when"], props)
+        ]
+    return [entry[0] if isinstance(entry, list) else entry for entry in entries if entry]
+
+
+def _rotate(point, origin, axis, degrees):
+    angle = math.radians(degrees)
+    cosine, sine = math.cos(angle), math.sin(angle)
+    x, y, z = (point[i] - origin[i] for i in range(3))
+    if axis == "x":
+        y, z = y * cosine - z * sine, y * sine + z * cosine
+    elif axis == "y":
+        x, z = x * cosine - z * sine, x * sine + z * cosine
+    else:
+        x, y = x * cosine - y * sine, x * sine + y * cosine
+    return x + origin[0], y + origin[1], z + origin[2]
+
+
+def rotate_vector(vector, x_deg, y_deg):
+    rotated = _rotate(vector, (0, 0, 0), "x", x_deg)
+    return tuple(round(v) for v in _rotate(rotated, (0, 0, 0), "y", y_deg))
+
+
+def rotate_direction(direction, x_deg, y_deg):
+    return VEC_AXIS[rotate_vector(AXIS_VEC[direction], x_deg, y_deg)]
+
+
+def rotate_element(point, rotation):
+    if not rotation:
+        return point
+    origin = rotation.get("origin", (8, 8, 8))
+    if "axis" not in rotation:
+        for axis in "xyz":
+            point = _rotate(point, origin, axis, rotation.get(axis, 0))
+        return point
+    axis, angle = rotation["axis"], rotation["angle"]
+    if rotation.get("rescale"):
+        scale = 1 / math.cos(math.radians(angle))
+        point = tuple(
+            origin[i] + (point[i] - origin[i]) * (1 if "xyz"[i] == axis else scale)
+            for i in range(3)
+        )
+    return _rotate(point, origin, axis, angle)
+
+
+def rotate_blockstate(point, x_deg, y_deg):
+    point = _rotate(point, (8, 8, 8), "x", x_deg)
+    return _rotate(point, (8, 8, 8), "y", y_deg)
+
+
+def box_corners(lo, hi):
+    return (
+        (lo[0], lo[1], lo[2]), (hi[0], lo[1], lo[2]),
+        (hi[0], lo[1], hi[2]), (lo[0], lo[1], hi[2]),
+        (lo[0], hi[1], lo[2]), (hi[0], hi[1], lo[2]),
+        (hi[0], hi[1], hi[2]), (lo[0], hi[1], hi[2]),
+    )
+
+
+def _neg(vector):
+    return tuple(-v for v in vector)
+
+
+def uvlock_quarters(direction, x_deg, y_deg):
+    world_direction = rotate_direction(direction, x_deg, y_deg)
+    u, v = (rotate_vector(axis, x_deg, y_deg) for axis in FACE_UV_BASIS[direction])
+    target_u, target_v = FACE_UV_BASIS[world_direction]
+    choices = ((u, v), (v, _neg(u)), (_neg(u), _neg(v)), (_neg(v), u))
+    return next((i for i, basis in enumerate(choices) if basis == (target_u, target_v)), 0)
+
+
+@safe
+def post_texture(name):
+    model = resolve_model(f"{strip_ns(name)}_post")
+    return resolve_texture(model["textures"].get("particle"), model["textures"])
+
+
+@safe
+def block_elements(name, props):
+    blockstate = load_blockstate(name)
+    if blockstate is None:
+        return None
+    entries = selected_models(blockstate, props)
+    result = []
+    for entry in entries:
+        model = resolve_model(entry["model"])
+        if not model["elements"]:
+            continue
+        x_deg, y_deg = entry.get("x", 0), entry.get("y", 0)
+        for element in model["elements"]:
+            lo, hi = element["from"], element["to"]
+            corners = [
+                rotate_blockstate(rotate_element(point, element.get("rotation")), x_deg, y_deg)
+                for point in box_corners(lo, hi)
+            ]
+            faces = {}
+            for direction, face in element.get("faces", {}).items():
+                texture = resolve_texture(face.get("texture"), model["textures"])
+                if texture is None:
+                    continue
+                uv = face.get("uv", default_uv(direction, lo, hi))
+                world_direction = rotate_direction(direction, x_deg, y_deg)
+                cullface = face.get("cullface")
+                cullface = {"top": "up", "bottom": "down"}.get(cullface, cullface)
+                faces[world_direction] = {
+                    "texture": texture,
+                    "uv": tuple(value / 16 for value in uv),
+                    "uv_rotation": (
+                        face.get("rotation", 0) // 90
+                        + (uvlock_quarters(direction, x_deg, y_deg) if entry.get("uvlock") else 0)
+                    ) % 4,
+                    "vertices": tuple(
+                        tuple(value / 16 for value in corners[i])
+                        for i in FACE_CORNERS[direction]
+                    ),
+                    "cullface": rotate_direction(cullface, x_deg, y_deg) if cullface else None,
+                    "tinted": "tintindex" in face,
+                }
+            if faces:
+                result.append({
+                    "lo": tuple(min(point[i] for point in corners) / 16 for i in range(3)),
+                    "hi": tuple(max(point[i] for point in corners) / 16 for i in range(3)),
+                    "faces": faces,
+                })
+    return result if result else ([] if entries else None)
+
+
+def default_uv(direction, lo, hi):
+    a, b = FACE_UV_PLANE[direction]
+    lo_b, hi_b = lo[b], hi[b]
+    if b == 1:
+        lo_b, hi_b = 16 - hi[b], 16 - lo[b]
+    return lo[a], lo_b, hi[a], hi_b

structura_render/build_full_cube_list.py

@@ -0,0 +1,90 @@
+#!/usr/bin/env python3
+"""Determine, for every vanilla block, whether it's a real full opaque
+cube (occupies [0,0,0]-[16,16,16] with all 6 faces defined) by resolving
+its actual blockstate -> model -> parent chain from the game's own
+files -- not a name/substring guess. Writes structura_render/data/full_cube_blocks.json,
+loaded by full_cube.is_full_cube_shape()."""
+import json
+from pathlib import Path
+
+from .assets import ASSETS
+from .block_model import DIRECTIONS
+
+BLOCKSTATES = ASSETS / "blockstates"
+MODELS = ASSETS / "models/block"
+
+MULTIPART_SOLID_FULL_CUBES = {
+    "minecraft:brown_mushroom_block",
+    "minecraft:red_mushroom_block",
+    "minecraft:mushroom_stem",
+    "minecraft:chiseled_bookshelf",
+}
+
+_model_cache = {}
+
+
+def load_model(name):
+    name = name.split(":", 1)[-1]
+    if name.startswith("block/"):
+        name = name[len("block/"):]
+    if name in _model_cache:
+        return _model_cache[name]
+    path = MODELS / f"{name}.json"
+    data = json.loads(path.read_text()) if path.exists() else None
+    _model_cache[name] = data
+    return data
+
+
+def resolve_elements(model_name, depth=0):
+    if depth > 10:
+        return None
+    data = load_model(model_name)
+    if data is None:
+        return None
+    if "elements" in data:
+        return data["elements"]
+    parent = data.get("parent")
+    return resolve_elements(parent, depth + 1) if parent else None
+
+
+def is_full_cube_element(element):
+    if element.get("from") != [0, 0, 0] or element.get("to") != [16, 16, 16]:
+        return False
+    faces = element.get("faces", {})
+    return all(d in faces for d in DIRECTIONS)
+
+
+def is_full_cube_elements(elements):
+    return bool(elements) and any(is_full_cube_element(el) for el in elements)
+
+
+def variant_model_name(blockstate):
+    first = next(iter(blockstate["variants"].values()))
+    if isinstance(first, list):
+        first = first[0]
+    return first.get("model")
+
+
+def classify_full_cube(name, blockstate):
+    if "multipart" in blockstate:
+        return name in MULTIPART_SOLID_FULL_CUBES
+    model_name = variant_model_name(blockstate)
+    return is_full_cube_elements(resolve_elements(model_name))
+
+
+def main():
+    results = {}
+    for path in sorted(BLOCKSTATES.glob("*.json")):
+        name = f"minecraft:{path.stem}"
+        blockstate = json.loads(path.read_text())
+        results[name] = classify_full_cube(name, blockstate)
+
+    out_dir = Path(__file__).resolve().parent / "data"
+    out_dir.mkdir(exist_ok=True)
+    out_path = out_dir / "full_cube_blocks.json"
+    out_path.write_text(json.dumps(results, indent=1, sort_keys=True) + "\n")
+    print(f"{out_path} full_cubes={sum(results.values())}/{len(results)}")
+
+
+if __name__ == "__main__":
+    main()

structura_render/build_opaque_blocks.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+"""For every block classified as a full cube (structura_render/data/full_cube_blocks.json),
+determine whether it's actually fully opaque by reading the real alpha channel
+of its real texture(s) -- not by name or by shape. A full-cube block whose
+texture has any non-255 alpha (leaves, ice, honey, slime...) must not occlude
+neighbor faces even though its shape is a full cube. Writes
+structura_render/data/opaque_blocks.json, loaded by full_cube.is_opaque_shape()."""
+import json
+from pathlib import Path
+
+import numpy as np
+from PIL import Image
+
+from .assets import ASSETS
+from .block_model import DIRECTIONS, block_elements
+from .build_full_cube_list import MULTIPART_SOLID_FULL_CUBES
+
+TEXTURES = ASSETS / "textures/block"
+FULL_CUBE_DATA = Path(__file__).resolve().parent / "data/full_cube_blocks.json"
+
+_texture_opacity_cache = {}
+
+
+def texture_is_opaque(texture_name):
+    if texture_name not in _texture_opacity_cache:
+        path = TEXTURES / f"{texture_name}.png"
+        if not path.exists():
+            _texture_opacity_cache[texture_name] = True
+        else:
+            image = Image.open(path).convert("RGBA")
+            array = np.asarray(image)
+            if array.shape[0] > array.shape[1]:
+                array = array[: array.shape[1]]
+            _texture_opacity_cache[texture_name] = bool((array[..., 3] == 255).all())
+    return _texture_opacity_cache[texture_name]
+
+
+def element_is_opaque_cube(element):
+    if element["lo"] != (0.0, 0.0, 0.0) or element["hi"] != (1.0, 1.0, 1.0):
+        return False
+    faces = element["faces"]
+    return all(d in faces and texture_is_opaque(faces[d]["texture"]) for d in DIRECTIONS)
+
+
+def block_is_opaque(name):
+    elements = block_elements(name, {})
+    if elements is None:
+        return name in MULTIPART_SOLID_FULL_CUBES
+    return any(element_is_opaque_cube(element) for element in elements)
+
+
+def main():
+    full_cubes = json.loads(FULL_CUBE_DATA.read_text())
+    results = {
+        name: block_is_opaque(name)
+        for name, is_full_cube in full_cubes.items()
+        if is_full_cube
+    }
+    out_path = Path(__file__).resolve().parent / "data/opaque_blocks.json"
+    out_path.write_text(json.dumps(results, indent=1, sort_keys=True) + "\n")
+    print(f"{out_path} opaque={sum(results.values())}/{len(results)}")
+
+
+if __name__ == "__main__":
+    main()