Document GPUParticles3D attractors and collision

10 files changed, 87 insertions, 0 deletions

diff --git a/doc/classes/GPUParticlesAttractor3D.xml b/doc/classes/GPUParticlesAttractor3D.xml
index 5577b47c89..e69255cc31 100644
--- a/doc/classes/GPUParticlesAttractor3D.xml
+++ b/doc/classes/GPUParticlesAttractor3D.xml
@@ -1,19 +1,31 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="GPUParticlesAttractor3D" inherits="VisualInstance3D" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
+		Abstract class for 3D particle attractors affecting [GPUParticles3D] nodes.
 	</brief_description>
 	<description>
+		Particle attractors can be used to attract particles towards the attractor's origin, or to push them away from the attractor's origin.
+		Particle attractors work in real-time and can be moved, rotated and scaled during gameplay. Unlike collision shapes, non-uniform scaling of attractors is also supported.
+		Attractors can be temporarily disabled by hiding them, or by setting their [member strength] to [code]0.0[/code].
+		[b]Note:[/b] Particle attractors only affect [GPUParticles3D], not [CPUParticles3D].
 	</description>
 	<tutorials>
 	</tutorials>
 	<members>
 		<member name="attenuation" type="float" setter="set_attenuation" getter="get_attenuation" default="1.0">
+			The particle attractor's attenuation. Higher values result in more gradual pushing of particles as they come closer to the attractor's origin. Zero or negative values will cause particles to be pushed very fast as soon as the touch the attractor's edges.
 		</member>
 		<member name="cull_mask" type="int" setter="set_cull_mask" getter="get_cull_mask" default="4294967295">
+			The particle rendering layers ([member VisualInstance3D.layers]) that will be affected by the attractor. By default, all particles are affected by an attractor.
+			After configuring particle nodes accordingly, specific layers can be unchecked to prevent certain particles from being affected by attractors. For example, this can be used if you're using an attractor as part of a spell effect but don't want the attractor to affect unrelated weather particles at the same position.
+			Particle attraction can also be disabled on a per-process material basis by setting [member ParticlesMaterial.attractor_interaction_enabled] on the [GPUParticles3D] node.
 		</member>
 		<member name="directionality" type="float" setter="set_directionality" getter="get_directionality" default="0.0">
+			Adjusts how directional the attractor is. At [code]0.0[/code], the attractor is not directional at all: it will attract particles towards its center. At [code]1.0[/code], the attractor is fully directional: particles will always be pushed towards local -Z (or +Z if [member strength] is negative).
+			[b]Note:[/b] If [member directionality] is greater than [code]0.0[/code], the direction in which particles are pushed can be changed by rotating the [GPUParticlesAttractor3D] node.
 		</member>
 		<member name="strength" type="float" setter="set_strength" getter="get_strength" default="1.0">
+			If [member strength] is negative, particles will be pushed in the reverse direction. Particles will be pushed [i]away[/i] from the attractor's  origin if [member directionality] is [code]0.0[/code], or towards local +Z if [member directionality] is greater than [code]0.0[/code].
 		</member>
 	</members>
 </class>
diff --git a/doc/classes/GPUParticlesAttractorBox3D.xml b/doc/classes/GPUParticlesAttractorBox3D.xml
index 3fa8276579..6595428cc2 100644
--- a/doc/classes/GPUParticlesAttractorBox3D.xml
+++ b/doc/classes/GPUParticlesAttractorBox3D.xml
@@ -1,13 +1,17 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="GPUParticlesAttractorBox3D" inherits="GPUParticlesAttractor3D" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
+		Box-shaped 3D particle attractor affecting [GPUParticles3D] nodes.
 	</brief_description>
 	<description>
+		Box-shaped 3D particle attractor affecting [GPUParticles3D] nodes.
+		[b]Note:[/b] Particle attractors only affect [GPUParticles3D], not [CPUParticles3D].
 	</description>
 	<tutorials>
 	</tutorials>
 	<members>
 		<member name="extents" type="Vector3" setter="set_extents" getter="get_extents" default="Vector3(1, 1, 1)">
+			The attractor box's extents in 3D units.
 		</member>
 	</members>
 </class>
