@funpixel/tools 0.0.0-stage → 0.1.1

package/bench/handlers/build_level.py

@@ -0,0 +1,395 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""`build_level` — a low-poly 3D level from a declarative spec (plan g4).
+
+The spec (funpixel-core `level_spec`, checked there and again in
+`level_check`) declares rooms and yards on a grid, walls with openings, ramps,
+stairs, platforms, props from a fixed kit and the named points a game reads.
+This handler builds exactly that and nothing else — no caller code runs.
+
+What comes out, as one GLB (+Y up, metres, the spec's numbers unchanged):
+
+    level_<name>              root; extras funpixel_level, funpixel_shading
+      art/                    area_<n>, wall_<n>, ramp_<n>, platform_<n>, prop_<n>
+      colliders/              col_<piece>_<i>: one convex box or wedge each
+      markers/                marker_<kind>_<name>: empties, extras funpixel_marker
+
+One material per palette ROLE (`mat_floor`, `mat_wall`, … `mat_ink`), shared
+by every piece: the level has one look because it has one palette. The ink
+outline is an inverted hull (`level_geo.add_ink_hull`), so it draws in any
+glTF viewer with back faces culled.
+
+Colliders are separate from art on purpose: a game raycasts and collides
+against simple convex shapes, never against a tree's leaves, and a stair's
+collider is a smooth wedge a character controller can climb.
+
+The audit is measured on the COLLIDERS, the shapes the game will collide with:
+a spawn, exit or checkpoint must have one under it and must not be inside one,
+and no prop collider may block a door.
+"""
+import json
+import math
+import os
+
+import bpy
+from mathutils import Matrix
+
+from . import level_check, level_geo, level_proof, level_props, scene
+from .level_geo import Piece
+
+# The spec's defaults (funpixel-core `level_spec`), for a spec that reaches
+# the bench without the service having filled them (local mode). Pinned
+# against the Rust ones by `level_defaults_match_the_spec`.
+DEFAULT_PALETTE = {
+    "floor": "#b08a62", "wall": "#e8dcc4", "trim": "#5a4332", "ground": "#6f9a4a",
+    "path": "#c9b48a", "water": "#3f8fc4", "prop": "#8a5a3b", "foliage": "#3f7d3a",
+    "accent": "#d9563a", "ink": "#1b1622",
+}
+ROLES = list(DEFAULT_PALETTE)
+WALL_T = 0.2
+FLOOR_T = 0.2
+DOOR_H = 2.2
+
+
+def _linear(hex_colour):
+    """sRGB `#rrggbb` to the linear RGBA a Principled BSDF (and glTF) holds."""
+    out = []
+    for i in (1, 3, 5):
+        c = int(hex_colour[i:i + 2], 16) / 255.0
+        out.append(c / 12.92 if c <= 0.04045 else ((c + 0.055) / 1.055) ** 2.4)
+    return (*out, 1.0)
+
+
+def _materials(style):
+    palette = dict(DEFAULT_PALETTE, **(style.get("palette") or {}))
+    shading = style.get("shading") or "toon"
+    mats = {}
+    for role in ROLES:
+        m = bpy.data.materials.new("mat_" + role)
+        m.use_nodes = True
+        bsdf = m.node_tree.nodes.get("Principled BSDF")
+        bsdf.inputs["Base Color"].default_value = _linear(palette[role])
+        bsdf.inputs["Metallic"].default_value = 0.0
+        rough = 0.55 if shading == "lit" else 0.95
+        bsdf.inputs["Roughness"].default_value = 0.15 if role == "water" else rough
+        # Single-sided: the exporter writes doubleSided false, and the ink hull
+        # only reads as an outline when its front faces are culled.
+        m.use_backface_culling = True
+        m["funpixel_shading"] = shading
+        m["funpixel_role"] = role
+        mats[role] = m
+    return mats
+
+
+def _empty(name, parent=None, location=(0.0, 0.0, 0.0)):
+    obj = bpy.data.objects.new(name, None)
+    obj.location = location
+    bpy.context.collection.objects.link(obj)
+    obj.parent = parent
+    return obj
+
+
+def _spans(length, height, openings):
+    """The solid parts of a wall `length` long and `height` tall, cut by
+    `openings`, as (s0, s1, y0, y1) rectangles in the wall's own plane."""
+    cuts = sorted(openings, key=lambda o: o["at"])
+    out, s = [], 0.0
+    for o in cuts:
+        a, b = o["at"], o["at"] + o["width"]
+        sill = o.get("sill", 0.0)
+        top = sill + o.get("height", DOOR_H)
+        if a > s:
+            out.append((s, a, 0.0, height))
+        if sill > 0:
+            out.append((a, b, 0.0, sill))
+        if top < height:
+            out.append((a, b, top, height))
+        s = max(s, b)
+    if s < length:
+        out.append((s, length, 0.0, height))
+    return out
+
+
+class Level:
+    """The pieces, colliders and markers of one spec, in spec space."""
+
+    def __init__(self, spec):
+        self.spec = spec
+        self.style = spec.get("style") or {}
+        self.art = []        # (node name, Piece)
+        self.colliders = []  # (node name, kind, lo, hi, extra)
+        self.doors = []      # (area, lo, hi) volumes a prop must not block
+        self.findings = []
+
+    def collide_box(self, name, lo, hi):
+        self.colliders.append((name, "box", lo, hi, None))
+
+    def wall(self, piece, name, origin, axis, length, base_y, height, thickness, openings, role, clip=(None, None)):
+        """A wall along `axis` ('x' or 'z') from `origin` (its start on the
+        wall's inner face line), `thickness` into the other axis."""
+        ox, oz = origin
+        lo_clip = clip[0] if clip[0] is not None else 0.0
+        hi_clip = clip[1] if clip[1] is not None else length
+        for i, (s0, s1, y0, y1) in enumerate(_spans(length, height, openings)):
+            s0, s1 = max(s0, lo_clip), min(s1, hi_clip)
+            if s1 - s0 < 1e-4:
+                continue
+            if axis == "x":
+                lo, hi = (ox + s0, base_y + y0, oz), (ox + s1, base_y + y1, oz + thickness)
+            else:
+                lo, hi = (ox, base_y + y0, oz + s0), (ox + thickness, base_y + y1, oz + s1)
+            piece.box(lo, hi, role)
+            self.collide_box("col_%s_%d" % (name, i), lo, hi)
+
+    def area(self, a):
+        kind = a.get("kind", "room")
+        x, z, w, d = a["x"], a["z"], a["w"], a["d"]
+        fy = a.get("floor_y", 0.0)
+        name = a["name"]
+        p = Piece()
+        role = {"room": "floor", "yard": "ground", "path": "path", "water": "water"}[kind]
+        # A path lies 2 cm proud of what it crosses, so the two never z-fight.
+        top = fy + (0.02 if kind == "path" else 0.0) - (0.15 if kind == "water" else 0.0)
+        p.box((x, top - FLOOR_T, z), (x + w, top, z + d), role)
+        if kind != "water":
+            self.collide_box("col_%s_floor" % name, (x, top - FLOOR_T, z), (x + w, top, z + d))
+        if kind == "room" and a.get("walls", True):
+            h = a.get("height", 3.0)
+            by_side = {s: [o for o in a.get("openings") or [] if o.get("side") == s] for s in "nsew"}
+            T = WALL_T
+            self.wall(p, name + "_n", (x, z), "x", w, fy, h, T, by_side["n"], "wall")
+            self.wall(p, name + "_s", (x, z + d - T), "x", w, fy, h, T, by_side["s"], "wall")
+            # East and west run between the north and south walls, so the
+            # corners are one solid, not two boxes fighting over a column.
+            self.wall(p, name + "_w", (x, z), "z", d, fy, h, T, by_side["w"], "wall", clip=(T, d - T))
+            self.wall(p, name + "_e", (x + w - T, z), "z", d, fy, h, T, by_side["e"], "wall", clip=(T, d - T))
+            for side, ops in by_side.items():
+                for o in ops:
+                    if o.get("sill", 0.0) > 0:
+                        continue
+                    s0, s1 = o["at"], o["at"] + o["width"]
+                    oh = fy + o.get("height", DOOR_H)
+                    if side in "ns":
+                        zz = z if side == "n" else z + d - T
+                        self.doors.append((name, (x + s0, fy + 0.05, zz - 0.6), (x + s1, oh, zz + T + 0.6)))
+                    else:
+                        xx = x if side == "w" else x + w - T
+                        self.doors.append((name, (xx - 0.6, fy + 0.05, z + s0), (xx + T + 0.6, oh, z + s1)))
+            if a.get("ceiling"):
+                lo, hi = (x, fy + h, z), (x + w, fy + h + 0.15, z + d)
+                p.box(lo, hi, "wall")
+                self.collide_box("col_%s_ceiling" % name, lo, hi)
+        self.art.append(("area_" + name, p))
+
+    def wall_run(self, wr):
+        (fx, fz), (tx, tz) = wr["from"], wr["to"]
+        T = wr.get("thickness", 0.2)
+        role = wr.get("role", "wall")
+        p = Piece()
+        if abs(tx - fx) > 0:
+            axis, length = "x", abs(tx - fx)
+            origin = (min(fx, tx), fz - T / 2)
+            flip = tx < fx
+        else:
+            axis, length = "z", abs(tz - fz)
+            origin = (fx - T / 2, min(fz, tz))
+            flip = tz < fz
+        # `at` counts from `from`; the geometry runs from the smaller end.
+        openings = [dict(o, at=length - o["at"] - o["width"]) if flip else o
+                    for o in wr.get("openings") or []]
+        self.wall(p, wr["name"], origin, axis, length, wr.get("y", 0.0),
+                  wr.get("height", 3.0), T, openings, role)
+        self.art.append(("wall_" + wr["name"], p))
+
+    def ramp(self, r):
+        x, z, w, d = r["x"], r["z"], r["w"], r["d"]
+        y0, y1 = r["from_y"], r["to_y"]
+        base = min(y0, y1) - 0.1
+        steps = int(r.get("steps", 0))
+        p = Piece()
+        if steps == 0:
+            p.wedge(x, z, x + w, z + d, base, y0, y1, r["dir"], "path")
+        else:
+            for i in range(steps):
+                t0, t1 = i / steps, (i + 1) / steps
+                h = y0 + (y1 - y0) * (t1 if y1 > y0 else t0)
+                sx0, sx1, sz0, sz1 = x, x + w, z, z + d
+                if r["dir"] == "n":
+                    sz0, sz1 = z + d - d * t1, z + d - d * t0
+                elif r["dir"] == "s":
+                    sz0, sz1 = z + d * t0, z + d * t1
+                elif r["dir"] == "e":
+                    sx0, sx1 = x + w * t0, x + w * t1
+                else:
+                    sx0, sx1 = x + w - w * t1, x + w - w * t0
+                p.box((sx0, base, sz0), (sx1, h, sz1), "path")
+        # Stairs collide as a smooth slope: a controller climbs a wedge, and
+        # catches on every riser of a staircase.
+        self.colliders.append(("col_%s" % r["name"], "wedge", (x, base, z), (x + w, max(y0, y1), z + d),
+                               (y0, y1, r["dir"])))
+        self.art.append(("ramp_" + r["name"], p))
+
+    def platform(self, pl):
+        x, z, w, d, y = pl["x"], pl["z"], pl["w"], pl["d"], pl["y"]
+        t = pl.get("thickness", 0.3)
+        lo, hi = (x, y - t, z), (x + w, y, z + d)
+        p = Piece()
+        p.box(lo, hi, pl.get("role", "floor"))
+        self.collide_box("col_" + pl["name"], lo, hi)
+        self.art.append(("platform_" + pl["name"], p))
+
+    def prop(self, pr):
+        p = Piece()
+        level_props.build(p, pr["kind"], pr["name"])
+        at, s = pr["at"], pr.get("scale", 1.0)
+        m = (Matrix.Translation(at) @ Matrix.Rotation(math.radians(pr.get("rot", 0.0)), 4, "Y")
+             @ Matrix.Scale(s, 4))
+        p.transformed(m)
+        if pr.get("collide", True):
+            xs = [v.co for v in p.bm.verts]
+            lo = (min(c.x for c in xs), min(c.y for c in xs), min(c.z for c in xs))
+            hi = (max(c.x for c in xs), max(c.y for c in xs), max(c.z for c in xs))
+            self.collide_box("col_" + pr["name"], lo, hi)
+        self.art.append(("prop_" + pr["name"], p))
+
+    def build(self):
+        for a in self.spec.get("areas") or []:
+            self.area(a)
+        for wr in self.spec.get("walls") or []:
+            self.wall_run(wr)
+        for r in self.spec.get("ramps") or []:
+            self.ramp(r)
+        for pl in self.spec.get("platforms") or []:
+            self.platform(pl)
+        for pr in self.spec.get("props") or []:
+            self.prop(pr)
+
+
+def _surface_under(level, x, y, z):
+    """The top of the collider under (x, z) nearest below y + 0.3, or None."""
+    best = None
+    for name, kind, lo, hi, extra in level.colliders:
+        if not (lo[0] <= x <= hi[0] and lo[2] <= z <= hi[2]):
+            continue
+        if kind == "wedge":
+            y0, y1, rise = extra
+            t = {"n": (hi[2] - z) / (hi[2] - lo[2]), "s": (z - lo[2]) / (hi[2] - lo[2]),
+                 "e": (x - lo[0]) / (hi[0] - lo[0]), "w": (hi[0] - x) / (hi[0] - lo[0])}[rise]
+            top = y0 + (y1 - y0) * t
+        else:
+            top = hi[1]
+        if top <= y + 0.3 and (best is None or top > best[0]):
+            best = (top, name)
+    return best
+
+
+def _audit(level, markers):
+    """Measured on the colliders. Findings are words; the marker list says
+    which markers stand on something, each marker once."""
+    out = []
+    for m in markers:
+        x, y, z = m["at"]
+        under = _surface_under(level, x, y, z)
+        standing = m["kind"] in ("spawn", "exit", "checkpoint")
+        supported = under is not None and y - under[0] <= 3.0
+        if standing and not supported:
+            level.findings.append("marker '%s' (%s) has no collider under it: a player there falls"
+                                  % (m["name"], m["kind"]))
+        for name, kind, lo, hi, _ in level.colliders:
+            if kind == "box" and lo[0] < x < hi[0] and lo[2] < z < hi[2] and lo[1] < y + 0.1 < hi[1]:
+                level.findings.append("marker '%s' is inside collider '%s'" % (m["name"], name))
+                break
+        out.append({"name": m["name"], "kind": m["kind"], "at": [x, y, z],
+                    "supported": bool(supported), "surface": under[1] if under else ""})
+    props = {"col_" + p["name"] for p in level.spec.get("props") or []}
+    for area, dlo, dhi in level.doors:
+        for name, kind, lo, hi, _ in level.colliders:
+            if name in props and all(lo[i] < dhi[i] and hi[i] > dlo[i] for i in range(3)):
+                level.findings.append("prop '%s' blocks a door of '%s'" % (name[4:], area))
+    return out
+
+
+def _overlaps(spec, findings):
+    areas = spec.get("areas") or []
+    for i, a in enumerate(areas):
+        for b in areas[i + 1:]:
+            same = abs(a.get("floor_y", 0.0) - b.get("floor_y", 0.0)) < 1e-3
+            kinds = {a.get("kind", "room"), b.get("kind", "room")}
+            if same and "path" not in kinds and (
+                    a["x"] < b["x"] + b["w"] and b["x"] < a["x"] + a["w"]
+                    and a["z"] < b["z"] + b["d"] and b["z"] < a["z"] + a["d"]):
+                findings.append("areas '%s' and '%s' overlap at the same height: their floors "
+                                "z-fight" % (a["name"], b["name"]))
+
+
+def run(args):
+    spec_path = args.get("spec_path") or ""
+    out_path = args.get("out_path") or ""
+    out_dir = args.get("out_dir") or ""
+    if not spec_path or not os.path.isfile(spec_path):
+        raise ValueError("spec_path does not exist")
+    if not out_path or not out_dir or not os.path.isdir(out_dir):
+        raise ValueError("out_path and an existing out_dir are required")
+    with open(spec_path, encoding="utf-8") as fh:
+        spec = json.load(fh)
+    level_check.check(spec)
+    size = scene.clamp_int(args.get("size"), 768, 256, 1024)
+
+    bpy.ops.wm.read_factory_settings(use_empty=True)
+    level = Level(spec)
+    level.build()
+    _overlaps(spec, level.findings)
+
+    style = level.style
+    mats = _materials(style)
+    root = _empty("level_" + spec["name"])
+    root["funpixel_level"] = spec["name"]
+    root["funpixel_shading"] = style.get("shading") or "toon"
+    art = _empty("art", root)
+    cols = _empty("colliders", root)
+    mark = _empty("markers", root)
+
+    triangles = 0
+    outline = style.get("outline", True)
+    width = float(style.get("outline_width", 0.03))
+    for name, piece in level.art:
+        if piece.empty():
+            piece.bm.free()
+            continue
+        if outline:
+            level_geo.add_ink_hull(piece, width, "ink")
+        triangles += piece.triangles()
+        level_geo.to_object(name, piece, mats, art)
+
+    for name, kind, lo, hi, extra in level.colliders:
+        p = Piece()
+        if kind == "wedge":
+            y0, y1, rise = extra
+            p.wedge(lo[0], lo[2], hi[0], hi[2], lo[1], y0, y1, rise, "floor")
+        else:
+            p.box(lo, hi, "floor")
+        obj = level_geo.to_object(name, p, {"floor": mats["floor"]}, cols)
+        obj.data.materials.clear()
+        obj["funpixel_collider"] = kind
+
+    markers = _audit(level, spec.get("markers") or [])
+    for m in spec.get("markers") or []:
+        e = _empty("marker_%s_%s" % (m["kind"], m["name"]), mark, level_geo.spec_point(m["at"]))
+        e.rotation_euler = (0.0, 0.0, math.radians(m.get("rot", 0.0)))
+        e.empty_display_type = "ARROWS"
+        e["funpixel_marker"] = m["kind"]
+
+    scene.export_glb(out_path, extras=True)
+    bounds = scene.world_bounds([o for o in bpy.data.objects if o.type == "MESH" and o.parent == art])
+    proof = level_proof.render(out_dir, size, cols, markers, bounds)
+    return {
+        "out_path": out_path,
+        "triangles": triangles,
+        "art_nodes": len(art.children),
+        "colliders": len(cols.children),
+        "markers": markers,
+        "findings": level.findings,
+        # Spec space (glTF): Blender's (x, y, z) is the spec's (x, -z, y).
+        "bounds": {"min": [bounds["min"][0], bounds["min"][2], -bounds["max"][1]],
+                   "max": [bounds["max"][0], bounds["max"][2], -bounds["min"][1]]},
+        **proof,
+    }

package/bench/handlers/decimate.py

@@ -0,0 +1,220 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""`decimate` — bring a model down to a triangle budget (plan b10), or to a
+share of what it has (`ratio`, plan b8; `lod` chains it).
+
+WHY: what shipped on phones in one studio's games was 0.8–9K triangles per mesh (research
+12 §2.3); fal's Hunyuan cannot go below 40K and a Pro mesh is often 300–450K
+(measured on the harness games' rigged characters). The budget is the
+caller's — this verb only meets it.
+
+NEVER WELDS. The glTF importer splits a vertex wherever its UV changes, so a UV
+seam is an open boundary in Blender. Edge collapse cannot cross a boundary it
+is not connected to, so every UV island keeps its own UVs. Merging vertices
+first ("remove doubles") connects the islands, and the collapse then drags UVs
+across the seam: one studio lost about an hour to exactly that — the sign "RAMEN"
+decimated to "RMEN" (research 12 §2.3.4; `funpixel-glb-optimize` refuses to
+weld for the same reason). `uv_split_vertices` is reported before and after so
+a caller can SEE that no seam was crossed: a vertex whose corners disagree on
+their UV is a seam running through connected geometry.
+
+A SKINNED MESH STAYS WITHIN ITS BONE INFLUENCES. Collapse interpolates vertex
+weights, so a merged vertex inherits the union of both sides' bones — measured
+on a real 362K-triangle rigged character decimated to 6K: at most 4 influences
+per vertex before, 10 after. glTF carries 4 per set and engines read one set,
+so the extra ones would be dropped at export in whatever order the exporter
+chose. Here they are limited to the source's own maximum and renormalised,
+explicitly, and counted. If decimation leaves vertices with no bone weight at
+all (they would render in the bind pose), the verb refuses with the numbers.
+
+SHAPE KEYS ARE REFUSED. A decimate modifier cannot be applied to a mesh with
+shape keys, and removing them to make it apply would delete the model's
+morph targets without asking.
+"""
+import os
+
+import bpy
+
+from . import scene
+
+# A mesh whose share of the budget would fall below this keeps its triangles:
+# a 42-vertex rigger's marker collapsed to 2 triangles helps nobody, and parts
+# this small are not where a budget goes. Measured on the harness characters,
+# which each carry one.
+SMALL_MESH_TRIANGLES = 64
+
+# One corrective pass when the first lands above budget by more than this.
+OVERSHOOT = 1.02
+
+# The UVs of one vertex's corners agree to this.
+UV_EPSILON = 1e-5
+
+
+def _uv_split_vertices(obj):
+    """Vertices whose corners carry different UVs (see the module doc)."""
+    uv = obj.data.uv_layers.active
+    if uv is None:
+        return 0
+    seen = {}
+    split = set()
+    for loop in obj.data.loops:
+        u = uv.data[loop.index].uv
+        prev = seen.setdefault(loop.vertex_index, (u.x, u.y))
+        if abs(prev[0] - u.x) > UV_EPSILON or abs(prev[1] - u.y) > UV_EPSILON:
+            split.add(loop.vertex_index)
+    return len(split)
+
+
+def _deform_indices(obj, arm):
+    if arm is None:
+        return set()
+    deform = {b.name for b in arm.data.bones if b.use_deform}
+    return {g.index for g in obj.vertex_groups if g.name in deform}
+
+
+def _influences(obj, deform):
+    """(max bone influences on one vertex, vertices with none)."""
+    most, none = 0, 0
+    for v in obj.data.vertices:
+        n = sum(1 for g in v.groups if g.group in deform and g.weight > 0.0)
+        most = max(most, n)
+        none += n == 0
+    return most, none
+
+
+def _collapse(obj, ratio):
+    mod = obj.modifiers.new("fp_decimate", "DECIMATE")
+    mod.decimate_type = "COLLAPSE"
+    mod.ratio = max(0.0, min(1.0, ratio))
+    mod.use_collapse_triangulate = True
+    with bpy.context.temp_override(object=obj, active_object=obj, selected_objects=[obj]):
+        # First in the stack, so it acts on the mesh as stored rather than on
+        # the armature-deformed result.
+        bpy.ops.object.modifier_move_to_index(modifier=mod.name, index=0)
+        bpy.ops.object.modifier_apply(modifier=mod.name)
+
+
+def _limit_influences(obj, limit):
+    scene.select_only([obj], obj)
+    bpy.ops.object.vertex_group_limit_total(group_select_mode="BONE_DEFORM", limit=limit)
+    bpy.ops.object.vertex_group_normalize_all(group_select_mode="BONE_DEFORM", lock_active=False)
+
+
+def skin_of(meshes, arm):
+    """Per skinned mesh, measured on the SOURCE: (deform groups, most bone
+    influences on one vertex, vertices with none). Every later level is held to
+    these, never to the level before it."""
+    skin = {}
+    for o in meshes:
+        if scene.is_skinned(o):
+            deform = _deform_indices(o, arm)
+            skin[o.name] = (deform,) + _influences(o, deform)
+    return skin
+
+
+def reduce_to(meshes, target, skin):
+    """Decimate `meshes` as they stand now to `target` triangles in total.
+    Returns the vertices whose extra influences were dropped. Raises with the
+    numbers when the budget cannot be met honestly (see the module doc)."""
+    before = {o.name: scene.triangles(o) for o in meshes}
+    total = sum(before.values())
+    small = [o for o in meshes if before[o.name] * target / total < SMALL_MESH_TRIANGLES]
+    rest = [o for o in meshes if o not in small]
+    room = target - sum(before[o.name] for o in small)
+    if room <= 0 or not rest:
+        raise ValueError(
+            "a budget of %d triangles is smaller than the model's small parts alone "
+            "(%d triangles across %d meshes)" % (target, total, len(meshes))
+        )
+    for o in rest:
+        if o.data.shape_keys is not None:
+            raise ValueError(
+                "mesh '%s' has %d shape keys (morph targets); decimating would delete "
+                "them. Remove them in the source if they are not needed"
+                % (o.name, len(o.data.shape_keys.key_blocks))
+            )
+    ratio = room / sum(before[o.name] for o in rest)
+    for o in rest:
+        _collapse(o, ratio)
+    landed = sum(scene.triangles(o) for o in rest)
+    if landed > room * OVERSHOOT:
+        for o in rest:
+            _collapse(o, room / landed)
+
+    limited = 0
+    for o in rest:
+        if o.name not in skin:
+            continue
+        deform, most, unweighted = skin[o.name]
+        after_most, _ = _influences(o, deform)
+        if after_most > most:
+            limited += sum(
+                1
+                for v in o.data.vertices
+                if sum(1 for g in v.groups if g.group in deform and g.weight > 0.0) > most
+            )
+            _limit_influences(o, most)
+        _, after_none = _influences(o, deform)
+        was = unweighted / max(1, len(o.data.vertices))
+        now = after_none / max(1, len(o.data.vertices))
+        if after_none > unweighted and now > was + 0.01:
+            raise ValueError(
+                "decimating '%s' left %d of %d vertices with no bone weight (%.1f%%, "
+                "was %.1f%%); they would stay in the bind pose while the rest moves"
+                % (o.name, after_none, len(o.data.vertices), now * 100, was * 100)
+            )
+    return limited
+
+
+def uv_split_vertices(meshes):
+    return sum(_uv_split_vertices(o) for o in meshes)
+
+
+def run(args):
+    path = args.get("model_path") or ""
+    out_path = args.get("out_path") or ""
+    if not path or not os.path.isfile(path):
+        raise ValueError("model_path does not exist")
+    if not out_path:
+        raise ValueError("out_path is required — this verb writes a new model")
+    target = int(args.get("target_triangles") or 0)
+    ratio = float(args.get("ratio") or 0.0)
+    if target <= 0 and not 0.0 < ratio <= 1.0:
+        raise ValueError("give target_triangles or a ratio in (0, 1]")
+
+    scene.import_model(path, args.get("format") or "")
+    meshes = scene.mesh_objects()
+    if not meshes:
+        raise ValueError("the file imported but contains no mesh")
+    arm = scene.armature_object()
+
+    before = {o.name: scene.triangles(o) for o in meshes}
+    total = sum(before.values())
+    if target <= 0:
+        # A share of what is there: the caller did not know the count.
+        target = max(1, int(round(total * ratio)))
+    uv_before = uv_split_vertices(meshes)
+    skin = skin_of(meshes, arm)
+
+    decimated = total > target
+    limited = reduce_to(meshes, target, skin) if decimated else 0
+
+    after = {o.name: scene.triangles(o) for o in meshes}
+    total_after = sum(after.values())
+    scene.export_glb(out_path)
+    return {
+        "out_path": out_path,
+        "decimated": decimated,
+        "target_triangles": target,
+        "triangles_before": total,
+        "triangles_after": total_after,
+        "within_budget": total_after <= target,
+        "meshes": [
+            {"name": n, "triangles_before": before[n], "triangles_after": after[n]}
+            for n in before
+        ],
+        "uv_split_vertices_before": uv_before,
+        "uv_split_vertices_after": uv_split_vertices(meshes),
+        "max_influences": max((s[1] for s in skin.values()), default=0),
+        "vertices_influence_limited": limited,
+        "external_images_dropped": scene.EXTERNAL_IMAGES_DROPPED,
+    }