Skip to content
Get started

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’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. parameters is 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’s modifier_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 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.

  • allyhub 3d-model <file> --inspect evaluates 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; --out names another (assets/media/models/<name>.glb to 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; --fresh builds 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.

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 for allyhub 3d-model); any other is from the project’s root.
  • A model used as a scenery prop for one video only is a SceneryProp whose build calls modelObject (scenery.md).
Was this page helpful?