@developerz.ai/ts23d 0.0.0-stage → 0.2.0

package/recipes/goblin_head/README.md

@@ -0,0 +1,75 @@
+# Goblin bust — original stylised design
+
+## Identity
+A sly, scrawny goblin tinker, read from the 3/4 view by: **huge leaf-shaped ears** wider than its
+shoulders, a **long hooked nose** (one form drawn out to a drooping point, nostrils tucked at its
+base), a **wide grin** of small pointed teeth with the cheeks bunched up beside it, **big amber eyes
+under heavy upper lids**, a **worried creased brow**, a **sharp little chin**, **pale wispy hair**
+straggling off a warty dome, a **skinny corded neck** on **narrow bony shoulders** in a linen shirt,
+leather vest, strap and buckle, a **knotted scarf** and a **hood worn down** on the back — cut as a
+collectible bust on a turned plinth.
+
+## Design spec (head units: 1 = chin to crown = 0.19 m, ≈ 0.8 × human)
+| Feature | Value (units) | Metres | Note |
+|---|---|---|---|
+| chin → crown | 1.00 | 0.190 | the `height` param |
+| overall bust L × W × H | — | 0.227 × 0.342 × 0.372 | `real`, ±5 %; width is the ears |
+| cranium width / depth / above eye line | 0.66 / 0.84 / 0.50 | 0.125 / 0.160 / 0.095 | |
+| eyeball radius / spacing / upper lid | 0.08 / 0.155 / 30° | 0.015 / pupils 0.059 apart | eyes 1.5 × human relative size, heavy lids |
+| ears length / width / sweep / lift | 0.66 / 0.30 / 24° / 6° | 0.125 long | two tapered blades + hollow, near level |
+| nose length / bridge / hook / tip | 0.20 / 0.13 / 0.065 / 0.046 | | bridge cone + hump + tip + drooping point cone |
+| mouth half-width / grin | 0.21 / 0.80 | | crescent cut, 3 + 3 pointed teeth a side, tongue |
+| forehead creases / chin | 3 / 0.72 | | creases painted (thinner than a cell) |
+| neck radius / shoulders / mass | 0.14 / 0.52 / 0 | 0.027 / 0.099 | bony: clavicles under the shirt |
+
+## Palette (sRGB)
+| Role | Hex |
+|---|---|
+| skin / shade / lips | `#9cb84a` / `#6a8a2c` / `#7a8e36` |
+| eyes: sclera / iris | `#f0e6a0` / `#e0a020` |
+| teeth / mouth | `#e8dcae` / `#3a1010` |
+| wispy hair | `#c8c0b0` |
+| linen shirt / vest + strap (×0.65) / scarf / hood / buckle | `#b8a47c` / `#6b4428` / `#9a3a24` / `#4e5e3a` / `#a88a4a` |
+| plinth / cut faces | `#6f6c6c` (linear 0.16, 0.15, 0.15) / ×1.3 |
+
+## Parts the engine needs
+| Part | Pivot | Motion |
+|---|---|---|
+| `bust` | origin, base on z = 0 | static |
+| `head` | origin | static (skull, neck, ears, hair) |
+| `jaw` | jaw hinge (in front of the ear), opens about +Y | static by default; `head(ctx, { jawSway: 4 })` bakes a sway with `clearOf: ['head']` |
+| `eye_l`, `eye_r` | eyeball centres, gaze +X | static; rotate them to aim |
+
+The jaw region is the chin + lower lip (an ellipsoid cut flat at the mouth line), so its seam runs
+along the lips, the marionette lines and under the chin. Its cut faces are painted mouth-dark for
+when it opens; it laps 0.75 cells over the head so no gap shows.
+
+## LODs
+Sculpt cell = 2 % / 4.5 % / 14 % of head height (bust 1.6 ×). LOD0/1 bake vertex AO across all
+parts (16/10 rays); every LOD carries the painted tone. LOD1/2 carve the grin as a plain wide line
+(no teeth or tongue: a crescent that thin folds over at coarse cells); LOD2 drops warts, hair and
+the AO bake, floors ear thickness and the nose's radii at about a cell, and makes the plinth one
+drum so the bust stays on the ground.
+
+## References (stylised anatomy, not likeness)
+| Topic | Link | Used for |
+|---|---|---|
+| Loomis head: eye line at half height, brow/nose/chin thirds | https://finearttutorials.com/guide/loomis-method/ | human eye line 0.5, nose base 0.32, mouth 0.22 |
+| Proportions of the head (ears between brow and nose base, head ≈ 5 eyes wide) | https://artyfactory.com/portraits/pencil-portraits/proportions-of-a-head.html | ear placement, eye size vs head width |
+| Primary → secondary → tertiary forms (block brow/cheek/jaw first, then cut lids and folds) | https://www.creativebloq.com/how-to/how-to-sculpt-and-pose-a-cartoon-head-in-zbrush | the edit order in `head-face.ts` |
+| Goblin from a base head: enlarge the top of the head, elongate the ears, broaden their base | https://create.roblox.com/docs/art/characters/creating/sculpting | cranium and ear roots |
+| Goblin sculpt breakdown: big nose, cracked grin, ears, sparse hair | https://www.foxrenderfarm.com/share/how-to-create-goblin-in-zbrush | feature priorities |
+| Goblin features: large pointed ears, mischievous grin with visible teeth | https://sketchok.com/other/monsters-and-fantasy-creatures/how-to-draw-a-goblin/ | grin + teeth |
+| Orc: widen head and jawline to break human proportion | https://www.creativebloq.com/3d/how-create-orc-zbrush-61411834 | orc jaw width 0.37 vs human 0.22 |
+| Stylised orc head study (silhouette, form language) | https://blenderartists.org/t/orc-head-study-stylized-characters/1655542 | massing check |
+| Stylised hair: large clumps first, hairline → crown, one primary flow direction | https://gamesartist.co.uk/curly-hair-ls/ · https://www.cgchannel.com/2023/03/tutorial-creating-stylized-hairstyles-using-zbrush | `swept` locks in head-hair.ts |
+| Dreams (Media Molecule, Evans, SIGGRAPH 2015): sculptures as ordered SDF edits + smooth-min | https://www.mediamolecule.com/blog/article/siggraph_2015 · slides https://advances.realtimerendering.com/s2015/AlexEvans_SIGGRAPH-2015-sml.pdf | the whole approach |
+
+Design is original: no character, logo, name or likeness from any game is copied. "Chunky
+hand-painted stylised fantasy" is the idiom (exaggerated primary forms, generous fillets, flat
+vertex colour with baked AO), not a specific source.
+
+## Known gaps
+Teeth are small at this scale and read best in the 3/4 view; the wisps are cone pairs, not hair
+cards; the jaw part's seam shows as a faint line at the mouth corners up close; garment edges are
+vertex-colour soft and the strap/buckle are simple shells.

