Posições

Matemática com pontos escritos como objetos simples (Vec3: { x, y, z } em metros). Não precisam de natives, então o mesmo código roda no servidor, no cliente e em uma página NUI.

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

distanceCopy Anchor Link

A distância em linha reta entre dois pontos, em metros.

Lado: Cliente, servidor e NUI · Espera: não

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

Lua: sem equivalente; use #(a - b) com dois vector3.

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

number: metros, 0 ou mais.

ExemploCopy 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

A distância no plano do chão, ignorando a altura (só x e y), em metros. Use para áreas em que a altura não importa (um estacionamento em uma ladeira, o raio de um blip).

Lado: Cliente, servidor e NUI · Espera: não

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

Lua: sem equivalente; use #(a.xy - b.xy).

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

number: metros no plano do chão.

ExemploCopy 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

O heading que olha de um ponto em direção a outro, na convenção do GTA: 0-360 graus, 0 = norte, sentido anti-horário. Use para virar um ped ou uma câmera para algo.

Lado: Cliente, servidor e NUI · Espera: não

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

local heading = aiLib.numbers.headingTo(from, to) -- vector3 ou tabelas { x, y }

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

number: um heading de 0 até 360 (sem incluir 360).

ExemploCopy 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

O item de uma lista mais próximo de um ponto (distância 3D), dentro de um alcance opcional. Funciona para qualquer lista: você diz como ler a posição de um item.

Lado: Cliente, servidor e NUI · Espera: não

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

Lua: sem equivalente.

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

O item mais próximo, ou undefined quando a lista está vazia ou todo item está mais longe que max.

ExemploCopy 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

A célula inteira da grade em que um ponto cai, em uma grade de quadrados de size metros. O streaming por área da lib (AreaStream no servidor, AreaFollower no cliente) a usa, para que os dois lados concordem sobre em qual célula um ponto está. As células são limitadas a mais ou menos 16.000.

Lado: Cliente, servidor e NUI · Espera: não

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

Lua: sem equivalente.

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

{ cx, cy }: a coluna e a linha da célula.

ExemploCopy 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

Um número para uma célula da grade, pequeno o bastante para ser uma chave rápida de Map (abaixo de 2^30).

Lado: Cliente, servidor e NUI · Espera: não

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

Lua: sem equivalente.

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

number: o mesmo número para a mesma célula, em todos os lados.

ExemploCopy 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]);
}