diff --git a/doc/classes/GPUParticlesAttractorSphere3D.xml b/doc/classes/GPUParticlesAttractorSphere3D.xml
index 2b68637b38..4077937ef3 100644
--- a/doc/classes/GPUParticlesAttractorSphere3D.xml
+++ b/doc/classes/GPUParticlesAttractorSphere3D.xml
@@ -1,13 +1,18 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="GPUParticlesAttractorSphere3D" inherits="GPUParticlesAttractor3D" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
+		Ellipse-shaped 3D particle attractor affecting [GPUParticles3D] nodes.
 	</brief_description>
 	<description>
+		Ellipse-shaped 3D particle attractor affecting [GPUParticles3D] nodes.
+		[b]Note:[/b] Particle attractors only affect [GPUParticles3D], not [CPUParticles3D].
 	</description>
 	<tutorials>
 	</tutorials>
 	<members>
 		<member name="radius" type="float" setter="set_radius" getter="get_radius" default="1.0">
+			The attractor sphere's radius in 3D units.
+			[b]Note:[/b] Stretched ellipses can be obtained by using non-uniform scaling on the [GPUParticlesAttractorSphere3D] node.
 		</member>
 	</members>
 </class>
diff --git a/doc/classes/GPUParticlesAttractorVectorField3D.xml b/doc/classes/GPUParticlesAttractorVectorField3D.xml
index cbf817f407..aeadfaf4ab 100644
--- a/doc/classes/GPUParticlesAttractorVectorField3D.xml
+++ b/doc/classes/GPUParticlesAttractorVectorField3D.xml
@@ -1,15 +1,22 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="GPUParticlesAttractorVectorField3D" inherits="GPUParticlesAttractor3D" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
+		Box-shaped 3D particle attractor with strength varying within the box, affecting [GPUParticles3D] nodes.
 	</brief_description>
 	<description>
+		Box-shaped 3D particle attractor with strength varying within the box, affecting [GPUParticles3D] nodes.
+		Unlike [GPUParticlesAttractorBox3D], [GPUParticlesAttractorVectorField3D] uses a [member texture] to affect attraction strength within the box. This can be used to create complex attraction scenarios where particles travel in different directions depending on their location. This can be useful for weather effects such as sandstorms.
+		[b]Note:[/b] Particle attractors only affect [GPUParticles3D], not [CPUParticles3D].
 	</description>
 	<tutorials>
 	</tutorials>
 	<members>
 		<member name="extents" type="Vector3" setter="set_extents" getter="get_extents" default="Vector3(1, 1, 1)">
+			The extents of the vector field box in 3D units.
 		</member>
 		<member name="texture" type="Texture3D" setter="set_texture" getter="get_texture">
+			The 3D texture to be used. Values are linearly interpolated between the texture's pixels.
+			[b]Note:[/b] To get better performance, the 3D texture's resolution should reflect the [member extents] of the attractor. Since particle attraction is usually low-frequency data, the texture can be kept at a low resolution such as 64×64×64.
 		</member>
 	</members>
 </class>
diff --git a/doc/classes/GPUParticlesCollision3D.xml b/doc/classes/GPUParticlesCollision3D.xml
index 45bc9b402b..435f9781f0 100644
--- a/doc/classes/GPUParticlesCollision3D.xml
+++ b/doc/classes/GPUParticlesCollision3D.xml
@@ -1,13 +1,23 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="GPUParticlesCollision3D" inherits="VisualInstance3D" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
+		Abstract class for 3D particle collision shapes affecting [GPUParticles3D] nodes.
 	</brief_description>
 	<description>
+		Particle collision shapes can be used to make particles stop or bounce against them.
+		Particle collision shapes in real-time and can be moved, rotated and scaled during gameplay. Unlike attractors, non-uniform scaling of collision shapes is [i]not[/i] supported.
+		Particle collision shapes can be temporarily disabled by hiding them.
+		[b]Note:[/b] [member ParticlesMaterial.collision_enabled] must be [code]true[/code] on the [GPUParticles3D]'s process material for collision to work.
+		[b]Note:[/b] Particle collision only affects [GPUParticles3D], not [CPUParticles3D].
+		[b]Note:[/b] Particles pushed by a collider that is being moved will not be interpolated, which can result in visible stuttering. This can be alleviated by setting [member GPUParticles3D.fixed_fps] to [code]0[/code] or a value that matches or exceeds the target framerate.
 	</description>
 	<tutorials>
 	</tutorials>
 	<members>
 		<member name="cull_mask" type="int" setter="set_cull_mask" getter="get_cull_mask" default="4294967295">
