mirror/godot
2
0
Fork 0
mirror of https://github.com/godotengine/godot.git synced 2024-11-21 03:18:37 +08:00
Code Issues Packages Projects Releases Wiki Activity

Document GPUParticles3D attractors and collision

Browse Source
This commit is contained in:
Hugo Locurcio 2022-05-13 04:11:01 +02:00
parent e8520044e7
commit e6b0b577ed
No known key found for this signature in database
GPG Key ID: 39E8F8BE30B0A49C
10 changed files with 87 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
doc/classes/GPUParticlesAttractor3D.xml
View File

@ -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>

4
doc/classes/GPUParticlesAttractorBox3D.xml
View File

@ -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>

5
doc/classes/GPUParticlesAttractorSphere3D.xml
View File

@ -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>

7
doc/classes/GPUParticlesAttractorVectorField3D.xml
View File

@ -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>

10
doc/classes/GPUParticlesCollision3D.xml
View File

@ -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>

5
doc/classes/GPUParticlesCollisionBox3D.xml
View File

@ -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>

20
doc/classes/GPUParticlesCollisionHeightField3D.xml
View File

@ -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>

18
doc/classes/GPUParticlesCollisionSDF3D.xml
View File

@ -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>

5
doc/classes/GPUParticlesCollisionSphere3D.xml
View File

@ -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>

1
doc/classes/VisualInstance3D.xml
View File

@ -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>