Geometria de zonas

Uma área no mundo é um ZoneShape: uma esfera, um cilindro ou um polígono no chão entre duas alturas. A classe Zones do cliente (callbacks de entrada e saída, veja Zonas) usa essas formas; os helpers desta página são a matemática simples por trás dela, sem natives, para que o servidor possa verificar a mesma área (o jogador está mesmo dentro da loja antes de ela vender?).

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

Lua: nenhum destes tem equivalente em Lua. As zonas em Lua são aiLib.Zones.new() no cliente (veja Zonas).

zoneContainsCopy Anchor Link

Se um ponto está dentro de uma forma de zona.

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

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

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

true quando o ponto está dentro (na borda conta como dentro para esferas e cilindros). Para um cilindro, o ponto também precisa estar a até height metros acima ou abaixo do centro. Para um polígono, z precisa estar entre minZ e maxZ.

ExemploCopy 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

A caixa delimitadora no chão de uma forma: o menor retângulo (x / y) que a contém. Use para uma primeira verificação barata, ou para colocar uma zona em células de grade.

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

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

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

[minX, minY, maxX, maxY] em metros. Para uma esfera ou um cilindro: o centro mais e menos o raio.

ExemploCopy 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

Transforma os cantos que o widget zone do painel salva em uma forma de polígono. A faixa de altura vai do z mais baixo ao mais alto dos cantos, ampliada em height metros para cima e para baixo.

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

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

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

O ZoneShape poly, ou null com menos de três cantos.

ExemploCopy 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

Verifica uma forma de zona que vem de outro recurso ou de um arquivo: todo número finito, um polígono com pelo menos três pontos. Use em uma forma passada para um dos seus exports.

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

readZoneShape(value: unknown): ZoneShape | null

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

Um ZoneShape limpo (campos extras descartados), ou null quando não é uma esfera, um cilindro ou um polígono válido.

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