@developerz.ai/ts23d 0.0.0-stage → 0.1.0

package/recipes/goblin_head/README.md

@@ -0,0 +1,62 @@
+# 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 humped nose**, a **wide toothy grin**, **big amber eyes** under a light brow,
+a few **wiry hair tufts** and warts on a bald dome, and a **draped hood** on narrow shoulders.
+
+## 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.236 × 0.322 × 0.366 | `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 | 0.072 / 0.15 | 0.014 / pupils 0.057 apart | eyes 1.4 × human relative size |
+| ears length / width / sweep / lift | 0.62 / 0.30 / 22° / 18° | 0.118 long | two tapered blades + hollow |
+| nose length / bridge / hook | 0.20 / 0.12 / 0.07 | tip ≈ 0.05 past the face | cone from between the eyes |
+| mouth half-width / grin | 0.20 / 0.75 | | corners lifted, teeth rows |
+| neck radius / shoulders | 0.20 / 0.75 | 0.038 / 0.143 | |
+
+## Palette (sRGB)
+| Role | Hex |
+|---|---|
+| skin / shade / lips | `#9cb84a` / `#6a8a2c` / `#7a8e36` |
+| eyes: sclera / iris | `#f0e6a0` / `#e0a020` |
+| teeth / mouth | `#e8dcae` / `#3a1010` |
+| hair tufts | `#3a3024` |
+| hood cloth / patch + cord leather | `#6a4a7a` / `#5a3a22` |
+
+## 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. LOD0/1 bake vertex AO across all parts (16/10 rays); LOD2 drops
+warts, wiry tufts and the AO bake, and floors ear thickness at 0.7 cells so ears stay attached.
+
+## 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
+Teeth sit deep in the grin and read only up close; no earrings or wrinkles; hood is a smooth roll
+with one patch.

package/recipes/goblin_head/goblin_head.ts

@@ -0,0 +1,36 @@
+// Stylised goblin bust — an original design in the chunky hand-painted fantasy idiom: huge leaf
+// ears, long humped nose, wide toothy grin, big amber eyes, a few wiry hair tufts, warts, and a
+// draped hood on narrow shoulders. 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: huge pointed ears, long humped nose, toothy grin, amber eyes, hood',
+  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.236,
+    width: 0.322,
+    height: 0.366,
+    measures: [
+      {
+        label: 'eye spacing (pupil to pupil)',
+        value: 0.057,
+        axis: 'y',
+        between: ['eye_l', 'eye_r'],
+        source: '0.15 × 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,64 @@
+# 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.
+
+## 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.464 × 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 |
+
+## 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` |
+
+## 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. LOD0/1 bake vertex AO across all parts (16/10 rays); LOD2 drops
+warts, wiry tufts and the AO bake, and floors ear thickness at 0.7 cells so ears stay attached.
+
+## 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,37 @@
+// 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 cloak roll. 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.464,
+    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.