@casmo/tree.js 0.0.0-stage → 0.1.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/LICENSE +21 -0
- package/README.md +485 -2
- package/dist/bake/index.d.ts +39 -0
- package/dist/bake/index.d.ts.map +1 -0
- package/dist/definition/defaults.d.ts +9 -0
- package/dist/definition/defaults.d.ts.map +1 -0
- package/dist/definition/index.d.ts +5 -0
- package/dist/definition/index.d.ts.map +1 -0
- package/dist/definition/migrations.d.ts +12 -0
- package/dist/definition/migrations.d.ts.map +1 -0
- package/dist/definition/parse.d.ts +30 -0
- package/dist/definition/parse.d.ts.map +1 -0
- package/dist/definition/schema.d.ts +13 -0
- package/dist/definition/schema.d.ts.map +1 -0
- package/dist/definition/types.d.ts +217 -0
- package/dist/definition/types.d.ts.map +1 -0
- package/dist/effects/effects.d.ts +46 -0
- package/dist/effects/effects.d.ts.map +1 -0
- package/dist/effects/glow.d.ts +19 -0
- package/dist/effects/glow.d.ts.map +1 -0
- package/dist/effects/grade.d.ts +19 -0
- package/dist/effects/grade.d.ts.map +1 -0
- package/dist/effects/index.d.ts +7 -0
- package/dist/effects/index.d.ts.map +1 -0
- package/dist/effects/mask.d.ts +44 -0
- package/dist/effects/mask.d.ts.map +1 -0
- package/dist/effects/outline.d.ts +18 -0
- package/dist/effects/outline.d.ts.map +1 -0
- package/dist/effects/suggested.d.ts +13 -0
- package/dist/effects/suggested.d.ts.map +1 -0
- package/dist/effects.js +249 -0
- package/dist/effects.js.map +1 -0
- package/dist/forest/Forest.d.ts +156 -0
- package/dist/forest/Forest.d.ts.map +1 -0
- package/dist/forest/index.d.ts +14 -0
- package/dist/forest/index.d.ts.map +1 -0
- package/dist/forest/nodes.d.ts +31 -0
- package/dist/forest/nodes.d.ts.map +1 -0
- package/dist/forest/placement.d.ts +52 -0
- package/dist/forest/placement.d.ts.map +1 -0
- package/dist/forest-OX9WvAwh.js +3057 -0
- package/dist/forest-OX9WvAwh.js.map +1 -0
- package/dist/generator/attributes.d.ts +20 -0
- package/dist/generator/attributes.d.ts.map +1 -0
- package/dist/generator/branches.d.ts +12 -0
- package/dist/generator/branches.d.ts.map +1 -0
- package/dist/generator/frames.d.ts +21 -0
- package/dist/generator/frames.d.ts.map +1 -0
- package/dist/generator/growth.d.ts +15 -0
- package/dist/generator/growth.d.ts.map +1 -0
- package/dist/generator/index.d.ts +22 -0
- package/dist/generator/index.d.ts.map +1 -0
- package/dist/generator/leaf-shapes.d.ts +10 -0
- package/dist/generator/leaf-shapes.d.ts.map +1 -0
- package/dist/generator/leaves.d.ts +14 -0
- package/dist/generator/leaves.d.ts.map +1 -0
- package/dist/generator/mesh.d.ts +11 -0
- package/dist/generator/mesh.d.ts.map +1 -0
- package/dist/generator/sculpt.d.ts +28 -0
- package/dist/generator/sculpt.d.ts.map +1 -0
- package/dist/generator/trunk.d.ts +6 -0
- package/dist/generator/trunk.d.ts.map +1 -0
- package/dist/generator/types.d.ts +126 -0
- package/dist/generator/types.d.ts.map +1 -0
- package/dist/generator/vec.d.ts +12 -0
- package/dist/generator/vec.d.ts.map +1 -0
- package/dist/generator/wind.d.ts +27 -0
- package/dist/generator/wind.d.ts.map +1 -0
- package/dist/growth/evaluate.d.ts +32 -0
- package/dist/growth/evaluate.d.ts.map +1 -0
- package/dist/growth/index.d.ts +3 -0
- package/dist/growth/index.d.ts.map +1 -0
- package/dist/growth/tsl.d.ts +12 -0
- package/dist/growth/tsl.d.ts.map +1 -0
- package/dist/index.d.ts +14 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +198 -0
- package/dist/index.js.map +1 -0
- package/dist/materials/index.d.ts +18 -0
- package/dist/materials/index.d.ts.map +1 -0
- package/dist/materials/maps.d.ts +23 -0
- package/dist/materials/maps.d.ts.map +1 -0
- package/dist/materials/shading.d.ts +18 -0
- package/dist/materials/shading.d.ts.map +1 -0
- package/dist/materials/toon.d.ts +12 -0
- package/dist/materials/toon.d.ts.map +1 -0
- package/dist/math/index.d.ts +23 -0
- package/dist/math/index.d.ts.map +1 -0
- package/dist/profiles-BAiyeFlh.js +113 -0
- package/dist/profiles-BAiyeFlh.js.map +1 -0
- package/dist/random/index.d.ts +37 -0
- package/dist/random/index.d.ts.map +1 -0
- package/dist/react/Forest.d.ts +54 -0
- package/dist/react/Forest.d.ts.map +1 -0
- package/dist/react/Tree.d.ts +41 -0
- package/dist/react/Tree.d.ts.map +1 -0
- package/dist/react/Wind.d.ts +17 -0
- package/dist/react/Wind.d.ts.map +1 -0
- package/dist/react/index.d.ts +6 -0
- package/dist/react/index.d.ts.map +1 -0
- package/dist/react/useTreeStyle.d.ts +15 -0
- package/dist/react/useTreeStyle.d.ts.map +1 -0
- package/dist/react.js +239 -0
- package/dist/react.js.map +1 -0
- package/dist/renderer/index.d.ts +7 -0
- package/dist/renderer/index.d.ts.map +1 -0
- package/dist/season/check.d.ts +3 -0
- package/dist/season/check.d.ts.map +1 -0
- package/dist/season/index.d.ts +4 -0
- package/dist/season/index.d.ts.map +1 -0
- package/dist/season/nodes.d.ts +32 -0
- package/dist/season/nodes.d.ts.map +1 -0
- package/dist/season/profile.d.ts +78 -0
- package/dist/season/profile.d.ts.map +1 -0
- package/dist/season/profiles.d.ts +40 -0
- package/dist/season/profiles.d.ts.map +1 -0
- package/dist/styles/low-poly/index.d.ts +16 -0
- package/dist/styles/low-poly/index.d.ts.map +1 -0
- package/dist/styles/low-poly.js +165 -0
- package/dist/styles/low-poly.js.map +1 -0
- package/dist/styles/realistic/index.d.ts +23 -0
- package/dist/styles/realistic/index.d.ts.map +1 -0
- package/dist/styles/realistic.js +206 -0
- package/dist/styles/realistic.js.map +1 -0
- package/dist/styles/registry.d.ts +17 -0
- package/dist/styles/registry.d.ts.map +1 -0
- package/dist/styles/stylized/index.d.ts +17 -0
- package/dist/styles/stylized/index.d.ts.map +1 -0
- package/dist/styles/stylized.js +266 -0
- package/dist/styles/stylized.js.map +1 -0
- package/dist/styles/types.d.ts +12 -0
- package/dist/styles/types.d.ts.map +1 -0
- package/dist/textures/index.d.ts +44 -0
- package/dist/textures/index.d.ts.map +1 -0
- package/dist/textures/realistic/bark-normal.png +0 -0
- package/dist/textures/realistic/bark.png +0 -0
- package/dist/textures/realistic/leaf.png +0 -0
- package/dist/textures/realistic/needles.png +0 -0
- package/dist/tree/Tree.d.ts +70 -0
- package/dist/tree/Tree.d.ts.map +1 -0
- package/dist/tree/index.d.ts +14 -0
- package/dist/tree/index.d.ts.map +1 -0
- package/dist/types-BZjHhNz7.js +20 -0
- package/dist/types-BZjHhNz7.js.map +1 -0
- package/dist/wind/Wind.d.ts +54 -0
- package/dist/wind/Wind.d.ts.map +1 -0
- package/dist/wind/index.d.ts +4 -0
- package/dist/wind/index.d.ts.map +1 -0
- package/dist/wind/node.d.ts +38 -0
- package/dist/wind/node.d.ts.map +1 -0
- package/dist/wind/response.d.ts +27 -0
- package/dist/wind/response.d.ts.map +1 -0
- package/package.json +107 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Mathieu
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,486 @@
|
|
|
1
|
-
#
|
|
1
|
+
# tree.js
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+

