@casmo/tree.js 0.4.0 → 0.5.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 +590 -4
- package/dist/effects/custom.d.ts +62 -0
- package/dist/effects/custom.d.ts.map +1 -0
- package/dist/effects/effects.d.ts +42 -1
- package/dist/effects/effects.d.ts.map +1 -1
- package/dist/effects/index.d.ts +2 -0
- package/dist/effects/index.d.ts.map +1 -1
- package/dist/effects/mask.d.ts +9 -1
- package/dist/effects/mask.d.ts.map +1 -1
- package/dist/effects/tree-id.d.ts.map +1 -1
- package/dist/effects-qHx_8Dlk.js +1052 -0
- package/dist/effects-qHx_8Dlk.js.map +1 -0
- package/dist/effects.js +2 -963
- package/dist/forest/Forest.d.ts +80 -4
- package/dist/forest/Forest.d.ts.map +1 -1
- package/dist/forest/forest-lod.d.ts +70 -0
- package/dist/forest/forest-lod.d.ts.map +1 -0
- package/dist/forest/impostor-material.d.ts +106 -0
- package/dist/forest/impostor-material.d.ts.map +1 -0
- package/dist/forest/impostor-season.d.ts +13 -0
- package/dist/forest/impostor-season.d.ts.map +1 -0
- package/dist/forest/impostor.d.ts +105 -0
- package/dist/forest/impostor.d.ts.map +1 -0
- package/dist/forest/index.d.ts +1 -0
- package/dist/forest/index.d.ts.map +1 -1
- package/dist/forest/levels.d.ts +144 -0
- package/dist/forest/levels.d.ts.map +1 -0
- package/dist/forest/lod.d.ts +106 -0
- package/dist/forest/lod.d.ts.map +1 -0
- package/dist/forest/nodes.d.ts +42 -1
- package/dist/forest/nodes.d.ts.map +1 -1
- package/dist/forest/octahedral.d.ts +33 -0
- package/dist/forest/octahedral.d.ts.map +1 -0
- package/dist/{forest-lg61rhKM.js → forest-CM5DrklM.js} +1723 -340
- package/dist/forest-CM5DrklM.js.map +1 -0
- package/dist/generator/fruit.d.ts +2 -0
- package/dist/generator/fruit.d.ts.map +1 -1
- package/dist/generator/index.d.ts +1 -0
- package/dist/generator/index.d.ts.map +1 -1
- package/dist/generator/light.d.ts +36 -0
- package/dist/generator/light.d.ts.map +1 -0
- package/dist/index.d.ts +3 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +5 -2
- package/dist/index.js.map +1 -1
- package/dist/materials/crown-nodes.d.ts +5 -0
- package/dist/materials/crown-nodes.d.ts.map +1 -1
- package/dist/materials/leaf-translucency-model.d.ts +6 -1
- package/dist/materials/leaf-translucency-model.d.ts.map +1 -1
- package/dist/materials/material-features.d.ts +12 -0
- package/dist/materials/material-features.d.ts.map +1 -1
- package/dist/materials/shader-hooks.d.ts +155 -0
- package/dist/materials/shader-hooks.d.ts.map +1 -0
- package/dist/motion-Qd7xjeZM.js +276 -0
- package/dist/motion-Qd7xjeZM.js.map +1 -0
- package/dist/nodes-DxgTyF9B.js +436 -0
- package/dist/nodes-DxgTyF9B.js.map +1 -0
- package/dist/react/Forest.d.ts +17 -3
- package/dist/react/Forest.d.ts.map +1 -1
- package/dist/react/ScenePipeline.d.ts +63 -0
- package/dist/react/ScenePipeline.d.ts.map +1 -0
- package/dist/react/SceneShaderHooks.d.ts +25 -0
- package/dist/react/SceneShaderHooks.d.ts.map +1 -0
- package/dist/react/Tree.d.ts +9 -2
- package/dist/react/Tree.d.ts.map +1 -1
- package/dist/react/Weather.d.ts +45 -0
- package/dist/react/Weather.d.ts.map +1 -0
- package/dist/react/Wind.d.ts +12 -1
- package/dist/react/Wind.d.ts.map +1 -1
- package/dist/react/index.d.ts +7 -1
- package/dist/react/index.d.ts.map +1 -1
- package/dist/react.js +347 -10
- package/dist/react.js.map +1 -1
- package/dist/renderer/index.d.ts +6 -0
- package/dist/renderer/index.d.ts.map +1 -1
- package/dist/scene/antialias.d.ts +35 -0
- package/dist/scene/antialias.d.ts.map +1 -0
- package/dist/scene/ao.d.ts +46 -0
- package/dist/scene/ao.d.ts.map +1 -0
- package/dist/scene/bloom.d.ts +19 -0
- package/dist/scene/bloom.d.ts.map +1 -0
- package/dist/scene/fog.d.ts +49 -0
- package/dist/scene/fog.d.ts.map +1 -0
- package/dist/scene/godrays.d.ts +37 -0
- package/dist/scene/godrays.d.ts.map +1 -0
- package/dist/scene/index.d.ts +14 -0
- package/dist/scene/index.d.ts.map +1 -0
- package/dist/scene/motion-blur.d.ts +23 -0
- package/dist/scene/motion-blur.d.ts.map +1 -0
- package/dist/scene/pipeline.d.ts +109 -0
- package/dist/scene/pipeline.d.ts.map +1 -0
- package/dist/scene/settings.d.ts +36 -0
- package/dist/scene/settings.d.ts.map +1 -0
- package/dist/scene/stack.d.ts +25 -0
- package/dist/scene/stack.d.ts.map +1 -0
- package/dist/scene/stage.d.ts +52 -0
- package/dist/scene/stage.d.ts.map +1 -0
- package/dist/scene/suggested.d.ts +12 -0
- package/dist/scene/suggested.d.ts.map +1 -0
- package/dist/scene/tone-mapping.d.ts +20 -0
- package/dist/scene/tone-mapping.d.ts.map +1 -0
- package/dist/scene/velocity.d.ts +34 -0
- package/dist/scene/velocity.d.ts.map +1 -0
- package/dist/scene.js +889 -0
- package/dist/scene.js.map +1 -0
- package/dist/season/nodes.d.ts +13 -0
- package/dist/season/nodes.d.ts.map +1 -1
- package/dist/shader-hooks-BFRtlWGI.js +275 -0
- package/dist/shader-hooks-BFRtlWGI.js.map +1 -0
- package/dist/tree/Tree.d.ts +8 -3
- package/dist/tree/Tree.d.ts.map +1 -1
- package/dist/tree/index.d.ts.map +1 -1
- package/dist/weather/index.d.ts +3 -0
- package/dist/weather/index.d.ts.map +1 -0
- package/dist/weather/shared.d.ts +43 -0
- package/dist/weather/shared.d.ts.map +1 -0
- package/dist/weather/snow.d.ts +87 -0
- package/dist/weather/snow.d.ts.map +1 -0
- package/dist/weather/wetness.d.ts +75 -0
- package/dist/weather/wetness.d.ts.map +1 -0
- package/dist/weather.js +288 -0
- package/dist/weather.js.map +1 -0
- package/dist/wind/Wind.d.ts +100 -5
- package/dist/wind/Wind.d.ts.map +1 -1
- package/dist/wind/burst.d.ts +28 -0
- package/dist/wind/burst.d.ts.map +1 -0
- package/dist/wind/index.d.ts +3 -2
- package/dist/wind/index.d.ts.map +1 -1
- package/dist/wind/motion.d.ts +30 -0
- package/dist/wind/motion.d.ts.map +1 -0
- package/dist/wind/node.d.ts +17 -3
- package/dist/wind/node.d.ts.map +1 -1
- package/package.json +9 -1
- package/dist/effects.js.map +0 -1
- package/dist/forest-lg61rhKM.js.map +0 -1
package/README.md
CHANGED
|
@@ -18,6 +18,7 @@ thousands at once as an instanced Forest, add opt-in Tree Effects, or design you
|
|
|
18
18
|
- [Wind](#wind)
|
|
19
19
|
- [Forests](#forests)
|
|
20
20
|
- [Material Features](#material-features)
|
|
21
|
+
- [Tree Shader Hook](#tree-shader-hook)
|
|
21
22
|
- [Tree Effects](#tree-effects)
|
|
22
23
|
- [React Three Fiber](#react-three-fiber)
|
|
23
24
|
- [Without a bundler: import map (CDN)](#without-a-bundler-import-map-cdn)
|
|
@@ -42,7 +43,9 @@ npm install @casmo/tree.js three
|
|
|
42
43
|
| `@casmo/tree.js/styles/low-poly` (`stylized`, `realistic`) | a built-in Style: one Tree Definition per Form (a few kB of data) |
|
|
43
44
|
| `@casmo/tree.js/species` | the 28 Species (`oak`, `douglasFir`, ...), `loadSpecies`, `SPECIES_NAMES`; JSON files |
|
|
44
45
|
| `@casmo/tree.js/effects` | Tree Effects (post-processing) |
|
|
45
|
-
| `@casmo/tree.js/
|
|
46
|
+
| `@casmo/tree.js/scene` | Scene Pipeline: the Style's suggested Tree Effects and Scene Effects (tone mapping, SMAA/FXAA, fog, ...) in one opt-in pipeline |
|
|
47
|
+
| `@casmo/tree.js/weather` | ready-made weather Tree Shader Hooks: [Snow Cover](#snow-cover), [Wetness](#wetness) |
|
|
48
|
+
| `@casmo/tree.js/react` | `<Tree>`, `<Forest>`, `<Wind>`, `useTreeStyle`, `<ScenePipeline>` for React Three Fiber |
|
|
46
49
|
|
|
47
50
|
## Quick start
|
|
48
51
|
|
|
@@ -384,6 +387,55 @@ scene.add(swaying, sheltered);
|
|
|
384
387
|
|
|
385
388
|
A swaying tree needs a render loop (`renderer.setAnimationLoop`).
|
|
386
389
|
|
|
390
|
+
### Wind Burst
|
|
391
|
+
|
|
392
|
+
A Wind Burst is a short, local push of air from a point on the ground, e.g. where the player places a
|
|
393
|
+
building: trees within its radius bend away from it, the front rolls outward at 30 m/s, and the push
|
|
394
|
+
springs back once and fades out within 1.2 s of Wind time. It adds to the Wind on trunk, branches and
|
|
395
|
+
leaves, scaled by each tree's Wind response, also when the Wind is calm:
|
|
396
|
+
|
|
397
|
+
```ts
|
|
398
|
+
import { createTree, sceneWind } from '@casmo/tree.js';
|
|
399
|
+
|
|
400
|
+
const tree = createTree({ schemaVersion: 3 }, { seed: 1 });
|
|
401
|
+
tree.position.set(3, 0, 0);
|
|
402
|
+
|
|
403
|
+
sceneWind.burst({ x: 1, z: 0, strength: 1, radius: 6 }); // radius defaults to 8 m per unit of strength
|
|
404
|
+
sceneWind.burst({ x: 1, z: 0, strength: -0.5 }); // reduced motion: lean away and settle, no swing
|
|
405
|
+
console.log(sceneWind.bursts.length); // the bursts running now
|
|
406
|
+
```
|
|
407
|
+
|
|
408
|
+
A negative strength is the reduced-motion mode, for players who turn motion down: trees within reach
|
|
409
|
+
lean away from the point all at once and settle, with no front travelling outward and no swing back; the
|
|
410
|
+
size of the value is the strength (and sets the default radius). A weaker positive strength simply
|
|
411
|
+
pushes less.
|
|
412
|
+
|
|
413
|
+
Up to 8 bursts (`MAX_WIND_BURSTS`) run at once per Wind; another one replaces the oldest. A burst starts
|
|
414
|
+
at the Wind's current time (its pinned `time`, or the renderer clock), so a pinned clock holds it still.
|
|
415
|
+
The Wind-aware velocity channel (TRAA, motion blur) includes burst motion.
|
|
416
|
+
|
|
417
|
+
Wind Bursts are opt-in at the material level: until a Wind has had its first `burst()`, the trees swaying
|
|
418
|
+
with it have no burst nodes at all, and their materials are exactly as without Wind Bursts. The first
|
|
419
|
+
burst on a Wind (or binding a tree or Forest to a Wind that has had one) rebuilds the node graphs of
|
|
420
|
+
those trees once, on Trees, every Forest Detail Level, Impostors and the velocity channel, so expect one
|
|
421
|
+
shader compile then; the geometry is never rebuilt. Call `burst()` once during loading (e.g. with a
|
|
422
|
+
small radius far away) to have that compile happen up front. After that a burst only writes uniforms,
|
|
423
|
+
and with no burst running the shader loop runs zero times.
|
|
424
|
+
|
|
425
|
+
Forests take the bursts of their Wind too: every Forest tree bends away from the burst point from its
|
|
426
|
+
own position and rotation, at every Detail Level, and Impostors sway with it, so the whole park reacts:
|
|
427
|
+
|
|
428
|
+
```ts
|
|
429
|
+
import { createForest, sceneWind } from '@casmo/tree.js';
|
|
430
|
+
|
|
431
|
+
const forest = createForest({ schemaVersion: 3 }, [{ position: [0, 0, 0] }, { position: [20, 0, 0] }], { lod: true });
|
|
432
|
+
scene.add(forest);
|
|
433
|
+
|
|
434
|
+
sceneWind.burst({ x: 2, z: 0, strength: 1, radius: 6 }); // the first tree bends, the second does not
|
|
435
|
+
```
|
|
436
|
+
|
|
437
|
+
Impostors also include their sway, bursts and all, in the Wind-aware velocity channel.
|
|
438
|
+
|
|
387
439
|
## Forests
|
|
388
440
|
|
|
389
441
|

|
|
@@ -422,6 +474,70 @@ if (hit) console.log(forest.treeAt(hit)?.key);
|
|
|
422
474
|
|
|
423
475
|
`forest.dispose()` frees everything. `forest.ready` resolves once its textures have loaded.
|
|
424
476
|
|
|
477
|
+
### Detail Levels
|
|
478
|
+
|
|
479
|
+
Far trees cover a few pixels but still cost their full mesh. With `lod` a Forest draws each tree at a
|
|
480
|
+
**Detail Level** for its distance from the camera: **Full** up close, **Light** (the same Variant
|
|
481
|
+
regenerated with fewer faces and larger leaves, every branch in place) in the middle distance, and an
|
|
482
|
+
**Impostor** far away: one camera-facing card per tree, lit by your lights from baked normals, that still
|
|
483
|
+
follows Season (leaf colour, leaf drop down to bare branches, blossom) and sways in the Wind. Neighbouring
|
|
484
|
+
levels cross-fade with an ordered dither, so trees never pop. A compute pass picks the levels on the GPU
|
|
485
|
+
every frame and fills indirect draws, so there is no per-tree work on the CPU. A tree that is not fully
|
|
486
|
+
grown is never an Impostor.
|
|
487
|
+
|
|
488
|
+
```ts
|
|
489
|
+
import { createForest, type ForestPlacement } from '@casmo/tree.js';
|
|
490
|
+
import lowPoly from '@casmo/tree.js/styles/low-poly';
|
|
491
|
+
|
|
492
|
+
declare const placements: ForestPlacement[]; // thousands of trees
|
|
493
|
+
|
|
494
|
+
// Light from 30 m, Impostor from 90 m (distances are divided by a tree's placement scale),
|
|
495
|
+
// cross-fading over 10% of the switch distance. `lod: true` uses 6 and 20 trunk heights.
|
|
496
|
+
const forest = createForest(lowPoly.broadleaf, placements, { variants: 4, lod: { light: 30, impostor: 90, fade: 0.1 } });
|
|
497
|
+
scene.add(forest);
|
|
498
|
+
renderer.render(scene, camera); // the first frame finds the backend and draws every tree in full
|
|
499
|
+
await forest.lodReady; // Detail Levels drawn, Impostors baked (far trees draw Light until then)
|
|
500
|
+
|
|
501
|
+
forest.lod = { impostor: 120 }; // distances, fade and the camera that picks the levels are live: no rebuild
|
|
502
|
+
```
|
|
503
|
+
|
|
504
|
+
- Detail Levels need WebGPU (compute and indirect draws). On WebGPURenderer's WebGL2 fallback a `lod`
|
|
505
|
+
Forest draws every tree in full, exactly as without `lod`, with one console warning. Without `lod` nothing
|
|
506
|
+
changes: no extra meshes, buffers or bake.
|
|
507
|
+
- The backend is only known when the Forest is first drawn: three.js hands it the renderer during that
|
|
508
|
+
render, after the frame's draw list is made. So on WebGPU the **first frame draws every tree in full**
|
|
509
|
+
(one full-cost frame), the Detail Levels take over from the next frame, and far trees switch from Light
|
|
510
|
+
to Impostor once the bake is done; on the WebGL2 fallback `lodReady` resolves on that first render, not
|
|
511
|
+
at once. To show neither switch, render once and `await forest.lodReady` before the forest is seen.
|
|
512
|
+
- One camera picks every tree's level: the first non-shadow camera that draws the Forest in a frame, or
|
|
513
|
+
`lod.camera`. Shadow passes and other cameras reuse its levels.
|
|
514
|
+
- Raycasting, `forest.treeAt`, `addTree`/`removeTree`, live Material Features and Tree Effects work as
|
|
515
|
+
without `lod`, at every Detail Level.
|
|
516
|
+
- **Memory**: the Impostors are baked into atlases of `impostorAtlas.size`² pixels (default 2048, with
|
|
517
|
+
`frames` 12 × 12 directions from the horizon to straight above), in two render targets per Variant: the
|
|
518
|
+
tree (colour, normals, Season data, and Material Feature inputs when the Definition sets them) and the
|
|
519
|
+
wood alone (colour, normals: shown where leaves have dropped). Each atlas is RGBA8 with mipmaps, about
|
|
520
|
+
21 MiB at 2048, and each render target has a depth buffer of the same size (16 MiB). That is about
|
|
521
|
+
139 MiB of GPU memory per Variant (five atlases), 160 MiB with Material Features (six), so 555 MiB or
|
|
522
|
+
640 MiB for 4 Variants. Halving `size` quarters it (`impostorAtlas: { size: 1024 }`: about 35 MiB per
|
|
523
|
+
Variant); fewer `frames` keep the memory and give each direction more pixels. `forest.dispose()` frees them.
|
|
524
|
+
|
|
525
|
+
[`examples/large-forest`](examples/large-forest/main.ts) draws 10,000 trees under an orbiting camera and
|
|
526
|
+
rebuilds the Forest with Detail Levels on or off, measuring both runs side by side. One example run
|
|
527
|
+
(not a guarantee; measure on your own hardware):
|
|
528
|
+
|
|
529
|
+
| 10,000 trees, 4 Variants | Detail Levels off | Detail Levels on (`lod: true`) |
|
|
530
|
+
| --- | --- | --- |
|
|
531
|
+
| frame time, average / p95 | 2,988 / 6,207 ms | 264 / 441 ms |
|
|
532
|
+
| draw calls | 10 | 22 |
|
|
533
|
+
| triangles drawn | 12,520,003 | 450,869 |
|
|
534
|
+
| trees Full / Light / Impostor | 10,000 / 0 / 0 | 40 / 1,639 / 8,630 |
|
|
535
|
+
|
|
536
|
+
*Measured with `?orbit=30` (camera pinned), 120 frames at 640 × 480, in headless Chromium (Playwright 1.65)
|
|
537
|
+
whose WebGPU runs on SwiftShader, a CPU rasterizer, on an AMD Ryzen 9 7900 that was also running other jobs.
|
|
538
|
+
That is why a frame takes seconds; on a GPU the frames are far faster and the ratio differs. The extra draw
|
|
539
|
+
calls are the indirect draws of every Variant and level, issued even when a level is empty.*
|
|
540
|
+
|
|
425
541
|
## Material Features
|
|
426
542
|
|
|
427
543
|

|
|
@@ -513,6 +629,185 @@ Material Features are a different thing from [Tree Effects](#tree-effects): thos
|
|
|
513
629
|
(the "leaf glow" effect is a screen-space bloom, not Leaf Translucency). See them side by side per Style in
|
|
514
630
|
[`examples/material-features`](examples/material-features/main.ts).
|
|
515
631
|
|
|
632
|
+
## Tree Shader Hook
|
|
633
|
+
|
|
634
|
+
A Tree Shader Hook is the one supported way to change how a tree's surface is shaded (snow, rain, drought
|
|
635
|
+
colour, a painterly foliage look) without touching its materials. You hand the library a
|
|
636
|
+
[TSL](https://threejs.org/docs/#api/en/nodes/TSL) function per tree part (`bark`, `leaves` or `fruit`),
|
|
637
|
+
and it applies it inside that part's node materials, which it keeps building and rewiring itself for
|
|
638
|
+
Growth, Season and Wind. Don't patch `tree.leaves.material` yourself; set a hook instead.
|
|
639
|
+
|
|
640
|
+
The hook gets TSL nodes for the fragment it shades and returns a colour (lit as before), or a colour and a
|
|
641
|
+
roughness:
|
|
642
|
+
|
|
643
|
+
| Input | What it is |
|
|
644
|
+
| --- | --- |
|
|
645
|
+
| `color` | The base colour (linear rgb): after Season, Ground Tint, textures and the Seed's tint, before lighting |
|
|
646
|
+
| `roughness` | The part's roughness before the hook |
|
|
647
|
+
| `normal` | The world-space normal the fragment is lit with, after Wind and Growth (and Crown Normals, the bark normal map) |
|
|
648
|
+
| `position`, `treePosition` | The fragment's world position, and the tree's own (the foot of its trunk) |
|
|
649
|
+
| `season`, `growth` | The tree's Season and Growth (0..1) |
|
|
650
|
+
| `part`, `shading` | The tree part, and the Style's shading (`'flat'`, `'toon'` or `'standard'`) |
|
|
651
|
+
|
|
652
|
+
```ts
|
|
653
|
+
import { createTree, type TreeShaderHook } from '@casmo/tree.js';
|
|
654
|
+
import stylized from '@casmo/tree.js/styles/stylized';
|
|
655
|
+
import { mix, smoothstep, uniform, vec3 } from 'three/tsl';
|
|
656
|
+
|
|
657
|
+
const frost = uniform(0.5); // animate the hook with uniforms: no rebuild
|
|
658
|
+
const frosty: TreeShaderHook = ({ color, normal, roughness }) => ({
|
|
659
|
+
color: mix(color, vec3(0.9, 0.95, 1), smoothstep(0.3, 0.8, normal.y).mul(frost)),
|
|
660
|
+
roughness: roughness.mul(0.8),
|
|
661
|
+
});
|
|
662
|
+
|
|
663
|
+
const tree = createTree(stylized.broadleaf, { seed: 3, shaderHooks: { leaves: frosty } });
|
|
664
|
+
tree.shaderHooks = { leaves: frosty, bark: frosty }; // set or change at runtime
|
|
665
|
+
tree.shaderHooks = {}; // remove: the tree is drawn exactly as before
|
|
666
|
+
```
|
|
667
|
+
|
|
668
|
+
`tree.shaderHooks` holds the hooks per part of a `Tree`; a part whose hooks didn't change is left alone. A
|
|
669
|
+
hook is called once when it is set, to build the node graph, not per frame. Setting, changing or removing it
|
|
670
|
+
rebuilds the node graph of that part's material once (a shader recompile) and never the geometry. With no
|
|
671
|
+
hook nothing changes: same geometry, attributes and materials as before. It works on WebGPU and on the
|
|
672
|
+
WebGL2 fallback.
|
|
673
|
+
|
|
674
|
+
### On Forests, Detail Levels and Impostors
|
|
675
|
+
|
|
676
|
+
A `Forest` takes hooks the same way, for every tree in it, near and far:
|
|
677
|
+
|
|
678
|
+
```ts
|
|
679
|
+
import { createForest } from '@casmo/tree.js';
|
|
680
|
+
import stylized from '@casmo/tree.js/styles/stylized';
|
|
681
|
+
import { mix, vec3 } from 'three/tsl';
|
|
682
|
+
|
|
683
|
+
const forest = createForest(stylized.broadleaf, [{ position: [0, 0, 0] }, { position: [6, 0, 2] }], {
|
|
684
|
+
lod: true,
|
|
685
|
+
shaderHooks: { leaves: ({ color }) => mix(color, vec3(0.9, 0.6, 0.2), 0.5) },
|
|
686
|
+
});
|
|
687
|
+
forest.shaderHooks = {}; // set, change or remove at runtime, as on a Tree
|
|
688
|
+
```
|
|
689
|
+
|
|
690
|
+
The hook runs at every [Detail Level](#detail-levels): Full and Light trees share the Variant's materials,
|
|
691
|
+
and Impostors apply it while they are drawn, to their baked colour, normals and Season data, with
|
|
692
|
+
`part` set per texel (bark or leaves; Impostors have no Fruit). So far trees follow a hook, and its
|
|
693
|
+
uniforms, live: changing a hook never rebakes an Impostor. `season`, `growth` and `treePosition` are each
|
|
694
|
+
tree's own.
|
|
695
|
+
|
|
696
|
+
### Scene-wide default and stacking
|
|
697
|
+
|
|
698
|
+
`setSceneShaderHooks` sets hooks every Tree and Forest runs, now and when created later, the way
|
|
699
|
+
`sceneWind` is shared:
|
|
700
|
+
|
|
701
|
+
```ts
|
|
702
|
+
import { createTree, setSceneShaderHooks, stackShaderHooks, type TreeShaderHook } from '@casmo/tree.js';
|
|
703
|
+
import stylized from '@casmo/tree.js/styles/stylized';
|
|
704
|
+
import { vec3 } from 'three/tsl';
|
|
705
|
+
|
|
706
|
+
const dusk: TreeShaderHook = ({ color }) => color.mul(vec3(1, 0.85, 0.7));
|
|
707
|
+
const pale: TreeShaderHook = ({ color }) => color.mul(1.2);
|
|
708
|
+
setSceneShaderHooks({ bark: dusk, leaves: dusk });
|
|
709
|
+
|
|
710
|
+
const tree = createTree(stylized.broadleaf, {
|
|
711
|
+
shaderHooks: {
|
|
712
|
+
leaves: pale, // stacks: dusk, then pale
|
|
713
|
+
bark: null, // overrides: no hook on this tree's bark, not even the scene-wide one
|
|
714
|
+
},
|
|
715
|
+
});
|
|
716
|
+
tree.shaderHooks = stackShaderHooks({ leaves: pale }, { leaves: dusk }); // several sets of hooks, joined per part
|
|
717
|
+
setSceneShaderHooks({}); // remove the scene-wide default
|
|
718
|
+
```
|
|
719
|
+
|
|
720
|
+
Per part, a Tree's or Forest's hooks work like this:
|
|
721
|
+
|
|
722
|
+
- **left out** (or `undefined`): only the scene-wide default's hooks run;
|
|
723
|
+
- **a hook or a list of hooks**: they stack after the scene-wide default's;
|
|
724
|
+
- **`null`**: no hook at all on that part, the scene-wide default is overridden.
|
|
725
|
+
|
|
726
|
+
Stacked hooks run in a fixed order: first the ready-made hooks the library ships (such as Snow Cover and
|
|
727
|
+
Wetness), then the app's own; within each group the scene-wide default's before the Tree's or Forest's,
|
|
728
|
+
each list in the order given. Each hook gets the colour and roughness the one before it returned. A hook
|
|
729
|
+
that is listed twice runs once.
|
|
730
|
+
|
|
731
|
+
### The normal after Wind
|
|
732
|
+
|
|
733
|
+
`normal` is the normal after Wind on every Style. three only moves a flat-shaded (low-poly) facet with the
|
|
734
|
+
swayed vertices; on smooth shading the library turns the lit normal by how the Wind turned the surface
|
|
735
|
+
(the facet of the unswayed positions to the swayed one, from screen-space derivatives). That costs one
|
|
736
|
+
varying and a few instructions, and only in a hook that reads `normal`. On an Impostor the baked normal is
|
|
737
|
+
turned with the card's sway the same way.
|
|
738
|
+
|
|
739
|
+
### Snow Cover
|
|
740
|
+
|
|
741
|
+
Snow Cover is a ready-made Tree Shader Hook that whitens the surfaces of trees that face up, by a
|
|
742
|
+
scene-wide snow amount from 0 (none) to 1 (full cover). The amount is shared the way `sceneWind` is:
|
|
743
|
+
`sceneSnow`, or a `Snow` of your own. It lives in its own entry point, `@casmo/tree.js/weather`, which
|
|
744
|
+
nothing else in the library imports, so a game without weather never loads it:
|
|
745
|
+
|
|
746
|
+
```ts
|
|
747
|
+
import { setSceneShaderHooks } from '@casmo/tree.js';
|
|
748
|
+
import { sceneSnow, snowCoverHooks } from '@casmo/tree.js/weather';
|
|
749
|
+
|
|
750
|
+
const snow = snowCoverHooks();
|
|
751
|
+
setSceneShaderHooks(snow); // every Tree and Forest, near and far (Impostors too); or `tree.shaderHooks = snow`
|
|
752
|
+
sceneSnow.amount = 0.8; // driven by your weather: a uniform, no rebuild
|
|
753
|
+
|
|
754
|
+
// Settings are live too (uniform writes):
|
|
755
|
+
snow.set({
|
|
756
|
+
color: '#f4f8ff', // sRGB, like any three.js colour
|
|
757
|
+
slope: 60, // the steepest surface (degrees from level, 0..90) that still holds snow
|
|
758
|
+
softness: 25, // degrees below `slope` over which the snow thins out to none (0: a hard edge)
|
|
759
|
+
strength: { bark: 1, leaves: 1, fruit: 0.5 }, // how much snow each part takes
|
|
760
|
+
});
|
|
761
|
+
```
|
|
762
|
+
|
|
763
|
+
It draws to suit the Style: hard flat caps on low-poly, toon bands on stylized, soft lit snow with a slight
|
|
764
|
+
sparkle on realistic. Snow is read from the `normal` after Wind, so it sways with the branches, lies on bare
|
|
765
|
+
winter branches when the leaves are gone, and undersides stay bare. It stacks like any hooks and always runs
|
|
766
|
+
before your own. At amount 0, or without the hooks set, trees look exactly as before.
|
|
767
|
+
`snowCoverHooks({ snow })` follows another `Snow` than `sceneSnow`. For snow of your own, start from
|
|
768
|
+
`snowCoverShading`, the body of the ready-made hook, which only uses the hook's inputs and the settings you
|
|
769
|
+
give it.
|
|
770
|
+
|
|
771
|
+
### Wetness
|
|
772
|
+
|
|
773
|
+
Wetness is a ready-made Tree Shader Hook for rain: trees get darker and get a sheen (a lower roughness),
|
|
774
|
+
most on surfaces that face up, by a scene-wide wetness amount from 0 (dry) to 1 (soaked). The amount is
|
|
775
|
+
shared the way `sceneWind` is: `sceneWetness`, or a `Wetness` of your own. It lives in its own entry
|
|
776
|
+
point, `@casmo/tree.js/weather`, so a game without weather never loads it:
|
|
777
|
+
|
|
778
|
+
```ts
|
|
779
|
+
import { createTree, setSceneShaderHooks, stackShaderHooks, type TreeShaderHook } from '@casmo/tree.js';
|
|
780
|
+
import stylized from '@casmo/tree.js/styles/stylized';
|
|
781
|
+
import { sceneWetness, wetnessHooks } from '@casmo/tree.js/weather';
|
|
782
|
+
|
|
783
|
+
const wet = wetnessHooks({ darkening: 0.5, sheen: 0.7 });
|
|
784
|
+
setSceneShaderHooks(wet); // every Tree and Forest, near and far (Impostors too)
|
|
785
|
+
sceneWetness.amount = 0.8; // driven by your weather: a uniform, no rebuild
|
|
786
|
+
|
|
787
|
+
// Settings are live too (uniform writes):
|
|
788
|
+
wet.set({
|
|
789
|
+
color: '#d8e0ea', // the tint wet surfaces take on
|
|
790
|
+
slope: 140, // the steepest surface (degrees from level, 0..180: facing down) that still gets wet
|
|
791
|
+
softness: 60, // degrees below `slope` over which it dries out to none (0: a hard edge)
|
|
792
|
+
strength: { bark: 1, leaves: 0.8, fruit: 0.5 }, // how much each part takes
|
|
793
|
+
darkening: 0.4, // how much darker a soaked surface gets
|
|
794
|
+
sheen: 0.6, // how much its roughness drops
|
|
795
|
+
});
|
|
796
|
+
|
|
797
|
+
// Stacks with your own hooks: the ready-made ones always run first.
|
|
798
|
+
const mine: TreeShaderHook = ({ color }) => color.mul(1.1);
|
|
799
|
+
const tree = createTree(stylized.broadleaf, { shaderHooks: stackShaderHooks({ leaves: mine }, wet) });
|
|
800
|
+
```
|
|
801
|
+
|
|
802
|
+
`slope` and `softness` mean the same as Snow Cover's: the angle of a surface from level (its normal from
|
|
803
|
+
straight up), fully wet up to `slope - softness` and dry from `slope` on. Unlike snow, rain also wets
|
|
804
|
+
sides and undersides, so Wetness's `slope` goes up to 180 (Snow Cover's to 90).
|
|
805
|
+
|
|
806
|
+
It draws to suit the Style: smooth on realistic, whole facets on low-poly, and toon bands with a light
|
|
807
|
+
glint band on top on stylized (toon lighting has no highlights for the sheen to show in). At amount 0, or
|
|
808
|
+
without the hooks set, trees look exactly as before. `wetnessHooks({ wetness })` follows another `Wetness`
|
|
809
|
+
than `sceneWetness`. For a look of your own, write your own hook instead, using this one as a model.
|
|
810
|
+
|
|
516
811
|
## Tree Effects
|
|
517
812
|
|
|
518
813
|

|
|
@@ -588,7 +883,9 @@ renderer.domElement.addEventListener('click', async (event) => {
|
|
|
588
883
|
```
|
|
589
884
|
|
|
590
885
|
- **Encoding:** `r32uint`, 0 = not a tree. A Forest Variant reserves a block of IDs the size of its
|
|
591
|
-
capacity, and its trees write block start +
|
|
886
|
+
capacity, and its trees write block start + slot, at every Detail Level (Impostors included). The
|
|
887
|
+
tree mask, outline, Inner Lines and Highlight work on far trees too; raycasting and `forest.treeAt`
|
|
888
|
+
keep hitting the full meshes.
|
|
592
889
|
- **No MSAA:** an integer target cannot be multisampled, so turning on the Tree ID turns MSAA off on
|
|
593
890
|
that scene pass: `treeIdTexture` sets `samples: 0`, also with an `antialias: true` renderer. This
|
|
594
891
|
applies wherever the ID channel is on: `treeIdTexture`, `treeEffectsPass(..., { treeId: true })`,
|
|
@@ -736,11 +1033,199 @@ renderer.domElement.addEventListener('pointermove', async (event) => {
|
|
|
736
1033
|
pipeline: `treeHighlight(input, highlighted, options)`, with the `treeId` input of
|
|
737
1034
|
`treeEffectsPass(scene, camera, null, { treeId: true })`, or `applyTreeEffects(input, settings, highlighted)`.
|
|
738
1035
|
|
|
1036
|
+
### Custom Tree Effects
|
|
1037
|
+
|
|
1038
|
+
Add a Tree Effect of your own to `TreeEffects`, such as a brush look on the foliage only. It is built
|
|
1039
|
+
the way the built-in ones are: from the colour so far and the tree mask, returning a colour node and an
|
|
1040
|
+
`update()` that changes its uniforms live. The tree mask's `r` is 1 on any tree pixel, `g` on leaf
|
|
1041
|
+
pixels only and `b` on the selected trees'.
|
|
1042
|
+
|
|
1043
|
+
```ts
|
|
1044
|
+
import { mix, uniform, vec4 } from 'three/tsl';
|
|
1045
|
+
import { createTreeEffects, type CustomTreeEffect } from '@casmo/tree.js/effects';
|
|
1046
|
+
|
|
1047
|
+
const foliage: CustomTreeEffect<{ strength: number }> = {
|
|
1048
|
+
before: 'outline', // where it runs among the built-in effects (default: last, under the Highlight; 'end': over it)
|
|
1049
|
+
// channels: { treeId: true, normal: true }, // only if it reads them: the scene pass adds them
|
|
1050
|
+
build(input, options) {
|
|
1051
|
+
const strength = uniform(options.strength);
|
|
1052
|
+
const look = input.color.rgb; // your look here (this is the bare pass-through)
|
|
1053
|
+
const node = vec4(mix(input.color.rgb, look, input.mask.g.mul(strength)), input.color.a);
|
|
1054
|
+
return { node, update: (next) => (strength.value = next.strength) };
|
|
1055
|
+
},
|
|
1056
|
+
};
|
|
1057
|
+
|
|
1058
|
+
const effects = createTreeEffects(renderer, scene, camera, { effects: 'stylized' });
|
|
1059
|
+
effects.addEffect(foliage, { strength: 1 });
|
|
1060
|
+
effects.updateEffect(foliage, { strength: 0.5 }); // live: no new graph, no recompile
|
|
1061
|
+
effects.removeEffect(foliage);
|
|
1062
|
+
```
|
|
1063
|
+
|
|
1064
|
+
- `before` names a built-in effect (`'grade'`, `'glow'`, `'innerLines'`, `'outline'` or `'highlight'`);
|
|
1065
|
+
the custom effect runs right before it, whether that one is on or not. `'end'` runs it after every
|
|
1066
|
+
built-in Tree Effect, the Highlight too (so it also changes the Highlight's tint and ring). Custom
|
|
1067
|
+
effects at the same place run in the order they were added. The default, `'highlight'`, runs it after
|
|
1068
|
+
every other built-in effect and under the Highlight.
|
|
1069
|
+
- The input has the colour so far (`color`), the tree mask (`mask`), `depth` and `camera`, plus the
|
|
1070
|
+
optional channels it declares in `channels` (`treeId`, `normal` with `normalEncoding`), which the scene
|
|
1071
|
+
pass then adds (a new scene pass, as for the built-in effects). Undeclared channels are never in its
|
|
1072
|
+
input, even when a built-in effect has them on.
|
|
1073
|
+
- Custom effects stay through `effects.set()`, which rebuilds them with their latest options when it
|
|
1074
|
+
builds a new graph. `effects.customEffects` lists them. Adding or removing one builds a new graph.
|
|
1075
|
+
- With no custom effect nothing changes: no channel, no pass. A custom effect itself adds no pass; it
|
|
1076
|
+
is part of the pipeline's output node.
|
|
1077
|
+
- The [Scene Pipeline](#scene-pipeline) takes the same custom effects, with the same `addEffect`,
|
|
1078
|
+
`updateEffect`, `removeEffect` and `customEffects`: see [Custom Tree Effects in the Scene
|
|
1079
|
+
Pipeline](#custom-tree-effects-in-the-scene-pipeline).
|
|
1080
|
+
- In your own pipeline, call `effect.build(input, options)` on the output of `applyTreeEffects` (or any
|
|
1081
|
+
colour) yourself. See [`examples/custom-effect`](examples/custom-effect/main.ts) for the bare setup of a
|
|
1082
|
+
foliage-only effect.
|
|
1083
|
+
|
|
1084
|
+
## Scene Pipeline
|
|
1085
|
+
|
|
1086
|
+

|
|
1087
|
+
|
|
1088
|
+
*Without (left) and with (right) `createScenePipeline(renderer, scene, camera, { style: 'stylized' })`.*
|
|
1089
|
+
|
|
1090
|
+
Tree Effects only change tree pixels. `@casmo/tree.js/scene` adds the whole-scene part around them,
|
|
1091
|
+
the **Scene Effects**: tone mapping, anti-aliasing, ground-contact ambient occlusion (GTAO), bloom, fog
|
|
1092
|
+
and god rays, plus TRAA and motion blur that see Wind. The **Scene Pipeline** renders a Style's
|
|
1093
|
+
suggested Tree Effects and Scene Effects in one `RenderPipeline`. It is opt-in: nothing changes until
|
|
1094
|
+
you create one. It never changes your renderer (tone mapping and the output colour space are applied
|
|
1095
|
+
inside the pipeline; shadows and lights are yours). Its only scene change is fog (`scene.fogNode`),
|
|
1096
|
+
and it gives your own value back.
|
|
1097
|
+
|
|
1098
|
+
```ts
|
|
1099
|
+
import * as THREE from 'three/webgpu';
|
|
1100
|
+
import { createScenePipeline } from '@casmo/tree.js/scene';
|
|
1101
|
+
|
|
1102
|
+
const sun = new THREE.DirectionalLight('#fff4e0', 3.5); // your own light; for god rays it casts shadows
|
|
1103
|
+
sun.castShadow = true;
|
|
1104
|
+
scene.add(sun);
|
|
1105
|
+
const pipeline = createScenePipeline(renderer, scene, camera, { style: 'stylized', sun });
|
|
1106
|
+
renderer.setAnimationLoop(() => pipeline.render()); // instead of renderer.render(scene, camera)
|
|
1107
|
+
pipeline.set({ style: 'realistic' }); // same parts on: only uniforms change, no recompile
|
|
1108
|
+
pipeline.dispose(); // also restores your scene.fogNode
|
|
1109
|
+
```
|
|
1110
|
+
|
|
1111
|
+
`ScenePipeline` replaces `TreeEffects` (use one or the other): the same options (`selection`, `treeId`,
|
|
1112
|
+
`highlighted`) and the same `set`, `pick`, `highlighted`, `scenePass`, `settings`, `render` and `dispose`,
|
|
1113
|
+
plus `pipeline` (the `RenderPipeline`).
|
|
1114
|
+
With no `style` and no overrides it adds nothing and renders exactly like `renderer.render()`.
|
|
1115
|
+
|
|
1116
|
+
The suggestion per Style (`SUGGESTED_SCENE_EFFECTS`, plain data). Fog is in metres, tuned for a small
|
|
1117
|
+
forest (trees 10-30 m away); scale it up for large worlds:
|
|
1118
|
+
|
|
1119
|
+
| Style | Tone mapping | AA | AO | Bloom | Fog | God rays |
|
|
1120
|
+
| --- | --- | --- | --- | --- | --- | --- |
|
|
1121
|
+
| `low-poly` | Neutral | SMAA | light | - | distance | - |
|
|
1122
|
+
| `stylized` | AgX | SMAA | yes | soft | distance + low mist | - |
|
|
1123
|
+
| `realistic` | AgX | SMAA | yes | subtle | distance + mist + far haze | yes (needs `sun`) |
|
|
1124
|
+
|
|
1125
|
+
SMAA is in every suggestion because the [Tree ID](#tree-id) channel turns MSAA off. TRAA and motion
|
|
1126
|
+
blur are never suggested. Override a whole group with `treeEffects` or `sceneEffects` (a Style name,
|
|
1127
|
+
settings or `null`; no deep merge, so spread the suggestion to change a part):
|
|
1128
|
+
|
|
1129
|
+
```ts
|
|
1130
|
+
import type { DirectionalLight } from 'three/webgpu';
|
|
1131
|
+
import { createScenePipeline, SUGGESTED_SCENE_EFFECTS } from '@casmo/tree.js/scene';
|
|
1132
|
+
|
|
1133
|
+
const sun = scene.getObjectByName('sun') as DirectionalLight;
|
|
1134
|
+
createScenePipeline(renderer, scene, camera, {
|
|
1135
|
+
treeEffects: 'low-poly', // or null: no Tree Effects
|
|
1136
|
+
sceneEffects: { ...SUGGESTED_SCENE_EFFECTS.realistic, antialias: 'traa', fog: { near: 60, far: 600 } },
|
|
1137
|
+
sun, // a DirectionalLight or PointLight that already casts shadows
|
|
1138
|
+
});
|
|
1139
|
+
```
|
|
1140
|
+
|
|
1141
|
+
- **God rays** need a `sun` that already casts shadows (with `renderer.shadowMap.enabled` and casting
|
|
1142
|
+
objects). Without one they are skipped with one console warning; the pipeline never turns shadows on.
|
|
1143
|
+
In the open they read as a faint warm haze, under a dense canopy as light shafts.
|
|
1144
|
+
- **Fog** takes its colour from `scene.background` when that is a plain `Color`, so far trees fade into
|
|
1145
|
+
the sky. `fog: { near, far, color?, mist?: { height, strength, near?, far?, farLayer? } }`.
|
|
1146
|
+
- **TRAA** (`antialias: 'traa'`) and **motion blur** (`motionBlur: { strength?, samples? }`) turn on a
|
|
1147
|
+
Wind-aware velocity channel in the scene pass: swaying leaves don't ghost under TRAA, and blur with
|
|
1148
|
+
the sway. Without them tree materials are unchanged. Pass `velocity: true` to keep the channel on for
|
|
1149
|
+
your own temporal effects (`pipeline.scenePass.velocity`).
|
|
1150
|
+
- The order is fixed: scene pass (fog in the materials, AO in the ambient light) -> Tree Effects -> god
|
|
1151
|
+
rays -> motion blur -> bloom -> TRAA -> tone mapping and output colour space -> SMAA / FXAA.
|
|
1152
|
+
|
|
1153
|
+
### Custom Tree Effects in the Scene Pipeline
|
|
1154
|
+
|
|
1155
|
+
A [custom Tree Effect](#custom-tree-effects) goes into the Scene Pipeline the same way as into
|
|
1156
|
+
`TreeEffects`. It runs among the Tree Effects, at the place its `before` names (`'end'`: after the
|
|
1157
|
+
Highlight), so on tree pixels and before every Scene Effect (god rays, bloom, tone mapping and anti-aliasing see its result):
|
|
1158
|
+
|
|
1159
|
+
```ts
|
|
1160
|
+
import { vec4 } from 'three/tsl';
|
|
1161
|
+
import type { CustomTreeEffect } from '@casmo/tree.js/effects';
|
|
1162
|
+
import { createScenePipeline } from '@casmo/tree.js/scene';
|
|
1163
|
+
|
|
1164
|
+
// The bare foliage-only setup of Custom Tree Effects above (put your look in place of `input.color.rgb`).
|
|
1165
|
+
const foliage: CustomTreeEffect<{ strength: number }> = {
|
|
1166
|
+
before: 'outline',
|
|
1167
|
+
build: (input) => ({ node: vec4(input.color.rgb, input.color.a), update: () => {} }),
|
|
1168
|
+
};
|
|
1169
|
+
|
|
1170
|
+
const pipeline = createScenePipeline(renderer, scene, camera, { style: 'stylized' });
|
|
1171
|
+
pipeline.addEffect(foliage, { strength: 1 });
|
|
1172
|
+
pipeline.updateEffect(foliage, { strength: 0.5 }); // live: no new graph, no recompile
|
|
1173
|
+
pipeline.set({ style: 'realistic' }); // the custom effect stays, rebuilt with its latest options
|
|
1174
|
+
pipeline.removeEffect(foliage);
|
|
1175
|
+
```
|
|
1176
|
+
|
|
1177
|
+
- The channels it declares (`treeId`, `normal`) are added to the scene pass by the same rule as for the
|
|
1178
|
+
built-in effects, and go again when it is removed and nothing else needs them.
|
|
1179
|
+
- With no custom effect the pipeline is unchanged. A custom effect alone (no Style, no overrides) makes
|
|
1180
|
+
the pipeline render through its `RenderPipeline` instead of `renderer.render()`.
|
|
1181
|
+
|
|
1182
|
+
### Scene Effects in your own pipeline
|
|
1183
|
+
|
|
1184
|
+
Every Scene Effect is also a stand-alone builder (every number and colour a uniform, every option with a
|
|
1185
|
+
default), for apps that already have a `RenderPipeline`. Pick by what you need:
|
|
1186
|
+
|
|
1187
|
+
| Builder | Returns | Use it when |
|
|
1188
|
+
| --- | --- | --- |
|
|
1189
|
+
| `sceneToneMapping(color, { mapping, exposure })` | display colours | you want AgX / Neutral without setting `renderer.toneMapping`; set `pipeline.outputColorTransform = false` |
|
|
1190
|
+
| `sceneAntialias(color, 'smaa' \| 'fxaa')` | display colours | edges alias (MSAA is off with the Tree ID, or you render without it); give it display colours (after `sceneToneMapping`, or `renderOutput(color)`); SMAA is sharper, FXAA cheaper |
|
|
1191
|
+
| `sceneAntialias(color, 'traa', { depth, velocity, camera })` | linear colours | you want the smoothest still image and alpha-cut leaves; before tone mapping, velocity from `windVelocityMRT()`; sets `samples = 0` (no MSAA) on the scene pass of `depth` |
|
|
1192
|
+
| `sceneAO(scene, camera, options)` | `{ prePass, node, context }` | trees and rocks float on the ground; set `scenePass.contextNode = context` (only ambient light darkens; the scene is drawn twice) |
|
|
1193
|
+
| `sceneFog(options, scene.background)` | a fog node | depth and mist; set `scene.fogNode` yourself (no pipeline needed) |
|
|
1194
|
+
| `sceneGodrays(color, depth, camera, sun, options)` | linear colours | light shafts; needs the shadow-casting `sun` and the scene pass's depth |
|
|
1195
|
+
| `sceneMotionBlur(color, velocity, options)` | linear colours | fast camera or strong Wind; velocity from `windVelocityMRT()` |
|
|
1196
|
+
| `sceneBloom(color, options)` | linear colours | bright skies or emissive parts should glow; before tone mapping |
|
|
1197
|
+
| `applySceneEffects(input, settings)` | the whole stack as one node | you want a Style's look in your own pipeline (like `applyTreeEffects`) |
|
|
1198
|
+
|
|
1199
|
+
```ts
|
|
1200
|
+
import * as THREE from 'three/webgpu';
|
|
1201
|
+
import { mrt, output, pass } from 'three/tsl';
|
|
1202
|
+
import { applyTreeEffects, SUGGESTED_TREE_EFFECTS, treeMaskMRT, TREE_MASK } from '@casmo/tree.js/effects';
|
|
1203
|
+
import { sceneAntialias, sceneBloom, sceneMotionBlur, sceneToneMapping, windVelocityMRT, WIND_VELOCITY } from '@casmo/tree.js/scene';
|
|
1204
|
+
|
|
1205
|
+
const scenePass = pass(scene, camera);
|
|
1206
|
+
scenePass.setMRT(mrt({ output }).merge(treeMaskMRT()).merge(windVelocityMRT())); // Wind-aware velocity
|
|
1207
|
+
const color = scenePass.getTextureNode();
|
|
1208
|
+
const trees = applyTreeEffects({ color, mask: scenePass.getTextureNode(TREE_MASK) }, SUGGESTED_TREE_EFFECTS.realistic); // grade + leaf glow: no extra channels
|
|
1209
|
+
const blurred = sceneMotionBlur(trees, scenePass.getTextureNode(WIND_VELOCITY));
|
|
1210
|
+
const display = sceneToneMapping(sceneBloom(blurred, { strength: 0.1 }), { mapping: 'agx' });
|
|
1211
|
+
const pipeline = new THREE.RenderPipeline(renderer);
|
|
1212
|
+
pipeline.outputNode = sceneAntialias(display, 'smaa');
|
|
1213
|
+
pipeline.outputColorTransform = false; // tone mapping already output display colours
|
|
1214
|
+
```
|
|
1215
|
+
|
|
1216
|
+
`applySceneEffects({ color, depth, camera, sun, velocity }, settings)` builds the same colour stack from
|
|
1217
|
+
settings (fog and AO are not colour steps: use `sceneFog` and `sceneAO` for them). The velocity channel
|
|
1218
|
+
(ADR 0011) is three's `velocity` (NDC per frame) plus the Wind sway since the previous frame:
|
|
1219
|
+
`windVelocityMRT()` adds it to a scene pass under the name `WIND_VELOCITY`, and `windVelocity` is the
|
|
1220
|
+
node for your own MRT. TRAA changes your scene pass: `sceneAntialias(color, 'traa', input)` sets its
|
|
1221
|
+
`options.samples = 0`, because TRAA copies the depth each frame and a multisampled depth cannot be copied
|
|
1222
|
+
(TRAA anti-aliases instead). The Scene Pipeline restores the old value when TRAA goes off.
|
|
1223
|
+
|
|
739
1224
|
## React Three Fiber
|
|
740
1225
|
|
|
741
1226
|

|
|
742
1227
|
|
|
743
|
-
`@casmo/tree.js/react` has `<Tree>`, `<Forest>`, `<Wind>` and `useTreeStyle
|
|
1228
|
+
`@casmo/tree.js/react` has `<Tree>`, `<Forest>`, `<Wind>` and `useTreeStyle` (and, opt-in, the [hooks, weather, Wind Bursts and custom Tree Effects](#tree-shader-hooks-weather-wind-bursts-and-custom-tree-effects-in-react)). Trees use TSL node
|
|
744
1229
|
materials, so give `<Canvas>` a `WebGPURenderer` (it falls back to WebGL2 by itself). R3F v9 takes an
|
|
745
1230
|
async `gl` factory, which must `await renderer.init()` before it returns:
|
|
746
1231
|
|
|
@@ -799,8 +1284,106 @@ createRoot(document.getElementById('root')!).render(<App />);
|
|
|
799
1284
|
- A new `seed`, `definition` (compared by value) or `style`/`form` regenerates the tree. Trees are disposed of on unmount.
|
|
800
1285
|
- `style` also takes a Style name (`<Tree style="low-poly" />`), which suspends like `useTreeStyle`. The `ref` is the tree.js `Tree` (or `Forest`) object.
|
|
801
1286
|
- `<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.
|
|
1287
|
+
- `<Forest lod>` takes `createForest`'s `lod`. Switching it on or off (or a new `impostorAtlas`/`lightDefinition`) rebuilds the forest; new distances, `fade` or `camera` only write `forest.lod`.
|
|
802
1288
|
- Use `shadows="percentage"` (plain `shadows` asks for a shadow type WebGPURenderer no longer has).
|
|
803
1289
|
|
|
1290
|
+
`<ScenePipeline>` renders the canvas through a [Scene Pipeline](#scene-pipeline) (same options as
|
|
1291
|
+
`createScenePipeline`). It takes over rendering (`useFrame` priority 1), follows the camera, calls `set()`
|
|
1292
|
+
when `style`/`treeEffects`/`sceneEffects` change and disposes of the pipeline on unmount. `sun` takes a
|
|
1293
|
+
light or a ref. The `ref` and `useScenePipeline()` (for children) give the `ScenePipeline` (`null` until
|
|
1294
|
+
built). It lazily loads `@casmo/tree.js/scene` (so apps without it don't bundle it) and suspends on
|
|
1295
|
+
its first render until that has loaded: put it inside a `<Suspense>` boundary (like `<Tree style>`), and
|
|
1296
|
+
call `preloadScenePipeline()` early (e.g. at module load) to start the download before it renders.
|
|
1297
|
+
|
|
1298
|
+
```tsx
|
|
1299
|
+
import { useRef } from 'react';
|
|
1300
|
+
import type { DirectionalLight } from 'three/webgpu';
|
|
1301
|
+
import { ScenePipeline, useScenePipeline } from '@casmo/tree.js/react';
|
|
1302
|
+
|
|
1303
|
+
function PickOnClick() {
|
|
1304
|
+
const pipeline = useScenePipeline(); // needs `treeId` for pick()
|
|
1305
|
+
return <mesh onClick={(e) => void pipeline?.pick(e.nativeEvent.offsetX, e.nativeEvent.offsetY)} />;
|
|
1306
|
+
}
|
|
1307
|
+
|
|
1308
|
+
function Look() {
|
|
1309
|
+
const sun = useRef<DirectionalLight>(null);
|
|
1310
|
+
return (
|
|
1311
|
+
<>
|
|
1312
|
+
<directionalLight ref={sun} position={[5, 8, 3]} castShadow />
|
|
1313
|
+
<ScenePipeline style="realistic" sun={sun} treeId>
|
|
1314
|
+
<PickOnClick />
|
|
1315
|
+
</ScenePipeline>
|
|
1316
|
+
</>
|
|
1317
|
+
);
|
|
1318
|
+
}
|
|
1319
|
+
```
|
|
1320
|
+
|
|
1321
|
+
### Tree Shader Hooks, weather, Wind Bursts and custom Tree Effects in React
|
|
1322
|
+
|
|
1323
|
+
All of these are opt-in: a React app that uses none of them renders exactly as before.
|
|
1324
|
+
|
|
1325
|
+
```tsx
|
|
1326
|
+
import { useState } from 'react';
|
|
1327
|
+
import { mix, vec3, vec4 } from 'three/tsl';
|
|
1328
|
+
import {
|
|
1329
|
+
SceneShaderHooks,
|
|
1330
|
+
ScenePipeline,
|
|
1331
|
+
SnowCover,
|
|
1332
|
+
Tree,
|
|
1333
|
+
TreeEffect,
|
|
1334
|
+
Wetness,
|
|
1335
|
+
useWindBurst,
|
|
1336
|
+
type CustomTreeEffect,
|
|
1337
|
+
type TreeShaderHooks,
|
|
1338
|
+
} from '@casmo/tree.js/react';
|
|
1339
|
+
|
|
1340
|
+
// Module scope (or useMemo): a new function is a new hook, and a new hook rebuilds the node graph.
|
|
1341
|
+
const autumn: TreeShaderHooks = { leaves: ({ color }) => mix(color, vec3(0.9, 0.5, 0.1), 0.5) };
|
|
1342
|
+
const dusk: TreeShaderHooks = { bark: ({ color }) => color.mul(vec3(1, 0.85, 0.7)) };
|
|
1343
|
+
const foliage: CustomTreeEffect<{ strength: number }> = {
|
|
1344
|
+
before: 'outline',
|
|
1345
|
+
build: (input) => ({ node: vec4(input.color.rgb, input.color.a), update: () => {} }), // your look here
|
|
1346
|
+
};
|
|
1347
|
+
|
|
1348
|
+
function Park({ snow, rain }: { snow: number; rain: number }) {
|
|
1349
|
+
const burst = useWindBurst(); // on the scene-wide Wind, or useWindBurst(otherWind)
|
|
1350
|
+
const [fall, setFall] = useState(false);
|
|
1351
|
+
return (
|
|
1352
|
+
<>
|
|
1353
|
+
<SceneShaderHooks hooks={dusk} />
|
|
1354
|
+
<SnowCover amount={snow} slope={60} />
|
|
1355
|
+
<Wetness amount={rain} sheen={0.7} />
|
|
1356
|
+
<Tree style="stylized" seed={1} shaderHooks={fall ? autumn : undefined} onClick={() => setFall(!fall)} />
|
|
1357
|
+
<mesh rotation-x={-Math.PI / 2} onClick={(e) => burst({ x: e.point.x, z: e.point.z, strength: 1, radius: 6 })}>
|
|
1358
|
+
<planeGeometry args={[40, 40]} />
|
|
1359
|
+
</mesh>
|
|
1360
|
+
<ScenePipeline style="stylized">
|
|
1361
|
+
<TreeEffect effect={foliage} options={{ strength: 0.5 }} />
|
|
1362
|
+
</ScenePipeline>
|
|
1363
|
+
</>
|
|
1364
|
+
);
|
|
1365
|
+
}
|
|
1366
|
+
```
|
|
1367
|
+
|
|
1368
|
+
- `<Tree shaderHooks>` and `<Forest shaderHooks>` set the [Tree Shader Hooks](#tree-shader-hook) of that tree
|
|
1369
|
+
or every tree of the forest (`tree.shaderHooks`, `forest.shaderHooks`); unset is none. Only the parts
|
|
1370
|
+
whose hooks change rebuild their node graph; the tree is never regenerated.
|
|
1371
|
+
- `<SceneShaderHooks hooks>` sets scene-wide default hooks while mounted (`setSceneShaderHooks`). Several
|
|
1372
|
+
stack in the order they mounted, after the hooks the scene already had, which the last one to unmount
|
|
1373
|
+
puts back. Don't call `setSceneShaderHooks` yourself while they are mounted.
|
|
1374
|
+
- `<SnowCover>` and `<Wetness>` put the ready-made [Snow Cover](#snow-cover) and [Wetness](#wetness)
|
|
1375
|
+
hooks on every tree while mounted (scene-wide, before the app's own hooks). `amount` is written to
|
|
1376
|
+
`sceneSnow` / `sceneWetness` (or the `snow` / `wetness` prop) and put back on unmount; the settings
|
|
1377
|
+
(`color`, `slope`, `softness`, `strength`, and Wetness's `darkening`, `sheen`) are live, an unset one is
|
|
1378
|
+
its default. Their `ref` gives the hooks (`SnowCoverHooks`, `WetnessHooks`). They load
|
|
1379
|
+
`@casmo/tree.js/weather` with a dynamic import on first use, so apps without weather never bundle it:
|
|
1380
|
+
they suspend like `<ScenePipeline>` (call `preloadWeather()` to start the download early).
|
|
1381
|
+
- `useWindBurst(wind?)` returns a stable function that starts a [Wind Burst](#wind-burst).
|
|
1382
|
+
- `<TreeEffect effect options>` inside a `<ScenePipeline>` adds a [custom Tree
|
|
1383
|
+
Effect](#custom-tree-effects-in-the-scene-pipeline) while mounted. New `options` (compared by value) go
|
|
1384
|
+
through `updateEffect` (no new graph); it stays through Style changes, moves into a rebuilt pipeline, and
|
|
1385
|
+
is removed on unmount. Several at the same place run in the order they mounted.
|
|
1386
|
+
|
|
804
1387
|
## Without a bundler: import map (CDN)
|
|
805
1388
|
|
|
806
1389
|

|
|
@@ -935,10 +1518,13 @@ a live preview (Seed, Growth, Season, Wind, Tree Effects), sculpt single branche
|
|
|
935
1518
|
| --- | --- | --- | --- |
|
|
936
1519
|
| [`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"> |
|
|
937
1520
|
| [`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"> |
|
|
938
|
-
| [`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"> |
|
|
1521
|
+
| [`examples/react`](examples/react/main.tsx) | `/examples/react/` | React Three Fiber: `<Tree>`, `<Wind>`, `useTreeStyle`; `?scene=forest` for `<Forest>`, `?scene=pipeline` for `<ScenePipeline>` | <img src="docs/images/example-react.png" alt="examples/react" width="160"> |
|
|
939
1522
|
| [`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"> |
|
|
1523
|
+
| [`examples/large-forest`](examples/large-forest/main.ts) | `/examples/large-forest/` | 10,000 trees with Detail Levels on and off: frame times, draw calls, triangles and trees per Detail Level; `?trees=&lod=0&frames=&orbit=` | <img src="docs/images/example-large-forest.png" alt="examples/large-forest" width="160"> |
|
|
940
1524
|
| [`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"> |
|
|
1525
|
+
| [`examples/custom-effect`](examples/custom-effect/main.ts) | `/examples/custom-effect/` | a foliage-only [custom Tree Effect](#custom-tree-effects) (the bare setup); `?effect=on\|pass-through\|off&effects=style&view=mask&backend=webgl` | <img src="docs/images/example-custom-effect.png" alt="examples/custom-effect" width="160"> |
|
|
941
1526
|
| [`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"> |
|
|
1527
|
+
| [`examples/scene-pipeline`](examples/scene-pipeline/main.ts) | `/examples/scene-pipeline/` | the opt-in [Scene Pipeline](#scene-pipeline) (`createScenePipeline`) per Style: `?style=low-poly\|stylized\|realistic`; one Scene Effect alone through its builder: `?scene=tone-mapping\|smaa\|fxaa\|traa\|gtao\|bloom\|fog\|godrays\|motion-blur` (`&sun=back` for light shafts); `?scene=none` (adds nothing) or `plain` (`renderer.render`); the Wind-aware velocity channel: `?scene=velocity&wind=1.5&windTime=3`; motion blur: `?scene=motion-blur&wind=3&windTime=3&cameraStep=0.5`; `?backend=webgl` | <img src="docs/images/example-scene-pipeline.png" alt="examples/scene-pipeline" width="160"> |
|
|
942
1528
|
| [`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"> |
|
|
943
1529
|
|
|
944
1530
|
```sh
|