Client API

Distance & Proximity

The #(GetEntityCoords(playerPed) - GetEntityCoords(ped)) < X check shows up in nearly every encounter file in wc_encounter. These four functions are that pattern, named.

GetDistance(a, b)client

Actual 3D distance between two points.

Param	Type
a, b	vector3 \| {x,y,z}

SquaredDistance(ax, ay, az, bx, by, bz)client

Squared 3D distance — skips the sqrt call. Use this in hot loops where you only need to compare against a squared radius.

IsNearCoords(point, center, radius)client

Whether point is within radius of center. Uses the squared comparison internally.

IsPlayerNearCoords(center, radius)client

Convenience wrapper — checks the local player ped against center without you writing GetEntityCoords(PlayerPedId()) at every call site.

before — repeated across 8 encounter files

local dist = #(GetEntityCoords(PlayerPedId()) - GetEntityCoords(ped))
if dist < 3.5 then ... end

after

if wc:IsPlayerNearCoords(GetEntityCoords(ped), 3.5) then ... end

Real Wild County example — admin "nearby suspects" utility

wc_admin/client/main.lua

local suspects = {}
for _, ped in ipairs(GetGamePool('CPed')) do
  if wc:IsPlayerNearCoords(GetEntityCoords(ped), 15.0) then
    suspects[#suspects + 1] = ped
  end
end

Common mistakes

Calling GetDistance (which does a sqrt) inside a tight per-frame loop over many entities — use SquaredDistance + a squared radius comparison instead when you don't need the actual distance value.
Passing entity handles directly instead of coordinates — these functions take vector3/{x,y,z} points, not entities. Call GetEntityCoords(entity) first.
Re-implementing this exact math inline in a new resource instead of reusing these — that's the duplicated pattern this module was extracted to remove.

Troubleshooting

If IsNearCoords gives unexpected results near a bridge/cliff: remember it's true 3D distance including vertical separation — a point directly below or above still counts as "near" if within the spherical radius.
If results look wrong for one axis only: confirm both points use the same coordinate space (world coords) — mixing local/relative offsets with world coords will produce nonsense distances.

← backPeds, horses & props next →Framework & Raw