Merge pull request #35633 from Xrayez/physics-shape-property

Expose shape property for shape query parameters classes

2 files changed, 34 insertions, 20 deletions

diff --git a/doc/classes/PhysicsShapeQueryParameters2D.xml b/doc/classes/PhysicsShapeQueryParameters2D.xml
index 9a162dabbb..63e13954ab 100644
--- a/doc/classes/PhysicsShapeQueryParameters2D.xml
+++ b/doc/classes/PhysicsShapeQueryParameters2D.xml
@@ -9,15 +9,6 @@
 	<tutorials>
 	</tutorials>
 	<methods>
-		<method name="set_shape">
-			<return type="void">
-			</return>
-			<argument index="0" name="shape" type="Resource">
-			</argument>
-			<description>
-				Sets the [Shape2D] that will be used for collision/intersection queries.
-			</description>
-		</method>
 	</methods>
 	<members>
 		<member name="collide_with_areas" type="bool" setter="set_collide_with_areas" getter="is_collide_with_areas_enabled" default="false">
@@ -38,8 +29,24 @@
 		<member name="motion" type="Vector2" setter="set_motion" getter="get_motion" default="Vector2( 0, 0 )">
 			The motion of the shape being queried for.
 		</member>
+		<member name="shape" type="Resource" setter="set_shape" getter="get_shape">
+			The [Shape2D] that will be used for collision/intersection queries. This stores the actual reference which avoids the shape to be released while being used for queries, so always prefer using this over [member shape_rid].
+		</member>
 		<member name="shape_rid" type="RID" setter="set_shape_rid" getter="get_shape_rid">
-			The queried shape's [RID]. See also [method set_shape].
+			The queried shape's [RID] that will be used for collision/intersection queries. Use this over [member shape] if you want to optimize for performance using the Servers API:
+			[codeblock]
+			var shape_rid = PhysicsServer2D.circle_shape_create()
+			var radius = 64
+			PhysicsServer2D.shape_set_data(shape_rid, radius)
+
+			var params = PhysicsShapeQueryParameters2D.new()
+			params.shape_rid = shape_rid
+
+			# Execute physics queries here...
+
+			# Release the shape when done with physics queries.
+			PhysicsServer2D.free_rid(shape_rid)
+			[/codeblock]
 		</member>
 		<member name="transform" type="Transform2D" setter="set_transform" getter="get_transform" default="Transform2D( 1, 0, 0, 1, 0, 0 )">
 			The queried shape's transform matrix.
diff --git a/doc/classes/PhysicsShapeQueryParameters3D.xml b/doc/classes/PhysicsShapeQueryParameters3D.xml
index 6606cfbc59..f4191d4862 100644
--- a/doc/classes/PhysicsShapeQueryParameters3D.xml
+++ b/doc/classes/PhysicsShapeQueryParameters3D.xml
@@ -9,15 +9,6 @@
 	<tutorials>
 	</tutorials>
 	<methods>
-		<method name="set_shape">
-			<return type="void">
-			</return>
-			<argument index="0" name="shape" type="Resource">
-			</argument>
-			<description>
-				Sets the [Shape3D] that will be used for collision/intersection queries.
-			</description>
-		</method>
 	</methods>
 	<members>
 		<member name="collide_with_areas" type="bool" setter="set_collide_with_areas" getter="is_collide_with_areas_enabled" default="false">
@@ -35,8 +26,24 @@
 		<member name="margin" type="float" setter="set_margin" getter="get_margin" default="0.0">
 			The collision margin for the shape.
 		</member>
+		<member name="shape" type="Resource" setter="set_shape" getter="get_shape">
+			The [Shape3D] that will be used for collision/intersection queries. This stores the actual reference which avoids the shape to be released while being used for queries, so always prefer using this over [member shape_rid].
+		</member>
 		<member name="shape_rid" type="RID" setter="set_shape_rid" getter="get_shape_rid">
-			The queried shape's [RID]. See also [method set_shape].
+			The queried shape's [RID] that will be used for collision/intersection queries. Use this over [member shape] if you want to optimize for performance using the Servers API:
+			[codeblock]
+			var shape_rid = PhysicsServer3D.shape_create(PhysicsServer3D.SHAPE_SPHERE)
+			var radius = 2.0
+			PhysicsServer3D.shape_set_data(shape_rid, radius)
+
+			var params = PhysicsShapeQueryParameters3D.new()
+			params.shape_rid = shape_rid
+
+			# Execute physics queries here...
+
+			# Release the shape when done with physics queries.
+			PhysicsServer3D.free_rid(shape_rid)
+			[/codeblock]
 		</member>
 		<member name="transform" type="Transform" setter="set_transform" getter="get_transform" default="Transform( 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0 )">
 			The queried shape's transform matrix.