@bitmagic/cli 0.1.71-dev.1 → 0.1.71-dev.4

package/README.md

@@ -1598,10 +1598,17 @@ requests except the intercepted SDK. Local validation uses an SDK test stub and
 pause/ad/resume cycle; it does not certify Poki acceptance. Test the payload folder with the real
 SDK in [Poki Inspector](https://inspector.poki.dev) before submitting. Game-specific paths that
 the startup check does not exercise also need testing. Runtime services such as multiplayer and
-AI cannot be bundled; observed dependencies fail export with diagnostics. The source scan also
-reports `serviceRisks` for known game-data, leaderboard identity, and AI calls, even when they
-sit behind custom chapter menus. These are review hints, not reachability analysis or a complete
-network inventory. Keep the game's features until its creator chooses an integration approach.
+AI cannot be bundled. Online-only APIs (game data, leaderboard identity, runtime AI/voice,
+ghost racing and live connections) and known Bitmagic backend URLs in game sources now fail
+preflight before building, even if they sit behind custom chapter menus. Neither `--force`
+nor a playtest bypasses this requirement. The scan is conservative: runtime conditions do not
+exempt online code from the Poki source variant. Keep the game's features until its creator
+chooses an offline implementation; ordinary Bitmagic publishing is unaffected.
+
+Game-owned resource APIs such as `fetch`, XHR, workers and beacons require `--poki-playtest`.
+Exercise their flows, including score submission and later levels. Known backend responses are
+never vendored as assets, even if an endpoint ends in `.json`. Browser-blocked requests and
+caught network errors still fail validation. The normal game/SDK layout is preserved.
 
 Use `--poki-playtest playtest/poki.mjs` to extend every desktop/mobile discovery and extracted-ZIP
 check with actual gameplay actions. Create a self-contained ESM module using the game's controls,
@@ -1621,8 +1628,10 @@ export default async ({ frame, platform }) => {
 The callback receives the game iframe and `desktop`/`mobile` platform, has a 30-second timeout,
 and must finish in active gameplay for the pause/ad/resume check. A scenario failure fails export;
 external requests it triggers are subject to the same packaging policy. Its path and SHA-256
-are recorded in the manifest. Without a scenario, the output explicitly reports the limited
-startup coverage. Neither path certifies every gameplay branch or physical-phone behavior.
+are recorded in the manifest. Without game-owned resource calls, a scenario remains optional
+and the output explicitly reports limited startup coverage. The source scan and runtime checks
+are not a complete reachability analysis: neither path certifies every gameplay branch or
+physical-phone behavior.
 
 The result reports `status: "exported"`, `uploaded: false`, and `handoffPath`. For an authorized
 upload, follow the [official Poki CLI](https://github.com/poki/poki-cli), uploading only `payloadDir`

package/assets/blender-level/README.md

@@ -13,9 +13,11 @@ skill's step 1 tells an agent how to copy them into a project's `tools/blender-l
 |---|---|---|
 | `find_blender.py` | python3 | prints the Blender executable, or how to install one |
 | `bmlevel/` | Blender, or python3 for a dry run | the authoring vocabulary (`__init__.py`), the bpy-free maths and JSON writers (`core.py`), the Blender backend (`scene_bpy.py`) and the recording backend (`scene_null.py`) |
+| `bmedit/` | Blender (`colour.py`: python3) | edit GLBs and make props: `load(id)` from `build/inputs/<id>.glb`, `paint` / `recolor` / `replace_colour` by face, `box` / `cylinder` / `cone` / `sphere`, `join`, `scatter`, `export(id)` to `build/assets/<id>.glb` — the vocabulary the web Creator's `blender` tool runs on the Asset Forger (`game/agent-docs/blender.md`) |
+| `review_asset.py` | Blender | two three-quarter renders per GLB and a contact sheet: the review for props and edited assets |
 | `example_level.py` | either | a complete hut-and-courtyard level using every helper; the tests' fixture |
 | `audit.py` | Blender | ray-cast audit of the COLLIDERS: floor continuity, door and route clearance, sealed envelopes, z-fighting candidates |
-| `review.py` | Blender | deterministic review renders (overview, every door, every stair, every room) and a contact sheet; `--shot 'FROM -> TO'` aims a frame anywhere, `--only` renders just those, `--lighting game` swaps the review fill for the engine's interior preset and the level's own lamps |
+| `review.py` | Blender | deterministic review renders (overview, every door, every stair, every room) and a contact sheet; `--shot 'FROM -> TO'` aims a frame anywhere, `--only` renders just those, `--lighting game` swaps the review fill for the engine's interior preset and the level's own lamps, `--engine cycles` renders without an OpenGL context |
 | `sync_world.py` | python3 | carries the doors, spawn and `terrain.shape: 'none'` into `src/work/world.json` |
 | `tests/` | python3 | `python3 -m unittest discover -s tests` — no Blender needed; `cli`'s `pnpm test` runs it |
 

package/assets/blender-level/bmedit/__init__.py

@@ -0,0 +1,26 @@
+"""bmedit — edit a game's GLBs and make new low-poly props in a short Blender script.
+
+    from bmedit import load, palette, recolor, cone, box, join, export
+    ground = load('ground')                       # the game's asset, imported
+    palette(ground)                               # its face colours, most used first
+    recolor(ground, '#eef3f7', where=lambda p, n, c: n[1] > 0.6)   # snow on everything flat
+    export('ground', ground)                      # replaces the asset, same id
+
+    post = join([box('post', (0.2, 1.2, 0.2), color='#6b4a2f'),
+                 box('cap', (0.3, 0.1, 0.3), at=(0, 1.2, 0), color='#4a3220')], 'post')
+    export('fence-post', post)                    # a new asset, 1.3 m tall
+
+Positions, sizes and normals are in GAME coordinates — metres, Y up, +Z forward, yaw in radians
+about +Y — the same as bmlevel; the Blender axis flip happens inside. Colours are sRGB: '#rrggbb',
+0-255 or 0-1 triples. Painting is per face (flat low-poly look), stored as the mesh's COLOR_0.
+
+`load()` and `export()` are the only file access a script has. The host decides where they point
+(`configure()`): the Asset Forger's job directory, or the GDK project's `build/` folder.
+"""
+try:  # inside Blender
+    import bpy  # noqa: F401
+except ImportError:  # plain python3: only bmedit.colour is usable (its tests run here)
+    __all__: list[str] = []
+else:
+    from bmedit.blender import *  # noqa: F401,F403
+    from bmedit.blender import __all__, configure, exports  # noqa: F401

package/assets/blender-level/bmedit/blender.py

@@ -0,0 +1,469 @@
+"""The Blender half of bmedit: every builder, edit and the export. See __init__.py."""
+from __future__ import annotations
+
+import math
+import os
+import random
+import re
+from typing import Callable, Iterable, Optional, Sequence, Union
+
+import bmesh
+import bpy
+from mathutils import Matrix, Vector
+
+from bmedit.colour import Colour, distance, mix, to_hex, to_linear
+
+__all__ = [
+    'load', 'box', 'cylinder', 'cone', 'sphere', 'join', 'copy', 'move', 'remove', 'objects',
+    'paint', 'recolor', 'replace_colour', 'palette', 'decimate', 'scatter', 'bounds', 'describe',
+    'height_at', 'export', 'mix',
+]
+
+MAX_EXPORTS = 8
+_ID = re.compile(r'^[a-z0-9][a-z0-9_-]{0,63}$')
+_state: dict = {'inputs': os.path.abspath('build/inputs'), 'out': os.path.abspath('build/assets'), 'exports': []}
+
+Objects = Union[bpy.types.Object, Iterable[bpy.types.Object]]
+Vec = Sequence[float]
+
+
+def configure(inputs_dir: str, out_dir: str) -> None:
+    """Where load() reads and export() writes. Called by the host before the script runs."""
+    _state['inputs'] = os.path.abspath(inputs_dir)
+    _state['out'] = os.path.abspath(out_dir)
+    _state['exports'] = []
+
+
+def exports() -> list[dict]:
+    """What the script exported, for the host: [{id, file, targetHeight, triangles}]."""
+    return list(_state['exports'])
+
+
+# ---- coordinates ---------------------------------------------------------------------------
+
+def _to_b(p: Vec) -> Vector:
+    return Vector((p[0], -p[2], p[1]))
+
+
+def _to_game(v: Vec) -> tuple[float, float, float]:
+    return (v[0], v[2], -v[1])
+
+
+def _list(objs: Objects) -> list[bpy.types.Object]:
+    if isinstance(objs, bpy.types.Object):
+        return [objs]
+    return [o for o in objs if o.type == 'MESH']
+
+
+def objects() -> list[bpy.types.Object]:
+    """Every mesh object in the scene."""
+    return [o for o in bpy.context.scene.objects if o.type == 'MESH']
+
+
+# ---- load ----------------------------------------------------------------------------------
+
+def load(input_id: str) -> list[bpy.types.Object]:
+    """Import one of the job's input GLBs (the game asset with that id) and return its meshes.
+
+    Transforms are applied, so every vertex position is where the game draws it."""
+    if not _ID.match(input_id):
+        raise ValueError(f'bad input id {input_id!r}')
+    path = os.path.join(_state['inputs'], f'{input_id}.glb')
+    if not os.path.exists(path):
+        have = sorted(f[:-4] for f in os.listdir(_state['inputs'])) if os.path.isdir(_state['inputs']) else []
+        raise FileNotFoundError(f'no input {input_id!r}; this job has {have}')
+    before = set(bpy.data.objects)
+    bpy.ops.import_scene.gltf(filepath=path)
+    new = [o for o in bpy.data.objects if o not in before]
+    meshes = [o for o in new if o.type == 'MESH']
+    for o in new:
+        if o.type != 'MESH':
+            continue
+        # Bake parent + own transform into the mesh, so positions are world positions.
+        world = o.matrix_world.copy()
+        o.parent = None
+        o.data.transform(world)
+        o.matrix_world = Matrix.Identity(4)
+    for o in new:
+        if o.type != 'MESH':
+            bpy.data.objects.remove(o, do_unlink=True)
+    for o in meshes:
+        _face_up(o)
+    return meshes
+
+
+def _face_up(obj: bpy.types.Object) -> None:
+    """Flip a mesh whose faces mostly point DOWN. Some generated grounds are wound inside-out and
+    drawn double-sided; left as they are, `n[1] > 0.7` would find no flat ground to paint."""
+    mesh = obj.data
+    total = sum(p.area * p.normal.z for p in mesh.polygons)
+    area = sum(p.area for p in mesh.polygons)
+    if area > 0 and total / area < -0.3:
+        mesh.flip_normals()
+        print(f'[bmedit] {obj.name}: faces pointed down; flipped')
+
+
+# ---- primitives ----------------------------------------------------------------------------
+
+def _vertex_material() -> bpy.types.Material:
+    mat = bpy.data.materials.get('bmedit_vertex')
+    if mat is None:
+        mat = bpy.data.materials.new('bmedit_vertex')
+        mat.use_nodes = True
+        nodes = mat.node_tree.nodes
+        bsdf = nodes['Principled BSDF']
+        bsdf.inputs['Roughness'].default_value = 1.0
+        attr = nodes.new('ShaderNodeVertexColor')
+        attr.layer_name = 'Col'
+        mat.node_tree.links.new(attr.outputs['Color'], bsdf.inputs['Base Color'])
+    return mat
+
+
+def _finish(name: str, bm: bmesh.types.BMesh, color: Colour, at: Vec, yaw: float) -> bpy.types.Object:
+    mesh = bpy.data.meshes.new(name)
+    bm.to_mesh(mesh)
+    bm.free()
+    for poly in mesh.polygons:
+        poly.use_smooth = False
+    mesh.materials.append(_vertex_material())
+    obj = bpy.data.objects.new(name, mesh)
+    bpy.context.scene.collection.objects.link(obj)
+    _colour_layer(obj)
+    _fill(obj, to_linear(color))
+    # Straight into the vertices: the object keeps an identity transform, so every position a
+    # later call reads (bounds, paint, scatter) is already where the game draws it.
+    mesh.transform(Matrix.Translation(_to_b(at)) @ Matrix.Rotation(yaw, 4, 'Z'))
+    return obj
+
+
+def box(name: str, size: Vec, at: Vec = (0, 0, 0), color: Colour = '#999999', yaw: float = 0.0) -> bpy.types.Object:
+    """A box `size` = (width x, height y, depth z) whose BOTTOM centre sits at `at`."""
+    bm = bmesh.new()
+    bmesh.ops.create_cube(bm, size=1.0)
+    bmesh.ops.scale(bm, vec=Vector((size[0], size[2], size[1])), verts=bm.verts)
+    bmesh.ops.translate(bm, vec=Vector((0, 0, size[1] / 2)), verts=bm.verts)
+    return _finish(name, bm, color, at, yaw)
+
+
+def cylinder(name: str, radius: float, height: float, at: Vec = (0, 0, 0), color: Colour = '#999999',
+             segments: int = 8, top_radius: Optional[float] = None, yaw: float = 0.0) -> bpy.types.Object:
+    """An upright cylinder (or frustum, with top_radius) standing on `at`."""
+    bm = bmesh.new()
+    bmesh.ops.create_cone(bm, cap_ends=True, cap_tris=False, segments=max(3, segments),
+                          radius1=radius, radius2=radius if top_radius is None else top_radius, depth=height)
+    bmesh.ops.translate(bm, vec=Vector((0, 0, height / 2)), verts=bm.verts)
+    return _finish(name, bm, color, at, yaw)
+
+
+def cone(name: str, radius: float, height: float, at: Vec = (0, 0, 0), color: Colour = '#999999',
+         segments: int = 8, yaw: float = 0.0) -> bpy.types.Object:
+    """An upright cone standing on `at` — a pine layer, a roof tip, a spike."""
+    return cylinder(name, radius, height, at, color, segments, top_radius=0.0, yaw=yaw)
+
+
+def sphere(name: str, radius: float, at: Vec = (0, 0, 0), color: Colour = '#999999', detail: int = 1) -> bpy.types.Object:
+    """A faceted ball centred on `at` (detail 1 = 80 faces, 2 = 320)."""
+    bm = bmesh.new()
+    bmesh.ops.create_icosphere(bm, subdivisions=max(1, min(3, detail)), radius=radius)
+    return _finish(name, bm, color, at, 0.0)
+
+
+# ---- object edits --------------------------------------------------------------------------
+
+def join(objs: Objects, name: str) -> bpy.types.Object:
+    """Merge meshes into one object (one draw call in the game)."""
+    items = _list(objs)
+    if not items:
+        raise ValueError('join() needs at least one mesh')
+    for o in items:
+        _colour_layer(o)
+    with bpy.context.temp_override(active_object=items[0], selected_editable_objects=items, selected_objects=items):
+        bpy.ops.object.join()
+    items[0].name = name
+    items[0].data.name = name
+    return items[0]
+
+
+def copy(obj: bpy.types.Object, at: Optional[Vec] = None, yaw: float = 0.0, scale: float = 1.0,
+         name: Optional[str] = None) -> bpy.types.Object:
+    """A copy of `obj`, rotated by `yaw` and scaled about its bottom centre, then moved so that
+    bottom centre sits at `at` (default: where it was)."""
+    dup = obj.copy()
+    dup.data = obj.data.copy()
+    dup.name = name or f'{obj.name}.copy'
+    bpy.context.scene.collection.objects.link(dup)
+    move(dup, at=at, yaw=yaw, scale=scale)
+    return dup
+
+
+def move(obj: bpy.types.Object, at: Optional[Vec] = None, yaw: float = 0.0, scale: float = 1.0) -> None:
+    """Rotate/scale `obj` about its bottom centre, then put that point at `at` (game coords)."""
+    lo, hi = bounds(obj)
+    base = Vector(_to_b(((lo[0] + hi[0]) / 2, lo[1], (lo[2] + hi[2]) / 2)))
+    target = _to_b(at) if at is not None else base
+    m = Matrix.Translation(target) @ Matrix.Rotation(yaw, 4, 'Z') @ Matrix.Scale(scale, 4) @ Matrix.Translation(-base)
+    obj.data.transform(m)
+
+
+def remove(objs: Objects) -> None:
+    for o in _list(objs):
+        bpy.data.objects.remove(o, do_unlink=True)
+
+
+def decimate(objs: Objects, ratio: float) -> None:
+    """Keep about `ratio` (0..1) of each mesh's triangles — cheaper, chunkier."""
+    for o in _list(objs):
+        mod = o.modifiers.new('decimate', 'DECIMATE')
+        mod.ratio = max(0.01, min(1.0, ratio))
+        with bpy.context.temp_override(object=o, active_object=o):
+            bpy.ops.object.modifier_apply(modifier=mod.name)
+
+
+# ---- colour --------------------------------------------------------------------------------
+
+def _colour_layer(obj: bpy.types.Object):
+    """The object's face-corner colour attribute — an imported GLB's own COLOR_0 (byte or float:
+    both read and write linear `.color`), else a new one filled from its materials' colours, with
+    the materials switched to show it (white base, colour from the attribute)."""
+    mesh = obj.data
+    attrs = mesh.color_attributes
+    layer = attrs.active_color
+    if layer is not None and layer.domain == 'CORNER':
+        return layer
+    old = layer
+    new = attrs.new('Col', 'FLOAT_COLOR', 'CORNER')
+    base = [_material_colour(m) for m in mesh.materials] or [(0.8, 0.8, 0.8, 1.0)]
+    for poly in mesh.polygons:
+        for li in poly.loop_indices:
+            if old is not None:  # a POINT-domain layer: each corner takes its vertex's colour
+                new.data[li].color = old.data[mesh.loops[li].vertex_index].color
+            else:
+                new.data[li].color = base[min(poly.material_index, len(base) - 1)]
+    attrs.active_color = new
+    # The glTF exporter's 'ACTIVE' mode writes the RENDER colour attribute.
+    attrs.default_color_name = new.name
+    for mat in mesh.materials:
+        _show_vertex_colour(mat, new.name)
+    return new
+
+
+def _material_colour(mat) -> tuple[float, float, float, float]:
+    if mat is None:
+        return (0.8, 0.8, 0.8, 1.0)
+    if mat.use_nodes and 'Principled BSDF' in mat.node_tree.nodes:
+        c = mat.node_tree.nodes['Principled BSDF'].inputs['Base Color'].default_value
+        return (c[0], c[1], c[2], 1.0)
+    c = mat.diffuse_color
+    return (c[0], c[1], c[2], 1.0)
+
+
+def _show_vertex_colour(mat, layer_name: str) -> None:
+    """Base colour from the attribute, unless an image texture drives it (then the attribute tints)."""
+    if mat is None or not mat.use_nodes or 'Principled BSDF' not in mat.node_tree.nodes:
+        return
+    for node in mat.node_tree.nodes:
+        if node.bl_idname == 'ShaderNodeVertexColor':
+            node.layer_name = layer_name
+            return
+    bsdf = mat.node_tree.nodes['Principled BSDF']
+    base = bsdf.inputs['Base Color']
+    if base.is_linked:
+        return
+    base.default_value = (1.0, 1.0, 1.0, 1.0)
+    attr = mat.node_tree.nodes.new('ShaderNodeVertexColor')
+    attr.layer_name = layer_name
+    mat.node_tree.links.new(attr.outputs['Color'], base)
+
+
+def _fill(obj: bpy.types.Object, rgba) -> None:
+    layer = _colour_layer(obj)
+    for d in layer.data:
+        d.color = rgba
+
+
+def _faces(obj: bpy.types.Object):
+    """(polygon, game centre, game normal, current sRGB hex) per face."""
+    layer = _colour_layer(obj)
+    mesh = obj.data
+    # The shading normals (an imported GLB's own NORMAL data), not the winding: generated grounds
+    # are often wound the other way and drawn double-sided, so poly.normal can point down.
+    corners = mesh.corner_normals
+    for poly in mesh.polygons:
+        c = layer.data[poly.loop_indices[0]].color
+        n = Vector((0.0, 0.0, 0.0))
+        for li in poly.loop_indices:
+            n += corners[li].vector
+        n = n.normalized() if n.length > 1e-9 else poly.normal
+        yield poly, _to_game(poly.center), _to_game(n), to_hex(c), layer
+
+
+def paint(objs: Objects, fn: Callable[[tuple, tuple, str], Optional[Colour]]) -> int:
+    """Call fn(position, normal, current_hex) for every face; a colour it returns repaints that
+    face, None keeps it. Position and normal are game coords (normal[1] > 0.7: roughly flat
+    ground; < 0.3: steep or a wall). Returns the number of faces repainted."""
+    changed = 0
+    for o in _list(objs):
+        for poly, pos, normal, current, layer in _faces(o):
+            out = fn(pos, normal, current)
+            if out is None:
+                continue
+            rgba = to_linear(out)
+            for li in poly.loop_indices:
+                layer.data[li].color = rgba
+            changed += 1
+    return changed
+
+
+def recolor(objs: Objects, colour: Colour, where: Optional[Callable[[tuple, tuple, str], bool]] = None) -> int:
+    """Paint every face (or those `where(position, normal, current_hex)` accepts) one colour."""
+    return paint(objs, lambda p, n, c: colour if where is None or where(p, n, c) else None)
+
+
+def replace_colour(objs: Objects, mapping: dict, tolerance: float = 0.08) -> int:
+    """Swap colours: {'#3f8f3a': '#eef3f7', ...}. A face within `tolerance` of a key takes its
+    value — the way to turn 'the green of the leaves' white without touching the bark."""
+    keys = list(mapping.items())
+
+    def swap(_p, _n, current):
+        best = min(keys, key=lambda kv: distance(kv[0], current))
+        return best[1] if distance(best[0], current) <= tolerance else None
+    return paint(objs, swap)
+
+
+def palette(objs: Objects, top: int = 12) -> list[tuple[str, int]]:
+    """The face colours in use, most common first, as [(hex, faces)] — printed too, so the build
+    log shows what an edit has to work with. Near-identical colours are merged."""
+    counts: dict[str, int] = {}
+    for o in _list(objs):
+        for _poly, _p, _n, current, _l in _faces(o):
+            for known in counts:
+                if distance(known, current) < 0.03:
+                    counts[known] += 1
+                    break
+            else:
+                counts[current] = 1
+    ranked = sorted(counts.items(), key=lambda kv: -kv[1])[:top]
+    print('[bmedit] palette: ' + ', '.join(f'{h} x{n}' for h, n in ranked))
+    return ranked
+
+
+# ---- placement -----------------------------------------------------------------------------
+
+def bounds(objs: Objects) -> tuple[tuple[float, float, float], tuple[float, float, float]]:
+    """(min, max) corners in game coords over every vertex."""
+    lo = [math.inf] * 3
+    hi = [-math.inf] * 3
+    for o in _list(objs):
+        for v in o.data.vertices:
+            g = _to_game(o.matrix_world @ v.co)
+            for i in range(3):
+                lo[i] = min(lo[i], g[i])
+                hi[i] = max(hi[i], g[i])
+    if lo[0] == math.inf:
+        return (0.0, 0.0, 0.0), (0.0, 0.0, 0.0)
+    return (lo[0], lo[1], lo[2]), (hi[0], hi[1], hi[2])
+
+
+def height_at(objs: Objects, x: float, z: float) -> Optional[float]:
+    """The top surface's height at game (x, z), or None off the mesh."""
+    best = None
+    for o in _list(objs):
+        origin = _to_b((x, 1e4, z))
+        hit, loc, _n, _i = o.ray_cast(o.matrix_world.inverted() @ origin, Vector((0, 0, -1)))
+        if hit:
+            y = _to_game(o.matrix_world @ loc)[1]
+            best = y if best is None else max(best, y)
+    return best
+
+
+def scatter(proto: bpy.types.Object, count: int, on: Optional[Objects] = None,
+            area: Sequence[float] = (0.0, 0.0, 20.0), seed: int = 1, min_spacing: float = 2.0,
+            scale: Sequence[float] = (0.8, 1.2), avoid: Sequence[Sequence[float]] = (),
+            max_slope: float = 0.5) -> list[bpy.types.Object]:
+    """Place up to `count` copies of `proto` at random inside the circle `area` = (x, z, radius),
+    random yaw and scale, standing on `on`'s surface (flat enough: normal-y >= 1 - max_slope).
+    `avoid` = [(x, z, radius), ...] keeps spots clear (the spawn, a path). Returns the copies."""
+    rng = random.Random(seed)
+    placed: list[tuple[float, float]] = []
+    out = []
+    ground = _list(on) if on is not None else []
+    for _ in range(count * 30):
+        if len(out) >= count:
+            break
+        a = rng.uniform(0, math.tau)
+        r = area[2] * math.sqrt(rng.random())
+        x, z = area[0] + r * math.cos(a), area[1] + r * math.sin(a)
+        if any((x - px) ** 2 + (z - pz) ** 2 < min_spacing ** 2 for px, pz in placed):
+            continue
+        if any((x - ax) ** 2 + (z - az) ** 2 < ar ** 2 for ax, az, ar in avoid):
+            continue
+        y = 0.0
+        if ground:
+            hit = _surface(ground, x, z)
+            if hit is None or hit[1] < 1.0 - max_slope:
+                continue
+            y = hit[0]
+        out.append(copy(proto, at=(x, y, z), yaw=rng.uniform(0, math.tau), scale=rng.uniform(*scale),
+                        name=f'{proto.name}.{len(out)}'))
+        placed.append((x, z))
+    return out
+
+
+def _surface(objs: list, x: float, z: float) -> Optional[tuple[float, float]]:
+    best = None
+    for o in objs:
+        origin = o.matrix_world.inverted() @ _to_b((x, 1e4, z))
+        hit, loc, normal, _i = o.ray_cast(origin, Vector((0, 0, -1)))
+        if hit:
+            y = _to_game(o.matrix_world @ loc)[1]
+            if best is None or y > best[0]:
+                best = (y, _to_game(normal)[1])
+    return best
+
+
+def describe(objs: Objects) -> None:
+    """Print name, triangle count and size of each mesh — cheap orientation for an edit."""
+    for o in _list(objs):
+        lo, hi = bounds(o)
+        tris = sum(len(p.vertices) - 2 for p in o.data.polygons)
+        size = tuple(round(hi[i] - lo[i], 2) for i in range(3))
+        print(f'[bmedit] {o.name}: {tris} tris, size {size}, min {tuple(round(v, 2) for v in lo)}')
+
+
+# ---- export --------------------------------------------------------------------------------
+
+def export(asset_id: str, objs: Optional[Objects] = None) -> dict:
+    """Write `objs` (default: every mesh in the scene) as the game asset `asset_id`. An id the game
+    already has REPLACES that asset everywhere it is placed; a new id adds one, sized to the
+    meshes' real height. Returns {id, targetHeight, triangles}."""
+    if not _ID.match(asset_id):
+        raise ValueError(f'asset id {asset_id!r}: use lowercase letters, digits, - and _')
+    if any(e['id'] == asset_id for e in _state['exports']):
+        raise ValueError(f'{asset_id!r} was already exported in this script')
+    if len(_state['exports']) >= MAX_EXPORTS:
+        raise ValueError(f'at most {MAX_EXPORTS} exports per script')
+    items = _list(objs) if objs is not None else objects()
+    if not items:
+        raise ValueError('nothing to export')
+    for o in items:
+        _colour_layer(o)
+    lo, hi = bounds(items)
+    os.makedirs(_state['out'], exist_ok=True)
+    path = os.path.join(_state['out'], f'{asset_id}.glb')
+    with bpy.context.temp_override(selected_objects=items, selected_editable_objects=items):
+        bpy.ops.object.select_all(action='DESELECT')
+        for o in items:
+            o.select_set(True)
+        bpy.ops.export_scene.gltf(
+            filepath=path, export_format='GLB', use_selection=True, export_apply=True, export_yup=True,
+            export_normals=True, export_vertex_color='ACTIVE', export_lights=False, export_cameras=False,
+        )
+    record = {
+        'id': asset_id,
+        'file': f'{asset_id}.glb',
+        'targetHeight': round(max(0.01, hi[1] - lo[1]), 3),
+        'triangles': sum(sum(len(p.vertices) - 2 for p in o.data.polygons) for o in items),
+    }
+    _state['exports'].append(record)
+    print(f'[bmedit] exported {asset_id}: {record["triangles"]} tris, {record["targetHeight"]} m tall')
+    return record

package/assets/blender-level/bmedit/colour.py

@@ -0,0 +1,61 @@
+"""Colour maths for bmedit, free of bpy so plain python3 tests cover it.
+
+Scripts speak sRGB — the numbers a colour picker shows, as `'#d8e4ea'`, `(216, 228, 234)` or
+`(0.85, 0.89, 0.92)`. Blender's float colour attributes and glTF's COLOR_0 are LINEAR, so every
+value is converted once on the way in and back on the way out. Storing sRGB numbers as linear is
+what turned early forged levels pastel.
+"""
+from __future__ import annotations
+
+from typing import Sequence, Union
+
+Colour = Union[str, Sequence[float]]
+
+
+def srgb_to_linear(c: float) -> float:
+    return c / 12.92 if c <= 0.04045 else ((c + 0.055) / 1.055) ** 2.4
+
+
+def linear_to_srgb(c: float) -> float:
+    c = max(0.0, min(1.0, c))
+    return c * 12.92 if c <= 0.0031308 else 1.055 * c ** (1 / 2.4) - 0.055
+
+
+def parse_srgb(colour: Colour) -> tuple[float, float, float]:
+    """'#rrggbb', 0-255 ints or 0-1 floats → sRGB floats in 0..1."""
+    if isinstance(colour, str):
+        h = colour.lstrip('#')
+        if len(h) == 3:
+            h = ''.join(ch * 2 for ch in h)
+        if len(h) != 6:
+            raise ValueError(f'colour {colour!r} is not #rgb or #rrggbb')
+        return (int(h[0:2], 16) / 255, int(h[2:4], 16) / 255, int(h[4:6], 16) / 255)
+    values = [float(v) for v in colour][:3]
+    if len(values) != 3:
+        raise ValueError(f'colour {colour!r} needs three channels')
+    if any(v > 1.0 for v in values):
+        values = [v / 255 for v in values]
+    return (values[0], values[1], values[2])
+
+
+def to_linear(colour: Colour) -> tuple[float, float, float, float]:
+    r, g, b = parse_srgb(colour)
+    return (srgb_to_linear(r), srgb_to_linear(g), srgb_to_linear(b), 1.0)
+
+
+def to_hex(linear: Sequence[float]) -> str:
+    """A stored linear colour as the sRGB hex a script would write."""
+    return '#' + ''.join(f'{round(linear_to_srgb(c) * 255):02x}' for c in linear[:3])
+
+
+def distance(a: Colour, b: Colour) -> float:
+    """Distance between two sRGB colours, 0..~1.7; under 0.1 reads as 'the same colour'."""
+    pa, pb = parse_srgb(a), parse_srgb(b)
+    return sum((x - y) ** 2 for x, y in zip(pa, pb)) ** 0.5
+
+
+def mix(a: Colour, b: Colour, t: float) -> tuple[float, float, float]:
+    """sRGB blend of two colours; t=0 is a, t=1 is b."""
+    pa, pb = parse_srgb(a), parse_srgb(b)
+    t = max(0.0, min(1.0, t))
+    return (pa[0] + (pb[0] - pa[0]) * t, pa[1] + (pb[1] - pa[1]) * t, pa[2] + (pb[2] - pa[2]) * t)