update ray cast docs and minor bug fix

docs/api/classes/broadphase.md

@@ -262,7 +262,7 @@ number of proxies in the tree.
 Name | Type | Description |
 ------ | ------ | ------ |
 `input` | [RayCastInput](../interfaces/raycastinput.md) | The ray-cast input data. The ray extends from `p1` to `p1 + maxFraction * (p2 - p1)`. |
-`rayCastCallback` | [RayCastCallback](../globals.md#raycastcallback) | A function that is called for each proxy that is hit by the ray.  |
+`rayCastCallback` | [RayCastCallback](../globals.md#raycastcallback) | A function that is called for each proxy that is hit by the ray. If the return value is a positive number it will update the maxFraction of the ray cast input, and if it is zero it will terminate they ray cast.  |
 
 **Returns:** *void*
 

docs/api/classes/dynamictree.md

@@ -316,7 +316,7 @@ number of proxies in the tree.
 Name | Type | Description |
 ------ | ------ | ------ |
 `input` | [RayCastInput](../interfaces/raycastinput.md) | The ray-cast input data. The ray extends from `p1` to `p1 + maxFraction * (p2 - p1)`. |
-`rayCastCallback` | [RayCastCallback](../globals.md#raycastcallback) | A function that is called for each proxy that is hit by the ray.  |
+`rayCastCallback` | [RayCastCallback](../globals.md#raycastcallback) | A function that is called for each proxy that is hit by the ray. If the return value is a positive number it will update the maxFraction of the ray cast input, and if it is zero it will terminate they ray cast.  |
 
 **Returns:** *void*
 

docs/api/classes/world.md

@@ -774,7 +774,7 @@ Name | Type | Description |
 ------ | ------ | ------ |
 `point1` | Vec2 | The ray starting point |
 `point2` | Vec2 | The ray ending point |
-`callback` | [WorldRayCastCallback](../globals.md#worldraycastcallback) | A user implemented callback function.  |
+`callback` | [WorldRayCastCallback](../globals.md#worldraycastcallback) | A function that is called for each fixture that is hit by the ray. You control how the ray cast proceeds by returning a numeric/float value.  |
 
 **Returns:** *void*
 

docs/api/globals.md

@@ -319,10 +319,14 @@ ___
 
 Callback function for ray casts, see [World.rayCast](classes/world.md#raycast).
 
-Called for each fixture found in the query. You control how the ray cast
-proceeds by returning a float: return -1: ignore this fixture and continue
-return 0: terminate the ray cast return fraction: clip the ray to this point
-return 1: don't clip the ray and continue
+Called for each fixture found in the query.
+The returned value replaces the ray-cast input maxFraction.
+You control how the ray cast proceeds by returning a numeric/float value.
+
+- `0` to terminate the ray cast
+- `fraction` to clip the ray cast at current point
+- `1` don't clip the ray and continue
+- `-1` (or anything else) to continue
 
 **`param`** The fixture hit by the ray
 
@@ -332,13 +336,7 @@ return 1: don't clip the ray and continue
 
 **`param`** The fraction along the ray at the point of intersection
 
-**`returns`** `-1` to ignore the current fixture and continue
-
-**`returns`** `0` to terminate the ray cast
-
-**`returns`** `fraction` to clip the raycast at current point
-
-**`returns`** `1` don't clip the ray and continue
+**`returns`** A number to update the maxFraction
 
 #### Type declaration:
 

src/collision/BroadPhase.ts

@@ -111,7 +111,7 @@ export class BroadPhase {
    * number of proxies in the tree.
    *
    * @param input The ray-cast input data. The ray extends from `p1` to `p1 + maxFraction * (p2 - p1)`.
-   * @param rayCastCallback A function that is called for each proxy that is hit by the ray.
+   * @param rayCastCallback A function that is called for each proxy that is hit by the ray. If the return value is a positive number it will update the maxFraction of the ray cast input, and if it is zero it will terminate they ray cast.
    */
   rayCast(input: RayCastInput, rayCastCallback: RayCastCallback): void {
     this.m_tree.rayCast(input, rayCastCallback);

src/collision/DynamicTree.ts

@@ -768,7 +768,7 @@ export class DynamicTree<T> {
    * number of proxies in the tree.
    *
    * @param input The ray-cast input data. The ray extends from `p1` to `p1 + maxFraction * (p2 - p1)`.
-   * @param rayCastCallback A function that is called for each proxy that is hit by the ray.
+   * @param rayCastCallback A function that is called for each proxy that is hit by the ray. If the return value is a positive number it will update the maxFraction of the ray cast input, and if it is zero it will terminate they ray cast.
    */
   rayCast(input: RayCastInput, rayCastCallback: RayCastCallback): void {
     // TODO: GC
@@ -825,10 +825,8 @@ export class DynamicTree<T> {
 
         if (value === 0.0) {
           // The client has terminated the ray cast.
-          return;
-        }
-
-        if (value > 0.0) {
+          break;
+        } else if (value > 0.0) {
           // update segment bounding box.
           maxFraction = value;
           t = Vec2.combine((1 - maxFraction), p1, maxFraction, p2);

src/dynamics/World.ts

@@ -78,20 +78,21 @@ export interface WorldDef {
 /**
  * Callback function for ray casts, see {@link World.rayCast}.
  *
- * Called for each fixture found in the query. You control how the ray cast
- * proceeds by returning a float: return -1: ignore this fixture and continue
- * return 0: terminate the ray cast return fraction: clip the ray to this point
- * return 1: don't clip the ray and continue
+ * Called for each fixture found in the query.
+ * The returned value replaces the ray-cast input maxFraction.
+ * You control how the ray cast proceeds by returning a numeric/float value.
+ * 
+ * - `0` to terminate the ray cast
+ * - `fraction` to clip the ray cast at current point
+ * - `1` don't clip the ray and continue
+ * - `-1` (or anything else) to continue
  *
  * @param fixture The fixture hit by the ray
  * @param point The point of initial intersection
  * @param normal The normal vector at the point of intersection
  * @param fraction The fraction along the ray at the point of intersection
  *
- * @return `-1` to ignore the current fixture and continue
- * @return `0` to terminate the ray cast
- * @return `fraction` to clip the raycast at current point
- * @return `1` don't clip the ray and continue
+ * @returns A number to update the maxFraction
  */
 export type WorldRayCastCallback = (fixture: Fixture, point: Vec2, normal: Vec2, fraction: number) => number;
 
@@ -404,7 +405,7 @@ export class World {
    *
    * @param point1 The ray starting point
    * @param point2 The ray ending point
-   * @param callback A user implemented callback function.
+   * @param callback A function that is called for each fixture that is hit by the ray. You control how the ray cast proceeds by returning a numeric/float value.
    */
   rayCast(point1: Vec2, point2: Vec2, callback: WorldRayCastCallback): void {
     _ASSERT && console.assert(typeof callback === 'function');