Problem Statement

Performing a raycast requires reaching deep into Jolt internals — constructing raw JPH::RRayCast and JPH::RayCastResult objects and calling physicsSystem.GetNarrowPhaseQuery().CastRay(...). This is verbose, unintuitive, and leaks Jolt implementation details into user code. Flagged in ES-Factoria src/system/SetupClickOnPlanet.cpp:

// TODO: give a better API to do raycast, it's really not intuitive
bool hitFound = physicsSystem.GetNarrowPhaseQuery().CastRay(jphRay, hit);

Proposed Solution

Expose a high-level raycast API on Physics::Resource::PhysicsManager (or equivalent) that works entirely with engine-native types:

auto hit = physicsManager.Raycast(origin, direction, maxDistance);
if (hit) { /* hit->entity, hit->position, hit->fraction */ }

Alternative Solutions

• Provide thin type-conversion helpers (ToJolt(vec), FromJolt((JPH)vec)) without wrapping the query — reduces boilerplate slightly but still exposes Jolt types.
• Keep the raw Jolt API and document it well — no effort required but every project writes the same low-level code.

Use Cases

• Use case 1: A click-to-select system performs a raycast in two lines using glm::vec3 without knowing about Jolt.
• Use case 2: Any AI or gameplay system that needs line-of-sight checks benefits from the same clean API.

Impact

• No performance implications (same underlying Jolt call).
• New methods added to the Physics plugin's public API.
• No breaking changes to existing direct Jolt usage.

Implementation Details (optional)

• Add std::optional<RaycastHit> PhysicsManager::Raycast(glm::vec3 origin, glm::vec3 direction, float maxDistance).
• RaycastHit contains Engine::Entity entity, glm::vec3 position, float fraction.
• Internally converts to/from Jolt types and resolves BodyID to Entity (see [FEATURE] Internalize Jolt BodyID ↔ Entity mapping inside the Physics plugin #496 ).

Additional Context

Spotted via a // TODO audit of the ES-Factoria demo project.

Related Issues

• [FEATURE] Provide a built-in utility to create a world-space ray from a screen-space click #494
• [FEATURE] Internalize Jolt BodyID ↔ Entity mapping inside the Physics plugin #496