A3D_RayCast

Find the first thing a segment between two points hits.

The map is hit from both sides of its surfaces, since the collision of the game is one sided. Zones are never hit, players only on foot, and a segment that starts inside a box, a sphere, a player or a vehicle leaves it unseen.

native bool:A3D_RayCast(
    Float:startX,
    Float:startY,
    Float:startZ,
    Float:endX,
    Float:endY,
    Float:endZ,
    &Float:x,
    &Float:y,
    &Float:z,
    &A3D_HIT:type = A3D_HIT_MAP,
    &hitid = 0,
    &material = 0,
    worldid = -1,
    A3D_COLLIDE:flags = A3D_COLLIDE_ALL
);

Parameters

Parameter	Description	Default
Float:startX	Start of the segment on the X axis.
Float:startY	Start on the Y axis.
Float:startZ	Start on the Z axis.
Float:endX	End of the segment on the X axis.
Float:endY	End on the Y axis.
Float:endZ	End on the Z axis.
&Float:x	Point hit on the X axis.
&Float:y	Point hit on the Y axis.
&Float:z	Point hit on the Z axis.
&A3D_HIT:type	What was hit.	A3D_HIT_MAP
&hitid	Model of the map object, or the physics object, static object, player, vehicle or actor hit.	0
&material	Surface of the game hit, see A3D_GetMaterialName.	0
worldid	Virtual world to look in, or -1 for every world.	-1
A3D_COLLIDE:flags	What the segment may hit.	A3D_COLLIDE_ALL

Returns

• true when something was hit.
• false when the segment is clear.

Remarks

The segment is followed from its start to its end and the nearest hit is kept. World queries covers what every query shares. In short:

• The map is hit from both sides of its faces, so a ray cast from inside a building meets its walls. Spheres, boxes, players, vehicles and actors are hit from outside only, so a ray that starts inside a player leaves the player unseen.
• hitid is the model of a map object, the id of a physics object or a static object, or the id of the player, vehicle or actor hit. See Hit types.
• material is the surface of the game hit, from 0 to 178. See Surfaces.
• The water stops the ray only when flags holds A3D_COLLIDE_WATER. A hit on the water gives A3D_HIT_WATER with 0 as its id and its surface.
• Zones are never hit, and players only while they are on foot. A player in a vehicle is inside its box.

A ray of 100 metres costs about 1.6 microseconds. See Performance.

Example

Tells a player what stands in front of them.

public OnPlayerCommandText(playerid, cmdtext[]) {
    if (strcmp(cmdtext, "/ahead", true) == 0) {
        new
            Float:x,
            Float:y,
            Float:z,
            Float:angle,
            Float:hitX,
            Float:hitY,
            Float:hitZ,
            A3D_HIT:type,
            hitid,
            material,
            message[128]
        ;

        GetPlayerPos(playerid, x, y, z);
        GetPlayerFacingAngle(playerid, angle);

        if (!A3D_RayCast(x, y, z + 0.5, x - 50.0 * floatsin(angle, degrees), y + 50.0 * floatcos(angle, degrees), z + 0.5, hitX, hitY, hitZ, type, hitid, material, GetPlayerVirtualWorld(playerid))) {
            SendClientMessage(playerid, -1, "Nothing within 50 metres ahead.");

            return 1;
        }

        format(message, sizeof (message), "Something of type %i with id %i stands %.1f metres ahead.", _:type, hitid, GetPlayerDistanceFromPoint(playerid, hitX, hitY, hitZ));
        SendClientMessage(playerid, -1, message);

        return 1;
    }

    return 0;
}

Related

• A3D_RayCastNormal: Find the first thing a segment hits, and the direction its surface faces there.
• A3D_RayCastAll: Find everything a segment hits, nearest first.
• A3D_IsLineOfSight: Whether nothing stands between two points.
• A3D_FindGround: Find the ground under a point.
• A3D_SweepSphere: Move a sphere along a segment and find where it first touches something.