+			The particle rendering layers ([member VisualInstance3D.layers]) that will be affected by the collision shape. By default, all particles that have [member ParticlesMaterial.collision_enabled] set to [code]true[/code] will be affected by a collision shape.
+			After configuring particle nodes accordingly, specific layers can be unchecked to prevent certain particles from being affected by attractors. For example, this can be used if you're using an attractor as part of a spell effect but don't want the attractor to affect unrelated weather particles at the same position.
+			Particle attraction can also be disabled on a per-process material basis by setting [member ParticlesMaterial.attractor_interaction_enabled] on the [GPUParticles3D] node.
 		</member>
 	</members>
 </class>
diff --git a/doc/classes/GPUParticlesCollisionBox3D.xml b/doc/classes/GPUParticlesCollisionBox3D.xml
index 091b4ca730..60d66ca682 100644
--- a/doc/classes/GPUParticlesCollisionBox3D.xml
+++ b/doc/classes/GPUParticlesCollisionBox3D.xml
@@ -1,13 +1,18 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="GPUParticlesCollisionBox3D" inherits="GPUParticlesCollision3D" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
+		Box-shaped 3D particle collision shape affecting [GPUParticles3D] nodes.
 	</brief_description>
 	<description>
+		Box-shaped 3D particle collision shape affecting [GPUParticles3D] nodes.
+		[b]Note:[/b] [member ParticlesMaterial.collision_enabled] must be [code]true[/code] on the [GPUParticles3D]'s process material for collision to work.
+		[b]Note:[/b] Particle collision only affects [GPUParticles3D], not [CPUParticles3D].
 	</description>
 	<tutorials>
 	</tutorials>
 	<members>
 		<member name="extents" type="Vector3" setter="set_extents" getter="get_extents" default="Vector3(1, 1, 1)">
+			The collision box's extents in 3D units.
 		</member>
 	</members>
 </class>
diff --git a/doc/classes/GPUParticlesCollisionHeightField3D.xml b/doc/classes/GPUParticlesCollisionHeightField3D.xml
index a7b59ea684..3fcad43efb 100644
--- a/doc/classes/GPUParticlesCollisionHeightField3D.xml
+++ b/doc/classes/GPUParticlesCollisionHeightField3D.xml
@@ -1,39 +1,59 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="GPUParticlesCollisionHeightField3D" inherits="GPUParticlesCollision3D" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
+		Real-time heightmap-shaped 3D particle attractor affecting [GPUParticles3D] nodes.
 	</brief_description>
 	<description>
+		Real-time heightmap-shaped 3D particle attractor affecting [GPUParticles3D] nodes.
+		Heightmap shapes allow for efficiently representing collisions for convex and concave objects with a single "floor" (such as terrain). This is less flexible than [GPUParticlesCollisionSDF3D], but it doesn't require a baking step.
+		[GPUParticlesCollisionHeightField3D] can also be regenerated in real-time when it is moved, when the camera moves, or even continuously. This makes [GPUParticlesCollisionHeightField3D] a good choice for weather effects such as rain and snow and games with highly dynamic geometry. However, since heightmaps cannot represent overhangs, [GPUParticlesCollisionHeightField3D] is not suited for indoor particle collision.
+		[b]Note:[/b] [member ParticlesMaterial.collision_enabled] must be [code]true[/code] on the [GPUParticles3D]'s process material for collision to work.
+		[b]Note:[/b] Particle collision only affects [GPUParticles3D], not [CPUParticles3D].
 	</description>
 	<tutorials>
 	</tutorials>
 	<members>
 		<member name="extents" type="Vector3" setter="set_extents" getter="get_extents" default="Vector3(1, 1, 1)">
+			The collision heightmap's extents in 3D units. To improve heightmap quality, [member extents] should be set as small as possible while covering the parts of the scene you need.
 		</member>
 		<member name="follow_camera_enabled" type="bool" setter="set_follow_camera_enabled" getter="is_follow_camera_enabled" default="false">
+			If [code]true[/code], the [GPUParticlesCollisionHeightField3D] will follow the current camera in global space. The [GPUParticlesCollisionHeightField3D] does not need to be a child of the [Camera3D] node for this to work.
+			Following the camera has a performance cost, as it will force the heightmap to update whenever the camera moves. Consider lowering [member resolution] to improve performance if [member follow_camera_enabled] is [code]true[/code].
 		</member>
 		<member name="resolution" type="int" setter="set_resolution" getter="get_resolution" enum="GPUParticlesCollisionHeightField3D.Resolution" default="2">
