Merge branch 'master' into partial_side_culling

# Conflicts:
#	meshers/blocky/voxel_blocky_model.h
#	meshers/blocky/voxel_mesher_blocky.cpp
#	util/math/triangle.h

.github/workflows/mono.yml

@@ -194,6 +194,13 @@ jobs:
           repository: godotengine/godot
           ref: ${{ env.GODOT_BASE_BRANCH }}
 
+      # The version of ThorVG in 4.3-stable hits an error in latest MSVC (see godot#95861).
+      # We should no longer need this in 4.3.1 and later.
+      - name: Patch ThorVG
+        run: |
+          curl -LO https://github.com/godotengine/godot/commit/4abc358952a69427617b0683fd76427a14d6faa8.patch
+          git apply 4abc358952a69427617b0683fd76427a14d6faa8.patch
+
       # Clone our module under the correct directory
       - uses: actions/checkout@v4
         with:

.github/workflows/windows.yml

@@ -63,6 +63,13 @@ jobs:
         with:
           path: modules/voxel
 
+      # The version of ThorVG in 4.3-stable hits an error in latest MSVC (see godot#95861).
+      # We should no longer need this in 4.3.1 and later.
+      - name: Patch ThorVG
+        run: |
+          curl -LO https://github.com/godotengine/godot/commit/4abc358952a69427617b0683fd76427a14d6faa8.patch
+          git apply 4abc358952a69427617b0683fd76427a14d6faa8.patch
+
       # Upload cache on completion and check it out now
       # Editing this is pretty dangerous for Windows since it can break and needs to be properly tested with a fresh cache.
       - name: Load .scons_cache directory

README.md

@@ -103,6 +103,7 @@ SummitCollie
 nulshift
 ddel-rio (Daniel del Río Román)
 Cyberphinx
