Géométrie des zones

Une zone du monde est un ZoneShape : une sphère, un cylindre ou un polygone au sol entre deux hauteurs. La classe client Zones (callbacks d’entrée et de sortie, voir Zones) utilise ces formes ; les utilitaires de cette page sont le simple calcul qui se trouve derrière, sans natives, pour que le serveur puisse vérifier la même zone (le joueur est-il vraiment dans le magasin avant la vente ?).

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

Lua : aucun de ces utilitaires n’a d’équivalent Lua. En Lua, les zones sont aiLib.Zones.new() sur le client (voir Zones).

zoneContainsCopy Anchor Link

Indique si un point se trouve dans une forme de zone.

Côté : client, serveur et NUI · Attend : non

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

ParamètresCopy Anchor Link

RetourCopy Anchor Link

true quand le point est à l’intérieur (sur le bord compte comme à l’intérieur pour les sphères et les cylindres). Pour un cylindre, le point doit aussi être à height mètres au plus au-dessus ou au-dessous du centre. Pour un polygone, z doit être entre minZ et maxZ.

ExempleCopy 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 boîte englobante au sol d’une forme : le plus petit rectangle (x / y) qui la contient. Utilisez-la pour une première vérification peu coûteuse, ou pour ranger une zone dans des cases de grille.

Côté : client, serveur et NUI · Attend : non

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

ParamètresCopy Anchor Link

RetourCopy Anchor Link

[minX, minY, maxX, maxY] en mètres. Pour une sphère ou un cylindre : le centre plus et moins le rayon.

ExempleCopy 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

Transforme les coins qu’enregistre le widget zone du panneau en une forme polygonale. La plage de hauteur va du z le plus bas au plus haut des coins, élargie de height mètres vers le haut et vers le bas.

Côté : client, serveur et NUI · Attend : non

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

ParamètresCopy Anchor Link

RetourCopy Anchor Link

Le ZoneShape polygonal, ou null avec moins de trois coins.

ExempleCopy 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

Vérifie une forme de zone qui vient d’une autre ressource ou d’un fichier : chaque nombre fini, un polygone d’au moins trois points. Utilisez-le sur une forme passée à l’un de vos exports.

Côté : client, serveur et NUI · Attend : non

readZoneShape(value: unknown): ZoneShape | null

ParamètresCopy Anchor Link

RetourCopy Anchor Link

Un ZoneShape propre (les champs en trop sont retirés), ou null quand ce n’est pas une sphère, un cylindre ou un polygone valide.

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