|
|
4
|
+
|
|
5
|
+
Procedural trees for [three.js](https://threejs.org): one Tree Definition and a Seed grow a unique tree, in a
|
|
6
|
+
low-poly, stylized or realistic Style. Trees grow (Growth), change through the year (Season) and sway in the
|
|
7
|
+
Wind, all on the GPU through TSL node materials, so animating them never regenerates geometry. Place
|
|
8
|
+
thousands at once as an instanced Forest, add opt-in Tree Effects, or design your own trees in the
|
|
9
|
+
[Tree Editor](#tree-editor).
|
|
10
|
+
|
|
11
|
+
- [Install](#install)
|
|
12
|
+
- [Quick start](#quick-start)
|
|
13
|
+
- [WebGPURenderer is required](#webgpurenderer-is-required)
|
|
14
|
+
- [Styles](#styles)
|
|
15
|
+
- [Tree Definitions and Seeds](#tree-definitions-and-seeds)
|
|
16
|
+
- [Growth and Season](#growth-and-season)
|
|
17
|
+
- [Wind](#wind)
|
|
18
|
+
- [Forests](#forests)
|
|
19
|
+
- [Tree Effects](#tree-effects)
|
|
20
|
+
- [React Three Fiber](#react-three-fiber)
|
|
21
|
+
- [Without a bundler: import map (CDN)](#without-a-bundler-import-map-cdn)
|
|
22
|
+
- [Baked Trees (glTF export)](#baked-trees-gltf-export)
|
|
23
|
+
- [Textures](#textures)
|
|
24
|
+
- [Tree Editor](#tree-editor)
|
|
25
|
+
- [Examples](#examples)
|
|
26
|
+
|
|
27
|
+
## Install
|
|
28
|
+
|
|
29
|
+
```sh
|
|
30
|
+
npm install @casmo/tree.js three
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
`three` (r187 or newer) is a peer dependency. For the React bindings also install `react` (19) and
|
|
34
|
+
`@react-three/fiber` (v9); vanilla three.js apps don't need them.
|
|
35
|
+
|
|
36
|
+
| Import | What |
|
|
37
|
+
| --- | --- |
|
|
38
|
+
| `@casmo/tree.js` | `createTree`, `createForest`, Definitions, Wind, Baked Tree export, `loadStyle`, ... |
|
|
39
|
+
| `@casmo/tree.js/styles/low-poly` (`stylized`, `realistic`) | a built-in Style: one Tree Definition per Form (a few kB of data) |
|
|
40
|
+
| `@casmo/tree.js/effects` | Tree Effects (post-processing) |
|
|
41
|
+
| `@casmo/tree.js/react` | `<Tree>`, `<Forest>`, `<Wind>`, `useTreeStyle` for React Three Fiber |
|
|
42
|
+
|
|
43
|
+
## Quick start
|
|
44
|
+
|
|
45
|
+

|
|
46
|
+
|
|
47
|
+
```ts
|
|
48
|
+
import * as THREE from 'three/webgpu';
|
|
49
|
+
import { createTree } from '@casmo/tree.js';
|
|
50
|
+
import lowPoly from '@casmo/tree.js/styles/low-poly';
|
|
51
|
+
|
|
52
|
+
const renderer = new THREE.WebGPURenderer({ antialias: true });
|
|
53
|
+
renderer.setSize(innerWidth, innerHeight);
|
|
54
|
+
document.body.appendChild(renderer.domElement);
|
|
55
|
+
await renderer.init();
|
|
56
|
+
|
|
57
|
+
const scene = new THREE.Scene();
|
|
58
|
+
scene.add(new THREE.HemisphereLight('#ffffff', '#6a7a4a', 1.5));
|
|
59
|
+
const sun = new THREE.DirectionalLight('#ffffff', 2.5);
|
|
60
|
+
sun.position.set(5, 8, 3);
|
|
61
|
+
scene.add(sun);
|
|
62
|
+
|
|
63
|
+
const camera = new THREE.PerspectiveCamera(45, innerWidth / innerHeight, 0.1, 100);
|
|
64
|
+
camera.position.set(9, 4, 9);
|
|
65
|
+
camera.lookAt(0, 2.5, 0);
|
|
66
|
+
|
|
67
|
+
const tree = createTree(lowPoly.broadleaf, { seed: 42, growth: 1, season: 0.4 });
|
|
68
|
+
scene.add(tree);
|
|
69
|
+
|
|
70
|
+
renderer.setAnimationLoop(() => renderer.render(scene, camera));
|
|
71
|
+
```
|
|
72
|
+
|
|
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.
|
|
75
|
+
|
|
76
|
+
## WebGPURenderer is required
|
|
77
|
+
|
|
78
|
+

|
|
79
|
+
|
|
80
|
+
*The same scene on WebGPU (left) and on WebGPURenderer's WebGL2 fallback (right).*
|
|
81
|
+
|
|
82
|
+
Tree materials are TSL node materials, so trees must be drawn by `WebGPURenderer` from `three/webgpu`
|
|
83
|
+
(not the classic `WebGLRenderer`). WebGPURenderer uses WebGPU where the browser has it and falls back to
|
|
84
|
+
WebGL2 by itself, so you keep WebGL2 support; pass `forceWebGL: true` to try the fallback. Call
|
|
85
|
+
`await renderer.init()` before the first render. Drawing a tree with any other renderer throws an
|
|
86
|
+
`UnsupportedRendererError` that says so:
|
|
87
|
+
|
|
88
|
+
```ts
|
|
89
|
+
import { assertWebGPURenderer, UnsupportedRendererError } from '@casmo/tree.js';
|
|
90
|
+
|
|
91
|
+
try {
|
|
92
|
+
assertWebGPURenderer(renderer); // what every tree mesh checks before it is drawn
|
|
93
|
+
} catch (error) {
|
|
94
|
+
if (error instanceof UnsupportedRendererError) console.error(error.message);
|
|
95
|
+
}
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
The rest of your scene can keep any materials; only the trees need the node renderer.
|
|
99
|
+
|
|
100
|
+
## Styles
|
|
101
|
+
|
|
102
|
+

|
|
103
|
+
|
|
104
|
+
*`low-poly`, `stylized` and `realistic`: a broadleaf and a conifer each.*
|
|
105
|
+
|
|
106
|
+
A Style is a ready-made look with one Tree Definition per Form (`broadleaf`, `conifer`):
|
|
107
|
+
|
|
108
|
+
| Style | Look |
|
|
109
|
+
| --- | --- |
|
|
110
|
+
| `low-poly` | faceted (flat shading), solid colours, clump and needle leaves |
|
|
111
|
+
| `stylized` | soft two-tone (toon) shading, round leaf puffs, pink blossom in early spring |
|
|
112
|
+
| `realistic` | textured bark (with normal map) and leaf cards |
|
|
113
|
+
|
|
114
|
+
Each Style is its own small module, so you only download the ones you use. Import one statically, or load
|
|
115
|
+
it on demand by name:
|
|
116
|
+
|
|
117
|
+
```ts
|
|
118
|
+
import { createTree, extendDefinition, loadStyle } from '@casmo/tree.js';
|
|
119
|
+
import stylized from '@casmo/tree.js/styles/stylized';
|
|
120
|
+
|
|
121
|
+
const oak = createTree(stylized.broadleaf, { seed: 1 });
|
|
122
|
+
const pine = createTree(stylized.conifer, { seed: 2 });
|
|
123
|
+
|
|
124
|
+
const realistic = await loadStyle('realistic'); // dynamic import of '@casmo/tree.js/styles/realistic'
|
|
125
|
+
const birch = createTree(realistic.broadleaf, { seed: 3 });
|
|
126
|
+
await birch.ready; // resolves once its textures have loaded (instantly for trees without textures)
|
|
127
|
+
|
|
128
|
+
// A Style's Definitions are plain data: start from one and change what you like.
|
|
129
|
+
const tallPine = createTree(extendDefinition(stylized.conifer, { trunk: { length: 9 } }), { seed: 2 });
|
|
130
|
+
scene.add(oak, pine, birch, tallPine);
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
## Tree Definitions and Seeds
|
|
134
|
+
|
|
135
|
+

|
|
136
|
+
|
|
137
|
+
*The birch Definition below with Seeds 1 to 5.*
|
|
138
|
+
|
|
139
|
+
A Tree Definition is plain JSON (what the Tree Editor exports): trunk, branch levels, leaves, materials,
|
|
140
|
+
the Season Profile, the Wind response, Seed variation ranges and Sculpts. Every field is documented in
|
|
141
|
+
[`src/definition/types.ts`](src/definition/types.ts); missing fields get defaults, so a Definition can be
|
|
142
|
+
small. The Seed picks one individual tree within the Definition's ranges: the same Definition and Seed
|
|
143
|
+
always give exactly the same tree.
|
|
144
|
+
|
|
145
|
+
```ts
|
|
146
|
+
import { createTree, fetchDefinition, parseDefinition, TreeDefinitionError, type TreeDefinitionInput } from '@casmo/tree.js';
|
|
147
|
+
|
|
148
|
+
const birch: TreeDefinitionInput = {
|
|
149
|
+
schemaVersion: 2,
|
|
150
|
+
form: 'broadleaf',
|
|
151
|
+
trunk: { length: 6, radius: 0.15 },
|
|
152
|
+
branches: [
|
|
153
|
+
{ count: 6, angle: 45 },
|
|
154
|
+
{ count: 4, length: 0.5 },
|
|
155
|
+
],
|
|
156
|
+
leaves: { count: 6, shape: 'card', size: 0.3 },
|
|
157
|
+
materials: { bark: { color: '#d8d2c4' } },
|
|
158
|
+
};
|
|
159
|
+
const trees = [1, 2, 3].map((seed) => createTree(birch, { seed })); // three different birches
|
|
160
|
+
|
|
161
|
+
const fromEditor = await fetchDefinition('/trees/my-oak.json'); // a Tree Editor export
|
|
162
|
+
const tree = createTree(fromEditor, { seed: 7 });
|
|
163
|
+
|
|
164
|
+
try {
|
|
165
|
+
parseDefinition('{"schemaVersion": 2, "trunk": {"length": -1}}');
|
|
166
|
+
} catch (error) {
|
|
167
|
+
if (error instanceof TreeDefinitionError) console.warn(error.field, error.message); // 'trunk.length'
|
|
168
|
+
}
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
Older Definitions (lower `schemaVersion`) are migrated when parsed. `extendDefinition(base, patch)`
|
|
172
|
+
deep-merges a patch (arrays replace) and validates the result. Sculpts (hand edits made in the Tree Editor)
|
|
173
|
+
belong to one Seed: they only change the tree of that Seed.
|
|
174
|
+
|
|
175
|
+
## Growth and Season
|
|
176
|
+
|
|
177
|
+

|
|
178
|
+
|
|
179
|
+
**Growth** goes from 0 (sapling) to 1 (fully grown); branches sprout after their parent and leaves come
|
|
180
|
+
last. **Season** goes from 0 (first day of spring) to 1 (last day of winter) and sets leaf colour, leaf
|
|
181
|
+
coverage and blossom from the Definition's Season Profile (values outside 0..1 wrap around the year).
|
|
182
|
+
Both only write a uniform, so they are cheap to animate every frame:
|
|
183
|
+
|
|
184
|
+
```ts
|
|
185
|
+
import { createTree, SEASON_PROFILES } from '@casmo/tree.js';
|
|
186
|
+
|
|
187
|
+
const tree = createTree({ schemaVersion: 2, season: SEASON_PROFILES.deciduous }, { seed: 5, growth: 0, season: 0 });
|
|
188
|
+
scene.add(tree);
|
|
189
|
+
|
|
190
|
+
renderer.setAnimationLoop((time) => {
|
|
191
|
+
tree.growth = Math.min(1, time / 10_000); // grows in 10 s
|
|
192
|
+
tree.season = time / 60_000; // a year per minute
|
|
193
|
+
renderer.render(scene, camera);
|
|
194
|
+
});
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
Each tree's Seed shifts its timing a little (`variation.growth`, `variation.season`), so trees of one
|
|
198
|
+
Definition don't change in lockstep. `SEASON_PROFILES.deciduous` and `.evergreen` are ready-made Season
|
|
199
|
+
Profiles; write your own as keyframes in the Definition's `season` (`leafColor`, `leafCoverage`,
|
|
200
|
+
`blossom`, `blossomColor`).
|
|
201
|
+
|
|
202
|
+
## Wind
|
|
203
|
+
|
|
204
|
+

|
|
205
|
+
|
|
206
|
+
Wind has a scene-wide part (direction and strength) and a per-tree part (the Definition's `wind`
|
|
207
|
+
response: how much the trunk, branches and leaves move). Every tree sways with the shared `sceneWind`
|
|
208
|
+
unless you give it another `Wind`. All of it is uniforms, so changing the wind is free:
|
|
209
|
+
|
|
210
|
+
```ts
|
|
211
|
+
import { createTree, sceneWind, Wind } from '@casmo/tree.js';
|
|
212
|
+
|
|
213
|
+
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 });
|
|
215
|
+
|
|
216
|
+
// A separate wind, e.g. for a sheltered courtyard:
|
|
217
|
+
const breeze = new Wind({ direction: [0, 0, 1], strength: 0.2 });
|
|
218
|
+
const sheltered = createTree({ schemaVersion: 2 }, { seed: 2, wind: breeze });
|
|
219
|
+
|
|
220
|
+
swaying.windResponse.set({ leaves: 0.5 }); // change one tree's response live
|
|
221
|
+
sceneWind.time = 1.5; // pin the wind clock (seconds), e.g. for screenshots; null = the renderer's clock
|
|
222
|
+
scene.add(swaying, sheltered);
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
A swaying tree needs a render loop (`renderer.setAnimationLoop`).
|
|
226
|
+
|
|
227
|
+
## Forests
|
|
228
|
+
|
|
229
|
+

|
|
230
|
+
|
|
231
|
+
*400 trees from 4 Variants, with a per-tree Season (autumn towards the right).*
|
|
232
|
+
|
|
233
|
+
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,
|
|
235
|
+
Season shift and wind phase come from a hash of the forest seed and the tree's id (or position), so adding
|
|
236
|
+
or removing trees never changes the others.
|
|
237
|
+
|
|
238
|
+
```ts
|
|
239
|
+
import { Raycaster } from 'three/webgpu';
|
|
240
|
+
import { createForest, type ForestPlacement } from '@casmo/tree.js';
|
|
241
|
+
import lowPoly from '@casmo/tree.js/styles/low-poly';
|
|
242
|
+
|
|
243
|
+
const placements: ForestPlacement[] = [];
|
|
244
|
+
for (let i = 0; i < 400; i++) {
|
|
245
|
+
placements.push({ id: i, position: [(i % 20) * 4, 0, Math.floor(i / 20) * 4], rotation: i * 2.4, scale: 0.8 + (i % 5) * 0.1 });
|
|
246
|
+
}
|
|
247
|
+
const forest = createForest(lowPoly.conifer, placements, { variants: 4, seed: 1, growth: 1, season: 0.3 });
|
|
248
|
+
scene.add(forest);
|
|
249
|
+
|
|
250
|
+
forest.season = 0.65; // every tree, each with its own shift
|
|
251
|
+
forest.addTree({ id: 'new', position: [-4, 0, 0] });
|
|
252
|
+
forest.removeTree(17); // by id, key or ForestTree
|
|
253
|
+
const tree = forest.get('new');
|
|
254
|
+
if (tree) tree.growth = 0.3; // per-tree Growth and Season
|
|
255
|
+
|
|
256
|
+
// Which tree did the user click?
|
|
257
|
+
const raycaster = new Raycaster(); // set from the pointer: raycaster.setFromCamera(pointer, camera)
|
|
258
|
+
const [hit] = raycaster.intersectObject(forest);
|
|
259
|
+
if (hit) console.log(forest.treeAt(hit)?.key);
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
`forest.dispose()` frees everything. `forest.ready` resolves once its textures have loaded.
|
|
263
|
+
|
|
264
|
+
## Tree Effects
|
|
265
|
+
|
|
266
|
+

|
|
267
|
+
|
|
268
|
+
*Without (left) and with (right) the `stylized` suggestion: only the tree changes, the rock and crate don't.*
|
|
269
|
+
|
|
270
|
+
`@casmo/tree.js/effects` has opt-in post-processing (TSL nodes for three.js `RenderPipeline`) that only
|
|
271
|
+
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
|
|
273
|
+
an MRT output), so no tree has to be registered.
|
|
274
|
+
|
|
275
|
+
```ts
|
|
276
|
+
import { createTreeEffects } from '@casmo/tree.js/effects';
|
|
277
|
+
|
|
278
|
+
const effects = createTreeEffects(renderer, scene, camera, { effects: 'stylized' }); // the Style's suggested combination
|
|
279
|
+
renderer.setAnimationLoop(() => effects.render()); // instead of renderer.render(scene, camera)
|
|
280
|
+
effects.set({ outline: { color: '#203018', thickness: 2 }, grade: { saturation: 1.1 } }); // or null = none
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
Pass `selection: [tree]` to outline only some trees. In your own pipeline, the effects are nodes that
|
|
284
|
+
compose with your other effects:
|
|
285
|
+
|
|
286
|
+
```ts
|
|
287
|
+
import * as THREE from 'three/webgpu';
|
|
288
|
+
import { float, screenUV, vec4 } from 'three/tsl';
|
|
289
|
+
import { applyTreeEffects, SUGGESTED_TREE_EFFECTS, treeEffectsPass } from '@casmo/tree.js/effects';
|
|
290
|
+
|
|
291
|
+
const pipeline = new THREE.RenderPipeline(renderer);
|
|
292
|
+
const input = treeEffectsPass(scene, camera); // { pass, color, mask }
|
|
293
|
+
const trees = applyTreeEffects(input, SUGGESTED_TREE_EFFECTS['low-poly']); // or treeOutline / leafGlow / treeColorGrade
|
|
294
|
+
const vignette = float(1).sub(screenUV.sub(0.5).length().mul(0.9).pow(2)); // your own effect on top
|
|
295
|
+
pipeline.outputNode = vec4(trees.rgb.mul(vignette), 1);
|
|
296
|
+
renderer.setAnimationLoop(() => pipeline.render());
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
To add the tree mask to a scene pass you already have, merge `treeMaskMRT()` into its MRT and read the
|
|
300
|
+
mask with `scenePass.getTextureNode(TREE_MASK)`.
|
|
301
|
+
|
|
302
|
+
## React Three Fiber
|
|
303
|
+
|
|
304
|
+

|
|
305
|
+
|
|
306
|
+
`@casmo/tree.js/react` has `<Tree>`, `<Forest>`, `<Wind>` and `useTreeStyle`. Trees use TSL node
|
|
307
|
+
materials, so give `<Canvas>` a `WebGPURenderer` (it falls back to WebGL2 by itself). R3F v9 takes an
|
|
308
|
+
async `gl` factory, which must `await renderer.init()` before it returns:
|
|
309
|
+
|
|
310
|
+
```tsx
|
|
311
|
+
import * as THREE from 'three/webgpu';
|
|
312
|
+
import { Suspense } from 'react';
|
|
313
|
+
import { createRoot } from 'react-dom/client';
|
|
314
|
+
import { Canvas } from '@react-three/fiber';
|
|
315
|
+
import { Forest, Tree, Wind, useTreeStyle } from '@casmo/tree.js/react';
|
|
316
|
+
|
|
317
|
+
function Trees() {
|
|
318
|
+
const lowPoly = useTreeStyle('low-poly'); // dynamic import; suspends while it loads
|
|
319
|
+
return (
|
|
320
|
+
<>
|
|
321
|
+
<Tree style={lowPoly} form="broadleaf" seed={1} growth={0.8} season={0.4} />
|
|
322
|
+
<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]} />
|
|
324
|
+
<Forest
|
|
325
|
+
style={lowPoly}
|
|
326
|
+
form="conifer"
|
|
327
|
+
placements={[
|
|
328
|
+
{ id: 'a', position: [0, 0, -8] },
|
|
329
|
+
{ id: 'b', position: [4, 0, -9], growth: 0.5 },
|
|
330
|
+
]}
|
|
331
|
+
/>
|
|
332
|
+
</>
|
|
333
|
+
);
|
|
334
|
+
}
|
|
335
|
+
|
|
336
|
+
function App() {
|
|
337
|
+
return (
|
|
338
|
+
<Canvas
|
|
339
|
+
shadows="percentage"
|
|
340
|
+
camera={{ position: [9, 4, 9] }}
|
|
341
|
+
gl={async (props) => {
|
|
342
|
+
const renderer = new THREE.WebGPURenderer(props as THREE.WebGPURendererParameters);
|
|
343
|
+
await renderer.init();
|
|
344
|
+
return renderer;
|
|
345
|
+
}}
|
|
346
|
+
>
|
|
347
|
+
<hemisphereLight args={['#ffffff', '#6a7a4a', 1.5]} />
|
|
348
|
+
<directionalLight position={[5, 8, 3]} intensity={2.5} castShadow />
|
|
349
|
+
<Wind direction={[1, 0, 0]} strength={0.5} />
|
|
350
|
+
<Suspense fallback={null}>
|
|
351
|
+
<Trees />
|
|
352
|
+
</Suspense>
|
|
353
|
+
</Canvas>
|
|
354
|
+
);
|
|
355
|
+
}
|
|
356
|
+
|
|
357
|
+
createRoot(document.getElementById('root')!).render(<App />);
|
|
358
|
+
```
|
|
359
|
+
|
|
360
|
+
- `growth`, `season`, `wind`, `castShadow`/`receiveShadow` and `<Wind>` props only update uniforms or flags on the same tree
|
|
361
|
+
(`tree.wind = otherWind` does the same outside React).
|
|
362
|
+
- A new `seed`, `definition` (compared by value) or `style`/`form` regenerates the tree. Trees are disposed of on unmount.
|
|
363
|
+
- `style` also takes a Style name (`<Tree style="low-poly" />`), which suspends like `useTreeStyle`. The `ref` is the tree.js `Tree` (or `Forest`) object.
|
|
364
|
+
- `<Forest>` diffs its `placements` by id: changing the array plants and cuts trees without touching the others; per-tree `growth`/`season` override the forest's.
|
|
365
|
+
- Use `shadows="percentage"` (plain `shadows` asks for a shadow type WebGPURenderer no longer has).
|
|
366
|
+
|
|
367
|
+
## Without a bundler: import map (CDN)
|
|
368
|
+
|
|
369
|
+

|
|
370
|
+
|
|
371
|
+
*[`examples/cdn`](examples/cdn/index.html): Growth, Season and Wind sliders, no build step.*
|
|
372
|
+
|
|
373
|
+
The package is plain ES modules, so it runs straight from a CDN with an
|
|
374
|
+
[import map](https://developer.mozilla.org/docs/Web/HTML/Element/script/type/importmap). Map `three`'s
|
|
375
|
+
entry points and the library (with a trailing-slash entry for its subpaths):
|
|
376
|
+
|
|
377
|
+
```html
|
|
378
|
+
<script type="importmap">
|
|
379
|
+
{
|
|
380
|
+
"imports": {
|
|
381
|
+
"three": "https://cdn.jsdelivr.net/npm/three@0.187.0/build/three.webgpu.js",
|
|
382
|
+
"three/webgpu": "https://cdn.jsdelivr.net/npm/three@0.187.0/build/three.webgpu.js",
|
|
383
|
+
"three/tsl": "https://cdn.jsdelivr.net/npm/three@0.187.0/build/three.tsl.js",
|
|
384
|
+
"three/addons/": "https://cdn.jsdelivr.net/npm/three@0.187.0/examples/jsm/",
|
|
385
|
+
"@casmo/tree.js": "https://cdn.jsdelivr.net/npm/@casmo/tree.js/dist/index.js",
|
|
386
|
+
"@casmo/tree.js/": "https://cdn.jsdelivr.net/npm/@casmo/tree.js/dist/"
|
|
387
|
+
}
|
|
388
|
+
}
|
|
389
|
+
</script>
|
|
390
|
+
<script type="module">
|
|
391
|
+
import * as THREE from 'three/webgpu';
|
|
392
|
+
import { createTree, loadStyle } from '@casmo/tree.js';
|
|
393
|
+
import { createTreeEffects } from '@casmo/tree.js/effects.js'; // subpaths: dist/<name>.js
|
|
394
|
+
|
|
395
|
+
const lowPoly = await loadStyle('low-poly'); // or import '@casmo/tree.js/styles/low-poly.js'
|
|
396
|
+
const tree = createTree(lowPoly.broadleaf, { seed: 3 });
|
|
397
|
+
// ...the same scene setup as in the quick start
|
|
398
|
+
</script>
|
|
399
|
+
```
|
|
400
|
+
|
|
401
|
+
Styles and the realistic textures load relative to the library's URL, so they come from the CDN too. See
|
|
402
|
+
[`examples/cdn/index.html`](examples/cdn/index.html) for a complete page (with Growth, Season and Wind sliders).
|
|
403
|
+
|
|
404
|
+
## Baked Trees (glTF export)
|
|
405
|
+
|
|
406
|
+

|
|
407
|
+
|
|
408
|
+
*A `.glb` from `exportBakedTree(tree, { season: 0.6 })`, loaded back with three.js' `GLTFLoader`.*
|
|
409
|
+
|
|
410
|
+
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:
|
|
412
|
+
|
|
413
|
+
```ts
|
|
414
|
+
import { bakeTree, createTree, disposeBakedTree, exportBakedTree } from '@casmo/tree.js';
|
|
415
|
+
|
|
416
|
+
const tree = createTree({ schemaVersion: 2 }, { seed: 4 });
|
|
417
|
+
const glb = await exportBakedTree(tree, { growth: 1, season: 0.6 }); // ArrayBuffer (.glb); binary: false = glTF JSON
|
|
418
|
+
const url = URL.createObjectURL(new Blob([glb], { type: 'model/gltf-binary' }));
|
|
419
|
+
|
|
420
|
+
const baked = bakeTree(tree, { season: 0.6 }); // a THREE.Group, e.g. for your own exporter
|
|
421
|
+
// ...export it, then free its geometries and materials:
|
|
422
|
+
disposeBakedTree(baked);
|
|
423
|
+
```
|
|
424
|
+
|
|
425
|
+
## Textures
|
|
426
|
+
|
|
427
|
+

|
|
428
|
+
|
|
429
|
+
Definitions with textures (the realistic Style, or your own `materials.bark.map` / `materials.leaf.map`
|
|
430
|
+
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:
|
|
432
|
+
|
|
433
|
+
```ts
|
|
434
|
+
import { createTree, setTextureOptions } from '@casmo/tree.js';
|
|
435
|
+
import realistic from '@casmo/tree.js/styles/realistic';
|
|
436
|
+
|
|
437
|
+
setTextureOptions({ basePath: 'https://cdn.example.com/tree-textures/' });
|
|
438
|
+
const tree = createTree(realistic.conifer, {
|
|
439
|
+
seed: 1,
|
|
440
|
+
textures: { urls: { 'realistic/needles.png': '/my-needles.png' } }, // per-tree overrides win
|
|
441
|
+
});
|
|
442
|
+
await tree.ready;
|
|
443
|
+
```
|
|
444
|
+
|
|
445
|
+
## Tree Editor
|
|
446
|
+
|
|
447
|
+

|
|
448
|
+
|
|
449
|
+
The Tree Editor is a web app for designing Tree Definitions: start from a Style, change every parameter with
|
|
450
|
+
a live preview (Seed, Growth, Season, Wind, Tree Effects), sculpt single branches and leaf areas of one Seed
|
|
451
|
+
(move, delete, paint leaves), undo/redo, and export the Definition as JSON for
|
|
452
|
+
`createTree(definition)` (or a Baked Tree as `.glb`). It is published on GitHub Pages
|
|
453
|
+
([casmo.github.io/tree.js](https://casmo.github.io/tree.js/)); run it locally with `npm run dev:editor`.
|
|
454
|
+
|
|
455
|
+
## Examples
|
|
456
|
+
|
|
457
|
+
| Example | Run | What | |
|
|
458
|
+
| --- | --- | --- | --- |
|
|
459
|
+
| [`examples/vanilla`](examples/vanilla/main.ts) | `/examples/vanilla/` | one tree in plain three.js; `?style=low-poly&form=conifer&seed=2&growth=0.6&season=0.7&wind=0.5` | <img src="docs/images/example-vanilla.png" alt="examples/vanilla" width="160"> |
|
|
460
|
+
| [`examples/cdn`](examples/cdn/index.html) | `/examples/cdn/` | no bundler: a single HTML page with an import map | <img src="docs/images/example-cdn.png" alt="examples/cdn" width="160"> |
|
|
461
|
+
| [`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
|
+
| [`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
|
+
| [`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"> |
|
|
464
|
+
|
|
465
|
+
```sh
|
|
466
|
+
npm install
|
|
467
|
+
npm run dev # then open http://localhost:5173/examples/vanilla/ (or any example above)
|
|
468
|
+
npm run build:examples # production build of the bundled examples -> examples/dist
|
|
469
|
+
```
|
|
470
|
+
|
|
471
|
+
The examples import the library by its package name (`@casmo/tree.js`), exactly like an app would; in this
|
|
472
|
+
repository that name resolves to the sources. The CDN example needs no build at all: copy
|
|
473
|
+
`examples/cdn/index.html` anywhere and open it over http(s). (The dev server rewrites its imports to the
|
|
474
|
+
sources too; the e2e test serves it unmodified, with the import map answered by the built `dist/`.)
|
|
475
|
+
|
|
476
|
+
## Development
|
|
477
|
+
|
|
478
|
+
`npm test` (Vitest), `npm run typecheck`, `npm run lint`, `npm run build` (library -> `dist/`),
|
|
479
|
+
`npm run test:e2e` (Playwright; run `npm run build` and `npm run build:examples` first, as CI does).
|
|
480
|
+
The README's screenshots and GIFs (`docs/images/`) are rendered by `npm run readme-media`
|
|
481
|
+
(Playwright + ffmpeg; run `npm run build` first; `npm run readme-media -- wind hero` redoes only those).
|
|
482
|
+
Design decisions live in [`docs/adr`](docs/adr), the vocabulary in [`GLOSSARY.md`](GLOSSARY.md).
|
|
483
|
+
|
|
484
|
+
## License
|
|
485
|
+
|
|
486
|
+
MIT
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
import { Group } from 'three/webgpu';
|
|
2
|
+
import type { Tree } from '../tree';
|
|
3
|
+
/**
|
|
4
|
+
* Baked Tree: one tree frozen at a Seed, Growth and Season as plain static geometry with
|
|
5
|
+
* standard PBR materials (`MeshStandardMaterial`, no node materials, no custom attributes), for
|
|
6
|
+
* glTF export and other tools. Growth and Season are evaluated on the CPU with the same models the
|
|
7
|
+
* shaders run (`growPositions`, `leafSeason`); Wind is left out (a Baked Tree stands still).
|
|
8
|
+
*/
|
|
9
|
+
/** Growth and Season to bake at; each defaults to the tree's current value. */
|
|
10
|
+
export interface BakeOptions {
|
|
11
|
+
growth?: number;
|
|
12
|
+
season?: number;
|
|
13
|
+
}
|
|
14
|
+
/**
|
|
15
|
+
* Freezes a tree at a Growth and Season (default: the tree's own) into a static `Group` of
|
|
16
|
+
* meshes `wood` and `leaves` (a mesh with nothing to show is left out) with standard PBR
|
|
17
|
+
* materials: no node materials, no Growth/Season/Wind attributes, no animation. The result is
|
|
18
|
+
* independent of `tree`; call `disposeBakedTree` when done with it.
|
|
19
|
+
*/
|
|
20
|
+
export declare function bakeTree(tree: Tree, options?: BakeOptions): Group;
|
|
21
|
+
/** Frees the geometries, materials and texture copies of a baked tree. */
|
|
22
|
+
export declare function disposeBakedTree(baked: Group): void;
|
|
23
|
+
export interface ExportBakedTreeOptions extends BakeOptions {
|
|
24
|
+
/** `.glb` (ArrayBuffer, default) or `.gltf` JSON with embedded buffers. */
|
|
25
|
+
binary?: boolean;
|
|
26
|
+
}
|
|
27
|
+
/**
|
|
28
|
+
* Bakes a tree (see {@link bakeTree}) and writes it as glTF 2.0: a `.glb` ArrayBuffer by default,
|
|
29
|
+
* or the `.gltf` JSON object with `binary: false`. Waits for the tree's textures first. In Node,
|
|
30
|
+
* three's GLTFExporter needs a `FileReader` global.
|
|
31
|
+
*/
|
|
32
|
+
export declare function exportBakedTree(tree: Tree, options?: ExportBakedTreeOptions & {
|
|
33
|
+
binary?: true;
|
|
34
|
+
}): Promise<ArrayBuffer>;
|
|
35
|
+
export declare function exportBakedTree(tree: Tree, options: ExportBakedTreeOptions & {
|
|
36
|
+
binary: false;
|
|
37
|
+
}): Promise<Record<string, unknown>>;
|
|
38
|
+
export declare function exportBakedTree(tree: Tree, options?: ExportBakedTreeOptions): Promise<ArrayBuffer | Record<string, unknown>>;
|
|
39
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/bake/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,EAIN,MAAM,cAAc,CAAC;AAQtB,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAEpC;;;;;GAKG;AAEH,+EAA+E;AAC/E,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AA+GD;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,GAAE,WAAgB,GAAG,KAAK,CA4CrE;AASD,0EAA0E;AAC1E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CASnD;AAED,MAAM,WAAW,sBAAuB,SAAQ,WAAW;IACzD,2EAA2E;IAC3E,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,EAAE,sBAAsB,GAAG;IAAE,MAAM,CAAC,EAAE,IAAI,CAAA;CAAE,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;AACxH,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,sBAAsB,GAAG;IAAE,MAAM,EAAE,KAAK,CAAA;CAAE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AACnI,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC"}
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
import { type BranchLevelDefinition, type TreeDefinition } from './types';
|
|
2
|
+
/** Defaults for one branching level; fills fields missing from a partial `branches[i]`. */
|
|
3
|
+
export declare const DEFAULT_BRANCH_LEVEL: BranchLevelDefinition;
|
|
4
|
+
/**
|
|
5
|
+
* The documented defaults: a small broadleaf tree with two branching levels.
|
|
6
|
+
* Anything a Definition leaves out is taken from here.
|
|
7
|
+
*/
|
|
8
|
+
export declare const DEFAULT_DEFINITION: TreeDefinition;
|
|
9
|
+
//# sourceMappingURL=defaults.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../../src/definition/defaults.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,KAAK,qBAAqB,EAAE,KAAK,cAAc,EAAE,MAAM,SAAS,CAAC;AAElG,2FAA2F;AAC3F,eAAO,MAAM,oBAAoB,EAAE,qBAelC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAE,cAqDhC,CAAC"}
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
export { CURRENT_SCHEMA_VERSION, MAX_BRANCH_LEVELS } from './types';
|
|
2
|
+
export type { TreeDefinition, TreeDefinitionInput, DeepPartial, HexColor, Vec3Tuple, TreeForm, TrunkDefinition, BranchLevelDefinition, LeafShape, LeavesDefinition, Shading, MaterialsDefinition, BarkMaterialDefinition, LeafMaterialDefinition, Keyframe, SeasonProfileDefinition, WindResponseDefinition, VariationDefinition, Sculpt, DeleteSculpt, MoveSculpt, LeavesSculpt, } from './types';
|
|
3
|
+
export { DEFAULT_DEFINITION, DEFAULT_BRANCH_LEVEL } from './defaults';
|
|
4
|
+
export { parseDefinition, extendDefinition, fetchDefinition, TreeDefinitionError, type DefinitionPatch, } from './parse';
|
|
5
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/definition/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AACpE,YAAY,EACV,cAAc,EACd,mBAAmB,EACnB,WAAW,EACX,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,eAAe,EACf,qBAAqB,EACrB,SAAS,EACT,gBAAgB,EAChB,OAAO,EACP,mBAAmB,EACnB,sBAAsB,EACtB,sBAAsB,EACtB,QAAQ,EACR,uBAAuB,EACvB,sBAAsB,EACtB,mBAAmB,EACnB,MAAM,EACN,YAAY,EACZ,UAAU,EACV,YAAY,GACb,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AACtE,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,mBAAmB,EACnB,KAAK,eAAe,GACrB,MAAM,SAAS,CAAC"}
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Schema migrations. `MIGRATIONS[n]` turns a raw (unvalidated) schemaVersion `n` object into
|
|
3
|
+
* a raw schemaVersion `n + 1` object. Migrations run in order before defaults and validation,
|
|
4
|
+
* so they only need to move/rename what changed; missing fields are defaulted afterwards.
|
|
5
|
+
*
|
|
6
|
+
* To change the format: bump CURRENT_SCHEMA_VERSION, add `MIGRATIONS[old]`, and add a
|
|
7
|
+
* fixture in test/fixtures/definition-v<old>.json with a test.
|
|
8
|
+
*/
|
|
9
|
+
type Raw = Record<string, unknown>;
|
|
10
|
+
export declare const MIGRATIONS: Record<number, (input: Raw) => Raw>;
|
|
11
|
+
export {};
|
|
12
|
+
//# sourceMappingURL=migrations.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"migrations.d.ts","sourceRoot":"","sources":["../../src/definition/migrations.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,KAAK,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEnC,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,GAAG,CAgB1D,CAAC"}
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
import { type DeepPartial, type TreeDefinition, type TreeDefinitionInput } from './types';
|
|
2
|
+
export { TreeDefinitionError } from './schema';
|
|
3
|
+
/**
|
|
4
|
+
* Turns untrusted input into a complete, valid Tree Definition:
|
|
5
|
+
* - `input` is a Definition object (e.g. parsed JSON) or a JSON string;
|
|
6
|
+
* - older `schemaVersion`s are migrated to {@link CURRENT_SCHEMA_VERSION};
|
|
7
|
+
* - missing fields are filled from {@link DEFAULT_DEFINITION} (missing fields of a
|
|
8
|
+
* `branches[i]` entry from {@link DEFAULT_BRANCH_LEVEL});
|
|
9
|
+
* - every field is validated; unknown fields are rejected.
|
|
10
|
+
* Throws {@link TreeDefinitionError} naming the first bad field (`field`, e.g. `branches[1].angle`).
|
|
11
|
+
* Never mutates `input`.
|
|
12
|
+
*/
|
|
13
|
+
export declare function parseDefinition(input: unknown): TreeDefinition;
|
|
14
|
+
/** Changes to apply on top of a Definition: any subset of its fields (arrays replace as a whole). */
|
|
15
|
+
export type DefinitionPatch = DeepPartial<Omit<TreeDefinition, 'schemaVersion'>>;
|
|
16
|
+
/**
|
|
17
|
+
* Starts from a Definition (e.g. a built-in Style) and changes a few parameters:
|
|
18
|
+
* objects are merged deeply, arrays and values replace. Returns a new, validated Definition.
|
|
19
|
+
*
|
|
20
|
+
* ```ts
|
|
21
|
+
* const tall = extendDefinition(broadleaf, { trunk: { length: 7 }, wind: { leaves: 1 } });
|
|
22
|
+
* ```
|
|
23
|
+
*/
|
|
24
|
+
export declare function extendDefinition(base: TreeDefinition | TreeDefinitionInput, patch: DefinitionPatch): TreeDefinition;
|
|
25
|
+
/**
|
|
26
|
+
* Fetches a Tree Definition JSON file (e.g. a Tree Editor export) and parses it with
|
|
27
|
+
* {@link parseDefinition}. Rejects with an Error for an HTTP error, or a TreeDefinitionError.
|
|
28
|
+
*/
|
|
29
|
+
export declare function fetchDefinition(url: string | URL, init?: RequestInit): Promise<TreeDefinition>;
|
|
30
|
+
//# sourceMappingURL=parse.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/definition/parse.ts"],"names":[],"mappings":"AAEA,OAAO,EAA0B,KAAK,WAAW,EAAE,KAAK,cAAc,EAAE,KAAK,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAElH,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAE/C;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CAuB9D;AAED,qGAAqG;AACrG,MAAM,MAAM,eAAe,GAAG,WAAW,CAAC,IAAI,CAAC,cAAc,EAAE,eAAe,CAAC,CAAC,CAAC;AAEjF;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,mBAAmB,EAAE,KAAK,EAAE,eAAe,GAAG,cAAc,CAInH;AAWD;;;GAGG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC,CAIpG"}
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
import { type TreeDefinition } from './types';
|
|
2
|
+
/** Thrown for an invalid Tree Definition; `field` is the path of the bad field, e.g. `branches[1].angle`. */
|
|
3
|
+
export declare class TreeDefinitionError extends Error {
|
|
4
|
+
readonly field: string;
|
|
5
|
+
constructor(field: string, message: string);
|
|
6
|
+
}
|
|
7
|
+
export declare function isObject(v: unknown): v is Record<string, unknown>;
|
|
8
|
+
/**
|
|
9
|
+
* Validates a raw current-version Definition and fills every missing field from
|
|
10
|
+
* {@link DEFAULT_DEFINITION}. Returns a fresh object (never aliases input or defaults).
|
|
11
|
+
*/
|
|
12
|
+
export declare function validateDefinition(raw: Record<string, unknown>): TreeDefinition;
|
|
13
|
+
//# sourceMappingURL=schema.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/definition/schema.ts"],"names":[],"mappings":"AACA,OAAO,EASL,KAAK,cAAc,EACpB,MAAM,SAAS,CAAC;AAEjB,6GAA6G;AAC7G,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBACX,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK3C;AAYD,wBAAgB,QAAQ,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEjE;AA+JD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,cAAc,CAE/E"}
|