From 3ae5687d48c0a933a684c863beadf769312ba1ac Mon Sep 17 00:00:00 2001 From: PouleyKetchoupp Date: Thu, 30 Sep 2021 11:28:57 -0700 Subject: Script interface improvements for test body motion -Physics servers test body motion use a class to hold parameters instead of multiple arguments to make it more readable and flexible since there are many options -Improved documentation for test body motion and kinematic collision -Removed read-only properties for body motion results (not handled in scripts, so they should be get_ methods only instead) --- doc/classes/KinematicCollision2D.xml | 103 +++++++++++++++--------- doc/classes/KinematicCollision3D.xml | 75 +++++++----------- doc/classes/PhysicsServer2D.xml | 12 +-- doc/classes/PhysicsServer3D.xml | 13 +--- doc/classes/PhysicsTestMotionParameters2D.xml | 29 +++++++ doc/classes/PhysicsTestMotionParameters3D.xml | 32 ++++++++ doc/classes/PhysicsTestMotionResult2D.xml | 108 +++++++++++++++++++------- doc/classes/PhysicsTestMotionResult3D.xml | 75 +++++++++++------- doc/classes/TileMap.xml | 2 +- 9 files changed, 294 insertions(+), 155 deletions(-) create mode 100644 doc/classes/PhysicsTestMotionParameters2D.xml create mode 100644 doc/classes/PhysicsTestMotionParameters3D.xml (limited to 'doc') diff --git a/doc/classes/KinematicCollision2D.xml b/doc/classes/KinematicCollision2D.xml index 29fc4700fd..23b01a0fc9 100644 --- a/doc/classes/KinematicCollision2D.xml +++ b/doc/classes/KinematicCollision2D.xml @@ -14,43 +14,74 @@ - The collision angle according to [code]up_direction[/code], which is [code]Vector2.UP[/code] by default. This value is always positive. + Returns the collision angle according to [code]up_direction[/code], which is [code]Vector2.UP[/code] by default. This value is always positive. + + + + + + Returns the colliding body's attached [Object]. + + + + + + Returns the unique instance ID of the colliding body's attached [Object]. See [method Object.get_instance_id]. + + + + + + Returns the colliding body's [RID] used by the [PhysicsServer2D]. + + + + + + Returns the colliding body's shape. + + + + + + Returns the colliding body's shape index. See [CollisionObject2D]. + + + + + + Returns the colliding body's velocity. + + + + + + Returns the moving object's colliding shape. + + + + + + Returns the colliding body's shape's normal at the point of collision. + + + + + + Returns the point of collision in global coordinates. + + + + + + Returns the moving object's remaining movement vector. + + + + + + Returns the moving object's travel before collision. - - - The colliding body. - - - The colliding body's unique instance ID. See [method Object.get_instance_id]. - - - The colliding body's [RID] used by the [PhysicsServer2D]. - - - The colliding body's shape. - - - The colliding shape's index. See [CollisionObject2D]. - - - The colliding object's velocity. - - - The moving object's colliding shape. - - - The colliding body's shape's normal at the point of collision. - - - The point of collision, in global coordinates. - - - The moving object's remaining movement vector. - - - The distance the moving object traveled before collision. - - diff --git a/doc/classes/KinematicCollision3D.xml b/doc/classes/KinematicCollision3D.xml index 3db6fe019b..372113b281 100644 --- a/doc/classes/KinematicCollision3D.xml +++ b/doc/classes/KinematicCollision3D.xml @@ -15,108 +15,89 @@ - The collision angle according to [code]up_direction[/code], which is [code]Vector3.UP[/code] by default. This value is always positive. + Returns the collision angle according to [code]up_direction[/code], which is [code]Vector3.UP[/code] by default. This value is always positive. - Returns the collider by index (the latest by default). + Returns the colliding body's attached [Object] given a collision index (the deepest collision by default). - Returns the collider ID by index (the latest by default). + Returns the unique instance ID of the colliding body's attached [Object] given a collision index (the deepest collision by default). See [method Object.get_instance_id]. - Returns the collider RID by index (the latest by default). + Returns the colliding body's [RID] used by the [PhysicsServer3D] given a collision index (the deepest collision by default). - Returns the collider shape by index (the latest by default). + Returns the colliding body's shape given a collision index (the deepest collision by default). - Returns the collider shape index by index (the latest by default). + Returns the colliding body's shape index given a collision index (the deepest collision by default). See [CollisionObject3D]. - Returns the collider velocity by index (the latest by default). + Returns the colliding body's velocity given a collision index (the deepest collision by default). + + + + + + Returns the number of detected collisions. - Returns the collider velocity by index (the latest by default). + Returns the moving object's colliding shape given a collision index (the deepest collision by default). - Returns the collider normal by index (the latest by default). + Returns the colliding body's shape's normal at the point of collision given a collision index (the deepest collision by default). - Returns the collider collision point by index (the latest by default). + Returns the point of collision in global coordinates given a collision index (the deepest collision by default). + + + + + + Returns the moving object's remaining movement vector. + + + + + + Returns the moving object's travel before collision. - - - The colliding body. - - - The colliding body's unique instance ID. See [method Object.get_instance_id]. - - - The colliding body's [RID] used by the [PhysicsServer3D]. - - - The colliding body's shape. - - - The colliding shape's index. See [CollisionObject3D]. - - - The colliding object's velocity. - - - - - The moving object's colliding shape. - - - The colliding body's shape's normal at the point of collision. - - - The point of collision, in global coordinates. - - - The moving object's remaining movement vector. - - - The distance the moving object traveled before collision. - - diff --git a/doc/classes/PhysicsServer2D.xml b/doc/classes/PhysicsServer2D.xml index b5b6a7ea58..d55feff829 100644 --- a/doc/classes/PhysicsServer2D.xml +++ b/doc/classes/PhysicsServer2D.xml @@ -584,14 +584,10 @@ - - - - - - - - Returns [code]true[/code] if a collision would result from moving in the given direction from a given point in space. Margin increases the size of the shapes involved in the collision detection. [PhysicsTestMotionResult2D] can be passed to return additional information in. + + + + Returns [code]true[/code] if a collision would result from moving along a motion vector from a given point in space. [PhysicsTestMotionParameters2D] is passed to set motion parameters. [PhysicsTestMotionResult2D] can be passed to return additional information. diff --git a/doc/classes/PhysicsServer3D.xml b/doc/classes/PhysicsServer3D.xml index 1d1ca54dbb..0e32d1defa 100644 --- a/doc/classes/PhysicsServer3D.xml +++ b/doc/classes/PhysicsServer3D.xml @@ -577,15 +577,10 @@ - - - - - - - - - Returns [code]true[/code] if a collision would result from moving in the given direction from a given point in space. Margin increases the size of the shapes involved in the collision detection. [PhysicsTestMotionResult3D] can be passed to return additional information in. + + + + Returns [code]true[/code] if a collision would result from moving along a motion vector from a given point in space. [PhysicsTestMotionParameters3D] is passed to set motion parameters. [PhysicsTestMotionResult3D] can be passed to return additional information. diff --git a/doc/classes/PhysicsTestMotionParameters2D.xml b/doc/classes/PhysicsTestMotionParameters2D.xml new file mode 100644 index 0000000000..7cea848039 --- /dev/null +++ b/doc/classes/PhysicsTestMotionParameters2D.xml @@ -0,0 +1,29 @@ + + + + Parameters to be sent to a 2D body motion test. + + + This class contains parameters used in [method PhysicsServer2D.body_test_motion]. + + + + + + If set to [code]true[/code], shapes of type [constant PhysicsServer2D.SHAPE_SEPARATION_RAY] are used to detect collisions and can stop the motion. Can be useful when snapping to the ground. + If set to [code]false[/code], shapes of type [constant PhysicsServer2D.SHAPE_SEPARATION_RAY] are only used for separation when overlapping with other bodies. That's the main use for separation ray shapes. + + + Optional array of body [RID] to exclude from collision. + + + Transform in global space where the motion should start. Usually set to [member Node2D.global_transform] for the current body's transform. + + + Increases the size of the shapes involved in the collision detection. + + + Motion vector to define the length and direction of the motion to test. + + + diff --git a/doc/classes/PhysicsTestMotionParameters3D.xml b/doc/classes/PhysicsTestMotionParameters3D.xml new file mode 100644 index 0000000000..07abbb1cb1 --- /dev/null +++ b/doc/classes/PhysicsTestMotionParameters3D.xml @@ -0,0 +1,32 @@ + + + + Parameters to be sent to a 3D body motion test. + + + This class contains parameters used in [method PhysicsServer3D.body_test_motion]. + + + + + + If set to [code]true[/code], shapes of type [constant PhysicsServer3D.SHAPE_SEPARATION_RAY] are used to detect collisions and can stop the motion. Can be useful when snapping to the ground. + If set to [code]false[/code], shapes of type [constant PhysicsServer3D.SHAPE_SEPARATION_RAY] are only used for separation when overlapping with other bodies. That's the main use for separation ray shapes. + + + Optional array of body [RID] to exclude from collision. + + + Transform in global space where the motion should start. Usually set to [member Node3D.global_transform] for the current body's transform. + + + Increases the size of the shapes involved in the collision detection. + + + Maximum number of returned collisions, between [code]1[/code] and [code]32[/code]. Always returns the deepest detected collisions. + + + Motion vector to define the length and direction of the motion to test. + + + diff --git a/doc/classes/PhysicsTestMotionResult2D.xml b/doc/classes/PhysicsTestMotionResult2D.xml index 8d594af673..355365cf25 100644 --- a/doc/classes/PhysicsTestMotionResult2D.xml +++ b/doc/classes/PhysicsTestMotionResult2D.xml @@ -1,35 +1,91 @@ + Result from a 2D body motion test. + This class contains the motion and collision result from [method PhysicsServer2D.body_test_motion]. - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + Returns the colliding body's attached [Object], if a collision occured. + + + + + + Returns the unique instance ID of the colliding body's attached [Object], if a collision occured. See [method Object.get_instance_id]. + + + + + + Returns the colliding body's [RID] used by the [PhysicsServer2D], if a collision occured. + + + + + + Returns the colliding body's shape index, if a collision occured. See [CollisionObject2D]. + + + + + + Returns the colliding body's velocity, if a collision occured. + + + + + + Returns the length of overlap along the collision normal, if a collision occured. + + + + + + Returns the moving object's colliding shape, if a collision occured. + + + + + + Returns the colliding body's shape's normal at the point of collision, if a collision occured. + + + + + + Returns the point of collision in global coordinates, if a collision occured. + + + + + + Returns the maximum fraction of the motion that can occur without a collision, between [code]0[/code] and [code]1[/code]. + + + + + + Returns the minimum fraction of the motion needed to collide, if a collision occured, between [code]0[/code] and [code]1[/code]. + + + + + + Returns the moving object's remaining movement vector. + + + + + + Returns the moving object's travel before collision. + + + diff --git a/doc/classes/PhysicsTestMotionResult3D.xml b/doc/classes/PhysicsTestMotionResult3D.xml index 8aa087e99a..282c140568 100644 --- a/doc/classes/PhysicsTestMotionResult3D.xml +++ b/doc/classes/PhysicsTestMotionResult3D.xml @@ -1,8 +1,10 @@ + Result from a 3D body motion test. + This class contains the motion and collision result from [method PhysicsServer3D.body_test_motion]. @@ -11,77 +13,94 @@ + Returns the colliding body's attached [Object] given a collision index (the deepest collision by default), if a collision occured. + Returns the unique instance ID of the colliding body's attached [Object] given a collision index (the deepest collision by default), if a collision occured. See [method Object.get_instance_id]. + Returns the colliding body's [RID] used by the [PhysicsServer3D] given a collision index (the deepest collision by default), if a collision occured. + Returns the colliding body's shape index given a collision index (the deepest collision by default), if a collision occured. See [CollisionObject3D]. + Returns the colliding body's velocity given a collision index (the deepest collision by default), if a collision occured. + + + + + + Returns the number of detected collisions. + Returns the length of overlap along the collision normal given a collision index (the deepest collision by default), if a collision occured. + + + + + + + Returns the moving object's colliding shape given a collision index (the deepest collision by default), if a collision occured. + Returns the colliding body's shape's normal at the point of collision given a collision index (the deepest collision by default), if a collision occured. + Returns the point of collision in global coordinates given a collision index (the deepest collision by default), if a collision occured. + + + + + + Returns the maximum fraction of the motion that can occur without a collision, between [code]0[/code] and [code]1[/code]. + + + + + + Returns the minimum fraction of the motion needed to collide, if a collision occured, between [code]0[/code] and [code]1[/code]. + + + + + + Returns the moving object's remaining movement vector. + + + + + + Returns the moving object's travel before collision. - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/doc/classes/TileMap.xml b/doc/classes/TileMap.xml index e5fe823be6..532c9a7128 100644 --- a/doc/classes/TileMap.xml +++ b/doc/classes/TileMap.xml @@ -73,7 +73,7 @@ - Returns the coodinates of the tile for given physics body RID. Such RID can be retrieved from [member KinematicCollision2D.collider_rid], when colliding with a tile. + Returns the coodinates of the tile for given physics body RID. Such RID can be retrieved from [method KinematicCollision2D.get_collider_rid], when colliding with a tile. -- cgit v1.2.3