Problem Statement

Every project using physics must manually maintain a PhysicsBodyToEntityMap resource — a bidirectional map between Jolt BodyIDs and engine Entity handles — to resolve which entity was hit by a raycast or collision event. This is error-prone boilerplate that belongs inside the Physics plugin. Flagged in ES-Factoria src/system/SetupClickOnPlanet.cpp:

// TODO: avoid to use a bidirectional map to handle jph types/world with core entities
const auto &physicsBodyToEntityMap = core.GetResource<Factoria::PhysicsBodyToEntityMap>();

Proposed Solution

Internalize the BodyID ↔ Entity mapping inside the Physics plugin itself (e.g., maintained automatically by PhysicsManager whenever a RigidBody or collider component is created/destroyed), and expose a lookup method: physicsManager.GetEntity(bodyID).

Alternative Solutions

• Provide the map as a built-in engine resource rather than a user-defined one — reduces duplication but still requires the user to remember to register and synchronize it.
• Use a Jolt BodyInterface user-data field to store the Entity handle directly — elegant, zero extra allocation, no separate map needed.

Use Cases

• Use case 1: A raycast result returns an Engine::Entity directly, with no external map lookup needed by the caller.
• Use case 2: Collision callbacks receive entity handles without any extra infrastructure.

Impact

• Simplifies the Physics plugin's public API significantly.
• Projects using physics no longer need to register or maintain PhysicsBodyToEntityMap.
• Potential minor memory overhead for the internal map, but negligible for typical scene sizes.

Implementation Details (optional)

• Store entt::entity (or Engine::Entity) in the Jolt body's user-data field when the body is created.
• Expose Engine::Entity PhysicsManager::GetEntity(JPH::BodyID) for internal plugin use, and surface it via higher-level APIs (e.g., RaycastHit::entity).
• Remove the need for PhysicsBodyToEntityMap in ES-Factoria as a validation step.

Additional Context

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

Related Issues

• [FEATURE] Provide a more intuitive high-level raycast API in the Physics plugin #495