Positions

Math on points written as plain objects (Vec3: { x, y, z } in metres). They need no natives, so the same code runs on the server, the client and in a NUI page.

import { distance, flatDistance, headingTo, nearestOf, gridCell, cellKey } from "@aicore-fivem/lib/shared";

distanceCopy Anchor Link

The straight distance between two points, in metres.

Side: Client, server and NUI · Waits: no

distance(a: Vec3, b: Vec3): number

Lua: no twin; use #(a - b) with two vector3s.

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

number: metres, 0 or more.

ExampleCopy Anchor Link

import { coordsOf } from "@aicore-fivem/lib/server";
import { distance } from "@aicore-fivem/lib/shared";

const counter = { x: 25.7, y: -1347.3, z: 29.5 };

function nearCounter(source: number): boolean {
  return distance(coordsOf(source), counter) <= 3;
}

flatDistanceCopy Anchor Link

The distance on the ground plane, ignoring height (only x and y), in metres. Use it for areas where height does not matter (a parking lot on a slope, a blip radius).

Side: Client, server and NUI · Waits: no

flatDistance(a: { x: number; y: number }, b: { x: number; y: number }): number

Lua: no twin; use #(a.xy - b.xy).

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

number: metres on the ground plane.

ExampleCopy Anchor Link

import { flatDistance } from "@aicore-fivem/lib/shared";

flatDistance({ x: 0, y: 0, z: 0 }, { x: 3, y: 4, z: 50 }); // 5

headingToCopy Anchor Link

The heading that faces from one point towards another, in GTA's convention: 0-360 degrees, 0 = north, counter-clockwise. Use it to turn a ped or a camera toward something.

Side: Client, server and NUI · Waits: no

headingTo(from: { x: number; y: number }, to: { x: number; y: number }): number

local heading = aiLib.numbers.headingTo(from, to) -- vector3s or { x, y } tables

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

number: a heading from 0 up to (not including) 360.

ExampleCopy Anchor Link

import { cache, player } from "@aicore-fivem/lib/client";
import { headingTo } from "@aicore-fivem/lib/shared";

const counter = { x: 25.7, y: -1347.3, z: 29.5 };
SetEntityHeading(cache.ped, headingTo(player.coords(), counter));

nearestOfCopy Anchor Link

The item of a list nearest to a point (3D distance), within an optional range. Works for any list: you tell it how to read an item's position.

Side: Client, server and NUI · Waits: no

nearestOf<T>(items: Iterable<T>, point: Vec3, pos: (item: T) => Vec3, max?: number): T | undefined

Lua: no twin.

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

The nearest item, or undefined when the list is empty or every item is farther than max.

ExampleCopy Anchor Link

import { coordsOf } from "@aicore-fivem/lib/server";
import { nearestOf, type Vec3 } from "@aicore-fivem/lib/shared";

const atms: Array<{ id: string; coords: Vec3 }> = [
  { id: "legion", coords: { x: 147.4, y: -1035.8, z: 29.3 } },
  { id: "pillbox", coords: { x: 296.2, y: -591.6, z: 43.3 } },
];

function atmNear(source: number) {
  return nearestOf(atms, coordsOf(source), (atm) => atm.coords, 2);
}

gridCellCopy Anchor Link

The integer grid cell a point falls in, on a grid of size-metre squares. The lib's area streaming (AreaStream on the server, AreaFollower on the client) uses it, so both sides agree on which cell a point is in. Cells are clamped to plus or minus 16,000.

Side: Client, server and NUI · Waits: no

gridCell(x: number, y: number, size: number): { cx: number; cy: number }

Lua: no twin.

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

{ cx, cy }: the cell's column and row.

ExampleCopy Anchor Link

import { gridCell, cellKey } from "@aicore-fivem/lib/shared";

const { cx, cy } = gridCell(147.4, -1035.8, 100); // { cx: 1, cy: -11 }
const key = cellKey(cx, cy);

cellKeyCopy Anchor Link

One number for a grid cell, small enough to be a fast Map key (below 2^30).

Side: Client, server and NUI · Waits: no

cellKey(cx: number, cy: number): number

Lua: no twin.

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

number: the same number for the same cell, on every side.

ExampleCopy Anchor Link

import { gridCell, cellKey } from "@aicore-fivem/lib/shared";

const byCell = new Map<number, string[]>();

function addSign(id: string, x: number, y: number): void {
  const { cx, cy } = gridCell(x, y, 100);
  const key = cellKey(cx, cy);
  byCell.set(key, [...(byCell.get(key) ?? []), id]);
}