+			Higher resolutions can represent small details more accurately in large scenes, at the cost of lower performance. If [member update_mode] is [constant UPDATE_MODE_ALWAYS], consider using the lowest resolution possible.
 		</member>
 		<member name="update_mode" type="int" setter="set_update_mode" getter="get_update_mode" enum="GPUParticlesCollisionHeightField3D.UpdateMode" default="0">
+			The update policy to use for the generated heightmap.
 		</member>
 	</members>
 	<constants>
 		<constant name="RESOLUTION_256" value="0" enum="Resolution">
+			Generate a 256×256 heightmap. Intended for small-scale scenes, or larger scenes with no distant particles.
 		</constant>
 		<constant name="RESOLUTION_512" value="1" enum="Resolution">
+			Generate a 512×512 heightmap. Intended for medium-scale scenes, or larger scenes with no distant particles.
 		</constant>
 		<constant name="RESOLUTION_1024" value="2" enum="Resolution">
+			Generate a 1024×1024 heightmap. Intended for large scenes with distant particles.
 		</constant>
 		<constant name="RESOLUTION_2048" value="3" enum="Resolution">
+			Generate a 2048×2048 heightmap. Intended for very large scenes with distant particles.
 		</constant>
 		<constant name="RESOLUTION_4096" value="4" enum="Resolution">
+			Generate a 4096×4096 heightmap. Intended for huge scenes with distant particles.
 		</constant>
 		<constant name="RESOLUTION_8192" value="5" enum="Resolution">
+			Generate a 8192×8192 heightmap. Intended for gigantic scenes with distant particles.
 		</constant>
 		<constant name="RESOLUTION_MAX" value="6" enum="Resolution">
+			Represents the size of the [enum Resolution] enum.
 		</constant>
 		<constant name="UPDATE_MODE_WHEN_MOVED" value="0" enum="UpdateMode">
+			Only update the heightmap when the [GPUParticlesCollisionHeightField3D] node is moved, or when the camera moves if [member follow_camera_enabled] is [code]true[/code]. An update can be forced by slightly moving the [GPUParticlesCollisionHeightField3D] in any direction.
 		</constant>
 		<constant name="UPDATE_MODE_ALWAYS" value="1" enum="UpdateMode">
+			Update the heightmap every frame. This has a significant performance cost. This update should only be used when geometry that particles can collide with changes significantly during gameplay.
 		</constant>
 	</constants>
 </class>
diff --git a/doc/classes/GPUParticlesCollisionSDF3D.xml b/doc/classes/GPUParticlesCollisionSDF3D.xml
index 6f59a18eb5..c9af07288e 100644
--- a/doc/classes/GPUParticlesCollisionSDF3D.xml
+++ b/doc/classes/GPUParticlesCollisionSDF3D.xml
@@ -1,35 +1,53 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="GPUParticlesCollisionSDF3D" inherits="GPUParticlesCollision3D" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
+		Baked signed distance field 3D particle attractor affecting [GPUParticles3D] nodes.
 	</brief_description>
 	<description>
+		Baked signed distance field 3D particle attractor affecting [GPUParticles3D] nodes.
+		Signed distance fields (SDF) allow for efficiently representing approximate collision shapes for convex and concave objects of any shape. This is more flexible than [GPUParticlesCollisionHeightField3D], but it requires a baking step.
+		[b]Baking:[/b] The signed distance field texture can be baked by selecting the [GPUParticlesCollisionSDF3D] node in the editor, then clicking [b]Bake SDF[/b] at the top of the 3D viewport. Any [i]visible[/i] [MeshInstance3D]s touching the [member extents] will be taken into account for baking, regardless of their [member GeometryInstance3D.gi_mode].
+		[b]Note:[/b] Baking a [GPUParticlesCollisionSDF3D]'s [member texture] is only possible within the editor, as there is no bake method exposed for use in exported projects. However, it's still possible to load pre-baked [Texture3D]s into its [member texture] property in an exported project.
+		[b]Note:[/b] [member ParticlesMaterial.collision_enabled] must be [code]true[/code] on the [GPUParticles3D]'s process material for collision to work.
+		[b]Note:[/b] Particle collision only affects [GPUParticles3D], not [CPUParticles3D].
 	</description>
 	<tutorials>
 	</tutorials>
 	<members>
 		<member name="extents" type="Vector3" setter="set_extents" getter="get_extents" default="Vector3(1, 1, 1)">
