Geometría de zonas

Un área del mundo es un ZoneShape: una esfera, un cilindro o un polígono en el suelo entre dos alturas. La clase Zones del cliente (callbacks de entrada y salida, consulta Zonas) usa estas formas; las utilidades de esta página son las matemáticas simples que hay detrás, sin natives, para que el servidor pueda comprobar la misma área (¿está el jugador de verdad dentro de la tienda antes de venderle?).

import { zoneContains, zoneBounds, polyFromCorners, readZoneShape, type ZoneShape } from "@aicore-fivem/lib/shared";

Lua: ninguna de estas tiene equivalente en Lua. Las zonas en Lua son aiLib.Zones.new() en el cliente (consulta Zonas).

zoneContainsCopy Anchor Link

Si un punto está dentro de una forma de zona.

Lado: Cliente, servidor y NUI · Espera: no

zoneContains(shape: ZoneShape, x: number, y: number, z: number): boolean

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

true cuando el punto está dentro (en el borde cuenta como dentro para esferas y cilindros). Para un cilindro, el punto también debe estar a menos de height metros por encima o por debajo del centro. Para un polígono, z debe estar entre minZ y maxZ.

EjemploCopy Anchor Link

import { coordsOf, onClientCallback } from "@aicore-fivem/lib/server";
import { fail, zoneContains, type ZoneShape } from "@aicore-fivem/lib/shared";

const shop: ZoneShape = { type: "cylinder", center: { x: 25.7, y: -1347.3, z: 29.5 }, radius: 6, height: 3 };

onClientCallback("my-shop:open", (source) => {
  const { x, y, z } = coordsOf(source);
  if (!zoneContains(shop, x, y, z)) return fail("TOO_FAR");
  return { ok: true };
});

zoneBoundsCopy Anchor Link

La caja delimitadora en el suelo de una forma: el rectángulo más pequeño (x / y) que la contiene. Úsalo para una primera comprobación barata, o para colocar una zona en celdas de una cuadrícula.

Lado: Cliente, servidor y NUI · Espera: no

zoneBounds(shape: ZoneShape): [minX: number, minY: number, maxX: number, maxY: number]

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

[minX, minY, maxX, maxY] en metros. Para una esfera o un cilindro: el centro más y menos el radio.

EjemploCopy Anchor Link

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

zoneBounds({ type: "sphere", center: { x: 100, y: 200, z: 30 }, radius: 10 }); // [90, 190, 110, 210]

polyFromCornersCopy Anchor Link

Convierte las esquinas que guarda el widget zone del panel en una forma de polígono. El rango de alturas va de la z más baja a la más alta de las esquinas, ampliado height metros hacia arriba y hacia abajo.

Lado: Cliente, servidor y NUI · Espera: no

polyFromCorners(corners: readonly Vec3[], height: number): { type: "poly"; points: Array<{ x: number; y: number }>; minZ: number; maxZ: number } | null

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

El ZoneShape poly, o null con menos de tres esquinas.

EjemploCopy Anchor Link

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

const lot = polyFromCorners(
  [ { x: 210, y: -810, z: 30 }, { x: 240, y: -800, z: 31 }, { x: 230, y: -770, z: 32 } ],
  3,
);
// { type: "poly", points: [...], minZ: 27, maxZ: 35 }

readZoneShapeCopy Anchor Link

Comprueba una forma de zona que viene de otro recurso o de un archivo: todos los números finitos, un polígono con al menos tres puntos. Úsalo en una forma pasada a uno de tus exports.

Lado: Cliente, servidor y NUI · Espera: no

readZoneShape(value: unknown): ZoneShape | null

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

Un ZoneShape limpio (sin campos extra), o null cuando no es una esfera, un cilindro o un polígono válido.

EjemploCopy Anchor Link

import { registerExport } from "@aicore-fivem/lib/server";
import { readZoneShape, type ZoneShape } from "@aicore-fivem/lib/shared";

const noParking = new Map<string, ZoneShape>();

registerExport("AddNoParkingZone", (id: unknown, raw: unknown) => {
  const shape = readZoneShape(raw);
  if (typeof id !== "string" || !shape) return false;
  noParking.set(id, shape);
  return true;
});