@casmo/tree.js 0.1.1 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (220) hide show
  1. package/README.md +312 -16
  2. package/dist/apply-Cio2t7CZ.js +285 -0
  3. package/dist/apply-Cio2t7CZ.js.map +1 -0
  4. package/dist/bake/index.d.ts +44 -5
  5. package/dist/bake/index.d.ts.map +1 -1
  6. package/dist/definition/crown-shape.d.ts +9 -0
  7. package/dist/definition/crown-shape.d.ts.map +1 -0
  8. package/dist/definition/defaults.d.ts +15 -1
  9. package/dist/definition/defaults.d.ts.map +1 -1
  10. package/dist/definition/index.d.ts +4 -3
  11. package/dist/definition/index.d.ts.map +1 -1
  12. package/dist/definition/migrations.d.ts +0 -8
  13. package/dist/definition/migrations.d.ts.map +1 -1
  14. package/dist/definition/schema.d.ts.map +1 -1
  15. package/dist/definition/types.d.ts +181 -6
  16. package/dist/definition/types.d.ts.map +1 -1
  17. package/dist/effects/mask.d.ts +3 -3
  18. package/dist/effects/mask.d.ts.map +1 -1
  19. package/dist/effects.js +3 -3
  20. package/dist/effects.js.map +1 -1
  21. package/dist/forest/Forest.d.ts +37 -2
  22. package/dist/forest/Forest.d.ts.map +1 -1
  23. package/dist/forest/nodes.d.ts +6 -1
  24. package/dist/forest/nodes.d.ts.map +1 -1
  25. package/dist/{forest-OX9WvAwh.js → forest-ChEaWJrf.js} +1763 -684
  26. package/dist/forest-ChEaWJrf.js.map +1 -0
  27. package/dist/generator/branches.d.ts +2 -2
  28. package/dist/generator/branches.d.ts.map +1 -1
  29. package/dist/generator/crown.d.ts +28 -0
  30. package/dist/generator/crown.d.ts.map +1 -0
  31. package/dist/generator/fruit.d.ts +28 -0
  32. package/dist/generator/fruit.d.ts.map +1 -0
  33. package/dist/generator/growth.d.ts +1 -1
  34. package/dist/generator/growth.d.ts.map +1 -1
  35. package/dist/generator/index.d.ts +5 -4
  36. package/dist/generator/index.d.ts.map +1 -1
  37. package/dist/generator/leaf-shapes.d.ts +33 -1
  38. package/dist/generator/leaf-shapes.d.ts.map +1 -1
  39. package/dist/generator/mesh.d.ts +10 -2
  40. package/dist/generator/mesh.d.ts.map +1 -1
  41. package/dist/generator/occlusion.d.ts +8 -0
  42. package/dist/generator/occlusion.d.ts.map +1 -0
  43. package/dist/generator/roots.d.ts +16 -0
  44. package/dist/generator/roots.d.ts.map +1 -0
  45. package/dist/generator/trunk.d.ts +16 -2
  46. package/dist/generator/trunk.d.ts.map +1 -1
  47. package/dist/generator/types.d.ts +61 -6
  48. package/dist/generator/types.d.ts.map +1 -1
  49. package/dist/growth/index.d.ts +1 -1
  50. package/dist/growth/index.d.ts.map +1 -1
  51. package/dist/growth/tsl.d.ts +2 -0
  52. package/dist/growth/tsl.d.ts.map +1 -1
  53. package/dist/index.d.ts +6 -3
  54. package/dist/index.d.ts.map +1 -1
  55. package/dist/index.js +274 -24
  56. package/dist/index.js.map +1 -1
  57. package/dist/materials/crown-nodes.d.ts +20 -0
  58. package/dist/materials/crown-nodes.d.ts.map +1 -0
  59. package/dist/materials/crown-normals.d.ts +17 -0
  60. package/dist/materials/crown-normals.d.ts.map +1 -0
  61. package/dist/materials/ground-tint.d.ts +13 -0
  62. package/dist/materials/ground-tint.d.ts.map +1 -0
  63. package/dist/materials/index.d.ts +13 -1
  64. package/dist/materials/index.d.ts.map +1 -1
  65. package/dist/materials/leaf-translucency-model.d.ts +14 -0
  66. package/dist/materials/leaf-translucency-model.d.ts.map +1 -0
  67. package/dist/materials/leaf-translucency.d.ts +73 -0
  68. package/dist/materials/leaf-translucency.d.ts.map +1 -0
  69. package/dist/materials/material-features.d.ts +43 -0
  70. package/dist/materials/material-features.d.ts.map +1 -0
  71. package/dist/materials/occlusion.d.ts +10 -0
  72. package/dist/materials/occlusion.d.ts.map +1 -0
  73. package/dist/materials/toon.d.ts +18 -1
  74. package/dist/materials/toon.d.ts.map +1 -1
  75. package/dist/names-BE9he6CS.js +713 -0
  76. package/dist/names-BE9he6CS.js.map +1 -0
  77. package/dist/react/Tree.d.ts +5 -2
  78. package/dist/react/Tree.d.ts.map +1 -1
  79. package/dist/react.js +10 -6
  80. package/dist/react.js.map +1 -1
  81. package/dist/season/nodes.d.ts +16 -0
  82. package/dist/season/nodes.d.ts.map +1 -1
  83. package/dist/season/profile.d.ts +26 -0
  84. package/dist/season/profile.d.ts.map +1 -1
  85. package/dist/species/almond.js +223 -0
  86. package/dist/species/almond.js.map +1 -0
  87. package/dist/species/almond.json +210 -0
  88. package/dist/species/apple.js +230 -0
  89. package/dist/species/apple.js.map +1 -0
  90. package/dist/species/apple.json +220 -0
  91. package/dist/species/ash.js +187 -0
  92. package/dist/species/ash.js.map +1 -0
  93. package/dist/species/ash.json +177 -0
  94. package/dist/species/beech.js +174 -0
  95. package/dist/species/beech.js.map +1 -0
  96. package/dist/species/beech.json +167 -0
  97. package/dist/species/birch.js +170 -0
  98. package/dist/species/birch.js.map +1 -0
  99. package/dist/species/birch.json +163 -0
  100. package/dist/species/catalog.d.ts +61 -0
  101. package/dist/species/catalog.d.ts.map +1 -0
  102. package/dist/species/cedar.js +169 -0
  103. package/dist/species/cedar.js.map +1 -0
  104. package/dist/species/cedar.json +168 -0
  105. package/dist/species/cherry.js +237 -0
  106. package/dist/species/cherry.js.map +1 -0
  107. package/dist/species/cherry.json +224 -0
  108. package/dist/species/chestnut.js +230 -0
  109. package/dist/species/chestnut.js.map +1 -0
  110. package/dist/species/chestnut.json +220 -0
  111. package/dist/species/douglas-fir.js +174 -0
  112. package/dist/species/douglas-fir.js.map +1 -0
  113. package/dist/species/douglas-fir.json +170 -0
  114. package/dist/species/elm.js +173 -0
  115. package/dist/species/elm.js.map +1 -0
  116. package/dist/species/elm.json +163 -0
  117. package/dist/species/hemlock.js +175 -0
  118. package/dist/species/hemlock.js.map +1 -0
  119. package/dist/species/hemlock.json +171 -0
  120. package/dist/species/hickory.js +200 -0
  121. package/dist/species/hickory.js.map +1 -0
  122. package/dist/species/hickory.json +192 -0
  123. package/dist/species/index.d.ts +10 -0
  124. package/dist/species/index.d.ts.map +1 -0
  125. package/dist/species/juniper.js +158 -0
  126. package/dist/species/juniper.js.map +1 -0
  127. package/dist/species/juniper.json +154 -0
  128. package/dist/species/loaders.d.ts +7 -0
  129. package/dist/species/loaders.d.ts.map +1 -0
  130. package/dist/species/mahogany.js +201 -0
  131. package/dist/species/mahogany.js.map +1 -0
  132. package/dist/species/mahogany.json +196 -0
  133. package/dist/species/maple.js +177 -0
  134. package/dist/species/maple.js.map +1 -0
  135. package/dist/species/maple.json +171 -0
  136. package/dist/species/oak.js +220 -0
  137. package/dist/species/oak.js.map +1 -0
  138. package/dist/species/oak.json +212 -0
  139. package/dist/species/olive.js +189 -0
  140. package/dist/species/olive.js.map +1 -0
  141. package/dist/species/olive.json +181 -0
  142. package/dist/species/peach.js +223 -0
  143. package/dist/species/peach.js.map +1 -0
  144. package/dist/species/peach.json +210 -0
  145. package/dist/species/pear.js +213 -0
  146. package/dist/species/pear.js.map +1 -0
  147. package/dist/species/pear.json +200 -0
  148. package/dist/species/pine.js +163 -0
  149. package/dist/species/pine.js.map +1 -0
  150. package/dist/species/pine.json +162 -0
  151. package/dist/species/plum.js +237 -0
  152. package/dist/species/plum.js.map +1 -0
  153. package/dist/species/plum.json +224 -0
  154. package/dist/species/red-oak.js +220 -0
  155. package/dist/species/red-oak.js.map +1 -0
  156. package/dist/species/red-oak.json +212 -0
  157. package/dist/species/redwood.js +174 -0
  158. package/dist/species/redwood.js.map +1 -0
  159. package/dist/species/redwood.json +170 -0
  160. package/dist/species/sequoia.js +167 -0
  161. package/dist/species/sequoia.js.map +1 -0
  162. package/dist/species/sequoia.json +166 -0
  163. package/dist/species/spruce.js +170 -0
  164. package/dist/species/spruce.js.map +1 -0
  165. package/dist/species/spruce.json +166 -0
  166. package/dist/species/teak.js +166 -0
  167. package/dist/species/teak.js.map +1 -0
  168. package/dist/species/teak.json +157 -0
  169. package/dist/species/types.d.ts +65 -0
  170. package/dist/species/types.d.ts.map +1 -0
  171. package/dist/species/walnut.js +220 -0
  172. package/dist/species/walnut.js.map +1 -0
  173. package/dist/species/walnut.json +212 -0
  174. package/dist/species/white-oak.js +213 -0
  175. package/dist/species/white-oak.js.map +1 -0
  176. package/dist/species/white-oak.json +208 -0
  177. package/dist/species.js +160 -0
  178. package/dist/species.js.map +1 -0
  179. package/dist/styles/apply.d.ts +12 -0
  180. package/dist/styles/apply.d.ts.map +1 -0
  181. package/dist/styles/low-poly/index.d.ts +1 -1
  182. package/dist/styles/low-poly/index.d.ts.map +1 -1
  183. package/dist/styles/low-poly.js +13 -10
  184. package/dist/styles/low-poly.js.map +1 -1
  185. package/dist/styles/material-features.d.ts +27 -0
  186. package/dist/styles/material-features.d.ts.map +1 -0
  187. package/dist/styles/names.d.ts +28 -0
  188. package/dist/styles/names.d.ts.map +1 -0
  189. package/dist/styles/realistic/index.d.ts +3 -8
  190. package/dist/styles/realistic/index.d.ts.map +1 -1
  191. package/dist/styles/realistic/textures.d.ts +20 -0
  192. package/dist/styles/realistic/textures.d.ts.map +1 -0
  193. package/dist/styles/realistic.js +14 -18
  194. package/dist/styles/realistic.js.map +1 -1
  195. package/dist/styles/registry.d.ts +2 -13
  196. package/dist/styles/registry.d.ts.map +1 -1
  197. package/dist/styles/stylized/index.d.ts +1 -1
  198. package/dist/styles/stylized/index.d.ts.map +1 -1
  199. package/dist/styles/stylized.js +13 -10
  200. package/dist/styles/stylized.js.map +1 -1
  201. package/dist/styles/types.d.ts +16 -2
  202. package/dist/styles/types.d.ts.map +1 -1
  203. package/dist/textures/realistic/bark-fibrous-normal.png +0 -0
  204. package/dist/textures/realistic/bark-fibrous.png +0 -0
  205. package/dist/textures/realistic/bark-papery-normal.png +0 -0
  206. package/dist/textures/realistic/bark-papery.png +0 -0
  207. package/dist/textures/realistic/bark-plated-normal.png +0 -0
  208. package/dist/textures/realistic/bark-plated.png +0 -0
  209. package/dist/textures/realistic/bark-smooth-normal.png +0 -0
  210. package/dist/textures/realistic/bark-smooth.png +0 -0
  211. package/dist/textures/realistic/leaf-compound.png +0 -0
  212. package/dist/textures/realistic/leaf-lobed.png +0 -0
  213. package/dist/textures/realistic/leaf-palmate.png +0 -0
  214. package/dist/textures/realistic/scale.png +0 -0
  215. package/dist/tree/Tree.d.ts +34 -5
  216. package/dist/tree/Tree.d.ts.map +1 -1
  217. package/package.json +9 -2
  218. package/dist/forest-OX9WvAwh.js.map +0 -1
  219. package/dist/types-BZjHhNz7.js +0 -20
  220. package/dist/types-BZjHhNz7.js.map +0 -1
