Better support kinematic rigid bodies.

Added explicit function to set the kinematic target. This is intended to be
set for each physics simulation step (such as from a
dsOnPhysicsSceneStepFunction callback) and allows linear collision checks
to be aware of the full motion.

Setting velocities and forces will now return with an error if the motion
type isn't dynamic rather than having motion properties. This avoids
inconsistent behavior between underlying physics engines that support
moving kinematics through velocities (e.g. Jolt) vs. others that are purely
step-based targets (e.g. PhysX, Bullet). Since the time step is passed when
setting the kinematic target, the same behavior should be possible across
both implementation types.

Added missing rigid body velocity access function implementations and fixed
find/replace error for naming of angular velocity access functions.

modules/Physics/Physics/include/DeepSea/Physics/RigidBody.h

@@ -343,6 +343,48 @@ DS_PHYSICS_EXPORT bool dsRigidBody_getTransformMatrix(dsMatrix44f* outTransform,
 DS_PHYSICS_EXPORT bool dsRigidBody_setTransformMatrix(dsRigidBody* rigidBody,
 	const dsMatrix44f* transform, bool activate);
 
+/**
+ * @brief Sets the target transform for a kinematic rigid body.
+ *
+ * This will linearly move the kinematic body for the next step of the physics simulation. When
+ * using linear collision, this allows for the full linear step to be considered. Most commonly
+ * this will be called as part of a dsOnPhysicsSceneStepFunction callback.
+ *
+ * This is only valid for a kinematic rigid body currently a part of a scene.
+ *
+ * @remark errno will be set on failure.
+ * @param rigidBody The rigid body to set the kinematic target transform on.
+ * @param time The time for the step, most commonly forwarded from the time parameter of a
+ *     dsOnPhysicsSceneStepFunction callback.
+ * @param position The new position or NULL to leave unchanged.
+ * @param orientation The new orientation or NULL to leave unchanged.
+ * @return False if the kinematic target couldn't be set.
+ */
+DS_PHYSICS_EXPORT bool dsRigidBody_setKinematicTarget(dsRigidBody* rigidBody,
+	float time, const dsVector3f* position, const dsQuaternion4f* orientation);
+
+/**
+ * @brief Sets the target transform for a kinematic rigid body based on a transform matrix.
+ *
+ * This will linearly move the kinematic body for the next step of the physics simulation. When
+ * using linear collision, this allows for the full linear step to be considered. Most commonly
+ * this will be called as part of a dsOnPhysicsSceneStepFunction callback.
+ *
+ * This is only valid for a kinematic rigid body currently a part of a scene.
+ *
+ * @remark errno will be set on failure.
+ * @param rigidBody The rigid body to set the kinematic target transform on.
+ * @param time The time for the step, most commonly forwarded from the time parameter of a
+ *     dsOnPhysicsSceneStepFunction callback.
+ * @param transform The transform matrix. This is expected to be orthogonal and not contain sheer.
+ *     If the transform has scale that's different from the current scale factor, it will be set
+ *     as weith dsRigidBody_setTransform(), meaning that it will be immediately applied rather than
+ *     over the time step.
+ * @return False if the kinematic target couldn't be set.
+ */
+DS_PHYSICS_EXPORT bool dsRigidBody_setKinematicTargetMatrix(dsRigidBody* rigidBody,
+	float time, const dsMatrix44f* transform);
+
 /**
  * @brief Gets the position around which the rigid body will rotate in world space.
  * @remark The shapes must be finalized before calling this function.
@@ -432,6 +474,9 @@ DS_PHYSICS_EXPORT bool dsRigidBody_setMaxAngularVelocity(dsRigidBody* rigidBody,
 
 /**
  * @brief Gets the current linear velocity for a rigid body.
+ *
+ * This is only valid if the motion type is dynamic.
+ *
  * @remark errno will be set on failure.
  * @param[out] outVelocity The storage for the linear velocity.
  * @param rigidBody The rigid body to get the linear velocity for.
@@ -442,6 +487,9 @@ DS_PHYSICS_EXPORT bool dsRigidBody_getLinearVelocity(dsVector3f* outVelocity,
 
 /**
  * @brief Sets the current linear velocity for a rigid body.
+ *
+ * The volicty may only be set if the motion type is dynamic.
+ *
  * @remark errno will be set on failure.
  * @param rigidBody The rigid body to set the linear velocity on.
  * @param velocity The new linear velocity.
@@ -451,28 +499,36 @@ DS_PHYSICS_EXPORT bool dsRigidBody_setLinearVelocity(dsRigidBody* rigidBody,
 	const dsVector3f* velocity);
 
 /**
- * @brief Gets the current linear angular for a rigid body.
+ * @brief Gets the current angular velocity for a rigid body.
+ *
+ * This is only valid if the motion type is dynamic.
+ *
  * @remark errno will be set on failure.
- * @param[out] outAngular The storage for the linear angular.
- * @param rigidBody The rigid body to get the linear angular for.
- * @return False if the linear angular couldn't be queried.
+ * @param[out] outVelocity The storage for the angular velocity.
+ * @param rigidBody The rigid body to get the angular velocity for.
+ * @return False if the angular velocity couldn't be queried.
  */
-DS_PHYSICS_EXPORT bool dsRigidBody_getLinearAngular(dsVector3f* outAngular,
+DS_PHYSICS_EXPORT bool dsRigidBody_getAngularVelocity(dsVector3f* outVelocity,
 	const dsRigidBody* rigidBody);
 
 /**
- * @brief Sets the current linear angular for a rigid body.
+ * @brief Sets the current angular velocity for a rigid body.
+ *
+ * The volicty may only be set if the motion type is dynamic.
+ *
  * @remark errno will be set on failure.
- * @param rigidBody The rigid body to set the linear angular on.
- * @param angular The new linear angular.
- * @return False if the linear angular couldn't be set.
+ * @param rigidBody The rigid body to set the angular velocity on.
+ * @param velocity The new angular velocity.
+ * @return False if the angular velocity couldn't be set.
  */
-DS_PHYSICS_EXPORT bool dsRigidBody_setLinearAngular(dsRigidBody* rigidBody,
-	const dsVector3f* angular);
+DS_PHYSICS_EXPORT bool dsRigidBody_setAngularVelocity(dsRigidBody* rigidBody,
+	const dsVector3f* velocity);
 
 /**
  * @brief Adds a force to a rigid body.
  *
+ * Forces may only be applied if the motion type is dynamic.
+ *
  * The force will only be active until the next time the physics scene is stepped.
  *
  * @remark The shapes must be finalized before calling this function.
@@ -486,6 +542,8 @@ DS_PHYSICS_EXPORT bool dsRigidBody_addForce(dsRigidBody* rigidBody, const dsVect
 /**
  * @brief Adds a force to a rigid body at a point.
  *
+ * Forces may only be applied if the motion type is dynamic.
+ *
  * This may add torque as well if the force isn't aligned with the center of rotation.
  * The force will only be active until the next time the physics scene is stepped.
  *
@@ -502,6 +560,8 @@ DS_PHYSICS_EXPORT bool dsRigidBody_addForceAtPoint(dsRigidBody* rigidBody, const
 /**
  * @brief Clears the previously accumulated force for a rigid body.
  *
+ * Forces may only be applied if the motion type is dynamic.
+ *
  * This will clear any forces previously added with dsRigidBody_addForce() since the previous step
  * of the physics scene.
  *
@@ -515,6 +575,8 @@ DS_PHYSICS_EXPORT bool dsRigidBody_clearForce(dsRigidBody* rigidBody);
 /**
  * @brief Adds a torque to a rigid body.
  *
+ * Forces may only be applied if the motion type is dynamic.
+ *
  * The torque will only be active until the next time the physics scene is stepped.
  *
  * @remark The shapes must be finalized before calling this function.
@@ -528,6 +590,8 @@ DS_PHYSICS_EXPORT bool dsRigidBody_addTorque(dsRigidBody* rigidBody, const dsVec
 /**
  * @brief Clears the previously accumulated torque for a rigid body.
  *
+ * Forces may only be applied if the motion type is dynamic.
+ *
  * This will clear any torque previously added with dsRigidBody_addTorque() since the previous step
  * of the physics scene.
  *
@@ -541,6 +605,8 @@ DS_PHYSICS_EXPORT bool dsRigidBody_clearTorque(dsRigidBody* rigidBody);
 /**
  * @brief Adds a linear impulse to a rigid body.
  *
+ * Forces may only be applied if the motion type is dynamic.
+ *
  * The torque will only be active until the next time the physics scene is stepped.
  *
  * @remark The shapes must be finalized before calling this function.
@@ -555,6 +621,8 @@ DS_PHYSICS_EXPORT bool dsRigidBody_addLinearImpulse(dsRigidBody* rigidBody,
 /**
  * @brief Clears the previously accumulated linear impulse for a rigid body.
  *
+ * Forces may only be applied if the motion type is dynamic.
+ *
  * This will clear any linear impulse previously added with dsRigidBody_addLinearImpulse() since the
  * previous step of the physics scene.
  *
@@ -568,6 +636,8 @@ DS_PHYSICS_EXPORT bool dsRigidBody_clearLinearImpulse(dsRigidBody* rigidBody);
 /**
  * @brief Adds a angular impulse to a rigid body.
  *
+ * Forces may only be applied if the motion type is dynamic.
+ *
  * The torque will only be active until the next time the physics scene is stepped.
  *
  * @remark The shapes must be finalized before calling this function.
@@ -582,6 +652,8 @@ DS_PHYSICS_EXPORT bool dsRigidBody_addAngularImpulse(dsRigidBody* rigidBody,
 /**
  * @brief Clears the previously accumulated angular impulse for a rigid body.
  *
+ * Forces may only be applied if the motion type is dynamic.
+ *
  * This will clear any angular impulse previously added with dsRigidBody_addAngularImpulse() since
  * the previous step of the physics scene.
  *

modules/Physics/Physics/include/DeepSea/Physics/RigidBodyTypes.h

@@ -581,7 +581,7 @@ typedef bool (*dsSetRigidBodyCanCollisionGroupsCollideFunction)(dsPhysicsEngine*
 /**
  * @brief Function to set the transform on a rigid body.
  * @param engine The physics engine the rigid body was created with.
- * @param rigidBody The rigid body to change the position on.
+ * @param rigidBody The rigid body to set the transform on.
  * @param position The new position or NULL to leave unchanged.
  * @param orientation The new orientation or NULL to leave unchanged.
  * @param scale The new scale or NULL to leave unchanged.
@@ -592,6 +592,19 @@ typedef bool (*dsSetRigidBodyTransformFunction)(dsPhysicsEngine* engine, dsRigid
 	const dsVector3f* position, const dsQuaternion4f* orientation, const dsVector3f* scale,
 	bool activate);
 
+/**
+ * @brief Function to set the transform target for moving a kinematic rigid body.
+ * @param engine The physics engine the rigid body was created with.
+ * @param rigidBody The rigid body to set the kinmatic target transform on.
+ * @param time The time over which the kinematic transform occurs.
+ * @param position The new position or NULL to leave unchanged.
+ * @param orientation The new orientation or NULL to leave unchanged.
+ * @return False if the kinematic target couldn't be set.
+ */
+typedef bool (*dsSetRigidBodyKinematicTargetFunction)(dsPhysicsEngine* engine,
+	dsRigidBody* rigidBody, float time, const dsVector3f* position,
+	const dsQuaternion4f* orientation);
+
 /**
  * @brief Function to set a float value on a rigid body.
  * @param engine The physics engine the rigid body was created with.

modules/Physics/Physics/include/DeepSea/Physics/SharedTypes.h

@@ -90,9 +90,8 @@ typedef enum dsPhysicsMotionType
 	dsPhysicsMotionType_Static,
 
 	/**
-	 * Object that may be moved directly or by setting the velocities, but won't be affected by
-	 * forces. When moved, it will be treated as an object with infinite mass and always move
-	 * dynamic objects away.
+	 * Object that may be moved directly, but won't be affected by forces. When moved, it will be
+	 * treated as an object with infinite mass and always move dynamic objects away.
 	 */
 	dsPhysicsMotionType_Kinematic,
 

modules/Physics/Physics/include/DeepSea/Physics/Types.h

@@ -1139,6 +1139,11 @@ struct dsPhysicsEngine
 	 */
 	dsSetRigidBodyTransformFunction setRigidBodyTransformFunc;
 
+	/**
+	 * @brief Function to set the transform target for a kinematic rigid body.
+	 */
+	dsSetRigidBodyKinematicTargetFunction setRigidBodyKinematicTargetFunc;
+
 	/**
 	 * @brief Function to set the mass on a rigid body.
 	 */