Three.js Procedural Low-Poly Asset Generator
This harness edition assumes a workspace and Node.js. Use the bundled builders and CLI gates to collect evidence from the actual asset.
Build every asset (single or composite) as a pure, seeded function. The live preview and the standalone code export call that same function, so what the user sees is what they export.
Surface detail: Start with solid material or vertex colors. Add an image map only for a requested or visible detail that needs one. Use the session's image generator when original artwork is the right fit, then keep its output as a fixed input to the builder.
Preview choice: When the user asks for a preview without choosing a mode, offer Fast Preview (orbit, pan, check textures, play or scrub embedded clips) and Full Preview (editable parameters, rig inspection, animation authoring, or expressions). Share a fast result if already available and use the requested mode. See references/studio-preview.md.
Target: three ≥ r170 as ES modules, checked against the official migration notes through r187 (§12 in references/export.md).
Code is in src/, not in the docs. Run, do not re-read: tsx src/<name>.test.ts (pure tests need no three). Reference files list each module's API.
Reference image given? Read references/reference-matching.md BEFORE writing code and run its loop after every build step (§15).
Where to read next
| You are doing | Read | Code |
|---|---|---|
| Materials, flat shading, procedural or image-generated textures, vertex jitter (§4, §5) | references/look.md | src/lowpoly.ts, src/jitter.ts |
| Custom geometry, winding, mirrored parts, overlays (§6, §7) | references/geometry.md | src/geometry.ts, src/overlay.ts |
| Creature, hull, wing, pure triangle kernel (§6.2, §6.3) | references/creatures.md | src/tri.ts, src/organic.ts |
| Anything that animates, humanoid, extrude, texture (§6.4 to §6.7) | references/rigging-biped.md | src/rig.ts, src/biped.ts, src/texture.ts |
| Flat or blocky look, atlas, chamfer, AO, sockets (§6.8) | references/detail.md | src/detail.ts, src/detailThree.ts |
| Several sub-assets in one (§8) | references/composite.md | |
| Grounding, disposal, rebuilds, lights (§9, §10) | references/lifecycle.md | src/lifecycle.ts |
| Code export, Three.js versions (§11, §12) | references/export.md | src/fingerprint.ts |
A .glb file of the asset (§16) | references/glb-export.md | scripts/export-glb.ts |
Is it too heavy, platform budget, LOD detail (§17) | references/budget.md | scripts/mesh-stats.ts, src/lod.ts |
| Rig, animation clips, drift, expressions (§18) | references/rig-check.md | scripts/rig-check.ts |
| Fast GLB viewer or Full Preview studio | references/studio-preview.md | Fast Preview HTML |
| Complete small example | references/examples.md | |
| Before saying an asset is done: QA gates, review image (§13) | references/qa-gates.md | scripts/qa-asset.ts |
0. Conventions (decide once, apply everywhere)
| Topic | Rule |
|---|---|
| Units | 1 unit = 1 meter |
| Axes | Y up, right-handed |
| Forward | +Z (same as glTF and Object3D.lookAt) |
| Sides | With forward +Z and up +Y, the asset's right is −X and its left is +X (right = forward × up) |
| Pivot | Origin at the footprint centre, lowest point at Y = 0 (see §9) |
| Face names | Name faces by axis (+X face, top), never by port/starboard/left/right, so a rule can't contradict the axes |
| Symmetry | Build one side, mirror the copy through PartBuilder.add or mirrorTris (§6.1). A bare applyMatrix4 with negative scale leaves the winding inside-out |
Why this matters: pairing "bow = +Z" with "starboard = +X" is mirrored, and a ship built from that pairing has its sides swapped. With forward +Z, starboard is −X and port is +X.
1. One pipeline, one source of truth
parameter schema (defaults, ranges) → resolveParams() → build…Asset() → THREE.Group
- Defaults and ranges live in the schema only.
build…Asset(rawParams)callsresolveParamsitself. Three competing defaults (params.seed || 12345, schemadefault: 42, composite?? 101) make preview, presets and exported code disagree. build…Assetis pure: same resolved params give identical geometry. NoMath.random,Date.now, DOM access or module-level mutable state.- Import
THREEnormally. Do not inject aTHREEInstance: helpers use the module import, so injection only half-works and hides bugs. The export step supplies the import line (§11). - Give every builder and parameter list a unique name (
buildTreeAsset,treeParameters). A genericbuildAssetcollides as soon as a composite imports two generators. - For custom geometry (creatures, hulls, wings), keep shape logic in pure functions over plain triangle arrays and let THREE wrap the result at the end (§6.2). Primitive-only props can stay on
PartBuilderdirectly.
Types: src/types.ts (ParamDef, AssetGeneratorSchema).
Worked example (tree): references/examples.md.
2. Determinism
Reproducible output is the whole point of a seed, so protect it:
- Use
??, never||, for seeds and any numeric fallback.seed || 12345silently turns seed0into12345. - Give each feature its own forked stream. With one shared
rng, changingsegmentsor togglinghasFruitsshifts every later random number and reshuffles unrelated parts of the asset. - Iterate in a fixed order (arrays, not object keys of unknown order, not
Setof mixed insertion).
Code: src/prng.ts. API:
export function hashString(str: string)export function createPRNG(seed = 1)export type Rng = ReturnType<typeof createPRNG>;
3. Parameters
resolveParams applies defaults, coerces types, clamps to min/max, snaps to step, and rejects bad colors and selects. Use it in the UI, in presets and in build…Asset, so no consumer can produce NaN or out-of-range geometry.
Code: src/params.ts. API:
-
export function resolveParams(schema: { parameters: ParamDef[] }, input: Record<string, unknown> = {}) -
After resolving, apply derived constraints so slider combinations can't produce degenerate shapes (for example
trunkRadius = Math.min(trunkRadius, crownRadius * 0.6)). -
Keep
seedmax at 99999 or higher. Composite builders derive sub-seeds asfork(label).seed % 100000; a smaller max would clamp them all to the same value. -
Toggles (
hasFruits,hasTurrets) change what is built, never which random numbers the other parts receive (§2). -
Detail toggles (
aoStrength,bevel,atlasOn) are ordinary parameters. They change what the detail pass adds, never which random numbers other parts receive. -
Atlas stream is forked. Generate atlases from
rng.fork('atlas'), so switchingatlasOnleaves every other part unchanged (references/detail.md).
13. Checklist (tick per asset, do not ship pre-ticked)
Run the gates, then look. npx tsx scripts/qa-asset.ts --module ./kernel.ts --export buildXTris --symmetric for a pure kernel, or --tris tris.json for the final grounded asset (usage and gate list: references/qa-gates.md). It prints Q1 to Q10, writes review.png and ends with an @@RESULT line. Fix the first failing gate and rerun.
Done rule. Never report an asset as done until qa-asset passed on the current build (or each failing gate is named with its reason), review.png was opened with the view tool and one line per panel says what was seen, and everything listed as UNVERIFIED or not checked is repeated in the answer. End with the gate table of the last run.
Determinism and parameters
- Defaults and ranges exist only in the schema;
build…AssetcallsresolveParams - Seeds use
??; seed0works; noMath.randomorDate.now - Each feature has its own forked stream; toggles do not reshuffle other parts
- Derived constraints prevent degenerate shapes; sub-seeds fit the seed range
Reference (only when the user gave an image)
-
ref-spec.mdwritten once,ref.jsonmade, mask PNG checked;ref-comparerun after every build step; gate table (§15) is in the answer
Geometry and look
- Axes follow §0; faces described by axis; right = −X when forward = +Z
- Custom geometry has positive
signedVolume, also after mirroring;DoubleSideonly on zero-thickness sheets - Mirrored parts go through
add()/addTrisormirrorTris, never a bare negative-scaleapplyMatrix4 - Custom-geometry and creature shapes live in pure triangle kernels with Node tests (determinism, signed volume, stream isolation)
- Parts go through
bakeFlat+paint; per-triangle color functions are pure - Jitter is applied before
add(), seam-welded, with bounding volumes recomputed - Metal parts have an environment map or a lowered
metalness - Overlays use a constant-distance inset and a small lift against z-fighting
Rigging, humanoids, textures (only when they apply)
- Moving parts are bones from
RigBuilder, authored in rest pose; static parts stay merged; bones ≤ about 12 - Left/right bones come from
mirrorBone+ a mirror matrix; clips useAnimationMixeron the rig root - Limb chains go through
twoBoneIKor fixed point chains; feet and hands have explicit forward/up - Extruded and lofted parts have positive
signedVolume, also after mirroring - UV is off unless a texture is used; with a texture,
PartBuilder({ uv })is set for every part of that material anddisposeAssetfreesmap
Detail pass (only when it applies)
- Atlas cells follow the convention (cell 0 top-left); every part of a textured material has uv; roughness/bump maps are
NoColorSpacewithroughness: 1 - Atlas is generated from a forked stream (
seededAtlas), or injected as a parameter; the builder never loads files or touches the DOM - Chamfered and sculpted parts have positive
signedVolume; sculpt amounts keep radii > 0 - AO is applied once (
aoShadeper part for rigs,applyAOfor static merges) and never darker than the 0.35 floor - Small details come from
raycastTris/scatterOnSurface+placeTriswithsink; mirrored side usesmirrorHit
Composite
- Unique exported builder names; params namespaced and sliced with
pickParams - Placement uses footprints, fixed priority order, and bounded attempts
- Skipped items are deterministic; repeated objects are cloned or instanced
QA (every asset)
-
scripts/qa-asset.tsexit 0 on the current build;review.pngviewed, one finding per panel; UNVERIFIED items listed; gate table in the answer
Lifecycle and export
- Wrapper group grounds the asset at Y = 0;
disposeAssetis called on every rebuild - Meshes are named; triangle count is inside budget
- Exporter uses a real TS transpiler, includes helpers once, and has zero imports except
three(three/addonsonly ifmergeGeometriesis used) - GLB asked for: choose the export path in §16. Report the file, checks performed on its bytes, and any unchecked visual or import stages.
- Platform given or
detailadded:scripts/mesh-stats.ts(--lodsfor LOD) exit 0, profile and kind named,not checkedrepeated;detaildefault 2 leaves the existing asset unchanged - Export target (module, import map, classic global) matches where the code will run
- Parity test passes:
generate(params)and the exported module give the same fingerprint
14. Minimal single asset (when a full schema is overkill)
The ~290 lines of a first asset are mostly fixed infrastructure (prng.ts, lowpoly.ts, params.ts), not per-asset cost. Write those once as shared modules and never inline them in an asset file. For a one-off prop, skip the schema and resolveParams, keep the PRNG (determinism still matters), and export with only the helpers actually used (helpers: [rawPrng, rawLowpoly]). A complete asset is then about 30 lines:
import * as THREE from 'three';
import { createPRNG } from './prng';
import { PartBuilder, lowPolyMaterial } from './lowpoly';
import { groundAsset } from './lifecycle';
export function buildCrateAsset(raw: { seed?: number; size?: number } = {}) {
const seed = raw.seed ?? 42, size = Math.min(Math.max(Number(raw.size ?? 1) || 1, 0.3), 3);
const rng = createPRNG(seed).fork('planks');
const wood = new PartBuilder();
wood.add(new THREE.BoxGeometry(size, size, size), () => (rng() < 0.5 ? '#8a6a45' : '#7a5c3b')); // per-face color, own stream
for (const s of [-1, 1]) // corner battens
wood.add(new THREE.BoxGeometry(size * 0.08, size * 1.02, size * 1.02), '#5b4329', new THREE.Matrix4().makeTranslation(s * size * 0.46, 0, 0));
const content = new THREE.Group();
content.add(wood.build(lowPolyMaterial({ roughness: 0.9 }), { name: 'crate' }));
return groundAsset(content);
}
Promote it to the full schema form (§1) as soon as it gets sliders, presets, or is used inside a composite.
15. Reference matching (when the user gives an image, screenshot or sketch)
Full procedure and scripts: references/reference-matching.md. The rules, in order:
- Intake once. View the reference once, write
ref-spec.md(max 15 lines: facing, measured proportions, parts, palette, 3 signature features, out of scope), runscripts/ref-intake.ts, look at the mask PNG once. After that, never re-read the image: work from the spec andref.json. - Build coarse to fine, compare after every step. A blockout (G1 proportions, G2 aspect) → B silhouette (G2 IoU ≥ 0.85 per view) → C colour (G3 palette) → D detail (G4 signature features). Run
scripts/ref-compare.tsafter each step; it takes under a second. - Numbers before pictures. Fix only the FIRST failing gate per round, change one parameter group, compare again. View an image only for the mask check, a failing IoU diff (
diff-<view>.png) and the G4 milestones. - Stop rule. Max 3 rounds per gate; then keep the best version and report the gap. Never distort a shape to fill a red area. No detail pass (§6.8) while G2 fails.
- Log one line per round (
step B, round 2: side IoU 0.71 -> 0.83, shortened neck) and end the answer with the gate table of the last compare run. "Matches the reference" without that table is not allowed.
16. GLB file (when the user wants a .glb)
For geometry-only GLB, run qa-asset.ts, then npx tsx scripts/export-glb.ts --module ./kernel.ts --export buildXTris --out asset.glb (or --tris tris.json). It reruns Q1 to Q5 and verifies the output with E1 to E6.
When the GLB must retain colors, UVs, maps, rigging, or clips, export the built Three.js group with GLTFExporter and reopen the result with GLTFLoader. Check the requested attributes and report evidence for the exact file. See references/glb-export.md.
17. Budget and LOD (when there is a target platform, or the asset may be too heavy)
Run npx tsx scripts/mesh-stats.ts --module ./kernel.ts --export buildXTris --profile web --kind prop (or --tris tris.json --meta meta.json --glb asset.glb). It counts triangles, GPU vertices (3 x triangles, flat non-indexed), draw calls, materials, textures, bones and GLB size against the platform table, and says what it could not check. --lods builds detail 2, 1, 0 and checks about half the triangles per level, the same parts, bounds and pivot, determinism. Add LOD with detailParam and lodRadiusScale from src/lod.ts: default 2 must leave the existing asset unchanged. The numbers are counted, not measured on a GPU: say so. Details: references/budget.md.
18. Rig, clip and expression check (when the asset has pivots, clips or expression swaps)
Run npx tsx scripts/rig-check.ts --meta char_metadata.json to verify R1 hierarchy · R2 rest-pose · R3 clips (excluding RefPose) · R4 tracks & in-place horizontal drift · R5 static expression mapping · R6 slide clearance. Use Fast Preview for exported textures and clip playback, Full Preview for rig and expression inspection, and the target engine to verify imports. Details: references/rig-check.md and references/studio-preview.md.