+Mia (Tigxette)
 ```
 
 

SCsub

@@ -37,9 +37,9 @@ if INCLUDE_TESTS:
 # SQLite
 env_sqlite = env_voxel.Clone()
 
-# Turn off some warnings produced when compiling with warnings=extra
-if env["warnings"] == "extra":
-	env_sqlite.disable_warnings()
+# Turn off warnings, we get some with Clang and with `warnings=extra`
+env_sqlite.disable_warnings()
+
 # if not env_sqlite.msvc:
 #     env_sqlite.Append(CXXFLAGS=["-Wno-discarded-qualifiers"])
 

constants/voxel_string_names.cpp

@@ -118,6 +118,12 @@ VoxelStringNames::VoxelStringNames() {
 	async_search_completed = StringName("async_search_completed");
 
 	file_selected = StringName("file_selected");
+
+	jitter = StringName("jitter");
+	triangle_area_threshold = StringName("triangle_area_threshold");
+	density = StringName("density");
+	noise_dimension = StringName("noise_dimension");
+	noise_on_scale = StringName("noise_on_scale");
 }
 
 } // namespace zylann::voxel

constants/voxel_string_names.h

@@ -106,6 +106,12 @@ class VoxelStringNames {
 	StringName async_search_completed;
 
 	StringName file_selected;
+
+	StringName jitter;
+	StringName triangle_area_threshold;
+	StringName density;
+	StringName noise_dimension;
+	StringName noise_on_scale;
 };
 
 } // namespace zylann::voxel

doc/classes/VoxelAStarGrid3D.xml

@@ -6,57 +6,73 @@
 	<description>
 		This can be used to find paths between two voxel positions on blocky terrain.
 		It is tuned for agents 2 voxels tall and 1 voxel wide, which must stand on solid voxels and can jump 1 voxel high.
-		Search radius may also be limited (50 voxels and above starts to be relatively expensive).
+		No navmesh is required, it uses voxels directly with no baking. However, search radius is limited by an area (50 voxels and above starts to be relatively expensive).
+		At the moment, this pathfinder only considers voxels with ID 0 to be air, and the rest is considered solid.
+		Note: "positions" in this class are expected to be in voxels. If your terrain is offset or if voxels are smaller or bigger than world units, you may have to convert coordinates.
 	</description>
 	<tutorials>
 	</tutorials>
 	<methods>
 		<method name="debug_get_visited_positions" qualifiers="const">
 			<return type="Vector3i[]" />
 			<description>
+				Gets the list of voxel positions that were visited by the last pathfinding request (relates to how A* works under the hood). This is for debugging.
 			</description>
 		</method>
 		<method name="find_path">
 			<return type="Vector3i[]" />
 			<param index="0" name="from_position" type="Vector3i" />
 			<param index="1" name="to_position" type="Vector3i" />
 			<description>
+				Calculates a path starting from a voxel position to a target voxel position. 
+				Those positions should be air voxels just above ground with enough room for agents to fit in. 
+				The returned path will be a series of contiguous voxel positions to walk through in order to get to the destination. 
+				If no path is found, or if either start or destination position is outside of the search area, an empty array will be returned.
+				You may also use [method set_region] to specify the search area.
 			</description>
 		</method>
 		<method name="find_path_async">
 			<return type="void" />
 			<param index="0" name="from_position" type="Vector3i" />
 			<param index="1" name="to_position" type="Vector3i" />
 			<description>
+				Same as [method find_path], but performs the calculation on a separate thread. The result will be emitted with the [signal async_search_completed] signal.
+				Only one asynchronous search can be active at a given time. Use [method is_running_async] to check this.
 			</description>
 		</method>
 		<method name="get_region">
 			<return type="AABB" />
 			<description>
+				Gets the maximum region limit that will be considered for pathfinding, in voxels.
 			</description>
 		</method>
 		<method name="is_running_async" qualifiers="const">
 			<return type="bool" />
 			<description>
+				Returns true if a path is currently being calculated asynchronously. See [method find_path_async].
 			</description>
 		</method>
 		<method name="set_region">
 			<return type="void" />
 			<param index="0" name="box" type="AABB" />
 			<description>
+				Sets the maximum region limit that will be considered for pathfinding, in voxels. You should usually set this before calling [method find_path].
+				The larger the region, the more expensive the search can get. Keep in mind voxel volumes scale cubically, so don't use this on large areas (for example 50 voxels is quite big).
 			</description>
 		</method>
 		<method name="set_terrain">
 			<return type="void" />
 			<param index="0" name="terrain" type="VoxelTerrain" />
 			<description>
+				Sets the terrain that will be used to do searches in.
 			</description>
 		</method>
 	</methods>
 	<signals>
 		<signal name="async_search_completed">
 			<param index="0" name="path" type="Vector3i[]" />
 			<description>
+				Emitted when searches triggered with [method find_path_async] are complete.
 			</description>
 		</signal>
 	</signals>

doc/classes/VoxelBuffer.xml

@@ -164,6 +164,7 @@
 		<method name="get_allocator" qualifiers="const">
 			<return type="int" enum="VoxelBuffer.Allocator" />
 			<description>
+				Gets which memory allocator is used by this buffer.
 			</description>
 		</method>
 		<method name="get_block_metadata" qualifiers="const">
@@ -408,12 +409,15 @@
 			How many compression modes there are.
 		</constant>
 		<constant name="ALLOCATOR_DEFAULT" value="0" enum="Allocator">
+			Uses Godot's default memory allocator (at time of writing, it is [code]malloc[/code]). Preferred for occasional buffers with uncommon size, or very large size.
 		</constant>
 		<constant name="ALLOCATOR_POOL" value="1" enum="Allocator">
+			Uses a pool allocator. Can be faster than the default allocator buffers are created very frequently with similar size. This memory will remain allocated after use, under the assumption that other buffers will need it soon after. Does not support very large buffers (greater than 2 megabytes)
 		</constant>
 		<constant name="ALLOCATOR_COUNT" value="2" enum="Allocator">
 		</constant>
 		<constant name="MAX_SIZE" value="65535">
+			Maximum size a buffer can have when serialized. Buffers that contain uniform-compressed voxels can reach it, but in practice, the limit is much lower and depends on available memory.
 		</constant>
 	</constants>
 </class>

doc/classes/VoxelColorPalette.xml

@@ -6,6 +6,7 @@
 	<description>
 		Contains a list of colors that can be accessed quickly by their index. This is useful to store colored voxels with small memory footprint.
 		It can be used with [VoxelMesherCubes].
+		Note: colors are internally stored with 8-bit components, so floats used by [Color] will be rounded to the nearest value.
 	</description>
 	<tutorials>
 	</tutorials>
@@ -26,8 +27,10 @@
 	</methods>
 	<members>
 		<member name="colors" type="PackedColorArray" setter="set_colors" getter="get_colors" default="PackedColorArray(0, 0, 0, 0, 1, 1, 1, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1)">
+			Array of all the colors in the palette. It must have 256 elements. You may use this if you want to get or set all colors at once. Otherwise, prefer using [method get_color] and [method set_color].
 		</member>
 		<member name="data" type="PackedInt32Array" setter="set_data" getter="get_data" default="PackedInt32Array(0, -1, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255)">
+			Array used to store colors as 8-bit binary components in the resource file. It must have 256 elements. To access colors with a script, prefer using [method get_color] and [method set_color].
 		</member>
 	</members>
 	<constants>

doc/classes/VoxelGeneratorFlat.xml

@@ -9,13 +9,13 @@
 	</tutorials>
 	<members>
 		<member name="channel" type="int" setter="set_channel" getter="get_channel" enum="VoxelBuffer.ChannelId" default="1">
-			Channel that will be used to generate the ground.
+			Channel that will be used to generate the ground. Use [member VoxelBuffer.CHANNEL_SDF] for smooth terrain, other channels for blocky.
 		</member>
 		<member name="height" type="float" setter="set_height" getter="get_height" default="0.0">
 			Altitude of the ground.
 		</member>
 		<member name="voxel_type" type="int" setter="set_voxel_type" getter="get_voxel_type" default="1">
-			If [member channel] is set to [constant VoxelBuffer.CHANNEL_TYPE], this value will be used to fill ground voxels.
+			If [member channel] is set to any channel other than [constant VoxelBuffer.CHANNEL_SDF], this value will be used to fill ground voxels, while air voxels will be set to 0.
 		</member>
 	</members>
 </class>

doc/classes/VoxelGeneratorHeightmap.xml

@@ -1,13 +1,15 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="VoxelGeneratorHeightmap" inherits="VoxelGenerator" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../doc/class.xsd">
 	<brief_description>
+		Base class for several basic height-based generators.
 	</brief_description>
 	<description>
 	</description>
 	<tutorials>
 	</tutorials>
 	<members>
 		<member name="channel" type="int" setter="set_channel" getter="get_channel" enum="VoxelBuffer.ChannelId" default="1">
+			Channel where voxels will be generated. If set to [constant VoxelBuffer.CHANNEL_SDF], voxels will be a signed distance field usable by smooth meshers. Otherwise, the value 1 will be set below ground, and the value 0 will be set above ground (blocky).
 		</member>
 		<member name="height_range" type="float" setter="set_height_range" getter="get_height_range" default="30.0">
 			Maximum distance between the lowest and highest surface points that can generate. 
@@ -17,7 +19,7 @@
 			Minimum height where the surface will generate.
 		</member>
 		<member name="iso_scale" type="float" setter="set_iso_scale" getter="get_iso_scale" default="1.0">
-			Scale applied to the signed distance field. This is useful when smooth voxels are used, to reduce blockyness over large distances.
+			Scale applied to the signed distance field when using a smooth terrain configuration.
 		</member>
 	</members>
 </class>

doc/classes/VoxelGeneratorImage.xml

@@ -4,6 +4,8 @@
 		Voxel generator producing a heightmap-based shape using an image.
 	</brief_description>
 	<description>
+		Uses the red channel of an image to generate a heightmap, such that the top left corner is centered on the world origin. The image will repeat if terrain generates beyond its size.
+		Note: values in the image are read using `get_pixel` and are assumed to be between 0 and 1 (normalized). These values will be transformed by [member VoxelGeneratorHeightmap.height_start] and [member VoxelGeneratorHeightmap.height_range].
 	</description>
 	<tutorials>
 	</tutorials>
@@ -12,6 +14,7 @@
 		</member>
 		<member name="height_range" type="float" setter="set_height_range" getter="get_height_range" overrides="VoxelGeneratorHeightmap" default="200.0" />
 		<member name="image" type="Image" setter="set_image" getter="get_image">
+			Sets the image that will be used as a heightmap. Only the red channel will be used. It is preferable to use an image using the `RF` or `RH` format, which contain higher resolution heights. Common images only have 8-bit depth and will appear blocky.
 		</member>
 	</members>
 </class>

doc/classes/VoxelGeneratorNoise2D.xml

@@ -11,6 +11,7 @@
 		<member name="curve" type="Curve" setter="set_curve" getter="get_curve">
 			When assigned, this curve will alter the distribution of height variations, allowing to give some kind of "profile" to the generated shapes.
 			By default, a linear curve from 0 to 1 is used.
+			It is assumed that the curve's domain goes from 0 to 1.
 		</member>
 		<member name="height_range" type="float" setter="set_height_range" getter="get_height_range" overrides="VoxelGeneratorHeightmap" default="200.0" />
 		<member name="noise" type="Noise" setter="set_noise" getter="get_noise">