Docs

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

Type Name Langs
Vector3 origin C++ | Lua
Vector3 direction C++ | Lua

Methods

Type Name Langs
Vector3 getPoint C++ | Lua
RayReturn intersects C++ | Lua

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. A ray that starts inside a 2D shape doesn't hit that shape, in these overloads and in BODY_2D scene queries, so a ray cast from inside a shooter reaches what is in front of it.

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. Layers go from 0 to 5 (MAX_BROADPHASELAYER_3D is 6); a higher one returns no hit.

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.