Ray casting

Ray casting is a technique to identify collisions of a ray from one point to another in 3D space. This can be useful to for example test if a character is in line of sight of another character or get the hit point of a bullet shot from a gun.

Ray test

The physics system has a method called rayTest which allows you to calculate collisions of a ray between two points.

import { Service, inject, PhysicsSystem, RayTestResult } from "@hology/core/gameplay"
import { Vector3 } from "three"

@Service()
class ExampleService {
    private physics = inject(PhysicsSystem)
    
    checkCollisions() {
        const result = new RayTestResult()
        const from = new Vector3(0,0,0)
        const to = new Vector3(0,0,100)
        this.physics.rayTest(from, to, result)
        
        console.log(result)
    }
}

export default ExampleService

Parameters

• from: Vector3 - The starting point of the ray

• to: Vector3 - The ending point of the ray.

• result: RayTestResult - An object in which to store the result of the ray. If you are doing a lot of ray casting, it is often best to reuse the RayTestResult object to avoid garbage collection and improving the performance of your code.

• options: RayTestOptions - Options to change the behaviour or debug of the ray testing.

RayTestResult

• hasHit: boolean - Whether the ray hit an object.

• hitPoint: Vector3 - The point in global space in which the ray hit

• hitNormal: Vector3 - The normal of the surface hit

• distance: number - The distance to the hit point from the start of the ray.

• actor: BaseActor - If the hit object is an actor, this field will reference the actor instance.

RayTestOptions

• debugColor: ColorRepresentation - If you have enabled the debug mode of the physics system, it will show an arrow for the ray. Use this option to change the color of the arrow to more easily distinguish it from others.

• debugLifetime: number - How many milliseconds the arrow should be visible. If you are doing a lot of raytesting.

• excludeActor: BaseActor - It is sometimes necessary to exclude some actor from collisions. Often it could be the actor from which the ray should be starting from to avoid colliding with the actor itself.