package/recipes/goblin_head/goblin_head.ts

@@ -0,0 +1,38 @@
+// Stylised goblin bust — an original design in the chunky hand-painted fantasy idiom: huge leaf
+// ears, a long hooked nose, a wide grin of small pointed teeth, big amber eyes under heavy lids, a
+// worried creased brow, pale wispy hair, warts; a skinny neck and bony shoulders in a linen shirt,
+// leather vest, strap, knotted scarf and a hood worn down, cut as a collectible bust on a turned
+// plinth. The `head` kind sculpts it (race preset `goblin`, chin to crown 0.19 m); this file is the
+// spec. Design dossier: recipes/goblin_head/README.md.
+
+import { defineAsset, head } from '@developerz.ai/ts23d';
+
+export const goblin_head = defineAsset({
+  name: 'goblin_head',
+  kind: 'character',
+  description:
+    'Stylised goblin bust on a plinth: huge pointed ears, long hooked nose, toothy grin, heavy-lidded amber eyes, wispy hair, leather vest and scarf',
+  tags: ['character', 'fantasy', 'goblin', 'bust', 'sculpt'],
+  license: 'CC0-1.0',
+  sources: ['recipes/goblin_head/README.md (design dossier: proportions, palette, references)'],
+  // Design spec, not a real-world one: overall bust size and eye spacing from the dossier.
+  real: {
+    length: 0.227,
+    width: 0.342,
+    height: 0.372,
+    measures: [
+      {
+        label: 'eye spacing (pupil to pupil)',
+        value: 0.0589,
+        axis: 'y',
+        between: ['eye_l', 'eye_r'],
+        source: '0.155 × 2 × 0.19 m',
+      },
+    ],
+  },
+  // Measured: sculpt cells 2 % / 4.5 % / 14 % of head height (LOD0/1 also bake vertex AO).
+  budget: { triangles: [55800, 10900, 1560] },
+  build(ctx) {
+    head(ctx, { race: 'goblin' });
+  },
+});

package/recipes/human_head/README.md