package/README.md CHANGED
@@ -12,14 +12,17 @@ thousands at once as an instanced Forest, add opt-in Tree Effects, or design you
12
12
  - [Quick start](#quick-start)
13
13
  - [WebGPURenderer is required](#webgpurenderer-is-required)
14
14
  - [Styles](#styles)
15
+ - [Species](#species)
15
16
  - [Tree Definitions and Seeds](#tree-definitions-and-seeds)
16
17
  - [Growth and Season](#growth-and-season)
17
18
  - [Wind](#wind)
18
19
  - [Forests](#forests)
20
+ - [Material Features](#material-features)
19
21
  - [Tree Effects](#tree-effects)
20
22
  - [React Three Fiber](#react-three-fiber)
21
23
  - [Without a bundler: import map (CDN)](#without-a-bundler-import-map-cdn)
22
24
  - [Baked Trees (glTF export)](#baked-trees-gltf-export)
25
+ - [Using a Baked Tree in other engines](#using-a-baked-tree-in-other-engines)
23
26
  - [Textures](#textures)
24
27
  - [Tree Editor](#tree-editor)
25
28
  - [Examples](#examples)
@@ -37,6 +40,7 @@ npm install @casmo/tree.js three
37
40
  | --- | --- |
38
41
  | `@casmo/tree.js` | `createTree`, `createForest`, Definitions, Wind, Baked Tree export, `loadStyle`, ... |
39
42
  | `@casmo/tree.js/styles/low-poly` (`stylized`, `realistic`) | a built-in Style: one Tree Definition per Form (a few kB of data) |
43
+ | `@casmo/tree.js/species` | the 28 Species (`oak`, `douglasFir`, ...), `loadSpecies`, `SPECIES_NAMES`; JSON files |
40
44
  | `@casmo/tree.js/effects` | Tree Effects (post-processing) |
41
45
  | `@casmo/tree.js/react` | `<Tree>`, `<Forest>`, `<Wind>`, `useTreeStyle` for React Three Fiber |
42
46
 
@@ -70,8 +74,8 @@ scene.add(tree);
70
74
  renderer.setAnimationLoop(() => renderer.render(scene, camera));
71
75
  ```
72
76
 
73
- A `Tree` is a three.js `Group` with two meshes, `tree.wood` and `tree.leaves` (both cast and receive
74
- shadows). `tree.dispose()` frees its geometries and materials and removes it from the scene.
77
+ A `Tree` is a three.js `Group` with three meshes, `tree.wood`, `tree.leaves` and `tree.fruit` (empty
78
+ without Fruit; all cast and receive shadows). `tree.dispose()` frees its geometries and materials and removes it from the scene.
75
79
 
76
80
  ## WebGPURenderer is required
77
81
 
@@ -130,6 +134,52 @@ const tallPine = createTree(extendDefinition(stylized.conifer, { trunk: { length
130
134
  scene.add(oak, pine, birch, tallPine);
131
135
  ```
132
136
 
137
+ ## Species
138
+
139
+ [![All 28 Species, each in the low-poly, stylized and realistic Styles](docs/species/contact-sheet.jpg)](docs/species/README.md)
140
+
141
+ *Every Species in `low-poly`, `stylized` and `realistic`; the [Species gallery](docs/species/README.md) has larger
142
+ images (with Fruit or in autumn), a code example and the JSON of each.*
143
+
144
+ 28 real trees ship with the library, each described once by its shape (Stems, Crown Shape), Leaf Type, Bark
145
+ Type, Fruit, colours and Season Profile, and drawn in any Style:
146
+
147
+ ```ts
148
+ import { createTree, loadStyle } from '@casmo/tree.js';
149
+ import { oak } from '@casmo/tree.js/species';
150
+ scene.add(createTree((await loadStyle('realistic')).apply(oak), { seed: 42 }));
151
+ ```
152
+
153
+ - **Broadleaf**: `almond`, `apple`, `ash`, `beech`, `birch`, `cherry`, `chestnut`, `elm`, `hickory`, `mahogany`, `maple`, `oak`, `olive`, `peach`, `pear`, `plum`, `redOak`, `teak`, `walnut`, `whiteOak`
154
+ - **Conifer**: `cedar`, `douglasFir`, `hemlock`, `juniper`, `pine`, `redwood`, `sequoia`, `spruce`
155
+
156
+ `style.apply(species, overrides?)` returns an ordinary, complete Tree Definition, so it works everywhere a
157
+ Definition does (`createTree`, `createForest`, Baked Trees, the Tree Editor). Each Species is its own module:
158
+ importing two doesn't bundle the other 26.
159
+
160
+ ```ts
161
+ import { createForest, createTree } from '@casmo/tree.js';
162
+ import { apple, douglasFir, loadSpecies, SPECIES_NAMES, type SpeciesName } from '@casmo/tree.js/species';
163
+ import lowPoly from '@casmo/tree.js/styles/low-poly';
164
+ import stylized from '@casmo/tree.js/styles/stylized';
165
+
166
+ const tallFir = createTree(stylized.apply(douglasFir, { trunk: { length: 14 } }), { seed: 3 });
167
+ const orchard = createForest(lowPoly.apply(apple), [
168
+ { id: 'a', position: [0, 0, 0] },
169
+ { id: 'b', position: [5, 0, 1] },
170
+ ]);
171
+
172
+ // At runtime, e.g. from level data: a dynamic import per Species (rejects unknown ids).
173
+ const name: SpeciesName = SPECIES_NAMES.includes('birch') ? 'birch' : 'oak';
174
+ const birch = createTree(lowPoly.apply(await loadSpecies(name)), { season: 0.6 });
175
+ scene.add(tallFir, orchard, birch);
176
+ ```
177
+
178
+ `SPECIES_BY_NAME` maps every id to its Species (for a picker that lists them all; it bundles all 28).
179
+ Without a bundler, every Species is also a plain JSON file: `@casmo/tree.js/species/<id>.json` (for example
180
+ `https://cdn.jsdelivr.net/npm/@casmo/tree.js/dist/species/douglas-fir.json`). In React:
181
+ `<Tree species={oak} style={lowPoly} seed={7} />`. Try them all in [`examples/species`](examples/species/main.ts).
182
+
133
183
  ## Tree Definitions and Seeds
134
184
 
135
185
  ![Five birches grown from the same Tree Definition with Seeds 1 to 5](docs/images/seeds.png)
@@ -146,8 +196,7 @@ always give exactly the same tree.
146
196
  import { createTree, fetchDefinition, parseDefinition, TreeDefinitionError, type TreeDefinitionInput } from '@casmo/tree.js';
147
197
 
148
198
  const birch: TreeDefinitionInput = {
149
- schemaVersion: 2,
150
- form: 'broadleaf',
199
+ schemaVersion: 3,
151
200
  trunk: { length: 6, radius: 0.15 },
152
201
  branches: [
153
202
  { count: 6, angle: 45 },
@@ -162,13 +211,123 @@ const fromEditor = await fetchDefinition('/trees/my-oak.json'); // a Tree Editor
162
211
  const tree = createTree(fromEditor, { seed: 7 });
163
212
 
164
213
  try {
165
- parseDefinition('{"schemaVersion": 2, "trunk": {"length": -1}}');
214
+ parseDefinition('{"schemaVersion": 3, "trunk": {"length": -1}}');
166
215
  } catch (error) {
167
216
  if (error instanceof TreeDefinitionError) console.warn(error.field, error.message); // 'trunk.length'
168
217
  }
169
218
  ```
170
219
 
171
- Older Definitions (lower `schemaVersion`) are migrated when parsed. `extendDefinition(base, patch)`
220
+ Each branch level can carry a **Crown Shape**: optional `lengthProfile` and `angleProfile` keyframe
221
+ curves over where a branch sits on its parent (0 = base .. 1 = tip) that multiply the level's `length`
222
+ and `angle` (linear between keyframes, flat = 1 when absent). A cone is
223
+ `lengthProfile: [{ t: 0.2, value: 1 }, { t: 1, value: 0.1 }]` on the first level; a ball, column, vase
224
+ or flat top are other curves.
225
+
226
+ A tree can grow several **Stems** from the ground: `trunk: { stems: 3, spread: 20 }` stands three full
227
+ trunks (each with the whole branch structure) in a small ring, leaning out about 20° from vertical (the
228
+ Seed varies each lean). `trunk.gravity` (−1..1) bends only the leader, the top third of each Stem: −1 makes
229
+ it nod like a hemlock's. Absent, a tree has one upright Stem without gravity.
230
+
231
+ A **Root Flare** widens each Stem towards the ground: `trunk.flare` (0..1) eases the bottom ~12% of the
232
+ Stem's length out to (1 + 0.8 × `flare`) × the trunk radius at the base, so the trunk grows into the soil
233
+ instead of standing on it like a post. It is geometry only: branches, leaves, Fruit, Growth, Wind and Sculpts
234
+ stay exactly where they were. The optional `flareSections` (integer ≥ 1) is how many extra rings the flare
235
+ gets, set by `Style.apply` (2 in low-poly, 3 in the others; absent = 3). Absent `flare` means none. Every
236
+ trunk's base ring sits a tenth of its radius below the ground (also without flare), so no seam shows on
237
+ uneven terrain:
238
+
239
+ ```ts
240
+ import { createTree, extendDefinition, type TreeDefinitionInput } from '@casmo/tree.js';
241
+
242
+ const oak: TreeDefinitionInput = { schemaVersion: 3, trunk: { length: 5, radius: 0.35, flare: 0.8 } };
243
+ const flared = createTree(oak, { seed: 3 });
244
+ const slender = extendDefinition(oak, { trunk: { flare: 0.15 } }); // a hint of a flare, same crown
245
+ ```
246
+
247
+ **Roots** are an optional `roots` block: a few Roots grow from the Root Flare of every Stem, run outward
248
+ and down, taper to a point and vanish below the ground. `count` is Roots per Stem (0..12), `length` a
249
+ fraction of the Stem's length (`lengthVariation` is the Seed's ± range), `radius` a fraction of the trunk's
250
+ base radius, `angle` how steeply they dive (degrees below horizontal, 0..60) and `bend` how much they wander
251
+ sideways. A partial block is filled from `DEFAULT_ROOTS` (5 Roots, length 0.25, radius 0.35, angle 12°);
252
+ absent means none. A single Stem's Roots spread all round it; with several Stems each Stem's Roots cover
253
+ only the half-circle facing away from the others. Roots follow the Sculpts of their Stem: a deleted Stem has
254
+ none, a turned Stem keeps them on the ground at its base, a scaled one scales them with its length, and
255
+ another Stem's Roots never change. The optional `sides` and `sections` are their polygon detail, set by `Style.apply`
256
+ (realistic 8 / 6, stylized 6 / 4, low-poly 3 / 2). Roots are part of the wood mesh, grow with the trunk from
257
+ Growth 0, never sway in the Wind and cannot be Sculpted; adding or removing them leaves the branches,
258
+ leaves and Fruit exactly as they were. The tree data lists them in `skeleton.roots` (`SkeletonRoot` entries
259
+ with paths `0/r0`, `0/r1`, ... and their Stem as `parent`) with their Growth windows in `growth.roots`:
260
+
261
+ ```ts
262
+ import { createTree, DEFAULT_ROOTS, type SkeletonRoot } from '@casmo/tree.js';
263
+
264
+ const rooted = createTree({ schemaVersion: 3, trunk: { flare: 0.6 }, roots: { count: 7, angle: 10 } }, { seed: 3 });
265
+ const roots: SkeletonRoot[] = rooted.data.skeleton.roots; // 7 Roots: '0/r0' .. '0/r6', parent '0'
266
+ const tips = roots.map((root) => root.points.at(-1)!.position); // all below the ground (y < 0)
267
+ const windows = rooted.data.growth.roots; // { start: 0, end: 0 }: there from Growth 0, like the trunk
268
+ const defaults = DEFAULT_ROOTS; // { count: 5, length: 0.25, lengthVariation: 0.3, radius: 0.35, angle: 12, bend: 0.3 }
269
+ ```
270
+
271
+ A **Ground Tint** darkens the bark or turns it mossy near the soil: the optional
272
+ `materials.bark.groundTint = { color, height, strength }`. At and below the ground the bark colour blends
273
+ towards `color` by `strength` (0..1); the blend fades smoothly to nothing `height` metres (> 0) up the Stem.
274
+ It works in every shading model (standard, flat, toon), is measured on the grown tree (a sapling's tint
275
+ reaches as high, in metres, as a grown tree's) and is baked into the wood's vertex colours of a Baked Tree.
276
+ A partial block is filled from `DEFAULT_GROUND_TINT` (height 0.5 m); absent means none, and no Species sets
277
+ one. It is not part of a Style's look, so `Style.apply` on a Definition keeps it:
278
+
279
+ ```ts
280
+ import { createTree, DEFAULT_GROUND_TINT, extendDefinition } from '@casmo/tree.js';
281
+ import realistic from '@casmo/tree.js/styles/realistic';
282
+ import { oak } from '@casmo/tree.js/species';
283
+
284
+ const mossy = extendDefinition(realistic.apply(oak), {
285
+ materials: { bark: { groundTint: { color: '#4d6a26', height: 0.8, strength: 0.7 } } },
286
+ });
287
+ const tree = createTree(mossy, { seed: 3 });
288
+ const wet = extendDefinition(mossy, { materials: { bark: { groundTint: { color: '#1e1610' } } } }); // dark wet bark
289
+ const defaults = DEFAULT_GROUND_TINT; // { color: '#3f4a2a', height: 0.5, strength: 0.6 }
290
+ ```
291
+
292
+ The **Crown Volume** is one smooth ellipsoid around all leaves of the fully grown tree (every Stem's
293
+ together), fitted as tightly as an axis-aligned ellipsoid can be. The Generator always computes it,
294
+ deterministically per Definition and Seed, and keeps it next to the geometry as `data.crown = { center, radii }`
295
+ (tree space, metres), so the meshes and `hashTreeData` are unchanged. Use it in your own shaders or
296
+ gameplay: `crownDistance` is 0 at its centre, 1 on its shell and more outside, and `crownNormal` is the
297
+ ellipsoid's outward normal through a point. A tree without leaves gets a Volume around its branches.
298
+
299
+ ```ts
300
+ import { createTree, crownDistance, crownNormal, type CrownVolume } from '@casmo/tree.js';
301
+
302
+ const tree = createTree({ schemaVersion: 3 }, { seed: 3 });
303
+ const crown: CrownVolume = tree.data.crown; // { center: [x, y, z], radii: [rx, ry, rz] }
304
+ const inside = crownDistance(crown, [0, 4, 0]) <= 1; // is this point within the crown?
305
+ const outward = crownNormal(crown, [0, 4, 0]); // unit normal of the ellipsoid through the point
306
+ ```
307
+
308
+ **Fruit** is an optional `fruit` block: `type` (`'round'`, `'pear'`, `'nut'`, `'cone'` or `'berry'`),
309
+ `count` per outermost twig, `size`, `sizeVariation` and `hang` (0 = sits on the twig .. 1 = hangs
310
+ straight down). A fractional `count` is a chance per twig: `0.3` puts one Fruit on about 30% of the
311
+ twigs, `1.5` one on every twig and a second on about half (the Seed picks which). The optional `sides`
312
+ (3..16) is its polygon detail, set by `Style.apply`: low-poly draws a few flat facets (5 or fewer sides
313
+ also coarsen the profile), stylized and realistic smoother shapes; absent = each Fruit Type's own detail.
314
+ It is drawn in its own mesh in the Definition's shading, only on a fully grown tree, and sways with its twig:
315
+
316
+ ```ts
317
+ import { createTree } from '@casmo/tree.js';
318
+
319
+ const apple = createTree({
320
+ schemaVersion: 3,
321
+ fruit: { type: 'round', count: 2, size: 0.1, hang: 0.8 },
322
+ season: {
323
+ fruit: [{ t: 0.1, value: 0 }, { t: 0.35, value: 1 }, { t: 0.6, value: 1 }, { t: 0.7, value: 0 }],
324
+ fruitColor: [{ t: 0.25, value: '#7cb342' }, { t: 0.5, value: '#c62828' }],
325
+ },
326
+ });
327
+ ```
328
+
329
+ Older Definitions (lower `schemaVersion`) are migrated when parsed (a v2 `form: 'conifer'` becomes the
330
+ equivalent cone `lengthProfile`, so the tree stays identical). `extendDefinition(base, patch)`
172
331
  deep-merges a patch (arrays replace) and validates the result. Sculpts (hand edits made in the Tree Editor)
173
332
  belong to one Seed: they only change the tree of that Seed.
174
333
 
@@ -184,7 +343,7 @@ Both only write a uniform, so they are cheap to animate every frame:
184
343
  ```ts
185
344
  import { createTree, SEASON_PROFILES } from '@casmo/tree.js';
186
345
 
187
- const tree = createTree({ schemaVersion: 2, season: SEASON_PROFILES.deciduous }, { seed: 5, growth: 0, season: 0 });
346
+ const tree = createTree({ schemaVersion: 3, season: SEASON_PROFILES.deciduous }, { seed: 5, growth: 0, season: 0 });
188
347
  scene.add(tree);
189
348
 
190
349
  renderer.setAnimationLoop((time) => {
@@ -197,7 +356,8 @@ renderer.setAnimationLoop((time) => {
197
356
  Each tree's Seed shifts its timing a little (`variation.growth`, `variation.season`), so trees of one
198
357
  Definition don't change in lockstep. `SEASON_PROFILES.deciduous` and `.evergreen` are ready-made Season
199
358
  Profiles; write your own as keyframes in the Definition's `season` (`leafColor`, `leafCoverage`,
200
- `blossom`, `blossomColor`).
359
+ `blossom`, `blossomColor`, and for Fruit `fruit` (amount: each Fruit shows above its own rank and swells
360
+ with the amount; 1 all year when absent) and `fruitColor` (ripening)).
201
361
 
202
362
  ## Wind
203
363
 
@@ -211,11 +371,11 @@ unless you give it another `Wind`. All of it is uniforms, so changing the wind i
211
371
  import { createTree, sceneWind, Wind } from '@casmo/tree.js';
212
372
 
213
373
  sceneWind.set({ direction: [1, 0, -0.4], strength: 0.6 }); // 0 = calm (default), 1 = strong
214
- const swaying = createTree({ schemaVersion: 2, wind: { trunk: 0.4, branches: 0.8, leaves: 1 } }, { seed: 1 });
374
+ const swaying = createTree({ schemaVersion: 3, wind: { trunk: 0.4, branches: 0.8, leaves: 1 } }, { seed: 1 });
215
375
 
216
376
  // A separate wind, e.g. for a sheltered courtyard:
217
377
  const breeze = new Wind({ direction: [0, 0, 1], strength: 0.2 });
218
- const sheltered = createTree({ schemaVersion: 2 }, { seed: 2, wind: breeze });
378
+ const sheltered = createTree({ schemaVersion: 3 }, { seed: 2, wind: breeze });
219
379
 
220
380
  swaying.windResponse.set({ leaves: 0.5 }); // change one tree's response live
221
381
  sceneWind.time = 1.5; // pin the wind clock (seconds), e.g. for screenshots; null = the renderer's clock
@@ -231,7 +391,8 @@ A swaying tree needs a render loop (`renderer.setAnimationLoop`).
231
391
  *400 trees from 4 Variants, with a per-tree Season (autumn towards the right).*
232
392
 
233
393
  A Forest draws many trees of one Definition from a few Variants (Seeds), each instanced, so 1,000 trees
234
- cost two draw calls per Variant. Every tree still looks its own: its Variant, rotation, Growth delay,
394
+ cost two draw calls per Variant (three with Fruit: `variant.fruit` is a third instanced mesh, null without
395
+ Fruit). Every tree still looks its own: its Variant, rotation, Growth delay,
235
396
  Season shift and wind phase come from a hash of the forest seed and the tree's id (or position), so adding
236
397
  or removing trees never changes the others.
237
398
 
@@ -261,6 +422,97 @@ if (hit) console.log(forest.treeAt(hit)?.key);
261
422
 
262
423
  `forest.dispose()` frees everything. `forest.ready` resolves once its textures have loaded.
263
424
 
425
+ ## Material Features
426
+
427
+ ![The same stylized tree without (left) and with (right) the suggested Material Features: the crown is lit as one rounded shape, glows at its edge against the low sun and is darker inside](docs/images/material-features.png)
428
+
429
+ *The same tree and lights, without (left) and with (right) `SUGGESTED_MATERIAL_FEATURES.stylized`.*
430
+
431
+ Material Features make a crown read as one soft volume instead of a noise of leaf cards. There are
432
+ three, each an optional field in the Definition's `materials` section:
433
+
434
+ | Field | Range | What it does |
435
+ | --- | --- | --- |
436
+ | `materials.leaf.crownNormals` | 0..1 | **Crown Normals**: each leaf's normal is blended towards the [Crown Volume](#tree-definitions-and-seeds)'s, so the crown is lit as one rounded shape (0 = each leaf on its own .. 1 = fully). With flat shading the facets stay visible below 1. |
437
+ | `materials.leaf.translucency` | `{ strength, edge, ambient }`, each 0..1 | **Leaf Translucency**: leaves glow in their own Season colour when you look towards a light through them. `strength` per direct light (shadowed leaves don't glow), `edge` = how much more the thin edge of the crown glows than its inside, `ambient` = the sky shining through, dimmed by occlusion. Leaves only, never bark or Fruit. |
438
+ | `materials.occlusion` | `{ strength }`, 0..1 | **Structural Occlusion**: the inside of the crown and the trunk under it get less ambient light. Worked out once from the tree's shape (baked per vertex, the same for every Season), for wood, leaves and Fruit. Changing `strength` doesn't regenerate the tree. |
439
+
440
+ **They are strictly opt-in and pass-free.** Absent means off, and no built-in Style or Species turns one
441
+ on, so a game that sets nothing sees exactly the trees it saw before (same geometry, attributes and
442
+ materials). Turning one on only changes the tree's own node materials: your renderer, scene, lights and
443
+ post-processing are left alone, and there is no extra render pass, only some shader math per pixel. They
444
+ work in every Style (flat, standard and toon shading), with Growth and Wind, and in Forests.
445
+
446
+ Each Style has suggested values. Opt in with one line: `withMaterialFeatures(definition, features)`
447
+ returns a new Definition whose Material Features are exactly `features` (a feature you leave out is off,
448
+ `{}` turns them all off) and leaves its input unchanged:
449
+
450
+ ```ts
451
+ import { createTree, SUGGESTED_MATERIAL_FEATURES, withMaterialFeatures } from '@casmo/tree.js';
452
+ import { oak } from '@casmo/tree.js/species';
453
+ import realistic from '@casmo/tree.js/styles/realistic';
454
+ import stylized from '@casmo/tree.js/styles/stylized';
455
+
456
+ const tree = createTree(withMaterialFeatures(stylized.broadleaf, SUGGESTED_MATERIAL_FEATURES.stylized), { seed: 3 });
457
+
458
+ // Or your own values, e.g. only a little crown shading and occlusion:
459
+ const subtle = withMaterialFeatures(realistic.apply(oak), { crownNormals: 0.4, occlusion: { strength: 0.5 } });
460
+ const off = withMaterialFeatures(subtle, {}); // the plain Style tree again
461
+ ```
462
+
463
+ | Style | `crownNormals` | `translucency` | `occlusion` |
464
+ | --- | --- | --- | --- |
465
+ | `low-poly` | 0.5 | (off: it would soften the flat look) | `{ strength: 0.8 }` |
466
+ | `stylized` | 1 | `{ strength: 0.3, edge: 0.8, ambient: 0.2 }` | `{ strength: 0.9 }` |
467
+ | `realistic` | 0.6 | `{ strength: 0.45, edge: 0.7, ambient: 0.25 }` | `{ strength: 0.9 }` |
468
+
469
+ The fields are plain numbers, so they are saved in the Definition JSON (the Tree Editor exports them) and
470
+ can be set with `extendDefinition` too (`{ materials: { leaf: { crownNormals: 1 } } }`). Validation
471
+ rejects values outside 0..1.
472
+
473
+ **Tuning live.** A feature that is on can be retuned on a Tree or Forest without regenerating it: the
474
+ values are uniforms, so there is no new geometry and no recompile. Values are clamped to 0..1; setting a
475
+ feature that is off throws (switching one on or off needs a new Tree or Forest). A Baked Tree is baked
476
+ with the values as tuned.
477
+
478
+ ```ts
479
+ import { createTree, SUGGESTED_MATERIAL_FEATURES, withMaterialFeatures } from '@casmo/tree.js';
480
+ import stylized from '@casmo/tree.js/styles/stylized';
481
+
482
+ const tree = createTree(withMaterialFeatures(stylized.broadleaf, SUGGESTED_MATERIAL_FEATURES.stylized));
483
+ tree.crownNormals = 0.8; // number | null (null = off)
484
+ tree.translucency = { strength: 0.6 }; // any of strength, edge, ambient; the others are kept
485
+ tree.occlusionStrength = 0.5; // number | null
486
+ tree.materialFeatures; // { crownNormals?, translucency?, occlusion? } as tuned now
487
+ ```
488
+
489
+ **With your SSAO/GTAO.** Structural Occlusion is the materials' built-in ambient occlusion (`aoNode`),
490
+ so it darkens ambient and indirect light only (sunlit sides stay sunlit) and three.js multiplies it
491
+ with screen-space AO the same way it does for any material. Your SSAO pass needs no changes; trees simply
492
+ bring their own occlusion, including the inside of the crown, which screen-space AO can't see:
493
+
494
+ ```ts
495
+ import * as THREE from 'three/webgpu';
496
+ import { builtinAOContext, mrt, normalView, output, pass, screenUV } from 'three/tsl';
497
+ import { ao } from 'three/addons/tsl/display/GTAONode.js';
498
+
499
+ const prePass = pass(scene, camera);
500
+ prePass.setMRT(mrt({ output, normal: normalView }));
501
+ const gtao = ao(prePass.getTextureNode('depth'), prePass.getTextureNode('normal'), camera);
502
+
503
+ const scenePass = pass(scene, camera);
504
+ // GTAO and the trees' Structural Occlusion are multiplied together, for ambient light only.
505
+ scenePass.contextNode = builtinAOContext(gtao.getTextureNode().sample(screenUV).r);
506
+
507
+ const pipeline = new THREE.RenderPipeline(renderer);
508
+ pipeline.outputNode = scenePass;
509
+ renderer.setAnimationLoop(() => pipeline.render());
510
+ ```
511
+
512
+ Material Features are a different thing from [Tree Effects](#tree-effects): those are post-processing
513
+ (the "leaf glow" effect is a screen-space bloom, not Leaf Translucency). See them side by side per Style in
514
+ [`examples/material-features`](examples/material-features/main.ts).
515
+
264
516
  ## Tree Effects
265
517
 
266
518
  ![A stylized tree, a rock and a crate without (left) and with (right) the stylized Tree Effects: only the tree gets an outline and colour grading](docs/images/effects.png)
@@ -269,7 +521,7 @@ if (hit) console.log(forest.treeAt(hit)?.key);
269
521
 
270
522
  `@casmo/tree.js/effects` has opt-in post-processing (TSL nodes for three.js `RenderPipeline`) that only
271
523
  changes the pixels of trees: an **outline**, a **leaf glow** and **colour grading**. Trees look fine
272
- without them. Every tree.js material (Trees and Forests) is found automatically (a per-object tree mask in
524
+ without them. Every tree.js material (wood, leaves and Fruit, of Trees and Forests) is found automatically (a per-object tree mask in
273
525
  an MRT output), so no tree has to be registered.
274
526
 
275
527
  ```ts
@@ -320,7 +572,7 @@ function Trees() {
320
572
  <>
321
573
  <Tree style={lowPoly} form="broadleaf" seed={1} growth={0.8} season={0.4} />
322
574
  <Tree style="low-poly" form="conifer" seed={2} position={[3, 0, 0]} castShadow={false} />
323
- <Tree definition={{ schemaVersion: 2, leaves: { count: 4 } }} seed={7} position={[-3, 0, 0]} />
575
+ <Tree definition={{ schemaVersion: 3, leaves: { count: 4 } }} seed={7} position={[-3, 0, 0]} />
324
576
  <Forest
325
577
  style={lowPoly}
326
578
  form="conifer"
@@ -408,12 +660,13 @@ Styles and the realistic textures load relative to the library's URL, so they co
408
660
  *A `.glb` from `exportBakedTree(tree, { season: 0.6 })`, loaded back with three.js' `GLTFLoader`.*
409
661
 
410
662
  A Baked Tree is a static copy of one tree at a fixed Growth and Season (no Growth, Season or Wind left), with
411
- classic `MeshStandardMaterial`s, for other engines or tools:
663
+ classic `MeshStandardMaterial`s, for other engines or tools. It has meshes `wood`, `leaves` and, when Fruit
664
+ shows at the baked Growth and Season, `fruit`:
412
665
 
413
666
  ```ts
414
667
  import { bakeTree, createTree, disposeBakedTree, exportBakedTree } from '@casmo/tree.js';
415
668
 
416
- const tree = createTree({ schemaVersion: 2 }, { seed: 4 });
669
+ const tree = createTree({ schemaVersion: 3 }, { seed: 4 });
417
670
  const glb = await exportBakedTree(tree, { growth: 1, season: 0.6 }); // ArrayBuffer (.glb); binary: false = glTF JSON
418
671
  const url = URL.createObjectURL(new Blob([glb], { type: 'model/gltf-binary' }));
419
672
 
@@ -422,13 +675,52 @@ const baked = bakeTree(tree, { season: 0.6 }); // a THREE.Group, e.g. for your o
422
675
  disposeBakedTree(baked);
423
676
  ```
424
677
 
678
+ ## Using a Baked Tree in other engines
679
+
680
+ A Baked Tree carries its Material Features (Crown Normals, Leaf Translucency, Structural Occlusion; see
681
+ `materials` in the Tree Definition) in standard glTF channels, so other engines can show them. With no
682
+ Material Feature set, the `.glb` is exactly what it was without them.
683
+
684
+ ```ts
685
+ import { createTree, exportBakedTree, extendDefinition } from '@casmo/tree.js';
686
+
687
+ const definition = extendDefinition({ schemaVersion: 3 }, {
688
+ materials: { leaf: { crownNormals: 1, translucency: { strength: 0.5, edge: 0.6, ambient: 0.3 } }, occlusion: { strength: 0.7 } },
689
+ });
690
+ const tree = createTree(definition, { seed: 4 });
691
+ const glb = await exportBakedTree(tree, { occlusionInVertexColors: true }); // the option works for bakeTree too
692
+ ```
693
+
694
+ | glTF channel | What it holds | Unity | Godot 4 | Unreal | Blender |
695
+ | --- | --- | --- | --- | --- | --- |
696
+ | `NORMAL` | Crown Normals already blended in (flat shading: the facet normals, blended by the same amount). Flat leaf cards (`leaves.shape: 'card'`) are turned (normal and winding together) to face outward of the Crown Volume, so engines that flip the normal of back faces still light every card from the crown's outside. Solid leaf shapes keep their winding. | Imported as mesh normals; keep the importer from recalculating them. | Imported as mesh normals. | Imported as mesh normals; turn "Recompute Normals" off. | Imported as custom normals. |
697
+ | `_OCCLUSION` (float, 0..1, all meshes) | Structural Occlusion as the tree shows it: `mix(1, aOcclusion, strength)`, 0 = occluded. **Final: the strength is already applied**, use it as AO as it is. Only when `materials.occlusion` is set. | Custom attributes are not imported by default: copy it into a UV channel or vertex colour in a custom importer, then feed it to the shader's occlusion. Or use `COLOR_0` (below). | Copy it into `CUSTOM0` with a `GLTFDocumentExtension` and read it as `AO` in a `ShaderMaterial`. Or use `COLOR_0`. | Not imported: use `COLOR_0`. | Imported as a mesh attribute `_OCCLUSION`: an Attribute node, multiplied into the indirect light or the Base Color. |
698
+ | `COLOR_0` | The vertex colours (Season colour, bark shading) as without the features; times `_OCCLUSION` with `occlusionInVertexColors: true`. | A shader that multiplies vertex colour into albedo (glTFast's shaders do). | `vertex_color_use_as_albedo` on the material. | Vertex Color node into Base Color. | Color Attribute node into Base Color (the importer wires it). |
699
+ | `KHR_materials_diffuse_transmission` (leaf material) | Leaf Translucency: `diffuseTransmissionFactor` = strength, `diffuseTransmissionColorFactor` = the leaf colour (linear, mean at the baked Season). | A foliage or translucent shader: transmission or thickness from the factor, colour from the colour factor. | `backlight_enabled`, `backlight` = colour × factor. | Shading model Two Sided Foliage, Subsurface Color = colour × factor. | Mix a Translucent BSDF (the colour) into the leaf shader by the factor. |
700
+ | `extras.treejs` (leaf and bark materials) | The settings `crownNormals`, `translucency { strength, edge, ambient }`, `occlusion { strength, strengthApplied: true, inVertexColors }` (only those set) and the Crown Volume `crown { center, radii }` in the Baked Tree's space (scaled by its Growth). `occlusion.strength` is for reference: `strengthApplied: true` says `_OCCLUSION` already has it, and `inVertexColors` whether `COLOR_0` has the occlusion too. | Read the glTF JSON in a custom importer to rebuild the effects in your own shader. | Imported as metadata on the material (`extras`), or read in a `GLTFDocumentExtension`. | Not imported: read the glTF JSON. | Imported as custom properties of the material. |
701
+
702
+ Importer support differs between versions; the columns show where each value goes.
703
+
704
+ **Don't apply the occlusion strength twice:** `_OCCLUSION` (and `COLOR_0` with `occlusionInVertexColors`)
705
+ already has `materials.occlusion.strength` applied. Use `_OCCLUSION` as AO directly, and only read
706
+ `extras.treejs.occlusion.strength` if you rebuild the effect from scratch.
707
+
708
+ **`occlusionInVertexColors`** (default `false`, in `bakeTree` and `exportBakedTree`): engines that only read
709
+ vertex colours show the occlusion without a custom shader. The trade-off: `COLOR_0` darkens all light,
710
+ direct sunlight included, while Structural Occlusion in tree.js (and `_OCCLUSION` used as AO) darkens only
711
+ ambient and indirect light. Leave it off when your engine can read `_OCCLUSION`, or keep the strength lower.
712
+
425
713
  ## Textures
426
714
 
427
715
  ![The realistic Style up close: textured bark and leaf cards on a broadleaf, needle cards on a conifer](docs/images/textures.png)
428
716
 
429
717
  Definitions with textures (the realistic Style, or your own `materials.bark.map` / `materials.leaf.map`
430
718
  URLs) load them relative to the package's `dist/textures/` by default. To serve them yourself, copy that
431
- folder and point tree.js at it, app-wide or per tree:
719
+ folder and point tree.js at it, app-wide or per tree. `realistic.apply` picks a leaf card per Leaf Type
720
+ (`realistic/leaf.png`, `leaf-lobed.png`, `leaf-palmate.png`, `leaf-compound.png`, `needles.png`,
721
+ `scale.png`) and a colour + normal pair per Bark Type (`realistic/bark.png` for furrowed, `bark-smooth.png`,
722
+ `bark-papery.png`, `bark-fibrous.png`, `bark-plated.png`, each with its `-normal.png`); all are made by
723
+ `scripts/generate-textures.mjs` (MIT, reproducible):
432
724
 
433
725
  ```ts
434
726
  import { createTree, setTextureOptions } from '@casmo/tree.js';
@@ -461,6 +753,8 @@ a live preview (Seed, Growth, Season, Wind, Tree Effects), sculpt single branche
461
753
  | [`examples/react`](examples/react/main.tsx) | `/examples/react/` | React Three Fiber: `<Tree>`, `<Wind>`, `useTreeStyle`; `?scene=forest` for `<Forest>` | <img src="docs/images/example-react.png" alt="examples/react" width="160"> |
462
754
  | [`examples/forest`](examples/forest/main.ts) | `/examples/forest/` | a 400-tree Forest; `?trees=&variants=&style=&season=` | <img src="docs/images/example-forest.png" alt="examples/forest" width="160"> |
463
755
  | [`examples/effects`](examples/effects/main.ts) | `/examples/effects/` | Tree Effects per Style; `?style=stylized&effects=outline` | <img src="docs/images/example-effects.png" alt="examples/effects" width="160"> |
756
+ | [`examples/material-features`](examples/material-features/main.ts) | `/examples/material-features/` | the same tree with Material Features off and on (`SUGGESTED_MATERIAL_FEATURES`); `?style=realistic&species=oak` | <img src="docs/images/example-material-features.png" alt="examples/material-features" width="160"> |
757
+ | [`examples/species`](examples/species/main.ts) | `/examples/species/` | a Species x Style picker over the whole collection; `?species=douglas-fir&style=realistic` | <img src="docs/images/example-species.png" alt="examples/species" width="160"> |
464
758
 
465
759
  ```sh
466
760
  npm install
@@ -477,6 +771,8 @@ sources too; the e2e test serves it unmodified, with the import map answered by
477
771
 
478
772
  `npm test` (Vitest), `npm run typecheck`, `npm run lint`, `npm run build` (library -> `dist/`),
479
773
  `npm run test:e2e` (Playwright; run `npm run build` and `npm run build:examples` first, as CI does).
774
+ The Species gallery (`docs/species/`: images, contact sheet and page) is regenerated by `npm run gallery`
775
+ (Playwright, the e2e renderer; `npm run gallery -- oak birch` redoes only those Species).
480
776
  The README's screenshots and GIFs (`docs/images/`) are rendered by `npm run readme-media`
481
777
  (Playwright + ffmpeg; run `npm run build` first; `npm run readme-media -- wind hero` redoes only those).
482
778
  Design decisions live in [`docs/adr`](docs/adr), the vocabulary in [`GLOSSARY.md`](GLOSSARY.md).