@leumas/body-3d

Procedurally composed 3D bodies and props. three and data — no React, no DOM, no router.

import { bodyParts, partsToObject3D, blueprintParts } from '@leumas/body-3d';
import { createProceduralResolver } from '@leumas/body-3d/resolver';

const { root, limbs } = partsToObject3D({ body: 'bot', color: '#7fd1c0' });
scene.add(root);            // limbs: [{role: 'leg-l', hinge}, …] — what an animator drives

Why it exists

The silhouette vocabulary lived in @leumas/features/nav-views/world, which is a React package: importing it drags React, the router and a stylesheet. @leumas/game-3d needs the same bodies and has exactly one runtime dependency. So the geometry moved down to a package both can import; features/nav-views/world/bodies3d.js is now a one-line re-export shim, and every existing call site kept working.

What it holds

The two things to know

Geometry is shared and you must not dispose it. Every camera in a room points at one tripod. A teardown that walks the tree calling geometry.dispose() blanks every other instance of that species, with no error, and the next mount renders nothing. Assembled meshes are tagged userData.sharedGeometry so a teardown can tell what it owns; disposeBodyCache() and disposeBlueprintCache() are the only things allowed to free them, and both are process-wide.

The resolver is a fallback, and the order matters. A source listed in the manifest resolves to its real URL and the registry's own GLTF loader fetches it, DRACO and KTX2 included. Only a source with no file becomes proc:<source> and is composed here. That is what makes a generated-asset pass an upgrade — same source strings, same call, better mesh when a file lands — rather than a migration out of something that replaced it.

Limbs

A part may name a role (leg-l, leg-r, arm-l, arm-r, head) and a pivot, the height its joint sits at. partsToObject3D hangs those parts off a hinge group at the pivot and offsets the mesh back to where it rests, so rotating the hinge swings the limb about the joint. Rotating the mesh instead swings it about its own centre, which reads as a limb being stirred rather than a body walking. Several parts may share a role and travel as one limb.

Bodies with no roles return limbs: [], and an animation driver over them is a no-op rather than an error — most silhouettes (a crate, a rack, a camera) have no joints.

@leumas/game-3d/anim drives these hinges from replicated velocity and grounded state.