World Queries

Queries ask the world a question and answer at once, inside the native. They see the same bodies the simulation does: the map, physics objects, static objects, players on foot, vehicles and actors.

Question	Natives
What does a segment hit?	A3D_RayCast, A3D_RayCastNormal, A3D_RayCastAll
Is the way clear?	A3D_IsLineOfSight
Where is the ground?	A3D_FindGround, A3D_FindRandomPoint
Where does something with a size stop?	A3D_SweepSphere, A3D_PredictTrajectory
What is inside a shape?	A3D_OverlapSphere, A3D_OverlapBox, A3D_OverlapModel, A3D_IsModelColliding
Who is around?	A3D_GetPlayersInSphere, A3D_GetPlayersInCone, A3D_GetVehiclesInSphere, A3D_GetActorsInSphere, A3D_GetActorsInCone
What does a player look at?	A3D_GetPlayerTarget, A3D_GetScreenTarget
Is a point inside the map?	A3D_IsPointInsideMap

What a query may hit

flags picks the kinds of body a query sees. See Collision flags.

• Rays, sweeps and overlaps see A3D_COLLIDE_ALL by default: the map, physics objects, static objects, players, vehicles and actors.
• A3D_IsLineOfSight and A3D_FindGround see the map and static objects by default.
• The water counts only with A3D_COLLIDE_WATER. Rays then stop at its surface. Without it they reach the bottom.

worldid picks the virtual world. -1 sees the bodies of every world. A world sees its own bodies and those of every world, and misses the map objects removed in it with A3D_RemoveBuilding.

How bodies are hit

• The collision of the game is one sided, so the faces of the map are hit from both sides. A ray from inside a building meets its walls.
• Spheres, boxes, capsules and the boxes of vehicles are solid. A ray that starts inside one leaves it unseen, which lets a ray start at the position of a player without hitting that player. Overlaps find them whenever they touch the shape.
• Zones are never hit.
• Players are capsules only while they are on foot. A player in a vehicle is inside the box of the vehicle.

The answer

A hit gives the point, what was hit and its surface. Some natives also give the normal of the surface, which faces the start of the query.

type	hitid
A3D_HIT_MAP	The model of the map object
A3D_HIT_OBJECT	The physics object
A3D_HIT_STATIC	The static object
A3D_HIT_PLAYER	The player
A3D_HIT_VEHICLE	The vehicle
A3D_HIT_WATER	0
A3D_HIT_ACTOR	The actor

material is the surface of the game at the point, from 0 to 178. Players and actors carry PED, vehicles CAR, spheres and boxes of scripts DEFAULT, and the water 0. See Hit types and Surfaces.

Precision

Points are exact to a millimetre across the whole map. Jolt solves the hit on a round shape in single precision, which strays by about a centimetre on a ray more than a kilometre long, so a hit on a sphere, a capsule or a cylinder more than 50 metres away is cast again over two metres around it.

Cost

Query	Time per call
A ray of 100 metres	1.6 µs
A line of sight of 100 metres	1.4 µs
The ground under a point	1.8 µs
A ray that returns every hit	9 µs
A model collision test	2 µs
A cone of players with sight	2.4 µs
A throw that lands 60 metres away	60 µs

Measured on one computer. See Performance.