Guides Physics 3D Use 3D Physics Queries

Physics 3D 1 min read Updated Aug 2026

Use 3D Physics Queries

Queries ask the physics world a question immediately.

Use them when you do not want to wait for a collision callback.

Good Fits

Use Physics3D queries for:

  • obstacle probes
  • ground checks
  • interaction ranges
  • line-of-sight checks
  • click or cursor picking

Raycast for the First Hit

A raycast is the simplest query: it checks the first thing along a line.

use Lenga\Engine\Core\Physics3D;

$hit = Physics3D::raycast(
    $this->transform->position,
    $this->transform->forward,
    5.0,
    false
);

if ($hit !== null) {
    Debug::info('Hit ' . ($hit->gameObject?->name ?? 'Unknown'));
}

Use raycasts for forward checks, targeting, and line-of-sight tests.

Use Overlaps for Volumes

Use overlap queries when you need everything inside a volume instead of one hit along a line.

Good examples:

  • enemies inside an explosion radius
  • pickups near the player
  • objects inside an interaction area
  • spawn points that must be clear before use

Keep Queries Focused

When a query starts returning too much, narrow it with a layer mask or by excluding triggers.

That keeps gameplay code simpler because the query only returns objects it actually cares about.

Next Guides