antics-modelkit

Build 3D assets in code, look at them in half a second, export glTF.

Dev-time only. Nothing here ships with your game — only its output does. It runs headless, because three's geometry classes are pure maths and need no DOM, so a browser is only ever for looking.

See what it makes → antics.gg/modelkit — every model in the catalogue is built with this kit and published with the recipe that generates it, so you change numbers instead of editing a mesh. Free, CC-BY or CC0.

npm i -D antics-modelkit
npm i -D playwright && npx playwright install chromium   # optional, for previews

Quickstart

npx modelkit palettes                          # what there is to pick from
npx modelkit build models.mjs                  # check every asset, write dist/*.glb
npx modelkit preview crate --models=models.mjs # look at one

A models module exports one function per asset. Return a bare array of parts, or a declaration that opts into the extent and colour checks:

import { box } from "antics-modelkit";
import { palette, PROPORTIONS } from "antics-modelkit/style";

export function crate() {
  const pal = palette("industrial");
  const s = PROPORTIONS.prop.crate * PROPORTIONS.character.height;
  return {
    category: "prop",
    palette: "industrial",
    parts: [
      { geometry: box(s, s, s), color: pal.timber.base,  name: "body" },
      { geometry: batten(s),    color: pal.timber.shade, name: "batten" },
    ],
  };
}

examples/styled.mjs is that end to end. Copy it; don't import from it — a kit that hands out named assets is a kit whose every project looks alike.

The loop

write a recipe  →  preview it  →  build (checks + writes .glb)  →  load at runtime
   models.mjs        half a sec       dist/crate.glb                 glbload.js

Build once, ship the .glb. Don't rebuild geometry on the page — that costs startup time on every visit, and it skips every check below:

import { loadGLB } from "antics-modelkit/glbload";   // core three only, safe to ship
const crate = await loadGLB("/models/crate.glb");
scene.add(crate);

API

Import from the root for the modelling vocabulary; the rest are subpaths.

| import | what's in it | | --- | --- | | antics-modelkit | the modelling vocabulary — 38 verbs, below | | antics-modelkit/style | palette paletteNames extendPalette PROPORTIONS READABLE CATEGORIES — pick names, not numbers | | antics-modelkit/texture | surface bakeColor bakeNormal + generators: plank stone weave plaster grain panel ribbed polished tile fur fbm noise | | antics-modelkit/creature | creature grow humanoid quadruped arachnid garment limbPose measure checkBend checkStride VRM_BONES | | antics-modelkit/anim | blendPose gait spring reach stride trail WALK | | antics-modelkit/basis | aimAt fitBox orbit orient heading moveDir poseRig unbakeRig FORWARD RIGHT UP | | antics-modelkit/glbload | loadGLB parseGLB parseClips scatter pivotAt — runtime, core three only | | antics-modelkit/validate | checkGeometry checkWinding checkAssembly checkHandedness coincidentSurfaces isClosed probePoint … | | antics-modelkit/motion | checkMotion checkClearance checkFrames checkPivots checkTravel checkGait bakeRig assembled | | antics-modelkit/gate | gate formatGate — the build's pass/fail policy | | antics-modelkit/retarget | retargetPose groundTo MIXAMO |

The vocabulary, grouped by what it does:

| | | | --- | --- | | surfaces | sweep (rings along a polyline) · ribbon (flat sections, past ~5:1) · lathe (surface of revolution) · patch (parametric grid) · extrude (an outline, with holes) · contour (iso-surface of a field) | | primitives | box · rect · spine · limb · frames | | combining | merge · weld · remesh · subdivide · facet · mirror | | deforming | twist · taper · bend · deform · sit | | placing | array · alongPath · grid · dice | | colour | tint · paint · mottle · tileOver · tangents | | rigs | rig · rigTree · stitch · weightsFor · bindTo · socketOn · collar |

Every verb carries its own documentation in src/, and the traps are written beside them.

Looking at it

npx modelkit preview crate --models=models.mjs
npx modelkit preview crate --turn        # four quarter turns, as a contact sheet
npx modelkit preview crate --walk=6      # six frames across a rig's drive
npx modelkit preview crate --winding     # back-faces in magenta
npx modelkit preview crate --elev=0      # eye level — use it on anything with a face

Looking is not a nicety here. Every asset in the catalogue that came out right came out right because it was looked at two to four times, and the defects that reach a person are silhouette errors that no measurement catches.

What the build checks

modelkit build gates every asset and refuses to write a broken one. Hard failures are the things no correct asset can have: NaN positions, inverted winding on a closed shell, and any file the Khronos glTF validator rejects. Everything else is advisory and printed — floating parts, z-fighting surfaces, unreadable colour at play size, implausible extents, left/right pairs on the wrong side.

Traps worth knowing

The six that cost the most time. All of them are explained properly in AGENTS.md.

• A reversed winding is invisible, not wrong-looking. Backface culling makes the surface vanish, so it reads as a lighting or material bug and gets debugged in the wrong file. checkGeometry() detects it; nothing else does.
• Weld before any topological operation. ExtrudeGeometry returns non-indexed geometry, so a mesh that looks closed is a pile of loose triangles.
• Primitives don't share an origin. box stands on y=0; a swept shape wraps around its spine, so a pipe laid along the ground is buried to its radius. Use sit().
• Texture tiles are in world units, because UVs are arc length. tileOver(geo, n) after any scaling, or the finest board you can describe is corduroy.
• sit() refuses a bound skin — it moves geometry and knows nothing about a rig, so on a rigged asset it silently slides the mesh off its own skeleton.
• The commonest error is a coefficient against the wrong quantity. Write every coefficient against the thing it is a fraction of, name that quantity in the expression, and render after each one.

Links

• antics.gg/modelkit — what the kit is, and the catalogue
• AGENTS.md — the long guide, written to be read end to end by an agent
• examples/ — worked recipes, shipped with the package

MIT.