diff --git a/.claude/skills/author-recipe/SKILL.md b/.claude/skills/author-recipe/SKILL.md index ce725bc5..fa82e440 100644 --- a/.claude/skills/author-recipe/SKILL.md +++ b/.claude/skills/author-recipe/SKILL.md @@ -83,7 +83,17 @@ features → secondary forms → tertiary detail and wear. 500–1,500 lines for ## Contact sheet layout Row 1: 3/4 FRONT · FRONT +X · SIDE -Y. Row 2: TOP · 3/4 REAR · FAR LOD2. Header: name, overall -dimensions, grid step, LOD. Grid = ground plane, step chosen from the asset size. +dimensions, grid step, LOD. Grid = ground plane, step chosen from the asset size. Colour is the +hero's base colour, flat per triangle (the strip's mean albedo × vertex colour; glass see-through; +cutout cards alpha-tested, so leaves and fur show their real silhouette): a part that is white in the +sheet is white in the GLB. Grain, joints and relief show only in `hero.png`. + +**Hero view.** The hero camera is a front-left 3/4 orbit. When that hides the point of the asset, +record the view in the recipe: `hero: { azDeg: 145, elDeg: 25 }` (same degrees as `--az` / `--el` / +`--fov`; turn the worn or detailed side to the lens) or a fixed viewpoint for a place, +`hero: { eye: [x, y, z], target: [x, y, z], fovDeg: 50 }` (metres in the asset frame, no +auto-framing). `t3d hero`, `bun run shots`, `t3d review` and `t3d critique` use it by default; a +flag still overrides it. The contact sheet, blueprint and icons keep their fixed views. ## QA gates (all must pass at every LOD) | Gate | Fails when | Fix | diff --git a/.claude/skills/blender-artist/SKILL.md b/.claude/skills/blender-artist/SKILL.md index dd4d580d..3284e74b 100644 --- a/.claude/skills/blender-artist/SKILL.md +++ b/.claude/skills/blender-artist/SKILL.md @@ -73,6 +73,7 @@ distance uneven: stroke after `voxelRemesh` or on the `retopo` shell when a raw | A cage wider than the gap between parts | fingers bake each other: use `cageFit`, or lower `cage` and `maxRay` | | Voxel finer than a generator's tunnels | floods the inside into confetti: let `retopo` measure, or set `voxel` and `close` | | Bone heat on nearby limbs | it reads distance, not anatomy: `unweb` first, then `isolate` chains | +| A chain generated fused to the body along its length (a tail lying on a thigh) | `unweb` cannot cut it and a hard `isolate` split stretches the joining edges: give `isolate` a `contact` distance (metres, start at 0.04) so the band shares the motion; check stifle volume does not drop | | Decimating code-built geometry | never; only imported or model-built meshes (ADR 011, ADR 016) | | GPU work | one job at a time on the shared GPU; `--software-gpu` reviews through lavapipe | diff --git a/.claude/skills/creature-artist/SKILL.md b/.claude/skills/creature-artist/SKILL.md index d3ee92fa..0ca2713f 100644 --- a/.claude/skills/creature-artist/SKILL.md +++ b/.claude/skills/creature-artist/SKILL.md @@ -98,7 +98,7 @@ Sources: [examples/neural-server/README.md](../../../examples/neural-server/READ Albedo keeps the generator's baked light. A gallop can exceed what the skin takes: drop it and let QA `deform` judge. Outputs are not bit-identical between GPU runs: the committed output is the input to the build. As of 2026-11 the quadruped example is [`recipes/wolf_hybrid`](../../../recipes/wolf_hybrid/README.md) (read its steps table), and -[`recipes/bear_hybrid`](../../../recipes/bear_hybrid/README.md) for a heavy plantigrade build (`nose: true`, wrist weights); [`recipes/dragon_hybrid`](../../../recipes/dragon_hybrid/README.md) for an invented winged body the plan cannot describe (`register: 'joints'`, `take` with `'tail'`, rigid wings); the humanoid example is [`recipes/ranger`](../../../recipes/ranger/README.md). +[`recipes/bear_hybrid`](../../../recipes/bear_hybrid/README.md) for a heavy plantigrade build (`nose: true`, wrist weights); [`recipes/dragon_hybrid`](../../../recipes/dragon_hybrid/README.md) for an invented winged body the plan cannot describe (`register: 'joints'`, `take` with `'tail'`, wings as `extra` bone chains with a `flap` clip: `wings.ts`); the humanoid example is [`recipes/ranger`](../../../recipes/ranger/README.md). ## Bodies built from chains For bodies the creature kind cannot describe, write a `defineBodyPlan` spec: a trunk chain plus child chains, `repeat: { kind: 'mirror' }` for paired fins and `{ kind: 'radial', count: 8, ... }` for arms. Declare `medium: 'water'` for swimmers. Motion comes from sourced numbers, not by eye ([research](../../../docs/research/swim-and-tentacle-animation.md)). @@ -205,5 +205,5 @@ skeleton types, staged sculpt, patterns, allometry and wing-loading checks — ` Shipped too: the kind's Armature (`ctx.bone`), a `jaw` part, fibre muscles (`build.muscle`). Planned (M4, [roadmap](../../../docs/plans/roadmap.md#m4-creatures)): tail and limbs as moving parts, `pose`/`warp`/`ffd`, fur shells and cards, skins and morph targets. -Model tier shipped (As of 2026-11): textured parts (ADR 016), the `blender` step task, `importModel`, `modelChain` / `defineModelCreature`, QA `model`. Planned: wing bones, gallop, jaw and blink on a model body, finger bones. +Model tier shipped (As of 2026-11): textured parts (ADR 016), the `blender` step task, `importModel`, `modelChain` / `defineModelCreature`, QA `model`. Bones the plan lacks (wings, fins, a second tail) are `extra` chains on `modelChain` (joints along the mesh, limits with a source, a `motion` clip). Planned: gallop, jaw and blink on a model body, finger bones. Neutral positioning: the free code-based option, no claims against other tools. diff --git a/.claude/skills/material-artist/SKILL.md b/.claude/skills/material-artist/SKILL.md index 62809206..ab6f56dc 100644 --- a/.claude/skills/material-artist/SKILL.md +++ b/.claude/skills/material-artist/SKILL.md @@ -10,6 +10,9 @@ Use with [11-materials-authoring](../../../docs/idea/11-materials-authoring.md), [surfaces-volumes research](../../../docs/research/surfaces-volumes.md) and [16-art-as-text](../../../docs/idea/16-art-as-text.md). One material per asset: everything lands on the shared trim sheet + vertex colour; extra slots only via `paint`, `finishes`, `optics`, surfaces. +The sheet's 14 custom rows are per asset: define as many materials as the work needs, an asset +maps onto at most 14, one per row (two on one row in one asset: `T3D_MATERIAL_CONFLICT` from +`compile`, give one a free `row`); other assets may reuse any row. Paint with `sheetFor(compiled)`. ## When A new strip or library material, a texture graph, a weathered variant, a palette, a finish, glass diff --git a/.claude/skills/presentation-artist/SKILL.md b/.claude/skills/presentation-artist/SKILL.md index 6f44c08a..5bd2b54e 100644 --- a/.claude/skills/presentation-artist/SKILL.md +++ b/.claude/skills/presentation-artist/SKILL.md @@ -17,16 +17,16 @@ image, or adding lamps/headlights to an asset. ## Workflow | # | Presentation stage | ts23d | Exit | |---|---|---|---| -| 1 | Neutral look first: orthographic views on a metre grid | `bun run t3d shot recipes/x/x.ts --out renders` → READ `sheet.png` | silhouette right in six views | +| 1 | Neutral look first: orthographic views on a metre grid | `bun run t3d shot recipes/x/x.ts --out renders` → READ `sheet.png` (flat-shaded in the hero's base colour: strip mean albedo × vertex colour, glass see-through, cutout leaf/fur cards alpha-tested to their real silhouette; no texture detail, shadows, AO or emission) | silhouette right in six views; base colours agree with `hero.png` | | 2 | Hero camera: 3/4 front, slightly above eye level | `bun run t3d hero … --az -35 --el 18 --fov 30 --size 1600x900` (defaults) | asset fills ~60–80 % of frame width *typical* | -| 3 | Pick the view that sells the design | vary `--az` (front-left 3/4 default; rear 3/4 for engines/exhausts), `--el` low for heroic scale, high for top detail | focal part faces camera | +| 3 | Pick the view that sells the design | vary `--az` (front-left 3/4 default; rear 3/4 for engines/exhausts), `--el` low for heroic scale, high for top detail; then record it in the recipe: `hero: { azDeg, elDeg, fovDeg }`, or for a place a fixed viewpoint `hero: { eye, target, fovDeg }` (metres, asset frame). `t3d hero`, `bun run shots`, `review` and `critique` then use it by default; flags still win | focal part faces camera; the committed hero is that view | | 2b | Judge under physical light | `bun run t3d hero … --quality path --spp 64` (path tracer: sun + sky, bounces, skin diffusion, strand lobes on fur/hair cards; same camera and studio) | fur, skin, metal read as themselves; committed heroes are path traced (960×540, 16 spp) | | 3b | Textured parts (model-built assets) | the raster beauty, the path tracer and `sheet.png` sample the part's own albedo, normal and ORM (ADR 016); READ them to judge baked light, blotches and seams that vertex colour never shows; `t3d blender review --views turnaround` shows the base colour under studio light before the build | no baked shadow in the albedo, no visible UV seam | | 4 | Check values: squint / greyscale | read `hero.png`; critique rubric `materials` | distinct value groups; focal part has max contrast | | 5 | Relief check under grazing light | `t3d critique` → `raking.png`, `raking_detail.png` | modelled detail casts shadow; painted detail stays flat | | 6 | Distance check | `review/` LOD strip (`lodStrip`), `sheet.png` FAR LOD2 cell, `thumbnail` | reads at thumbnail size | | 7 | Machine review | `t3d review` → `review.json` warnings (exposure, tiny-in-frame, LOD popping) | no warning you cannot explain | -| 8 | Lights the asset carries | `ctx.socket('headlamp_l', { kind: 'light', dir, data: { light: 'spot', color, intensity, range, cone } })` → KHR_lights_punctual; `glow` for emissive parts | lamps light the scene in engines | +| 8 | Lights the asset carries | `ctx.socket('headlamp_l', { kind: 'light', dir, data: { light: 'spot', color, intensity, range, cone } })` → KHR_lights_punctual; `glow` for emissive parts (both beauty renders show the emission: colour × strength added to the surface, seen through glass tinted by it; strength above ~1.5 on a large face clips to pale yellow-white, as in an engine without bloom) | lamps light the scene in engines; glowing parts keep their hue in `hero.png` | | 9 | Publish | `bun run shots ` (refreshes committed `out//hero.png`, `sheet.png`, `thumb.png`) | recipes gate sees current images | ## Vocabulary → measurable @@ -36,7 +36,8 @@ image, or adding lamps/headlights to an asset. | Fill | lifts shadows; key:fill ratio 2:1 commercial, 4:1 portrait, 8:1 dramatic | fixed studio rig; judge shadow detail | | Rim | back light separating silhouette from background | not separately controllable (gap) | | Raking light | light at ~80° incidence to show relief | `raking.png` in critique | -| Azimuth / elevation / FOV | camera angle from front (+X), height angle, vertical field of view | `--az`, `--el`, `--fov` | +| Azimuth / elevation / FOV | camera angle from front (+X), height angle, vertical field of view | `--az`, `--el`, `--fov`; per asset `hero: { azDeg, elDeg, fovDeg }` | +| Viewpoint | a camera standing at a real place, looking at a landmark | `hero: { eye, target, fovDeg }` (no auto-framing; the raster drops triangles that cross the eye plane, the path tracer does not) | | Framing | subject size in frame; too small = `tiny-in-frame` warning | `review.json` | | Exposure | no clipped whites, no crushed blacks on the subject | `review.json` exposure warning | | Value grouping | 3–5 clear value masses; focal part highest contrast | **planned** focal check; judge by eye | @@ -84,7 +85,11 @@ Shipped: `t3d shot | hero | review | critique | blueprint | gaps`, `contactSheet `thumbnail`, `lodStrip`, `reviewPack`, light sockets → KHR_lights_punctual, `glow`, `pathHero` / `t3d hero --quality path` (deterministic CPU path tracer, procedural sky IBL + sun), `skin` / `skin_*` finishes → KHR_materials_diffuse_transmission + volume in the GLB. -Planned: HDRI environments, glow/emission and clearcoat-only parts in the path tracer (sheen, +`glow` emission in both beauty renders (the path tracer also lets it light its neighbours, by +BSDF sampling: noisy for a small bright emitter at 16 spp), per-asset `hero` view. +See-through parts dim the sun on what they hold in the raster (one shade per render, no coloured +shadow) and cast no shadow in the path tracer. +Planned: HDRI environments, emitters sampled as lights and clearcoat-only parts in the path tracer (sheen, anisotropy, iridescence are raster-only today), custom light rigs (rim control), turntable/animated presentation, zebra reflection renders, `photoMatch` side-by-side with reference photos (stub throws `T3D_NOT_IMPLEMENTED`), greyscale focal-point check. diff --git a/.claude/skills/rigger-animator/SKILL.md b/.claude/skills/rigger-animator/SKILL.md index bf980f21..bf545bdf 100644 --- a/.claude/skills/rigger-animator/SKILL.md +++ b/.claude/skills/rigger-animator/SKILL.md @@ -35,6 +35,7 @@ weights with Blender steps, not `ctx.bone` + `skinWeights`. | Need | Do | Check | |---|---|---| | Quadruped skeleton | our sourced plan fitted INTO the mesh (`fitSkeleton`: legs on each leg's centre line, spine under the dorsal line); optional learned joints: `modelChain({ rig: 'unirig' })`, mapped by topology | QA `model`: every joint inside the mesh (`T3D_MODEL_SKELETON`), mesh hugs the bones (`T3D_MODEL_FIT`) | +| Bones the plan lacks (wings, fins, a second tail) | `modelChain({ extra })`: per chain a name (`wing_l`), the plan bone it hangs from, joints root to tip along the mesh (`tracePath` finds a spar's centre line), a limit per bone with its source, and a `motion` (own clip + idle and gait parts). `bind` weights them with the rest; nothing in the rigger's output is needed | QA `model` (joints inside), `deform` at each declared limit, `skin` (`T3D_SKIN_CROSSED`: beyond the wrist a wing is one side's); a skin with an undeclared bone is `T3D_MODEL_SKELETON` | | Humanoid skeleton | the model's own (hosted rig: Meshy `rig` with `height`); `bind: { from: 'source' }` keeps its weights and clips | no vertex unweighted, <= 4 influences (Blender report) | | Gait clips (quadruped) | the creature clips (`idle`, `look`, `walk`, `trot`, `gallop`) baked on the fitted bones; `bite` and `blink` are dropped (fused head, no jaw or lids); `drop: ['gallop']` when the skin cannot take it | QA `deform` poses the skin at the limits; QA `gait` seam, slide, sink | | Humanoid clips | library clips by name (`Idle`, `Casual Walk`, `Run 2`) renamed `idle`, `walk`, `jog`; `importModel` closes a cycle one frame short and warns; `lift` raises a root that sinks | `gait`: skin of a foot <= 3 mm under the floor in in-place clips | diff --git a/CHANGELOG.md b/CHANGELOG.md index 0f7bd4c3..6e65fe02 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,43 @@ All notable changes to `@developerz.ai/ts23d`. Format: [Keep a Changelog](https: ## [Unreleased] +Contact sheets show the hero's base colour, triangle budgets are checked against the playbook bands, custom materials are per asset, and every committed asset was reworked and independently re-judged: criteria below the pass mark of 8 fell from 416 to 352, and two assets now pass on all seven. + +### Added +- `contactSheet(asset, { sheet })`, `thumbnail(asset, { sheet })` and `previewSheet()` (a 512² default sheet). Omitting `sheet` keeps the previous vertex-colour output pixel for pixel. +- `sheetFor(compiled, recipe)`, `sheetWith(ids, recipe)`, `materialsOf(compiled)`, `CompiledAsset.materials`, `paintTrimSheet(recipe, ids)`, `previewSheet(assets)`, `ReviewOptions.sheetRecipe`. +- Blender `isolate` step: optional `contact` (metres) for a chain generated fused to the body along its length (a tail lying on a thigh). Weights within that distance of an edge joining chain skin to body skin are blended. No default: committed programs keep their request keys. +- Per-asset hero view: `hero: { azDeg, elDeg, fovDeg }` or `hero: { eye, target, fovDeg }` on the definition; `t3d hero`, `bun run shots`, `review` and `critique` use it by default, `--az` / `--el` / `--fov` override. +- `glow` parts emit in the raster and path-traced hero, visible through glass and translucent shells; in the path tracer they light their neighbours. +- `modelChain`, `modelRig` and `modelBody` take `extra`: bone chains the creature plan lacks (wings, fins, a second tail), each declared by its joints along the mesh, the bone it hangs from, a limit per bone with a source, and an optional `motion` clip. Blender `bind` weights the skin to them; QA `deform` and `model` cover them. `tracePath(mesh, from, to, { cell })` finds a limb's centre line for placing the joints. +- `dragon_hybrid`: three bones a wing and a `flap` clip (0.9 Hz, design values); the wings settle in `idle` and are carried in the walk. +- Creature kind: `options.cells { body, head }` sets sculpt density directly; `spec.fur { density, guard }` sets fur card counts; `build.hock`, `build.heel`, `build.track` and `build.topline` give a shoulder hump, a plantigrade heel under the hip and a stance that holds its width; `CreatureInfo.rig` / `.bare` and `creatureHeadFur` let a recipe groom its own coat with the kind's skinning. +- Triangle bands per asset class: the `conventions` gate fails a committed asset whose triangles at any LOD exceed its class band from the playbooks (`T3D_BUDGET_BAND`, `scripts/lib/budget-bands.ts`), unless its README says `Budget why: `. The assets over band on 2026-11-19 are listed in `scripts/lib/budget-baseline.ts`; they warn until reduced or justified, new offenders fail now, and the list only shrinks. + +### Fixed +- `king_cobra`: `idle_ground` is a resting loose coil instead of a straight stick, `rear` lifts the front from a body that stays planted, and the coil rests on the ground instead of floating 2–7 cm above it. +- Review of the quality wave: 58 of 60 findings fixed (D340–D396), among them open holes in `joint_demo`'s sword, scar discs painted at both ends of every creature scar, normals left stale after four deformations, river ribbons under flat terrain, a shared trim sheet repainted by a later build into the same folder, and nine tests that could not fail. +- Gallery: `bear_hybrid`'s page shows the model-built bear. It has no CPU asset named `bear` to pair with, so the page used to compile the code creature instead. +- Creature kind: far-LOD legs are 8-sided with a ring wherever the coat's colour turns, on rounded paws, so stockings and leg colour survive at LOD2; QA connections no longer flips on a 2–5 % change of chest width or limb thickness. +- `tree` kind: LOD2 is the tree's own LOD0 crown as card clumps over a visible trunk and main limbs (palms: one folded card per frond); silhouette IoU ≥ 0.8 for oak, pine and palm (was 0.55–0.72). `impostor` takes `'clumps' | 'fronds'` (`'blob' | 'cards'` still accepted). +- `cityBlock`: walls use `wallStrip` (default `brick`) at true scale; windows are LOD-gated (LOD1 about 0.2 × LOD0 triangles, LOD2 keeps window rows as dark bands); with `trim`, LOD0 gets a cornice, belt course and plinth. +- `terrainFromDEM`'s default ground no longer bands: welded mesh, classes blended per vertex, rock strata on cut sides. Default output changes; `strips: false` is unchanged. +- QA `skin` (`T3D_SKIN_CROSSED`) reads a paired limb that stands on its roots (raised wings) the right way up. +- A model body whose Blender skin has a bone that is neither the plan's nor a declared `extra` chain fails with `T3D_MODEL_SKELETON` naming the bones; it used to re-bind silently. +- Contact sheet and thumbnail alpha-test cutout cards against the trim sheet, so foliage and fur show their real silhouette. +- See-through parts no longer put what they hold in opaque shadow in the raster hero; they dim the sun instead. +- `rts_faction` builds again: far-LOD tool handles are six-sided, so a grip joint agrees at any heading. +- Shared recipe libraries: mud contrasts with the paint instead of being near-black, `reproject` handles project materials, and the parts kit's hose, ladder, crate and painted door read correctly. +- The gallery binds each asset's own trim sheet instead of one sheet per worker. +- `wolf_hybrid` passes QA `deform` with no declared tolerance: hip stretch ×5.7 → ×2.2 through `isolate`'s `contact: 0.04`; both `limitTolerances` are removed (D253, open since 0.13.0). + +### Changed +- Recipes: a quality pass over all 76 committed assets (wear, materials, far-LOD identity, triangle counts). `roadster_v10` ships 155k / 23k / 3k triangles (was 909k / 78k / 5.5k), `hydra` 210k (was 348k), `weather_demo` 21k (was 95k); the over-band baseline went from 44 assets to 10. Every `critique.json` was re-judged by a reviewer other than the author; the typical overall score rose from about 6.3 to 7.0. +- The trim sheet's 14 custom rows are per asset. Define any number of materials; a conflict is two materials on one row in the same asset (`T3D_MATERIAL_CONFLICT` from `compile`), including assets composed with `ctx.use`. `T3D_SHEET_FULL` now means one asset maps onto more than 14. +- Breaking (0.x): `checkSheetFor(sheet, assets)` takes compiled assets, not UVs; `paintTrimSheet(recipe)` throws once two defined materials share a row (use `sheetFor`); `stripCredits` takes an optional material list. +- `t3d build --sheet external` writes an asset's own `trim_sheet_*.png` beside its GLBs when its materials cannot share the run's sheet; `--sheet embed` bytes no longer depend on what else the run loaded. A single-recipe build no longer paints rows of materials it defines but never maps onto. +- `sheet.png` and `thumb.png` show the hero's base colour (trim-sheet albedo × vertex colour, flat per triangle) and draw glass, ice and liquid parts see-through. Wood, bark, leather and terrain no longer read white or grey in the sheet (ADR 007 revisited). Every committed `sheet.png` and `thumb.png` changed. `blueprint.png` stays vertex colour. + ## [0.14.0] - 2026-11-19 Several agents can share one machine through a resource queue, the npm package shrinks from 40 MB to 4 MB, CI runs in under five minutes, and the check that committed renders are fresh now works. diff --git a/CLAUDE.md b/CLAUDE.md index caf1e4b3..847d706a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -12,7 +12,7 @@ project that installed the package, read `node_modules/@developerz.ai/ts23d/CLAU - **Real units and references.** Metres, Z up, +X front. Vehicles/buildings declare `real` + `sources` + spec `measures`; gates: `proportions` ±5%, `measures` ±2%. Parts touch their supports (`floating-parts`); moving parts clear everything (`clashes`); no slit you can see light through (`gaps`; real openings declared with a `why`). - **LOD-gate, never decimate.** Recipes read `ctx.lod` and choose what to emit. Imported and model-built meshes (scans, CC0 base meshes, image-to-3D output) are the one exception: they have no recipe to gate, so `simplify` or the Blender `retopo`/`lods` steps may decimate them (gated: bbox, surface, tunnels, UV), never code-built geometry (ADR 011, 016). - **One material.** Shared trim sheet, vertex colour; one draw per moving pivot (plus one merged static body), capped by `budget.draws`. Exception (ADR 016): a model-built part may carry its own `TextureSet` (albedo, normal, ORM; on every LOD; no `paint`/`finish`); declare `budget.textureSets { count, size }`; one material per set. -- **See the result.** Every asset has a contact sheet (`sheet.png`) and a beauty render (`hero.png`); every error and QA finding has a `T3D_*` code and a `fix:`. +- **See the result.** Every asset has a contact sheet (`sheet.png`: six views in the hero's base colours, trim-sheet albedo × vertex colour) and a beauty render (`hero.png`); every error and QA finding has a `T3D_*` code and a `fix:`. - **Enforce rules.** A rule without a script in `bun run verify` is a suggestion. Every defect found once gets a row in `docs/architecture/defect-catalogue.md` and a check that fails on it before the fix. ## Project and stack diff --git a/README.md b/README.md index 777dbb27..8259bf27 100644 --- a/README.md +++ b/README.md @@ -92,7 +92,7 @@ Each asset is a TypeScript module. `t3d build` compiles it, deterministically, t - **Code-level checks.** The recipe states its physical intent and QA enforces it at every LOD: `checks: [clear('track_*', 'hull_*'), noOverlap('road_wheel_l_*'), touches('turret_body', 'hull_top'), symmetric('_l', '_r', 'y')]`. "The track hits the frame" becomes a failing build. - **Textures from code.** A procedural albedo / normal / ORM trim sheet (bricks, planks, plates, slate, foliage), written once and shared by every GLB, plus three.js TSL and Godot shader sources. - **Spec-sheet fidelity.** Declare `real: { length, width, height, measures }` with `sources`. QA holds the overall size to ±5% and each named dimension (driver diameter, gauge, wheelbase) to ±2%. Fix the model, never the spec. -- **A contact sheet.** One PNG, six labelled orthographic views on a metre grid, rendered on the CPU. A vision-capable agent reads it once, sees what's wrong and fixes it. +- **A contact sheet.** One PNG, six labelled orthographic views on a metre grid, rendered on the CPU in the asset's base colours (trim-sheet albedo × vertex colour, glass see-through). A vision-capable agent reads it once, sees what's wrong and fixes it. - **A beauty render and an AI review pack.** `t3d hero` renders a textured, lit, soft-shadowed 3/4 product shot on the CPU (the images above). `t3d review` writes hero, sheet, close-ups, an LOD strip, a checklist prompt for a vision agent and image metrics: QA with pictures, no GPU. - **Organic modelling.** `sdf` (surface nets / marching cubes) with `sd.*` combinators and `sculpt`, an ordered add / subtract / paint edit list with smooth blends: busts, rocks, asteroids. - **Draw → 3D.** An agent writes SVG (drawing as text) and ts23d builds from it: `extrudeSvg` (holes, chamfered edges), `latheSvg` (half profile), and `visualHull`, a front + side (+ top) silhouette block-out you refine with sculpt edits ([`svg_showcase`](recipes/svg_showcase/)). @@ -222,7 +222,7 @@ Draw calls column: static assets (the Eiffel Tower) are 1; vehicles are one per | Optimisation | `passes/optimize`, `export` | Shipped: weld, degenerate removal, Forsyth vertex-cache + vertex-fetch order (ACMR reported), weighted normals, baked AO, u16 indices and colours, batching. Planned: opt-in `web` profile (quantisation + meshopt) | meshoptimizer / gltfpack | | LODs | `ctx.lod` | Shipped | Decimators | | QA | `qa` | Shipped: budget, surface-contact floating parts, motion clashes, names, proportions, spec measures, non-finite, winding, hidden parts, degenerate triangles, cross-LOD triangles; opt-in z-fighting, LOD silhouette and pivots. `/testing` helpers | Manual review | -| Renders and photo match | `render` | Shipped: contact sheet, beauty `hero` render (raster, or `--quality path` CPU path tracing), `review` pack for a vision agent, `photoMatch` with a camera solve, `silhouetteIoU` gate | — | +| Renders and photo match | `render` | Shipped: contact sheet (cutout cards alpha-tested), beauty `hero` render (raster, or `--quality path` CPU path tracing; `glow` parts emit), per-asset hero view (`hero: { azDeg, elDeg, fovDeg }` or `{ eye, target }` on `defineAsset`; `--az` / `--el` / `--fov` override), `review` pack for a vision agent, `photoMatch` with a camera solve, `silhouetteIoU` gate | — | | GLB export | `export` | Shipped: faces +Z, seamless loops, trim-sheet textures, punctual lights, emissive glow, XMP provenance, 0 glTF-Validator errors and warnings (tested) | — | | Engine import adapters | `threeMaterialSource` (TSL), `godotShaderSource` | Shipped: shader sources with wind, window glow, wear. Planned, M3: import settings and collision naming per engine, as hooks, not runtime | — | @@ -305,7 +305,7 @@ bunx -p @developerz.ai/ts23d t3d --version # also: t3d ` | Output directory (default `out`) | | `--no-shot` | `build` without rendering the contact sheet | -| `--sheet external\|embed\|none` | Trim-sheet textures. `external` (default): `out/trim_sheet_{albedo,normal,orm}.png` written once, every GLB references `../trim_sheet_*.png`. `embed`: inside each GLB. `none`: vertex colour only | +| `--sheet external\|embed\|none` | Trim-sheet textures. `external` (default): `out/trim_sheet_{albedo,normal,orm}.png` written once, every GLB references `../trim_sheet_*.png`; an asset whose material sits on a row the shared sheet already shows another material on (this run or an earlier one into the same `--out`, recorded in `trim_sheet_owners.json`) gets its own `out//trim_sheet_*.png`. `embed`: inside each GLB. `none`: vertex colour only | | `--sheet-size 512\|1024\|2048` | Sheet resolution (default 1024) | | `--lods 0,1,2` | Which detail levels to build (default all three). `--lods 0` = hero mesh only, `--lods 0,2` = near + far. QA and the manifest cover exactly what was built | | `--no-animations` | Skip the baked `run` clip. `t3d build` bakes it by default so viewers (e.g. VS Code glTF Tools) show play controls | @@ -339,18 +339,18 @@ compiles every recipe in a worker). ```ts // build.ts → bun build.ts -import { compile, contactSheet, DEFAULT_SHEET, paintTrimSheet, runQa, toGlb } from '@developerz.ai/ts23d'; +import { compile, contactSheet, DEFAULT_SHEET, runQa, sheetFor, toGlb } from '@developerz.ai/ts23d'; import { tiger_1 } from './recipes/tiger_1/tiger_1.ts'; -const sheet = paintTrimSheet({ ...DEFAULT_SHEET, size: 512 }); // textures are optional +const lods = ([0, 2] as const).map((lod) => compile(tiger_1, { lod })); // only the detail levels you need +const sheet = sheetFor(lods, { ...DEFAULT_SHEET, size: 512 }); // this asset's own trim sheet -for (const lod of [0, 2] as const) { // only the detail levels you need - const asset = compile(tiger_1, { lod }); +for (const asset of lods) { const findings = runQa(asset); // gate it your way, or skip it if (findings.length) throw new Error(findings.map((f) => `${f.message} — fix: ${f.fix}`).join('\n')); - await Bun.write(`out/tiger_1.lod${lod}.glb`, toGlb(asset, { sheet, animations: true })); + await Bun.write(`out/tiger_1.lod${asset.lod}.glb`, toGlb(asset, { sheet, animations: true })); } -await Bun.write('out/tiger_1.png', contactSheet(compile(tiger_1, { lod: 0 }))); // for your agent's eyes +await Bun.write('out/tiger_1.png', contactSheet(lods[0] ?? compile(tiger_1), { sheet })); // for your agent's eyes ``` Runnable copy: [`examples/build-with-bun.ts`](examples/build-with-bun.ts) — executed in CI, so this path can't rot. @@ -361,8 +361,8 @@ Runnable copy: [`examples/build-with-bun.ts`](examples/build-with-bun.ts) — ex | `runQa(compiled)` / single gates / `inspect(compiled)` | findings with fixes; geometry queries for your own checks | | `toGlb(compiled, { sheet, animations, keepParts })` | GLB bytes (`Uint8Array`) — write them anywhere | | `mergeToPivots(compiled)` | the batched part list the GLB uses (draw calls = movable parts) | -| `contactSheet(compiled, { far, cell })` | six-view PNG bytes | -| `paintTrimSheet(recipe)` + `sheetPngs(sheet)` | the texture set (albedo / normal / ORM) as RGBA or PNG | +| `contactSheet(compiled, { far, cell, sheet })` | six-view PNG bytes; with `sheet` in the hero's base colours, without it vertex colour only | +| `sheetFor(compiled, recipe)` + `sheetPngs(sheet)` | the asset's own texture set (albedo / normal / ORM) as RGBA or PNG | | `threeMaterialSource(hints)` / `godotShaderSource(hints)` | shader source strings for your engine | | `manifest` data | build it from `compiled.parts` (pivots, emitters, sockets) — see `src/cli/manifest.ts` | @@ -503,7 +503,7 @@ As of 2026-10. Full matrix: [docs/idea/07-what-fits.md](docs/idea/07-what-fits.m | Fit | Asset categories | |---|---| | **Strong** | Hard-surface props, architecture (facades, towers), vehicles (tracked, wheeled, rail), modular kits, anything with real dimensions or repeated parts | -| **Shipped, early** | Vegetation: Weber–Penn trees (oak, pine, palm, birch, willow); LOD2 impostors are crude | +| **Shipped, early** | Vegetation: Weber–Penn trees (oak, pine, palm, birch, willow); LOD2 is the tree's own crown as card clumps over the trunk (oak, pine and palm hold 0.8 of the near silhouette; birch and willow less) | | **Shipped, early** | Stylised organic: `sculpt` busts, SDF rocks and asteroids, eroded terrain. Boats: lofted `hull` | | **Shipped, early** | Stylised creatures: `creature()` over a skeleton with per-family biology (`recipes/wolf`); [animal research](docs/research/animal-anatomy.md) | | **Shipped, early** | Model-first humanoids: [`recipes/ranger`](recipes/ranger/README.md), an image-to-3D body with the rig service's skin and clips, finished by Blender steps (As of 2026-11: QA PASS; no finger bones, no blink or jaw, hair as sculpted clumps) | diff --git a/apps/site/CLAUDE.md b/apps/site/CLAUDE.md index 66c16125..dd6be000 100644 --- a/apps/site/CLAUDE.md +++ b/apps/site/CLAUDE.md @@ -11,7 +11,7 @@ The gate is the repo root’s: `bin/check` (see the root `CLAUDE.md`). - `index.html` — skeleton (canonical, Open Graph/Twitter meta with `media/tiger_1/hero.webp`, `