# 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.

Source: https://allyhub.com/docs/reference/sdk/modeling · AllyHub 0.10.0
Index of all docs: https://allyhub.com/llms.txt

## 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](https://allyhub.com/docs/reference/sdk/project.md#items)) (`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.

```ts file=room/stick.ts

  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 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.

```ts file=room/hand.ts
  capsule,
  defineModel,
  ellipsoid,
  meshField,
  smoothUnion,
  type Vec3,
} from "@allyhub/model";

  // 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

- `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.

## 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.

```ts file=room/room.ts

  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](https://allyhub.com/docs/reference/sdk/scenery.md#the-scenery-layer)).
