Improve physics API docs (#7553)

* Improve physics API docs

* Lint fixes

* Whitespace

Author: willeastcott

src/core/wasm-module.js

@@ -124,7 +124,26 @@ class Impl {
  */
 
 /**
- * A pure static utility class which supports immediate and lazy loading of wasm modules.
+ * A pure static utility class which supports immediate and lazy loading of
+ * [WebAssembly](https://developer.mozilla.org/en-US/docs/WebAssembly) modules. Note that you can
+ * load WebAssembly modules even before instantiating your {@link AppBase} instance.
+ *
+ * This class is generally only needed if you are developing against the Engine directly. Editor
+ * projects automatically load WebAssembly modules included in the project's assets.
+ *
+ * Do not use this class to load the Basis WebAssembly module. Instead, please refer to
+ * {@link basisInitialize}.
+ *
+ * @example
+ * // Load the Ammo.js physics engine
+ * pc.WasmModule.setConfig('Ammo', {
+ *     glueUrl: `ammo.wasm.js`,
+ *     wasmUrl: `ammo.wasm.wasm`,
+ *     fallbackUrl: `ammo.js`
+ * });
+ * await new Promise((resolve) => {
+ *     pc.WasmModule.getInstance('Ammo', () => resolve());
+ * });
  */
 class WasmModule {
     /**

src/framework/components/rigid-body/system.js

@@ -16,7 +16,13 @@ import { RigidBodyComponentData } from './data.js';
 let ammoRayStart, ammoRayEnd;
 
 /**
- * Object holding the result of a successful raycast hit.
+ * Contains the result of a successful raycast intersection with a rigid body. When a ray
+ * intersects with a rigid body in the physics simulation, this class stores the complete
+ * information about that intersection including the entity, the exact point of impact, the normal
+ * at the impact point, and the fractional distance along the ray where the intersection occurred.
+ *
+ * Instances of this class are created and returned by {@link RigidBodyComponentSystem#raycastFirst}
+ * and {@link RigidBodyComponentSystem#raycastAll} methods when performing physics raycasts.
  *
  * @category Physics
  */
@@ -69,8 +75,20 @@ class RaycastResult {
 }
 
 /**
- * Object holding the result of a contact between two rigid bodies.
+ * Represents the detailed data of a single contact point between two rigid bodies in the physics
+ * simulation. This class provides comprehensive information about the contact, including the
+ * entities involved, the exact contact points in both local and world space coordinates, the
+ * contact normal, and the collision impulse force.
+ *
+ * Instances of this class are created by the physics engine when collision events occur and are
+ * passed to event handlers only through the global `contact` event on the
+ * {@link RigidBodyComponentSystem}. Individual rigid body components receive instances of
+ * {@link ContactResult} instead.
  *
+ * @example
+ * app.systems.rigidbody.on('contact', (result) => {
+ *     console.log(`Contact between ${result.a.name} and ${result.b.name}`);
+ * });
  * @category Physics
  */
 class SingleContactResult {
@@ -163,7 +181,33 @@ class SingleContactResult {
 }
 
 /**
- * Object holding the result of a contact between two Entities.
+ * Represents a single point of contact between two colliding rigid bodies in the physics
+ * simulation. Each contact point stores detailed spatial information about the collision,
+ * including both local and world space coordinates of the exact contact points on both entities,
+ * the contact normal  direction, and the collision impulse force.
+ *
+ * Contact points are generated by the physics engine during collision detection and are typically
+ * accessed through a {@link ContactResult} object, which can contain multiple contact points for a
+ * single collision between two entities. Multiple contact points commonly occur when objects
+ * collide along edges or faces rather than at a single point.
+ *
+ * The impulse property can be particularly useful for gameplay mechanics that need to respond
+ * differently based on the force of impact, such as damage calculations or sound effect volume.
+ *
+ * @example
+ * // Access contact points from a collision event
+ * entity.collision.on('contact', (result) => {
+ *     // Get the first contact point
+ *     const contact = result.contacts[0];
+ *
+ *     // Get the contact position in world space
+ *     const worldPos = contact.point;
+ *
+ *     // Check how hard the collision was
+ *     if (contact.impulse > 10) {
+ *         console.log("That was a hard impact!");
+ *     }
+ * });
  *
  * @category Physics
  */
@@ -197,15 +241,16 @@ class ContactPoint {
     pointOther;
 
     /**
-     * The normal vector of the contact on the other entity, in world space.
+     * The normal vector of the contact on the other entity, in world space. This vector points
+     * away from the surface of the other entity at the point of contact.
      *
      * @type {Vec3}
      */
     normal;
 
     /**
      * The total accumulated impulse applied by the constraint solver during the last sub-step.
-     * Describes how hard two objects collide.
+     * This value represents how hard two objects collided. Higher values indicate stronger impacts.
      *
      * @type {number}
      */
@@ -238,7 +283,24 @@ class ContactPoint {
 }
 
 /**
- * Object holding the result of a contact between two Entities.
+ * Represents a collection of contact points between two entities in a physics collision.
+ * When rigid bodies collide, this object stores the entity involved in the collision and
+ * an array of specific contact points where the collision occurred. This information is
+ * used by the physics system to resolve collisions and notify components through events.
+ *
+ * Instances of this class are passed to event handlers for the `contact` and `collisionstart`
+ * events on individual {@link RigidBodyComponent} and {@link CollisionComponent} instances.
+ *
+ * Unlike {@link SingleContactResult} which is used for global contact events, ContactResult
+ * objects provide information about collision from the perspective of one entity, with
+ * information about which other entity was involved and all points of contact.
+ *
+ * Please refer to the following event documentation for more information:
+ *
+ * - {@link CollisionComponent.EVENT_CONTACT}
+ * - {@link CollisionComponent.EVENT_COLLISIONSTART}
+ * - {@link RigidBodyComponent.EVENT_CONTACT}
+ * - {@link RigidBodyComponent.EVENT_COLLISIONSTART}
  *
  * @category Physics
  */
@@ -273,10 +335,15 @@ class ContactResult {
 const _schema = ['enabled'];
 
 /**
- * The RigidBodyComponentSystem maintains the dynamics world for simulating rigid bodies, it also
- * controls global values for the world such as gravity. Note: The RigidBodyComponentSystem is only
- * valid if 3D Physics is enabled in your application. You can enable this in the application
- * settings for your project.
+ * The RigidBodyComponentSystem manages the physics simulation for all rigid body components
+ * in the application. It creates and maintains the underlying Ammo.js physics world, handles
+ * physics object creation and destruction, performs physics raycasting, detects and reports
+ * collisions, and updates the transforms of entities with rigid bodies after each physics step.
+ *
+ * The system controls global physics settings like gravity and provides methods for raycasting
+ * and collision detection.
+ *
+ * This system is only functional if your application has loaded the Ammo.js {@link WasmModule}.
  *
  * @category Physics
  */
@@ -310,6 +377,9 @@ class RigidBodyComponentSystem extends ComponentSystem {
      * [0, -9.81, 0] which is an approximation of the gravitational force on Earth.
      *
      * @type {Vec3}
+     * @example
+     * // Set the gravity in the physics world to simulate a planet with low gravity
+     * app.systems.rigidbody.gravity = new pc.Vec3(0, -3.7, 0);
      */
     gravity = new Vec3(0, -9.81, 0);