SDK: Modeling props
A prop no library has is modelled in code with @allyhub/model: a subset of Blender 4.5's data API (bpy.data, bmesh, modifiers, materials, curves, UVs) in TypeScript, evaluated without Blender, the same in allyhub 3d-model and in a scenery's page. This file covers a model module, how it is built and measured, and how a scenery shows it. What the subset holds, every option and each deliberate difference from Blender, is allyhub 3d-model capabilities (JSON; also capabilities from @allyhub/model): a call outside it fails and names what is missing.
A model module
Section titled “A model module”A model module’s default export is defineModel(build), or defineModel({ title, build }): title is the item’s name where allyhub.yaml gives it none, read from the module as written (a string, not computed); without either, its file’s name. A model made to be used again is an item of its own, listed in allyhub.yaml as kind: model (project.md) (models/desk/desk.ts), made once and put in any scenery that imports it, each with its own parameters (a size, a finish). It opens alone in the scenery’s viewer (allyhub dev, Studio), allyhub check builds it (one that does not build is AK-B010), and allyhub render writes its GLB, by its id. AllyHub’s registry has products as model pieces to start from (allyhub add 3d-model/monitor adds models/monitor/monitor.ts and the kit it is built with; allyhub add search --type 3d-model lists them). A part only one scenery uses may stay a module beside it (room/stick.ts) that the list does not name: the scenery’s alone. @allyhub/model is lent by the CLI, with no package.json entry.
import { defineModel } from "@allyhub/model";
export default defineModel((bpy, parameters) => { const length = Number(parameters["length"] ?? 0.3); const mesh = bpy.data.meshes.new("Stick"); mesh.from_pydata( [ [0, 0, 0], [0, 0.004, 0], [-length, 0.004, 0], [-length, 0, 0], ], [ [0, 1], [1, 2], [2, 3], ], [], ); const stick = bpy.data.objects.new("Stick", mesh); bpy.context.collection.objects.link(stick); const lathe = stick.modifiers.new("Lathe", "SCREW"); lathe.axis = "X"; lathe.use_merge_vertices = true; lathe.merge_threshold = 1e-6; const brass = bpy.data.materials.new("Brass"); brass.diffuse_color = [0.8, 0.6, 0.3, 1]; brass.metallic = 1; brass.roughness = 0.2; mesh.materials.append(brass);});build(bpy, parameters)may be async.parametersis plain JSON (--args, or a scenery’s call).bpy.random()is seeded (--param seed=, default 0);Math.random()is not.- There is no
bpy.ops: no edit mode, selection or active object.bmesh.ops.*take the geometry they act on and return the new geometry, as in Blender’s Python.applyModifier(bpy, object, { modifier })applies one named modifier to its base mesh (Blender’smodifier_apply). - Relative imports name their extension (
./parts.ts); only erasable TypeScript. - An object’s name is what the scenery commands and measurements call it; a taken name gets Blender’s suffix (
Part.001).
Axes. Blender’s: right-handed, Z up, metres, radians (Euler XYZ), unlike a scenery (Y up, degrees). The GLB and modelObject turn Z up to Y up with one root rotation: Blender’s (x, y, z) is the scenery’s (x, z, −y). Blender’s length defaults are sized for a room (Bevel width 0.1 m, Solidify thickness 0.01 m, Screw and Array merge_threshold 0.01 m, Mirror 0.001 m): a hand-sized prop sets its own.
A soft shape: a distance field
Section titled “A soft shape: a distance field”A shape with no edges (a foam hand, a pebble) can be written as a signed distance field, Field = (p) => number, negative inside. meshField(field, { min, max, cell, project?, maxSamples? }) meshes it by surface nets, each vertex moved onto the surface by project Newton steps (default 3), refusing a grid over maxSamples (default 40 million; FIELD_DEFAULTS). It gives { vertices, faces, closed, samples }: faces counterclockwise seen from outside, closed when the field is outside on all of the box’s faces.
import { capsule, defineModel, ellipsoid, meshField, smoothUnion, type Vec3,} from "@allyhub/model";
export default defineModel((bpy) => { // Millimetres while it is written, metres when it is made. const fist = (p: Vec3) => smoothUnion( ellipsoid(p, [-11, 0, 0], [13, 12.6, 10.8]), capsule(p, [0, 0, 2], [26, 0, 6], 5.3, 4.5), 3.2, ); const m = meshField(fist, { min: [-36, -17, -17], max: [34, 17, 16], cell: 0.5, }); const mesh = bpy.data.meshes.new("Hand"); mesh.from_pydata( m.vertices.map(([x, y, z]): Vec3 => [x / 1000, y / 1000, z / 1000]), [], m.faces, ); mesh.shade_smooth(); bpy.context.collection.objects.link(bpy.data.objects.new("Hand", mesh));});| Helper | The shape |
|---|---|
sphere(p, center, radius) |
A ball |
box(p, center, half, round = 0) |
A box of half-sizes half, its edges rounded inside it |
capsule(p, a, b, ra, rb = ra) |
From a to b, its radius running from ra to rb |
ellipsoid(p, center, radii) |
Radii along the axes (exact on its surface) |
torus(p, center, axis, major, minor) |
Round "x", "y" or "z" |
cylinder(p, a, b, radius, round = 0) |
From a to b, its rims rounded |
smoothUnion(d1, d2, k), smoothIntersect, smoothSubtract |
Joined, intersected or cut, the seam rounded k wide |
The surface’s detail is about one cell.
Build and measure
Section titled “Build and measure”allyhub 3d-model <file> --inspectevaluates it without writing anything: each object’s parent, matrix, bounds after its modifiers (Blender’s Z-up metres), triangles, materials as glTF reads them, UV layers, a curve’s splines, and the objects left with no triangles.allyhub 3d-model <file>writes a GLB (Y up), by default.allyhub/out/<module>.glb;--outnames another (assets/media/models/<name>.glbto load it as media). A failed build leaves the last GLB in place.- A build is kept in
.allyhub/cache/model/while the module, the files it read, its folder’s files, its parameters and seed are unchanged;--freshbuilds anew. - The program is trusted project code, run in a child process; its logs go to stderr. An error names the call and the place in the project’s files it failed at.
- A subdivision surface lies inside its cage: measure the surface (
--inspect), not the cage.
In a scenery
Section titled “In a scenery”modelObject(w, model, parameters?, options?) from @allyhub/model/three builds the model in the scenery’s page (a model item is imported by its path, import desk from "../../models/desk/desk.ts", as any module), drawn as its GLB is, its images read through w.texture. It returns a Group not yet in the scene, whose own rotation turns Z up to Y up: place and turn it inside a group of the scenery’s own. A model built once into a GLB loads as any model instead (import, w.load), and stays as built until built again.
import { Group, Mesh, MeshPhysicalMaterial } from "three";import { defineScenery } from "@allyhub/scenery-host/layer";import { modelObject } from "@allyhub/model/three";import stick from "./stick.ts";
export default defineScenery({ async build(w) { const held = new Group(); held.name = "stick"; held.add(await modelObject(w, stick, { length: 0.32 })); w.scene.add(held); held.traverse((o) => { // A lacquer over the brass, which glTF's metallic-roughness cannot say. if ( o instanceof Mesh && (o.material as MeshPhysicalMaterial).name === "Brass" ) o.material = new MeshPhysicalMaterial({ color: 0xc89a4a, metalness: 1, roughness: 0.25, clearcoat: 1, }); }); },});- Materials are glTF’s metallic-roughness: the Principled BSDF’s base colour, metallic, roughness, alpha, normal and emission, from values or images; anything else fails with
unsupported_material, naming the node and socket. Each three.js material keeps its Blender material’s name, so a scenery replaces one by name to draw what glTF cannot say (sheen, clearcoat, transmission). - Images:
bpy.data.images.load(path)takes a PNG or JPEG. A path that starts with./or../is from the module that draws the model (the scenery’s module in a scenery, the model’s own forallyhub 3d-model); any other is from the project’s root. - A model used as a scenery prop for one video only is a
SceneryPropwhosebuildcallsmodelObject(scenery.md).