Ray¶

C++ type: Ray

Description¶

A ray defined by an origin point and a direction/length vector. Used for raycasting — detecting which objects lie along the ray. Doriax supports raycasts against geometric volumes (AABB, OBB, Sphere, Plane), against the physics simulation (Body2D / Body3D), and against the bounds of every mesh in a scene, which needs no physics at all.

The direction vector doubles as the length of the ray — objects beyond origin + direction are not reported as hits.

Properties¶

Methods¶

Property details¶

origin / direction¶

• Setter: void setOrigin(Vector3 point) / void setDirection(Vector3 direction)
• Getter: Vector3 getOrigin() const / Vector3 getDirection() const

origin is the start of the ray. direction is both the normalised direction and the maximum reach (its magnitude = ray length). Use Camera::screenToRay() to generate a ray from a screen pixel.

Method details¶

getPoint¶

• Vector3 getPoint(float distance) const

Returns origin + direction * distance. Hits report distance as a fraction of the ray, from 0 at origin to 1 at origin + direction, so getPoint(hit.distance) is the hit point.

intersects¶

Multiple overloads for different collision targets:

• RayReturn intersects(const Plane& plane) const
• RayReturn intersects(const AABB& box) const
• RayReturn intersects(const OBB& obb) const
• RayReturn intersects(const Sphere& sphere) const
• RayReturn intersects(const Body2D& body) const
• RayReturn intersects(const Body2D& body, size_t shape) const
• RayReturn intersects(const Body3D& body) const
• RayReturn intersects(const Body3D& body, size_t shape) const
• RayReturn intersects(Scene* scene, RayFilter raytest) const
• RayReturn intersects(Scene* scene, RayFilter raytest, bool onlyStatic) const
• RayReturn intersects(Scene* scene, RayFilter raytest, uint16_t categoryBits, uint16_t maskBits) const
• RayReturn intersects(Scene* scene, RayFilter raytest, bool onlyStatic, uint16_t categoryBits, uint16_t maskBits) const
• RayReturn intersects(Scene* scene, RayFilter raytest, Entity ignoreEntity) const
• RayReturn intersects(Scene* scene, RayFilter raytest, const std::vector\<Entity>& ignoreEntities) const
• RayReturn intersects(Scene* scene, RayFilter raytest, bool onlyStatic, uint16_t categoryBits, uint16_t maskBits, Entity ignoreEntity) const
• RayReturn intersects(Scene* scene, RayFilter raytest, bool onlyStatic, uint16_t categoryBits, uint16_t maskBits, const std::vector\<Entity>& ignoreEntities) const
• RayReturn intersects(Scene* scene, uint8_t broadPhaseLayer3D) const
• RayReturn intersects(Scene* scene, uint8_t broadPhaseLayer3D, uint16_t categoryBits, uint16_t maskBits) const
• RayReturn intersects(Scene* scene, uint8_t broadPhaseLayer3D, Entity ignoreEntity) const
• RayReturn intersects(Scene* scene, uint8_t broadPhaseLayer3D, const std::vector\<Entity>& ignoreEntities) const
• RayReturn intersects(Scene* scene, uint8_t broadPhaseLayer3D, uint16_t categoryBits, uint16_t maskBits, Entity ignoreEntity) const
• RayReturn intersects(Scene* scene, uint8_t broadPhaseLayer3D, uint16_t categoryBits, uint16_t maskBits, const std::vector\<Entity>& ignoreEntities) const

Returns a RayReturn struct. Test the result with if (result) or result.hit.

The Body2D overload returns the closest hit among the body's shapes. Both Body2D overloads return no hit for a body that is not in the physics world yet, and the shape overload also for an index past the body's shapes.

Scene queries return the closest hit. RayFilter only selects what is tested — 2D bodies, 3D bodies or mesh bounds — it does not skip a specific entity. Checking hit.body == entity after the fact also fails, because that body is already the closest hit and the ray never continues past it. Pass the entity (or a list of entities) to intersects so those bodies are ignored and the next hit is returned. This works with every filter.

The uint8_t broadPhaseLayer3D overloads test 3D bodies on one broad-phase layer only.

The Body2D overloads exist only when the build has 2D physics, and the Body3D and broadPhaseLayer3D ones only with 3D physics — see Project Settings → Physics backends. A BODY_2D or BODY_3D query against a disabled backend returns no hit.

// Screen-to-world raycast, skipping this script's own body
Ray ray = camera.screenToRay(mouseX, mouseY);
RayReturn hit = ray.intersects(scene, RayFilter::BODY_3D, entity);
if (hit) {
    Log::print("Hit body at distance: " + std::to_string(hit.distance));
}

// Ignore several bodies
RayReturn hit2 = ray.intersects(scene, RayFilter::BODY_3D, std::vector<Entity>{entity, other});

-- Screen-to-world raycast, skipping this script's own body
local ray = camera:screenToRay(mouseX, mouseY)
local hit = ray:intersects(scene, RayFilter.BODY_3D, self.entity)
if hit.hit then
    Log.print("Hit at " .. tostring(hit.distance))
end

-- Ignore several bodies
local hit2 = ray:intersects(scene, RayFilter.BODY_3D, {self.entity, other.entity})

Enumerations¶

RayFilter¶

Selects what a scene raycast tests. Use a separate ignoreEntity / ignoreEntities argument to skip specific entities.

• BODY_2D — Test against Body2D physics bodies.
• BODY_3D — Test against Body3D physics bodies.
• BOUNDS — Test against the world-space AABB of every mesh — models, shapes, sprites, tilemaps and terrain. Needs no physics backend. The hit is the box, not the surface, so it is coarser than a collider cast; body holds the mesh entity and normal the face of the box that was hit (zero when the ray starts inside a box, which hits at distance 0). onlyStatic and the category/mask bits are ignored.