You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: doc/source/instancing.md
+38-10
Original file line number
Diff line number
Diff line change
@@ -32,28 +32,56 @@ Items created this way come with a default setup, so you should be able to see s
32
32
33
33
### Block LOD
34
34
35
-
The range at which items spawn is based on the LOD system of the voxel terrain itself. This is configured in the `lod_index` property of [VoxelInstanceLibraryItem](api/VoxelInstanceLibraryItem.md). For example, choosing `0` will make the item spawn at the closest range, and fade quickly in the distance. Higher indexes will spawn on a larger range, so will also start to appear earlier as the player gets closer. Instances spawn in the same "blocks" as the ground.
35
+
The range at which items spawn is based on the LOD system of the voxel terrain itself, either on high-resolution chunks, or low-resolution ones. This is configured in the `lod_index` property of [VoxelInstanceLibraryItem](api/VoxelInstanceLibraryItem.md). For example, choosing `0` will make the item spawn on chunks of LOD0 at closest range, and fade quickly in the distance. Higher indexes will spawn on bigger chunks covering a larger range.
36
36
37
37
38
38
39
39
Usually landscapes may be composed of multiple layers so that the closer you get, the more details come in. Bigger items use high lod indexes to be seen from far away, while smaller items may use lower indexes.
40
40
41
41
42
42
43
-
There is a balance to consider when choosing the appropriate `lod_index`: currently, larger indexes are *much more imprecise*, because they work on top of a lower-resolution mesh. When getting closer, it's possible that such instances are seen floating above ground, or sinking into it. This mostly happens in areas with sharp changes such as ridges, crevices or caves:
43
+
!!! note
44
+
When making grass or other items, it may be a good idea to fade meshes based on distance from the camera using a custom shader, so they won't disappear abruptly. Using a ground texture of similar colors also helps to make it blend.
44
45
45
-
46
+
### Placement precision
46
47
47
-
To combat this, you can adjust the `offset_along_normal` parameter in the `generator` associated to the item. This depends on the asset, so designing them such that they can have part of their bottom sunk into the ground can give some margin of error.
48
+
There is a balance to consider when choosing the appropriate `lod_index`: currently, larger indexes are *much more imprecise*, because they work on top of a lower-resolution mesh. This allows to generate instances much quicker at larger distances, without having to calculate full-precision LODs.
48
49
49
-
Sometimes it might not be enough, so this problem still has to be worked out in the future. Possible approaches include:
50
+
The downside is, as getting closer and terrain calculates higher-resolution LODs, it's possible that such instances are seen floating above ground, or sinking into it. This mostly happens in areas with sharp changes such as ridges, crevices or caves:
50
51
51
-
- Querying the world generator to approximate the surface without using the mesh (not suitable if the ground was edited)
52
-
- Gradually snap the instances somehow as higher-resolution data becomes available
53
-
- Load edited voxels for the entire world at once so they can be queried even from far distance (takes more memory)
52
+
54
53
55
-
!!! note
56
-
When making grass or other items, it may be a good idea to fade meshes based on distance from the camera using a custom shader, so they won't disappear abruptly. Using a ground texture of similar colors also helps to make it blend.
54
+
#### Offset along normal
55
+
56
+
A first option to adjust placement, is to adjust the `offset_along_normal` parameter in the `generator` associated to the item. This depends on the asset, so designing them such that they can have part of their bottom sunk into the ground can give some margin of error.
57
+
58
+
#### Affining from generator SDF
59
+
60
+
Another option is to enable `affine_from_generator_sdf_enabled`, at the cost of slower instance generation. This is preferably used when `lod_index` > 0, as LOD0 already has maximum precision.
61
+
62
+
Without affining:
63
+
64
+
65
+
66
+
With affining:
67
+
68
+
69
+
70
+
This option queries the `VoxelGenerator` at floating point positions to approximate where the surface is, assuming the mesh-based position was a good starting point.
71
+
The generator can only return SDF values, which roughly tells how "close" each 3D point is from the surface. With at least 2 nearby samples or more, we can interpolate to snap positions closer to that surface.
72
+
73
+
Limitations:
74
+
75
+
- Requires a generator that supports series generation (i.e query arbitrary floating point positions to get voxel data from, instead of voxel chunks). At time of writing, only `VoxelGeneratorGraph` supports this.
76
+
- Doesn't work if the terrain is modified: if a player comes back to the edited area and instances have to re-generate on top, estimations from the generator will not account for edited areas. To workaround this, instances could be set as `persistent`, so editing terrain marks them as modified and saves their positions onwards instead of re-generating.
77
+
- Tends to "bury" or "float" instances far away when their low-resolution mesh is active, since they get moved closer to the high-resolution one. This should however not be as noticeable as before, when that was happening at close range.
78
+
79
+
80
+
#### Research
81
+
82
+
More options may be researched in the future in case the current workarounds aren't enough:
83
+
84
+
- Gradually snap instances as higher-resolution meshes become available. Requires fast mesh raycast, if possible doable from threads (that unfortunately excludes Godot physics).
0 commit comments