godotengine/godot
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #63638 from PrecisionRender/improve-shape-cast-docs

Browse Source
This commit is contained in:
Rémi Verschelde 2022-07-29 22:29:10 +02:00 committed by GitHub
commit b7639c2995
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 21 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
doc/classes/ShapeCast2D.xml
View File

@ -6,7 +6,7 @@
<description> <description>
Shape casting allows to detect collision objects by sweeping the [member shape] along the cast direction determined by [member target_position] (useful for things like beam weapons). Shape casting allows to detect collision objects by sweeping the [member shape] along the cast direction determined by [member target_position] (useful for things like beam weapons).
Immediate collision overlaps can be done with the [member target_position] set to [code]Vector2(0, 0)[/code] and by calling [method force_shapecast_update] within the same [b]physics_frame[/b]. This also helps to overcome some limitations of [Area2D] when used as a continuous detection area, often requiring waiting a couple of frames before collision information is available to [Area2D] nodes, and when using the signals creates unnecessary complexity. Immediate collision overlaps can be done with the [member target_position] set to [code]Vector2(0, 0)[/code] and by calling [method force_shapecast_update] within the same [b]physics_frame[/b]. This also helps to overcome some limitations of [Area2D] when used as a continuous detection area, often requiring waiting a couple of frames before collision information is available to [Area2D] nodes, and when using the signals creates unnecessary complexity.
The node can detect multiple collision objects, but usually the first detected collision The node can detect multiple collision objects, but it's usually used to detect the first collision.
[b]Note:[/b] shape casting is more computationally expensive compared to ray casting. [b]Note:[/b] shape casting is more computationally expensive compared to ray casting.
</description> </description>
<tutorials> <tutorials>
@ -42,27 +42,27 @@
<method name="get_closest_collision_safe_fraction" qualifiers="const"> <method name="get_closest_collision_safe_fraction" qualifiers="const">
<return type="float" /> <return type="float" />
<description> <description>
The fraction of the motion (between 0 and 1) of how far the shape can move without triggering a collision. The motion is determined by [member target_position]. The fraction from the [ShapeCast2D]'s origin to its [member target_position] (between 0 and 1) of how far the shape can move without triggering a collision.
</description> </description>
</method> </method>
<method name="get_closest_collision_unsafe_fraction" qualifiers="const"> <method name="get_closest_collision_unsafe_fraction" qualifiers="const">
<return type="float" /> <return type="float" />
<description> <description>
The fraction of the motion (between 0 and 1) when the shape triggers a collision. The motion is determined by [member target_position]. The fraction from the [ShapeCast2D]'s origin to its [member target_position] (between 0 and 1) of how far the shape must move to trigger a collision.
</description> </description>
</method> </method>
<method name="get_collider" qualifiers="const"> <method name="get_collider" qualifiers="const">
<return type="Object" /> <return type="Object" />
<argument index="0" name="index" type="int" /> <argument index="0" name="index" type="int" />
<description> <description>
Returns the [Object] of one of the multiple collisions at [code]index[/code], or [code]null[/code] if no object is intersecting the shape (i.e. [method is_colliding] returns [code]false[/code]). Returns the collided [Object] of one of the multiple collisions at [code]index[/code], or [code]null[/code] if no object is intersecting the shape (i.e. [method is_colliding] returns [code]false[/code]).
</description> </description>
</method> </method>
<method name="get_collider_shape" qualifiers="const"> <method name="get_collider_shape" qualifiers="const">
<return type="int" /> <return type="int" />
<argument index="0" name="index" type="int" /> <argument index="0" name="index" type="int" />
<description> <description>
Returns the shape ID of one of the multiple collisions at [code]index[/code] that the shape intersects, or [code]0[/code] if no object is intersecting the shape (i.e. [method is_colliding] returns [code]false[/code]). Returns the shape ID of the colliding shape of one of the multiple collisions at [code]index[/code], or [code]0[/code] if no object is intersecting the shape (i.e. [method is_colliding] returns [code]false[/code]).
</description> </description>
</method> </method>
<method name="get_collision_count" qualifiers="const"> <method name="get_collision_count" qualifiers="const">
@ -82,14 +82,14 @@
<return type="Vector2" /> <return type="Vector2" />
<argument index="0" name="index" type="int" /> <argument index="0" name="index" type="int" />
<description> <description>
Returns the normal containing one of the multiple collisions at [code]index[/code] of the intersecting object. Returns the normal of one of the multiple collisions at [code]index[/code] of the intersecting object.
</description> </description>
</method> </method>
<method name="get_collision_point" qualifiers="const"> <method name="get_collision_point" qualifiers="const">
<return type="Vector2" /> <return type="Vector2" />
<argument index="0" name="index" type="int" /> <argument index="0" name="index" type="int" />
<description> <description>
Returns the collision point containing one of the multiple collisions at [code]index[/code] at which the shape intersects the object. Returns the collision point of one of the multiple collisions at [code]index[/code] where the shape intersects the colliding object.
[b]Note:[/b] this point is in the [b]global[/b] coordinate system. [b]Note:[/b] this point is in the [b]global[/b] coordinate system.
</description> </description>
</method> </method>
@ -133,7 +133,7 @@
The shape's collision mask. Only objects in at least one collision layer enabled in the mask will be detected. The shape's collision mask. Only objects in at least one collision layer enabled in the mask will be detected.
</member> </member>
<member name="collision_result" type="Array" setter="" getter="_get_collision_result" default="[]"> <member name="collision_result" type="Array" setter="" getter="_get_collision_result" default="[]">
A complete collision information. The data returned is the same as in the [method PhysicsDirectSpaceState2D.get_rest_info] method. Returns the complete collision information from the collision sweep. The data returned is the same as in the [method PhysicsDirectSpaceState2D.get_rest_info] method.
</member> </member>
<member name="enabled" type="bool" setter="set_enabled" getter="is_enabled" default="true"> <member name="enabled" type="bool" setter="set_enabled" getter="is_enabled" default="true">
If [code]true[/code], collisions will be reported. If [code]true[/code], collisions will be reported.
@ -148,7 +148,7 @@
The number of intersections can be limited with this parameter, to reduce the processing time. The number of intersections can be limited with this parameter, to reduce the processing time.
</member> </member>
<member name="shape" type="Shape2D" setter="set_shape" getter="get_shape"> <member name="shape" type="Shape2D" setter="set_shape" getter="get_shape">
Any [Shape2D] derived shape used for collision queries. The [Shape2D]-derived shape to be used for collision queries.
</member> </member>
<member name="target_position" type="Vector2" setter="set_target_position" getter="get_target_position" default="Vector2(0, 50)"> <member name="target_position" type="Vector2" setter="set_target_position" getter="get_target_position" default="Vector2(0, 50)">
The shape's destination point, relative to this node's [code]position[/code]. The shape's destination point, relative to this node's [code]position[/code].

