@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.
- package/README.md +312 -16
- package/dist/apply-Cio2t7CZ.js +285 -0
- package/dist/apply-Cio2t7CZ.js.map +1 -0
- package/dist/bake/index.d.ts +44 -5
- package/dist/bake/index.d.ts.map +1 -1
- package/dist/definition/crown-shape.d.ts +9 -0
- package/dist/definition/crown-shape.d.ts.map +1 -0
- package/dist/definition/defaults.d.ts +15 -1
- package/dist/definition/defaults.d.ts.map +1 -1
- package/dist/definition/index.d.ts +4 -3
- package/dist/definition/index.d.ts.map +1 -1
- package/dist/definition/migrations.d.ts +0 -8
- package/dist/definition/migrations.d.ts.map +1 -1
- package/dist/definition/schema.d.ts.map +1 -1
- package/dist/definition/types.d.ts +181 -6
- package/dist/definition/types.d.ts.map +1 -1
- package/dist/effects/mask.d.ts +3 -3
- package/dist/effects/mask.d.ts.map +1 -1
- package/dist/effects.js +3 -3
- package/dist/effects.js.map +1 -1
- package/dist/forest/Forest.d.ts +37 -2
- package/dist/forest/Forest.d.ts.map +1 -1
- package/dist/forest/nodes.d.ts +6 -1
- package/dist/forest/nodes.d.ts.map +1 -1
- package/dist/{forest-OX9WvAwh.js → forest-ChEaWJrf.js} +1763 -684
- package/dist/forest-ChEaWJrf.js.map +1 -0
- package/dist/generator/branches.d.ts +2 -2
- package/dist/generator/branches.d.ts.map +1 -1
- package/dist/generator/crown.d.ts +28 -0
- package/dist/generator/crown.d.ts.map +1 -0
- package/dist/generator/fruit.d.ts +28 -0
- package/dist/generator/fruit.d.ts.map +1 -0
- package/dist/generator/growth.d.ts +1 -1
- package/dist/generator/growth.d.ts.map +1 -1
- package/dist/generator/index.d.ts +5 -4
- package/dist/generator/index.d.ts.map +1 -1
- package/dist/generator/leaf-shapes.d.ts +33 -1
- package/dist/generator/leaf-shapes.d.ts.map +1 -1
- package/dist/generator/mesh.d.ts +10 -2
- package/dist/generator/mesh.d.ts.map +1 -1
- package/dist/generator/occlusion.d.ts +8 -0
- package/dist/generator/occlusion.d.ts.map +1 -0
- package/dist/generator/roots.d.ts +16 -0
- package/dist/generator/roots.d.ts.map +1 -0
- package/dist/generator/trunk.d.ts +16 -2
- package/dist/generator/trunk.d.ts.map +1 -1
- package/dist/generator/types.d.ts +61 -6
- package/dist/generator/types.d.ts.map +1 -1
- package/dist/growth/index.d.ts +1 -1
- package/dist/growth/index.d.ts.map +1 -1
- package/dist/growth/tsl.d.ts +2 -0
- package/dist/growth/tsl.d.ts.map +1 -1
- package/dist/index.d.ts +6 -3
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +274 -24
- package/dist/index.js.map +1 -1
- package/dist/materials/crown-nodes.d.ts +20 -0
- package/dist/materials/crown-nodes.d.ts.map +1 -0
- package/dist/materials/crown-normals.d.ts +17 -0
- package/dist/materials/crown-normals.d.ts.map +1 -0
- package/dist/materials/ground-tint.d.ts +13 -0
- package/dist/materials/ground-tint.d.ts.map +1 -0
- package/dist/materials/index.d.ts +13 -1
- package/dist/materials/index.d.ts.map +1 -1
- package/dist/materials/leaf-translucency-model.d.ts +14 -0
- package/dist/materials/leaf-translucency-model.d.ts.map +1 -0
- package/dist/materials/leaf-translucency.d.ts +73 -0
- package/dist/materials/leaf-translucency.d.ts.map +1 -0
- package/dist/materials/material-features.d.ts +43 -0
- package/dist/materials/material-features.d.ts.map +1 -0
- package/dist/materials/occlusion.d.ts +10 -0
- package/dist/materials/occlusion.d.ts.map +1 -0
- package/dist/materials/toon.d.ts +18 -1
- package/dist/materials/toon.d.ts.map +1 -1
- package/dist/names-BE9he6CS.js +713 -0
- package/dist/names-BE9he6CS.js.map +1 -0
- package/dist/react/Tree.d.ts +5 -2
- package/dist/react/Tree.d.ts.map +1 -1
- package/dist/react.js +10 -6
- package/dist/react.js.map +1 -1
- package/dist/season/nodes.d.ts +16 -0
- package/dist/season/nodes.d.ts.map +1 -1
- package/dist/season/profile.d.ts +26 -0
- package/dist/season/profile.d.ts.map +1 -1
- package/dist/species/almond.js +223 -0
- package/dist/species/almond.js.map +1 -0
- package/dist/species/almond.json +210 -0
- package/dist/species/apple.js +230 -0
- package/dist/species/apple.js.map +1 -0
- package/dist/species/apple.json +220 -0
- package/dist/species/ash.js +187 -0
- package/dist/species/ash.js.map +1 -0
- package/dist/species/ash.json +177 -0
- package/dist/species/beech.js +174 -0
- package/dist/species/beech.js.map +1 -0
- package/dist/species/beech.json +167 -0
- package/dist/species/birch.js +170 -0
- package/dist/species/birch.js.map +1 -0
- package/dist/species/birch.json +163 -0
- package/dist/species/catalog.d.ts +61 -0
- package/dist/species/catalog.d.ts.map +1 -0
- package/dist/species/cedar.js +169 -0
- package/dist/species/cedar.js.map +1 -0
- package/dist/species/cedar.json +168 -0
- package/dist/species/cherry.js +237 -0
- package/dist/species/cherry.js.map +1 -0
- package/dist/species/cherry.json +224 -0
- package/dist/species/chestnut.js +230 -0
- package/dist/species/chestnut.js.map +1 -0
- package/dist/species/chestnut.json +220 -0
- package/dist/species/douglas-fir.js +174 -0
- package/dist/species/douglas-fir.js.map +1 -0
- package/dist/species/douglas-fir.json +170 -0
- package/dist/species/elm.js +173 -0
- package/dist/species/elm.js.map +1 -0
- package/dist/species/elm.json +163 -0
- package/dist/species/hemlock.js +175 -0
- package/dist/species/hemlock.js.map +1 -0
- package/dist/species/hemlock.json +171 -0
- package/dist/species/hickory.js +200 -0
- package/dist/species/hickory.js.map +1 -0
- package/dist/species/hickory.json +192 -0
- package/dist/species/index.d.ts +10 -0
- package/dist/species/index.d.ts.map +1 -0
- package/dist/species/juniper.js +158 -0
- package/dist/species/juniper.js.map +1 -0
- package/dist/species/juniper.json +154 -0
- package/dist/species/loaders.d.ts +7 -0
- package/dist/species/loaders.d.ts.map +1 -0
- package/dist/species/mahogany.js +201 -0
- package/dist/species/mahogany.js.map +1 -0
- package/dist/species/mahogany.json +196 -0
- package/dist/species/maple.js +177 -0
- package/dist/species/maple.js.map +1 -0
- package/dist/species/maple.json +171 -0
- package/dist/species/oak.js +220 -0
- package/dist/species/oak.js.map +1 -0
- package/dist/species/oak.json +212 -0
- package/dist/species/olive.js +189 -0
- package/dist/species/olive.js.map +1 -0
- package/dist/species/olive.json +181 -0
- package/dist/species/peach.js +223 -0
- package/dist/species/peach.js.map +1 -0
- package/dist/species/peach.json +210 -0
- package/dist/species/pear.js +213 -0
- package/dist/species/pear.js.map +1 -0
- package/dist/species/pear.json +200 -0
- package/dist/species/pine.js +163 -0
- package/dist/species/pine.js.map +1 -0
- package/dist/species/pine.json +162 -0
- package/dist/species/plum.js +237 -0
- package/dist/species/plum.js.map +1 -0
- package/dist/species/plum.json +224 -0
- package/dist/species/red-oak.js +220 -0
- package/dist/species/red-oak.js.map +1 -0
- package/dist/species/red-oak.json +212 -0
- package/dist/species/redwood.js +174 -0
- package/dist/species/redwood.js.map +1 -0
- package/dist/species/redwood.json +170 -0
- package/dist/species/sequoia.js +167 -0
- package/dist/species/sequoia.js.map +1 -0
- package/dist/species/sequoia.json +166 -0
- package/dist/species/spruce.js +170 -0
- package/dist/species/spruce.js.map +1 -0
- package/dist/species/spruce.json +166 -0
- package/dist/species/teak.js +166 -0
- package/dist/species/teak.js.map +1 -0
- package/dist/species/teak.json +157 -0
- package/dist/species/types.d.ts +65 -0
- package/dist/species/types.d.ts.map +1 -0
- package/dist/species/walnut.js +220 -0
- package/dist/species/walnut.js.map +1 -0
- package/dist/species/walnut.json +212 -0
- package/dist/species/white-oak.js +213 -0
- package/dist/species/white-oak.js.map +1 -0
- package/dist/species/white-oak.json +208 -0
- package/dist/species.js +160 -0
- package/dist/species.js.map +1 -0
- package/dist/styles/apply.d.ts +12 -0
- package/dist/styles/apply.d.ts.map +1 -0
- package/dist/styles/low-poly/index.d.ts +1 -1
- package/dist/styles/low-poly/index.d.ts.map +1 -1
- package/dist/styles/low-poly.js +13 -10
- package/dist/styles/low-poly.js.map +1 -1
- package/dist/styles/material-features.d.ts +27 -0
- package/dist/styles/material-features.d.ts.map +1 -0
- package/dist/styles/names.d.ts +28 -0
- package/dist/styles/names.d.ts.map +1 -0
- package/dist/styles/realistic/index.d.ts +3 -8
- package/dist/styles/realistic/index.d.ts.map +1 -1
- package/dist/styles/realistic/textures.d.ts +20 -0
- package/dist/styles/realistic/textures.d.ts.map +1 -0
- package/dist/styles/realistic.js +14 -18
- package/dist/styles/realistic.js.map +1 -1
- package/dist/styles/registry.d.ts +2 -13
- package/dist/styles/registry.d.ts.map +1 -1
- package/dist/styles/stylized/index.d.ts +1 -1
- package/dist/styles/stylized/index.d.ts.map +1 -1
- package/dist/styles/stylized.js +13 -10
- package/dist/styles/stylized.js.map +1 -1
- package/dist/styles/types.d.ts +16 -2
- package/dist/styles/types.d.ts.map +1 -1
- package/dist/textures/realistic/bark-fibrous-normal.png +0 -0
- package/dist/textures/realistic/bark-fibrous.png +0 -0
- package/dist/textures/realistic/bark-papery-normal.png +0 -0
- package/dist/textures/realistic/bark-papery.png +0 -0
- package/dist/textures/realistic/bark-plated-normal.png +0 -0
- package/dist/textures/realistic/bark-plated.png +0 -0
- package/dist/textures/realistic/bark-smooth-normal.png +0 -0
- package/dist/textures/realistic/bark-smooth.png +0 -0
- package/dist/textures/realistic/leaf-compound.png +0 -0
- package/dist/textures/realistic/leaf-lobed.png +0 -0
- package/dist/textures/realistic/leaf-palmate.png +0 -0
- package/dist/textures/realistic/scale.png +0 -0
- package/dist/tree/Tree.d.ts +34 -5
- package/dist/tree/Tree.d.ts.map +1 -1
- package/package.json +9 -2
- package/dist/forest-OX9WvAwh.js.map +0 -1
- package/dist/types-BZjHhNz7.js +0 -20
- 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
|
|
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
|
+
[](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
|

|
|
@@ -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:
|
|
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":
|
|
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
|
-
|
|
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:
|
|
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:
|
|
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:
|
|
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
|
|
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
|
+

|
|
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
|

|
|
@@ -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:
|
|
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:
|
|
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
|

|
|
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).
|