@bitmagic/cli 0.1.71-dev.4 → 0.1.71

package/assets/blender-level/README.md

@@ -13,7 +13,7 @@ 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`) |
+| `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`, `turn`, `scatter`, `export(id)` to `build/assets/<id>.glb`; smart props (moving parts the engine animates) with `part()`, `anchor()` and `export(..., smart=)` — 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 |

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

@@ -16,7 +16,7 @@ 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',
+    'height_at', 'turn', 'part', 'anchor', 'export', 'mix',
 ]
 
 MAX_EXPORTS = 8
@@ -205,6 +205,23 @@ def move(obj: bpy.types.Object, at: Optional[Vec] = None, yaw: float = 0.0, scal
     obj.data.transform(m)
 
 
+def turn(objs: Objects, angle: float, axis: Vec = (0, 1, 0), about: Optional[Vec] = None) -> None:
+    """Rotate by `angle` radians about `axis` (game coords, right-handed: about +Z, +Y turns toward
+    -X) through the point `about` (default: the objects' box centre). A spoke is a box standing on
+    the hub turned about the hub; a leaning leg is turned about its foot."""
+    items = _list(objs)
+    if about is None:
+        lo, hi = bounds(items)
+        about = tuple((lo[k] + hi[k]) / 2 for k in range(3))
+    pivot = _to_b(about)
+    a = _to_b(axis)
+    m = Matrix.Translation(pivot) @ Matrix.Rotation(angle, 4, Vector(a).normalized()) @ Matrix.Translation(-pivot)
+    for o in items:
+        o.data.transform(m)
+        for child in o.children:
+            child.location = m @ child.location
+
+
 def remove(objs: Objects) -> None:
     for o in _list(objs):
         bpy.data.objects.remove(o, do_unlink=True)
@@ -432,10 +449,155 @@ def describe(objs: Objects) -> None:
 
 # ---- export --------------------------------------------------------------------------------
 
-def export(asset_id: str, objs: Optional[Objects] = None) -> dict:
+def _coplanar_overlaps(items: list, limit: int = 5) -> tuple[int, list[str]]:
+    """Faces that lie in the same plane, facing the same way, and overlap: they z-fight (flicker
+    between their colours) in the game. Typical cause: trim laid flush on a surface — a rim whose
+    top cap sits at the platform's height, a stripe on a wall. Returns (count, examples)."""
+    faces = []
+    for o in items:
+        layer = o.data.color_attributes.active_color
+        for poly in o.data.polygons:
+            n = poly.normal
+            if n.length < 1e-6:
+                continue
+            pts = [o.data.vertices[v].co.copy() for v in poly.vertices]
+            colour = to_hex(layer.data[poly.loop_indices[0]].color) if layer and layer.domain == 'CORNER' else '?'
+            faces.append((n.normalized(), n.normalized().dot(pts[0]), pts, poly.center.copy(), poly.area, colour))
+    buckets: dict = {}
+    for i, (n, d, _p, _c, _a, _col) in enumerate(faces):
+        key = (round(n.x, 2), round(n.y, 2), round(n.z, 2), round(d * 200))   # same direction, within ~5 mm
+        buckets.setdefault(key, []).append(i)
+
+    def inside(point, pts, n) -> bool:
+        # Convex polygon test in its own plane: the point is on the inner side of every edge.
+        sign = 0
+        for k in range(len(pts)):
+            edge = pts[(k + 1) % len(pts)] - pts[k]
+            side = n.dot(edge.cross(point - pts[k]))
+            if abs(side) < 1e-7:
+                continue
+            if sign == 0:
+                sign = 1 if side > 0 else -1
+            elif (side > 0) != (sign > 0):
+                return False
+        return True
+
+    count, examples = 0, []
+    for group in buckets.values():
+        if len(group) < 2:
+            continue
+        for x in range(len(group)):
+            for y in range(x + 1, len(group)):
+                fa, fb = faces[group[x]], faces[group[y]]
+                small, big = (fa, fb) if fa[4] <= fb[4] else (fb, fa)
+                # Two faces of one colour flicker between identical pixels: invisible, not reported.
+                if small[5] == big[5] or not inside(small[3], big[2], big[0]):
+                    continue
+                count += 1
+                if len(examples) < limit:
+                    g = _to_game(small[3])
+                    examples.append(f'({g[0]:.2f}, {g[1]:.2f}, {g[2]:.2f}) {small[5]} vs {big[5]}')
+    return count, examples
+
+
+PART_PREFIX = 'BM_part_'
+_PART_NAME = re.compile(r'^[A-Za-z][A-Za-z0-9_]*$')
+MOTIONS = ('spin', 'upright', 'pendulum', 'none')
+
+
+def part(obj: bpy.types.Object, name: str) -> bpy.types.Object:
+    """Mark `obj` as the moving part `name` of a smart prop (export it with `smart=`). A part
+    is one object: join its pieces first. Names: letters, digits and _, starting with a letter."""
+    if not _PART_NAME.match(name):
+        raise ValueError(f'part name {name!r}: letters, digits and _, starting with a letter')
+    obj.name = f'{PART_PREFIX}{name}'
+    obj.data.name = obj.name
+    return obj
+
+
+ANCHOR_PREFIX = 'BM_anchor_'
+
+
+def anchor(obj: bpy.types.Object, name: str, at: Vec) -> bpy.types.Object:
+    """A named point game code will want: a door, an entrance, a seat, a cabin floor. `at` is in
+    game coordinates at rest. On a part (after part()) it rides with the part and code finds it as
+    `smart.pivotOf(id, 'cabin_3').getObjectByName('BM_anchor_floor')` — every part may reuse the
+    same names. On any other exported object it stays put, found on the placed object:
+    `getObjectIdService().getObjectById(id).getObjectByName('BM_anchor_door')` — so those names
+    must be unique within the prop."""
+    if not _PART_NAME.match(name):
+        raise ValueError(f'anchor name {name!r}: letters, digits and _, starting with a letter')
+    owner = obj.name[len(PART_PREFIX):] if obj.name.startswith(PART_PREFIX) else re.sub(r'[^A-Za-z0-9_]', '_', obj.name)
+    empty = bpy.data.objects.new(f'{ANCHOR_PREFIX}{owner}__{name}', None)
+    bpy.context.scene.collection.objects.link(empty)
+    empty.parent = obj  # the part keeps an identity transform, so `at` is also its local position
+    empty.location = _to_b(at)
+    return empty
+
+
+def _vec(value, what: str) -> dict:
+    if not (isinstance(value, (list, tuple)) and len(value) == 3):
+        raise ValueError(f'{what} must be (x, y, z)')
+    return {'x': float(value[0]), 'y': float(value[1]), 'z': float(value[2])}
+
+
+def _smart_declaration(smart: dict, items: list, lo, hi) -> tuple[dict, list[dict]]:
+    """Validate `smart` against the exported objects; return the GLB's bmSmartObject extras and
+    the asset-record light emitters (offsets in the asset frame: bottom-centre origin)."""
+    names = {o.name[len(PART_PREFIX):]: o for o in items if o.name.startswith(PART_PREFIX)}
+    parts = []
+    for p in smart.get('parts', []):
+        name = p.get('name')
+        if name not in names:
+            raise ValueError(f'smart part {name!r} has no object: call part(obj, {name!r}) on one of the exported objects')
+        motion = dict(p.get('motion') or {})
+        if motion.get('kind') not in MOTIONS:
+            raise ValueError(f'smart part {name!r}: motion kind must be one of {MOTIONS}')
+        if 'axis' in motion:
+            motion['axis'] = [float(v) for v in motion['axis']]
+        entry = {'name': name, 'motion': motion}
+        if p.get('parent'):
+            if p['parent'] not in names:
+                raise ValueError(f'smart part {name!r}: parent {p["parent"]!r} is not a part')
+            entry['parent'] = p['parent']
+        if p.get('pivot') is not None:
+            entry['pivot'] = _vec(p['pivot'], f'smart part {name!r} pivot')
+        parts.append(entry)
+    origin = ((lo[0] + hi[0]) / 2, lo[1], (lo[2] + hi[2]) / 2)
+    lights = []
+    for i, l in enumerate(smart.get('lights', [])):
+        if 'color' not in l:
+            raise ValueError('a smart light needs a color')
+        where = l.get('position')
+        if where is None:
+            if l.get('part') not in names:
+                raise ValueError('a smart light needs a position, or a part to sit at the centre of')
+            plo, phi = bounds(names[l['part']])
+            where = tuple((plo[k] + phi[k]) / 2 for k in range(3))
+        offset = {'x': where[0] - origin[0], 'y': where[1] - origin[1], 'z': where[2] - origin[2]}
+        emitter = {'color': to_hex(to_linear(l['color'])), 'offset': offset}
+        for key in ('intensity', 'distance'):
+            if key in l:
+                emitter[key] = float(l[key])
+        if l.get('part'):
+            if l['part'] not in names:
+                raise ValueError(f'smart light: part {l["part"]!r} is not a part')
+            emitter['part'] = l['part']
+        lights.append(emitter)
+    return {'parts': parts}, lights
+
+
+def export(asset_id: str, objs: Optional[Objects] = None, smart: Optional[dict] = 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}."""
+    meshes' real height. Returns {id, targetHeight, triangles}.
+
+    `smart` makes it a SMART OBJECT the engine animates with no game code:
+        {'parts': [{'name': 'wheel', 'motion': {'kind': 'spin', 'axis': (0, 0, 1), 'rpm': 3}},
+                   {'name': 'cabin_1', 'parent': 'wheel', 'motion': {'kind': 'upright'}}],
+         'lights': [{'color': '#ffd27a', 'part': 'cabin_1', 'intensity': 4}]}
+    Every part is an exported object marked with part(obj, name). Pivots default to the part's
+    box centre (the top centre for upright / pendulum); give 'pivot': (x, y, z) to override."""
     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']):
@@ -448,22 +610,43 @@ def export(asset_id: str, objs: Optional[Objects] = None) -> dict:
     for o in items:
         _colour_layer(o)
     lo, hi = bounds(items)
+    overlaps, where = _coplanar_overlaps(items)
+    if overlaps:
+        print(f'[bmedit] WARNING {asset_id}: {overlaps} overlapping coplanar face pair(s) will FLICKER in the game '
+              f'(z-fighting), e.g. at {"; ".join(where)}. Lift the upper surface by at least 1 cm, or make '
+              f'the trim not cover the surface under it.')
+    extras, lights = _smart_declaration(smart, items, lo, hi) if smart else (None, [])
+    scene = bpy.context.scene
+    if extras is not None:
+        scene['bmSmartObject'] = extras  # scene custom properties are the GLB's scene extras
     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,
-        )
+    try:
+        anchors = [c for o in items for c in o.children if c.name.startswith(ANCHOR_PREFIX)]
+        chosen = items + anchors
+        with bpy.context.temp_override(selected_objects=chosen, selected_editable_objects=chosen):
+            bpy.ops.object.select_all(action='DESELECT')
+            for o in chosen:
+                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,
+                export_extras=extras is not None,
+            )
+    finally:
+        if 'bmSmartObject' in scene:
+            del scene['bmSmartObject']
     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),
     }
+    if extras is not None:
+        record['smartParts'] = [p['name'] for p in extras['parts']]
+    if lights:
+        record['lights'] = lights
     _state['exports'].append(record)
-    print(f'[bmedit] exported {asset_id}: {record["triangles"]} tris, {record["targetHeight"]} m tall')
+    moving = f', smart: {", ".join(record["smartParts"])}' if extras else ''
+    print(f'[bmedit] exported {asset_id}: {record["triangles"]} tris, {record["targetHeight"]} m tall{moving}')
     return record

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitmagic/cli",
-  "version": "0.1.71-dev.4",
+  "version": "0.1.71",
   "description": "Build Bitmagic games from your own agent tool",
   "license": "SEE LICENSE IN LICENSE.md",
   "author": "Bitmagic Oy",
@@ -25,9 +25,9 @@
     "playwright-core": "^1.59.1",
     "tar": "^7.4.3",
     "ws": "^8.21.3",
-    "@bitmagic/animation-forger": "0.1.26-dev.4",
-    "@bitmagic/asset-core": "0.2.26-dev.4",
-    "@bitmagic/world-forger": "0.1.31-dev.4"
+    "@bitmagic/asset-core": "0.2.26",
+    "@bitmagic/animation-forger": "0.1.26",
+    "@bitmagic/world-forger": "0.1.31"
   },
   "devDependencies": {
     "@eslint/js": "^9.38.0",