I would like to request a supported client-side API for querying collision geometry that is currently streamed into the game.
This would be useful for custom movement controllers, procedural locomotion, geometry-aware interactions, and collision debugging.
Existing shape tests provide hit positions, surface normals, materials, and entity handles. However, they do not expose the surrounding collision geometry. Features that need to examine adjacent surfaces, identify edges, or build a local collision representation cannot reliably recover that information from individual raycasts.
A useful starting point would be a read-only query within a bounded region, such as an AABB or a radius around a position. It should include loaded static world collision, including geometry that has no script entity handle, and work with custom streamed maps.
The most useful data would be:
- Triangle vertices and indices, with documented winding and coordinate space. Either world-space vertices or local vertices with the complete instance transform would work.
- Composite shape transforms, so nested collision shapes can be positioned correctly.
- Collision categories and filtering information, or query filters that distinguish collision relevant to characters from weapon-only, camera-only, or other collision categories.
- Material identifiers for individual triangles or shapes, using a documented representation.
- Primitive collision shapes, such as boxes, spheres, and capsules, returned as typed shape data or a documented triangulated approximation.
- Instance identity and cache invalidation information, allowing a resource to detect when nearby collision has streamed out, been replaced, or changed.
For performance, the API could use asynchronous queries or bounded batches, with limits on the region size and amount of returned geometry. Explicit loading, incomplete-result, and invalidation states would help resources handle streaming correctly. Opaque identifiers and copied snapshots would provide a practical interface without exposing internal memory addresses.
Support for static world collision alone would already be valuable as an initial implementation. Entity-associated collision geometry could follow, with an entity handle where available and transforms that can be refreshed independently of the mesh.
Offline extraction requires maintaining a separate geometry dataset and accounting for custom maps and map changes. A query against the client’s currently loaded collision would let resources work with the scene that is actually present.
FiveM already contains internal collision structures and geometry processing in phBound.h. A supported scripting interface would still need careful handling of streaming lifetimes, data consistency, and performance.