@@ -0,0 +1,68 @@
+# Human hero bust — original stylised design
+
+## Identity
+A young adventurer, read from the 3/4 view by: **classical proportions pushed slightly heroic**
+(square jaw, strong brow, thick neck), **defined arched eyebrows**, **swept-back hair** in chunky
+tapered two-tone locks over a rounded hairline, a **clipped beard with chin volume and a drooping
+moustache**, clear blue eyes, a **blue tunic** with a standing leather collar, placket and brass
+buttons, and a **red mantle** over the shoulders pinned with a brass brooch — cut as a collectible
+bust (U-cut under the chest) on a turned plinth.
+
+## Design spec (head units: 1 = chin to crown = 0.23 m, adult human)
+| Feature | Value (units) | Metres | Note |
+|---|---|---|---|
+| chin → crown | 1.00 | 0.230 | adult menton–vertex ≈ 0.22–0.24 m |
+| overall bust L × W × H | — | 0.247 × 0.428 × 0.439 | `real`, ±5 % |
+| cranium width / depth | 0.66 / 0.86 | 0.152 / 0.198 | adult head breadth ≈ 0.15 m, length ≈ 0.19–0.20 m |
+| eye line | 0.50 | — | Loomis: half height |
+| eyeball radius / spacing | 0.052 / 0.135 | 0.012 / pupils 0.062 apart | human eyeball ≈ 24 mm; IPD ≈ 62 mm |
+| eye line → nose base | 0.18 | 0.041 | thirds: brow / nose / chin |
+| jaw half-width | 0.22 | 0.051 | bigonial ≈ 0.10 m |
+| ears | round, 0.27 long | 0.062 | between brow and nose base |
+| neck radius | 0.27 | 0.062 | heroic: thicker than average |
+| shoulders / mass | 0.95 / 0.5 (default) | 0.219 | pectorals, deltoids, trapezius under the tunic |
+
+## Palette (sRGB)
+| Role | Hex |
+|---|---|
+| skin / shade / lips | `#d9a07a` / `#a8644a` / `#b86b5c` |
+| eyes: sclera / iris | `#ece6dc` / `#3d6e9e` |
+| hair + beard (two-tone locks ×1.5) | `#5a3a22` |
+| tunic / mantle / collar, placket / brooch, buttons | `#2e4f8a` / `#7a2420` / `#6b4428` / `#c9a24a` |
+| plinth / cut faces | `#6f6c6c` (linear 0.16, 0.15, 0.15) / ×1.3 |
+
+## Parts the engine needs
+| Part | Pivot | Motion |
+|---|---|---|
+| `bust` | origin, base on z = 0 | static |
+| `head` | origin | static (skull, neck, ears, hair) |
+| `jaw` | jaw hinge (in front of the ear), opens about +Y | static by default; `head(ctx, { jawSway: 4 })` bakes a sway with `clearOf: ['head']` |
+| `eye_l`, `eye_r` | eyeball centres, gaze +X | static; rotate them to aim |
+
+The jaw region is the chin + lower lip (an ellipsoid cut flat at the mouth line), so its seam runs
+along the lips, the marionette lines and under the chin. Its cut faces are painted mouth-dark for
+when it opens; it laps 0.75 cells over the head so no gap shows.
+
+## LODs
+Sculpt cell = 2 % / 4.5 % / 14 % of head height (bust 1.6 ×). LOD0/1 bake vertex AO across all
+parts (16/10 rays); every LOD carries the painted tone (cavity, warm top, cool under). LOD2 drops
+the AO bake, floors ear thickness at 0.7 cells and makes the plinth one drum.
+
+## References (stylised anatomy, not likeness)
+| Topic | Link | Used for |
+|---|---|---|
+| Loomis head: eye line at half height, brow/nose/chin thirds | https://finearttutorials.com/guide/loomis-method/ | human eye line 0.5, nose base 0.32, mouth 0.22 |
+| Proportions of the head (ears between brow and nose base, head ≈ 5 eyes wide) | https://artyfactory.com/portraits/pencil-portraits/proportions-of-a-head.html | ear placement, eye size vs head width |
+| Primary → secondary → tertiary forms (block brow/cheek/jaw first, then cut lids and folds) | https://www.creativebloq.com/how-to/how-to-sculpt-and-pose-a-cartoon-head-in-zbrush | the edit order in `head-face.ts` |
+| Orc: widen head and jawline to break human proportion | https://www.creativebloq.com/3d/how-create-orc-zbrush-61411834 | orc jaw width 0.37 vs human 0.22 |
+| Stylised orc head study (silhouette, form language) | https://blenderartists.org/t/orc-head-study-stylized-characters/1655542 | massing check |
+| Stylised hair: large clumps first, hairline → crown, one primary flow direction | https://gamesartist.co.uk/curly-hair-ls/ · https://www.cgchannel.com/2023/03/tutorial-creating-stylized-hairstyles-using-zbrush | `swept` locks in head-hair.ts |
+| Dreams (Media Molecule, Evans, SIGGRAPH 2015): sculptures as ordered SDF edits + smooth-min | https://www.mediamolecule.com/blog/article/siggraph_2015 · slides https://advances.realtimerendering.com/s2015/AlexEvans_SIGGRAPH-2015-sml.pdf | the whole approach |
+
+Design is original: no character, logo, name or likeness from any game is copied. "Chunky
+hand-painted stylised fantasy" is the idiom (exaggerated primary forms, generous fillets, flat
+vertex colour with baked AO), not a specific source.
+
+## Known gaps
+Hair locks are tapered cone pairs (no strand grooves inside a lock); the beard's clump grooves are
+two shallow cuts; mantle colour edges are soft (vertex colour at 5 mm cells); no ear detail.