24
doc/classes/ShapeCast3D.xml
View File

@ -6,7 +6,7 @@
<description> <description>
Shape casting allows to detect collision objects by sweeping the [member shape] along the cast direction determined by [member target_position] (useful for things like beam weapons). Shape casting allows to detect collision objects by sweeping the [member shape] along the cast direction determined by [member target_position] (useful for things like beam weapons).
Immediate collision overlaps can be done with the [member target_position] set to [code]Vector3(0, 0, 0)[/code] and by calling [method force_shapecast_update] within the same [b]physics_frame[/b]. This also helps to overcome some limitations of [Area3D] when used as a continuous detection area, often requiring waiting a couple of frames before collision information is available to [Area3D] nodes, and when using the signals creates unnecessary complexity. Immediate collision overlaps can be done with the [member target_position] set to [code]Vector3(0, 0, 0)[/code] and by calling [method force_shapecast_update] within the same [b]physics_frame[/b]. This also helps to overcome some limitations of [Area3D] when used as a continuous detection area, often requiring waiting a couple of frames before collision information is available to [Area3D] nodes, and when using the signals creates unnecessary complexity.
The node can detect multiple collision objects, but usually the first detected collision. The node can detect multiple collision objects, but it's usually used to detect the first collision.
[b]Note:[/b] Shape casting is more computationally expensive compared to ray casting. [b]Note:[/b] Shape casting is more computationally expensive compared to ray casting.
</description> </description>
<tutorials> <tutorials>
@ -29,7 +29,7 @@
<method name="clear_exceptions"> <method name="clear_exceptions">
<return type="void" /> <return type="void" />
<description> <description>
Removes all collision exceptions for this shape. Removes all collision exceptions for this [ShapeCast3D].
</description> </description>
</method> </method>
<method name="force_shapecast_update"> <method name="force_shapecast_update">
@ -42,27 +42,27 @@
<method name="get_closest_collision_safe_fraction" qualifiers="const"> <method name="get_closest_collision_safe_fraction" qualifiers="const">
<return type="float" /> <return type="float" />
<description> <description>
The fraction of the motion (between 0 and 1) of how far the shape can move without triggering a collision. The motion is determined by [member target_position]. The fraction from the [ShapeCast3D]'s origin to its [member target_position] (between 0 and 1) of how far the shape can move without triggering a collision.
</description> </description>
</method> </method>
<method name="get_closest_collision_unsafe_fraction" qualifiers="const"> <method name="get_closest_collision_unsafe_fraction" qualifiers="const">
<return type="float" /> <return type="float" />
<description> <description>
The fraction of the motion (between 0 and 1) when the shape triggers a collision. The motion is determined by [member target_position]. The fraction from the [ShapeCast3D]'s origin to its [member target_position] (between 0 and 1) of how far the shape must move to trigger a collision.
</description> </description>
</method> </method>
<method name="get_collider" qualifiers="const"> <method name="get_collider" qualifiers="const">
<return type="Object" /> <return type="Object" />
<argument index="0" name="index" type="int" /> <argument index="0" name="index" type="int" />
<description> <description>
Returns the [Object] of one of the multiple collisions at [code]index[/code], or [code]null[/code] if no object is intersecting the shape (i.e. [method is_colliding] returns [code]false[/code]). Returns the collided [Object] of one of the multiple collisions at [code]index[/code], or [code]null[/code] if no object is intersecting the shape (i.e. [method is_colliding] returns [code]false[/code]).
</description> </description>
</method> </method>
<method name="get_collider_shape" qualifiers="const"> <method name="get_collider_shape" qualifiers="const">
<return type="int" /> <return type="int" />
<argument index="0" name="index" type="int" /> <argument index="0" name="index" type="int" />
<description> <description>
Returns the shape ID of one of the multiple collisions at [code]index[/code] that the shape intersects, or [code]0[/code] if no object is intersecting the shape (i.e. [method is_colliding] returns [code]false[/code]). Returns the shape ID of the colliding shape of one of the multiple collisions at [code]index[/code], or [code]0[/code] if no object is intersecting the shape (i.e. [method is_colliding] returns [code]false[/code]).
</description> </description>
</method> </method>
<method name="get_collision_count" qualifiers="const"> <method name="get_collision_count" qualifiers="const">
@ -82,14 +82,14 @@
<return type="Vector3" /> <return type="Vector3" />
<argument index="0" name="index" type="int" /> <argument index="0" name="index" type="int" />
<description> <description>
Returns the normal containing one of the multiple collisions at [code]index[/code] of the intersecting object. Returns the normal of one of the multiple collisions at [code]index[/code] of the intersecting object.
</description> </description>
</method> </method>
<method name="get_collision_point" qualifiers="const"> <method name="get_collision_point" qualifiers="const">
<return type="Vector3" /> <return type="Vector3" />
<argument index="0" name="index" type="int" /> <argument index="0" name="index" type="int" />
<description> <description>
Returns the collision point containing one of the multiple collisions at [code]index[/code] at which the shape intersects the object. Returns the collision point of one of the multiple collisions at [code]index[/code] where the shape intersects the colliding object.
[b]Note:[/b] this point is in the [b]global[/b] coordinate system. [b]Note:[/b] this point is in the [b]global[/b] coordinate system.
</description> </description>
</method> </method>
@ -117,7 +117,7 @@
<return type="void" /> <return type="void" />
<argument index="0" name="resource" type="Resource" /> <argument index="0" name="resource" type="Resource" />
<description> <description>
Used internally to update the debug gizmo in the editor. Any code placed in this function will be called whenever the [member shape] resource is modified. This method is used internally to update the debug gizmo in the editor. Any code placed in this function will be called whenever the [member shape] resource is modified.
</description> </description>
</method> </method>
<method name="set_collision_mask_value"> <method name="set_collision_mask_value">
@ -137,10 +137,10 @@
If [code]true[/code], collision with [PhysicsBody3D]s will be reported. If [code]true[/code], collision with [PhysicsBody3D]s will be reported.
</member> </member>
<member name="collision_mask" type="int" setter="set_collision_mask" getter="get_collision_mask" default="1"> <member name="collision_mask" type="int" setter="set_collision_mask" getter="get_collision_mask" default="1">
The shape's collision mask. Only objects in at least one collision layer enabled in the mask will be detected. The shape's collision mask. Only objects in at least one collision layer enabled in the mask will be detected. See [url=$DOCS_URL/tutorials/physics/physics_introduction.html#collision-layers-and-masks]Collision layers and masks[/url] in the documentation for more information.
</member> </member>
<member name="collision_result" type="Array" setter="" getter="_get_collision_result" default="[]"> <member name="collision_result" type="Array" setter="" getter="_get_collision_result" default="[]">
A complete collision information. The data returned is the same as in the [method PhysicsDirectSpaceState3D.get_rest_info] method. Returns the complete collision information from the collision sweep. The data returned is the same as in the [method PhysicsDirectSpaceState3D.get_rest_info] method.
</member> </member>
<member name="debug_shape_custom_color" type="Color" setter="set_debug_shape_custom_color" getter="get_debug_shape_custom_color" default="Color(0, 0, 0, 1)"> <member name="debug_shape_custom_color" type="Color" setter="set_debug_shape_custom_color" getter="get_debug_shape_custom_color" default="Color(0, 0, 0, 1)">
The custom color to use to draw the shape in the editor and at run-time if [b]Visible Collision Shapes[/b] is enabled in the [b]Debug[/b] menu. This color will be highlighted at run-time if the [ShapeCast3D] is colliding with something. The custom color to use to draw the shape in the editor and at run-time if [b]Visible Collision Shapes[/b] is enabled in the [b]Debug[/b] menu. This color will be highlighted at run-time if the [ShapeCast3D] is colliding with something.
@ -159,7 +159,7 @@
The number of intersections can be limited with this parameter, to reduce the processing time. The number of intersections can be limited with this parameter, to reduce the processing time.
</member> </member>
<member name="shape" type="Shape3D" setter="set_shape" getter="get_shape"> <member name="shape" type="Shape3D" setter="set_shape" getter="get_shape">
Any [Shape3D] derived shape used for collision queries. The [Shape3D]-derived shape to be used for collision queries.
</member> </member>
<member name="target_position" type="Vector3" setter="set_target_position" getter="get_target_position" default="Vector3(0, -1, 0)"> <member name="target_position" type="Vector3" setter="set_target_position" getter="get_target_position" default="Vector3(0, -1, 0)">
The shape's destination point, relative to this node's [code]position[/code]. The shape's destination point, relative to this node's [code]position[/code].