+			The collision SDF's extents in 3D units. To improve SDF quality, the [member extents] should be set as small as possible while covering the parts of the scene you need.
 		</member>
 		<member name="resolution" type="int" setter="set_resolution" getter="get_resolution" enum="GPUParticlesCollisionSDF3D.Resolution" default="2">
+			The bake resolution to use for the signed distance field [member texture]. The texture must be baked again for changes to the [member resolution] property to be effective. Higher resolutions have a greater performance cost and take more time to bake. Higher resolutions also result in larger baked textures, leading to increased VRAM and storage space requirements. To improve performance and reduce bake times, use the lowest resolution possible for the object you're representing the collision of.
 		</member>
 		<member name="texture" type="Texture3D" setter="set_texture" getter="get_texture">
+			The 3D texture representing the signed distance field.
 		</member>
 		<member name="thickness" type="float" setter="set_thickness" getter="get_thickness" default="1.0">
+			The collision shape's thickness. Unlike other particle colliders, [GPUParticlesCollisionSDF3D] is actually hollow on the inside. [member thickness] can be increased to prevent particles from tunneling through the collision shape at high speeds, or when the [GPUParticlesCollisionSDF3D] is moved.
 		</member>
 	</members>
 	<constants>
 		<constant name="RESOLUTION_16" value="0" enum="Resolution">
+			Bake a 16×16×16 signed distance field. This is the fastest option, but also the least precise.
 		</constant>
 		<constant name="RESOLUTION_32" value="1" enum="Resolution">
+			Bake a 32×32×32 signed distance field.
 		</constant>
 		<constant name="RESOLUTION_64" value="2" enum="Resolution">
+			Bake a 64×64×64 signed distance field.
 		</constant>
 		<constant name="RESOLUTION_128" value="3" enum="Resolution">
+			Bake a 128×128×128 signed distance field.
 		</constant>
 		<constant name="RESOLUTION_256" value="4" enum="Resolution">
+			Bake a 256×256×256 signed distance field.
 		</constant>
 		<constant name="RESOLUTION_512" value="5" enum="Resolution">
+			Bake a 512×512×512 signed distance field. This is the slowest option, but also the most precise.
 		</constant>
 		<constant name="RESOLUTION_MAX" value="6" enum="Resolution">
+			Represents the size of the [enum Resolution] enum.
 		</constant>
 	</constants>
 </class>
diff --git a/doc/classes/GPUParticlesCollisionSphere3D.xml b/doc/classes/GPUParticlesCollisionSphere3D.xml
index b78e114d09..6651a732da 100644
--- a/doc/classes/GPUParticlesCollisionSphere3D.xml
+++ b/doc/classes/GPUParticlesCollisionSphere3D.xml
@@ -1,13 +1,18 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="GPUParticlesCollisionSphere3D" inherits="GPUParticlesCollision3D" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
+		Sphere-shaped 3D particle collision shape affecting [GPUParticles3D] nodes.
 	</brief_description>
 	<description>
+		Sphere-shaped 3D particle collision shape affecting [GPUParticles3D] nodes.
+		[b]Note:[/b] [member ParticlesMaterial.collision_enabled] must be [code]true[/code] on the [GPUParticles3D]'s process material for collision to work.
+		[b]Note:[/b] Particle collision only affects [GPUParticles3D], not [CPUParticles3D].
 	</description>
 	<tutorials>
 	</tutorials>
 	<members>
 		<member name="radius" type="float" setter="set_radius" getter="get_radius" default="1.0">
+			The collision sphere's radius in 3D units.
 		</member>
 	</members>
 </class>
diff --git a/doc/classes/VisualInstance3D.xml b/doc/classes/VisualInstance3D.xml
index 78a681d92a..2468042850 100644
--- a/doc/classes/VisualInstance3D.xml
+++ b/doc/classes/VisualInstance3D.xml
@@ -66,6 +66,7 @@
 		<member name="layers" type="int" setter="set_layer_mask" getter="get_layer_mask">
 			The render layer(s) this [VisualInstance3D] is drawn on.
 			This object will only be visible for [Camera3D]s whose cull mask includes the render object this [VisualInstance3D] is set to.
+			For [Light3D]s, this can be used to control which [VisualInstance3D]s are affected by a specific light. For [GPUParticles3D], this can be used to control which particles are effected by a specific attractor. For [Decal]s, this can be used to control which [VisualInstance3D]s are affected by a specific decal.
 		</member>
 	</members>
 </class>