Posiciones

Matemáticas sobre puntos escritos como objetos simples (Vec3: { x, y, z } en metros). No necesitan natives, así que el mismo código funciona en el servidor, en el cliente y en una página NUI.

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

distanceCopy Anchor Link

La distancia en línea recta entre dos puntos, en metros.

Lado: Cliente, servidor y NUI · Espera: no

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

Lua: sin equivalente; usa #(a - b) con dos vector3.

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

number: metros, 0 o más.

EjemploCopy 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

La distancia sobre el plano del suelo, ignorando la altura (solo x e y), en metros. Úsalo para áreas en las que la altura no importa (un aparcamiento en cuesta, el radio de un blip).

Lado: Cliente, servidor y NUI · Espera: no

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

Lua: sin equivalente; usa #(a.xy - b.xy).

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

number: metros sobre el plano del suelo.

EjemploCopy 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

El heading que mira desde un punto hacia otro, con la convención de GTA: 0-360 grados, 0 = norte, en sentido antihorario. Úsalo para girar un ped o una cámara hacia algo.

Lado: Cliente, servidor y NUI · Espera: no

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

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

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

number: un heading desde 0 hasta 360 (sin incluirlo).

EjemploCopy 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

El elemento de una lista más cercano a un punto (distancia 3D), dentro de un alcance opcional. Funciona con cualquier lista: tú le dices cómo leer la posición de un elemento.

Lado: Cliente, servidor y NUI · Espera: no

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

Lua: sin equivalente.

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

El elemento más cercano, o undefined cuando la lista está vacía o todos los elementos están más lejos que max.

EjemploCopy 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

La celda entera de la cuadrícula en la que cae un punto, en una cuadrícula de cuadrados de size metros. El streaming por áreas de la lib (AreaStream en el servidor, AreaFollower en el cliente) la usa, así que ambos lados coinciden en qué celda está un punto. Las celdas se limitan a más o menos 16.000.

Lado: Cliente, servidor y NUI · Espera: no

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

Lua: sin equivalente.

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

{ cx, cy }: la columna y la fila de la celda.

EjemploCopy 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

Un único número para una celda de la cuadrícula, lo bastante pequeño para ser una clave rápida de Map (por debajo de 2^30).

Lado: Cliente, servidor y NUI · Espera: no

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

Lua: sin equivalente.

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

number: el mismo número para la misma celda, en todos los lados.

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