Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(cocos): PhysicsSystem.instance.raycast and raycastClosest cross the world's box colliders as oriented boxes, nearest first, with the point and face met

yhh509000113e56
diff --git a/sdk/src/cocos/index.ts b/sdk/src/cocos/index.ts
index d5ca11044..3c25d5cec 100644
--- a/sdk/src/cocos/index.ts
+++ b/sdk/src/cocos/index.ts
@@ -31,6 +31,7 @@ export { unsupported } from './unsupported';
export { ccenum, js, NodePool, profiler } from './misc';
export { MeshRenderer, ModelRenderer, UIMeshRenderer } from './meshRenderer';
export { Collider, BoxCollider } from './collider';
+export { PhysicsSystem, PhysicsRayResult } from './physicsSystem';
export { UIRenderer } from './ui/renderer';
export { geometry } from './geometry';
export { UITransform, Label, LabelOutline, LabelShadow, Sprite, UIOpacity, Button, EventHandler, Widget, Layout, Camera, RichText, Mask, Toggle, ToggleContainer, ProgressBar, Slider, BlockInputEvents, ScrollView, Graphics, Line, EditBox, PageView, PageViewIndicator, ScrollBar, SafeArea, WebView, getVisibleSize, setVisibleSize } from './ui';
diff --git a/sdk/src/cocos/physicsSystem.ts b/sdk/src/cocos/physicsSystem.ts
new file mode 100644
index 000000000..996112740
--- /dev/null
+++ b/sdk/src/cocos/physicsSystem.ts
@@ -0,0 +1,102 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file cocos/physicsSystem.ts
+ * @brief `PhysicsSystem.instance.raycast`: which colliders a ray crosses, nearest first.
+ *
+ * A Cocos game asks the physics system one thing of its colliders: what did this touch ray hit. The answer is a walk over the world's box
+ * colliders, each tested as the oriented box it is, so a project that only picks does not have to load a solver and step bodies for it.
+ */
+import { BoxCollider3D } from '../physics3d/Physics3DComponents';
+import { BoxCollider } from './collider';
+import { getCurrentWorld, nodeForEntity } from './node';
+import { Quat, Vec3 } from './math';
+import { Ray } from './geometry';
+
+/** One collider a ray crossed. */
+export class PhysicsRayResult {
+ collider!: BoxCollider;
+ /** Where the ray met it. */
+ hitPoint = new Vec3();
+ /** How far along the ray. */
+ distance = 0;
+ /** The side that was met, pointing out of the box. */
+ hitNormal = new Vec3();
+}
+
+/** The nearest distance at which @p ray crosses the box, or -1; the normal of the face goes to @p normal. */
+function crossBox(ray: Ray, centre: Vec3, half: Vec3, rotation: Quat, position: Vec3, normal: Vec3): number {
+ const inverse = Quat.invert(new Quat(), rotation);
+ const o = Vec3.transformQuat(new Vec3(), new Vec3(ray.o.x - position.x, ray.o.y - position.y, ray.o.z - position.z), inverse);
+ const d = Vec3.transformQuat(new Vec3(), ray.d, inverse);
+ let near = -Infinity, far = Infinity, axisHit: 'x' | 'y' | 'z' = 'y', sign = 1;
+ for (const axis of ['x', 'y', 'z'] as const) {
+ const lo = centre[axis] - half[axis], hi = centre[axis] + half[axis];
+ if (Math.abs(d[axis]) < 1e-12) {
+ if (o[axis] < lo || o[axis] > hi) return -1;
+ continue;
+ }
+ let t1 = (lo - o[axis]) / d[axis], t2 = (hi - o[axis]) / d[axis];
+ let s = -1;
+ if (t1 > t2) { [t1, t2] = [t2, t1]; s = 1; }
+ if (t1 > near) { near = t1; axisHit = axis; sign = s; }
+ far = Math.min(far, t2);
+ }
+ if (far < Math.max(near, 0)) return -1;
+ // a ray that starts inside a box meets nothing on the way in: it leaves, and is reported at the origin, as the engine reports an inside start
+ const t = near >= 0 ? near : 0;
+ const local = new Vec3();
+ local[axisHit] = sign;
+ Vec3.transformQuat(normal, local, rotation);
+ return t;
+}
+
+export class PhysicsSystem {
+ private static instance_: PhysicsSystem | null = null;
+ static get instance(): PhysicsSystem { return (PhysicsSystem.instance_ ??= new PhysicsSystem()); }
+
+ /** Every collider the last `raycast` crossed, nearest first. */
+ readonly raycastResults: PhysicsRayResult[] = [];
+ readonly raycastClosestResult = new PhysicsRayResult();
+
+ /** Whether the ray crosses any collider the mask lets in; the crossings are `raycastResults`. */
+ raycast(worldRay: Ray, _mask = 0xffffffff, maxDistance = 10000000, queryTrigger = true): boolean {
+ this.raycastResults.length = 0;
+ const world = getCurrentWorld();
+ if (!world) return false;
+ const found: PhysicsRayResult[] = [];
+ for (const entity of world.getEntitiesWithComponents([BoxCollider3D])) {
+ const data = world.get(entity, BoxCollider3D);
+ if (!data.enabled || (data.isSensor && !queryTrigger) || !world.isEntityActive(entity)) continue;
+ const node = nodeForEntity(world, entity);
+ const scaleRatio = new Vec3(1, 1, 1);
+ const local = node.scale, wide = node.worldScale;
+ for (const a of ['x', 'y', 'z'] as const) if (Math.abs(local[a]) > 1e-6) scaleRatio[a] = Math.abs(wide[a] / local[a]);
+ const centre = new Vec3((data.center?.x ?? 0) * scaleRatio.x, (data.center?.y ?? 0) * scaleRatio.y, (data.center?.z ?? 0) * scaleRatio.z);
+ const half = new Vec3(data.halfExtents.x * scaleRatio.x, data.halfExtents.y * scaleRatio.y, data.halfExtents.z * scaleRatio.z);
+ const normal = new Vec3();
+ const t = crossBox(worldRay, centre, half, node.worldRotation, node.worldPosition, normal);
+ if (t < 0 || t > maxDistance) continue;
+ const result = new PhysicsRayResult();
+ result.collider = node.getComponent(BoxCollider)!;
+ result.distance = t;
+ worldRay.computeHit(result.hitPoint, t);
+ result.hitNormal = normal;
+ found.push(result);
+ }
+ found.sort((a, b) => a.distance - b.distance);
+ this.raycastResults.push(...found);
+ return found.length > 0;
+ }
+
+ /** Whether the ray crosses any; the nearest is `raycastClosestResult`. */
+ raycastClosest(worldRay: Ray, mask = 0xffffffff, maxDistance = 10000000, queryTrigger = true): boolean {
+ if (!this.raycast(worldRay, mask, maxDistance, queryTrigger)) return false;
+ const nearest = this.raycastResults[0]!;
+ this.raycastClosestResult.collider = nearest.collider;
+ this.raycastClosestResult.distance = nearest.distance;
+ this.raycastClosestResult.hitPoint.set(nearest.hitPoint);
+ this.raycastClosestResult.hitNormal.set(nearest.hitNormal);
+ return true;
+ }
+}
diff --git a/sdk/tests/cocos/collider-wasm.test.ts b/sdk/tests/cocos/collider-wasm.test.ts
index 0b8c1e551..874ba920e 100644
--- a/sdk/tests/cocos/collider-wasm.test.ts
+++ b/sdk/tests/cocos/collider-wasm.test.ts
@@ -10,7 +10,7 @@ import { World } from '../../src/ecs/world';
import { Transform, ensureBuiltinComponentsRegistered } from '../../src/ecs/component';
import { AppContext, setDefaultContext } from '../../src/ecs/context';
import { BoxCollider3D, RigidBody3D } from '../../src/physics3d/Physics3DComponents';
-import { BoxCollider, Node, Vec3, setCurrentWorld } from '../../src/cocos';
+import { BoxCollider, Node, PhysicsSystem, Vec3, geometry, setCurrentWorld } from '../../src/cocos';
import { HAS_WASM, loadWasmModule } from '../helpers/loadWasm';
describe.skipIf(!HAS_WASM)('BoxCollider on the engine', () => {
@@ -64,3 +64,50 @@ describe.skipIf(!HAS_WASM)('BoxCollider on the engine', () => {
expect(c.isTrigger).toBe(true);
});
});
+
+describe.skipIf(!HAS_WASM)('PhysicsSystem on the engine', () => {
+ let module: ESEngineModule;
+ let registry: InstanceType<ESEngineModule['Registry']> | undefined;
+ let world: World | undefined;
+ beforeAll(async () => { ensureBuiltinComponentsRegistered(); module = await loadWasmModule(); });
+ afterEach(() => { setCurrentWorld(null); world?.disconnectCpp(); registry?.delete(); registry = undefined; world = undefined; });
+
+ function box(name: string, at: Vec3, size: Vec3, trigger = false): Node {
+ const n = new Node(name);
+ world!.insert(n._entity, Transform);
+ n.setPosition(at);
+ const c = n.addComponent(BoxCollider)!;
+ c.size = size;
+ c.isTrigger = trigger;
+ return n;
+ }
+
+ it('lists the boxes a ray crosses nearest first and names the face it met', () => {
+ setDefaultContext(new AppContext());
+ registry = new module.Registry(); world = new World(); world.connectCpp(registry, module); setCurrentWorld(world);
+ const far = box('far', new Vec3(0, 0, -10), new Vec3(2, 2, 2));
+ const near = box('near', new Vec3(0, 0, -4), new Vec3(2, 2, 2));
+ box('aside', new Vec3(8, 0, -4), new Vec3(2, 2, 2));
+ const ray = new geometry.Ray(0, 0, 0, 0, 0, -1);
+ expect(PhysicsSystem.instance.raycast(ray)).toBe(true);
+ const hits = PhysicsSystem.instance.raycastResults;
+ expect(hits.map((h) => h.collider.node.name)).toEqual(['near', 'far']);
+ expect(hits[0]!.distance).toBeCloseTo(3, 6);
+ expect(hits[0]!.hitPoint.z).toBeCloseTo(-3, 6);
+ expect(hits[0]!.hitNormal.z).toBeCloseTo(1, 6);
+ expect(PhysicsSystem.instance.raycastClosest(ray)).toBe(true);
+ expect(PhysicsSystem.instance.raycastClosestResult.collider.node).toBe(near);
+ expect(far).toBeTruthy();
+ });
+
+ it('skips triggers when asked not to, and boxes behind the origin or past the range', () => {
+ setDefaultContext(new AppContext());
+ registry = new module.Registry(); world = new World(); world.connectCpp(registry, module); setCurrentWorld(world);
+ box('trigger', new Vec3(0, 0, -4), new Vec3(2, 2, 2), true);
+ box('behind', new Vec3(0, 0, 6), new Vec3(2, 2, 2));
+ const ray = new geometry.Ray(0, 0, 0, 0, 0, -1);
+ expect(PhysicsSystem.instance.raycast(ray, 0xffffffff, 100, false)).toBe(false);
+ expect(PhysicsSystem.instance.raycast(ray, 0xffffffff, 2, true)).toBe(false);
+ expect(PhysicsSystem.instance.raycast(ray, 0xffffffff, 100, true)).toBe(true);
+ });
+});