package/recipes/human_head/human_head.ts

@@ -0,0 +1,38 @@
+// Stylised human hero bust — an original design in the chunky hand-painted fantasy idiom:
+// classical proportions (eye line at half height, brow/nose/chin thirds) pushed slightly heroic —
+// square jaw, strong brow — with short swept hair, a short beard and moustache, a blue tunic,
+// leather collar and mantle, cut as a collectible bust on a turned plinth. The `head` kind sculpts
+// it (race preset `human`, chin to crown 0.23 m); this file is the spec. Design dossier:
+// recipes/human_head/README.md.
+
+import { defineAsset, head } from '@developerz.ai/ts23d';
+
+export const human_head = defineAsset({
+  name: 'human_head',
+  kind: 'character',
+  description:
+    'Stylised human hero bust: square jaw, swept hair, short beard, blue tunic and leather cloak roll',
+  tags: ['character', 'fantasy', 'human', 'bust', 'sculpt'],
+  license: 'CC0-1.0',
+  sources: ['recipes/human_head/README.md (design dossier: proportions, palette, references)'],
+  // Design spec, not a real-world one: overall bust size and eye spacing from the dossier.
+  real: {
+    length: 0.247,
+    width: 0.428,
+    height: 0.439,
+    measures: [
+      {
+        label: 'eye spacing (pupil to pupil)',
+        value: 0.0621,
+        axis: 'y',
+        between: ['eye_l', 'eye_r'],
+        source: '0.135 × 2 × 0.23 m — adult interpupillary ≈ 62 mm',
+      },
+    ],
+  },
+  // Measured: sculpt cells 2 % / 4.5 % / 14 % of head height (LOD0/1 also bake vertex AO).
+  budget: { triangles: [64000, 12700, 1720] },
+  build(ctx) {
+    head(ctx, { race: 'human' });
+  },
+});

package/recipes/loco_440/README.md

@@ -0,0 +1,32 @@
+# Jupiter — Central Pacific No. 60, 4-4-0 "American" (Schenectady 1868)
+
+## Identity
+The 1979 operating replica at Golden Spike National Historical Park, in its blue / red / gold
+Golden Spike livery. Signature features: balloon stack, oil headlamp on a bracket, brass bell and
+dome, cowcatcher pilot, wooden cab with arched windows, 4-wheel lead truck, two coupled drivers
+with side rods, an 8-wheel tender with JUPITER lettering. The recipe is a family over the Whyte
+arrangement: frame, boiler and rods are laid out from `'4-4-0'`.
+
+## Specs
+| Dimension | Value (m) | Source |
+|---|---|---|
+| driver diameter (5 ft 4 in) | 1.626 | https://en.wikipedia.org/wiki/Jupiter_(locomotive) |
+| cylinders | 16 × 24 in | https://en.wikipedia.org/wiki/Jupiter_(locomotive) |
+| track gauge | 1.435 | https://en.wikipedia.org/wiki/Standard-gauge_railway |
+| lead truck wheel diameter | 0.762 | typical for the type; not in the Jupiter infobox |
+| engine + tender length | ≈ 17.4 | estimated from the photo, drivers as ruler |
+| width / height | ≈ 2.8 / 4.6 | estimated from the photo, drivers as ruler |
+
+## Photos (by view)
+| View | URL | Notes |
+|---|---|---|
+| side, 3/4 | https://en.wikipedia.org/wiki/Jupiter_(locomotive) | replica at Promontory Summit |
+| type overview | https://en.wikipedia.org/wiki/4-4-0 | American type layout |
+| photo match | `docs/reference/loco-photo-match.png` | photo · model · overlay |
+
+## Parts the engine needs
+`axle_lead_*`, `axle_driver_*`, `axle_tender_*` (spin), side rods (orbit with the drivers),
+`emitter` smoke at the stack mouth.
+
+## Open questions
+Overall length, width and height are photo estimates (±5% gate), not published figures.