raycast result includes closest hit fraction

cocos/physics/bullet/bullet-world.ts

@@ -28,7 +28,7 @@
 import { BulletShape } from './shapes/bullet-shape';
 import { ArrayCollisionMatrix } from '../utils/array-collision-matrix';
 import { TupleDictionary } from '../utils/tuple-dictionary';
 import { TriggerEventObject, CollisionEventObject, CC_V3_0, CC_V3_1, CC_V3_2, CC_COLOR_0, BulletCache, CharacterTriggerEventObject } from './bullet-cache';
 import { bullet2CocosVec3, cocos2BulletQuat, cocos2BulletVec3 } from './bullet-utils';
 import { IRaycastOptions, IPhysicsWorld } from '../spec/i-physics-world';
 import { PhysicsRayResult, PhysicsMaterial, CharacterControllerContact, EPhysicsDrawFlags } from '../framework';
@@ -237,12 +237,13 @@
             const posArray = bt.ccAllRayCallback_getHitPointWorld(allHitsCB);
             const normalArray = bt.ccAllRayCallback_getHitNormalWorld(allHitsCB);
             const ptrArray = bt.ccAllRayCallback_getCollisionShapePtrs(allHitsCB);
+            const closestHitFraction = bt.ccAllRayCallback_getClosestHitFraction(allHitsCB);
             for (let i = 0, n = bt.int_array_size(ptrArray); i < n; i++) {
                 bullet2CocosVec3(v3_0, bt.Vec3_array_at(posArray, i));
                 bullet2CocosVec3(v3_1, bt.Vec3_array_at(normalArray, i));
                 const shape = BulletCache.getWrapper<BulletShape>(bt.int_array_at(ptrArray, i), BulletShape.TYPE);
                 const r = pool.add(); results.push(r);
-                r._assign(v3_0, Vec3.distance(worldRay.o, v3_0), shape.collider, v3_1);
+                r._assign(v3_0, Vec3.distance(worldRay.o, v3_0), shape.collider, v3_1, closestHitFraction);
             }
             return true;
         }
@@ -261,7 +262,8 @@
             bullet2CocosVec3(v3_0, bt.ccClosestRayCallback_getHitPointWorld(closeHitCB));
             bullet2CocosVec3(v3_1, bt.ccClosestRayCallback_getHitNormalWorld(closeHitCB));
             const shape = BulletCache.getWrapper<BulletShape>(bt.ccClosestRayCallback_getCollisionShapePtr(closeHitCB), BulletShape.TYPE);
-            result._assign(v3_0, Vec3.distance(worldRay.o, v3_0), shape.collider, v3_1);
+            const closestHitFraction = bt.ccClosestConvexCallback_getClosestHitFraction(closeHitCB);
+            result._assign(v3_0, Vec3.distance(worldRay.o, v3_0), shape.collider, v3_1, closestHitFraction);
             return true;
         }
         return false;
@@ -398,12 +400,13 @@
             const posArray = bt.ccAllConvexCallback_getHitPointWorld(allHitsCB);
             const normalArray = bt.ccAllConvexCallback_getHitNormalWorld(allHitsCB);
             const ptrArray = bt.ccAllConvexCallback_getCollisionShapePtrs(allHitsCB);
+            const closestHitFraction = bt.ccAllConvexCallback_getClosestHitFraction(allHitsCB);
             for (let i = 0, n = bt.int_array_size(ptrArray); i < n; i++) {
                 bullet2CocosVec3(v3_0, bt.Vec3_array_at(posArray, i));
                 bullet2CocosVec3(v3_1, bt.Vec3_array_at(normalArray, i));
                 const shape = BulletCache.getWrapper<BulletShape>(bt.int_array_at(ptrArray, i), BulletShape.TYPE);
                 const r = pool.add(); results.push(r);
-                r._assign(v3_0, Vec3.distance(worldRay.o, v3_0), shape.collider, v3_1);
+                r._assign(v3_0, Vec3.distance(worldRay.o, v3_0), shape.collider, v3_1, closestHitFraction);
             }
             return true;
         }
@@ -439,7 +442,8 @@
             bullet2CocosVec3(v3_0, bt.ccClosestConvexCallback_getHitPointWorld(closeHitCB));
             bullet2CocosVec3(v3_1, bt.ccClosestConvexCallback_getHitNormalWorld(closeHitCB));
             const shape = BulletCache.getWrapper<BulletShape>(bt.ccClosestConvexCallback_getCollisionShapePtr(closeHitCB), BulletShape.TYPE);
-            result._assign(v3_0, Vec3.distance(worldRay.o, v3_0), shape.collider, v3_1);
+            const closestHitFraction = bt.ccClosestConvexCallback_getClosestHitFraction(closeHitCB);
+            result._assign(v3_0, Vec3.distance(worldRay.o, v3_0), shape.collider, v3_1, closestHitFraction);
             return true;
         }
         return false;

cocos/physics/framework/physics-ray-result.ts

@@ -72,10 +72,28 @@ export class PhysicsRayResult {
         return this._hitNormal;
     }
 
+    /**
+     * @en
+     * Represents the fraction (range: 0.0 to 1.0) along the ray's path where the closest collision occurs.
+     * A value of 0.0 indicates an immediate collision at the ray's starting point,
+     * while a value of 1.0 means no collision along the entire ray length.
+     * Intermediate values indicate the fraction of the ray distance at which the closest hit is detected.
+     * Warning: only take effect with Bullet.
+     * @zh
+     * 表示射线路径上最近碰撞发生的位置，以百分比形式（范围：0.0 到 1.0）。
+     * 0.0 表示射线在起点处立即发生碰撞，1.0 表示射线在整个路径上未发生碰撞。
+     * 中间值表示碰撞点在射线总长度上的比例位置。
+     * 注意：只在 Bullet 引擎起效.
+     */
+    get closestHitFraction (): number {
+        return this._closestHitFraction;
+    }
+
     protected _hitPoint: Vec3 = new Vec3();
     protected _hitNormal: Vec3 = new Vec3();
     protected _distance = 0;
     protected _collider: Collider | null = null;
+    protected _closestHitFraction = 0;
 
     /**
      * @en
@@ -85,11 +103,12 @@ export class PhysicsRayResult {
      *
      * @deprecated since v3.5.0, this is an engine private interface that will be removed in the future.
      */
-    public _assign (hitPoint: IVec3Like, distance: number, collider: Collider, hitNormal: IVec3Like): void {
+    public _assign (hitPoint: IVec3Like, distance: number, collider: Collider, hitNormal: IVec3Like, closestHitFraction?: number): void {
         Vec3.copy(this._hitPoint, hitPoint);
         Vec3.copy(this._hitNormal, hitNormal);
         this._distance = distance;
         this._collider = collider;
+        if (closestHitFraction) this._closestHitFraction = closestHitFraction;
     }
 
     /**
@@ -104,6 +123,7 @@ export class PhysicsRayResult {
         Vec3.copy(c._hitNormal, this._hitNormal);
         c._distance = this._distance;
         c._collider = this._collider;
+        c._closestHitFraction = this._closestHitFraction;
         return c;
     }
 }

native/external-config.json

@@ -3,6 +3,6 @@
         "type": "github",
         "owner": "cocos-creator",
         "name": "engine-native-external",
-        "checkout": "v3.8.5-3"
+        "checkout": "v3.8.5-4"
     }
 }