Zonengeometrie

Ein Bereich in der Welt ist ein ZoneShape: eine Kugel, ein Zylinder oder ein Bodenpolygon zwischen zwei Höhen. Die Client-Klasse Zones (Betreten- und Verlassen-Callbacks, siehe Zonen) nutzt diese Formen; die Helfer auf dieser Seite sind die reine Mathematik dahinter, ohne Natives, sodass der Server denselben Bereich prüfen kann (ist der Spieler wirklich im Shop, bevor er verkauft?).

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

Lua: Keiner davon hat einen Lua-Zwilling. Lua-Zonen sind aiLib.Zones.new() auf dem Client (siehe Zonen).

zoneContainsCopy Anchor Link

Ob ein Punkt innerhalb einer Zonenform liegt.

Seite: Client, Server und NUI · Wartet: nein

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

ParameterCopy Anchor Link

RückgabewertCopy Anchor Link

true, wenn der Punkt drin ist (auf dem Rand zählt bei Kugeln und Zylindern als drin). Bei einem Zylinder muss der Punkt außerdem innerhalb von height Metern über oder unter dem Mittelpunkt liegen. Bei einem Polygon muss z zwischen minZ und maxZ liegen.

BeispielCopy 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

Die Bounding Box einer Form am Boden: das kleinste Rechteck (x / y), das sie enthält. Nutze es für eine günstige erste Prüfung oder um eine Zone in Rasterzellen einzuordnen.

Seite: Client, Server und NUI · Wartet: nein

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

ParameterCopy Anchor Link

RückgabewertCopy Anchor Link

[minX, minY, maxX, maxY] in Metern. Bei einer Kugel oder einem Zylinder: der Mittelpunkt plus und minus der Radius.

BeispielCopy 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

Wandelt die Ecken, die das zone-Widget des Panels speichert, in eine Polygonform um. Der Höhenbereich ist das niedrigste und höchste z der Ecken, um height Meter nach oben und unten erweitert.

Seite: Client, Server und NUI · Wartet: nein

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

ParameterCopy Anchor Link

RückgabewertCopy Anchor Link

Die Polygon-ZoneShape, oder null bei weniger als drei Ecken.

BeispielCopy 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

Prüft eine Zonenform, die von einer anderen Ressource oder aus einer Datei kommt: jede Zahl endlich, ein Polygon mit mindestens drei Punkten. Nutze es auf einer Form, die an einen deiner Exports übergeben wird.

Seite: Client, Server und NUI · Wartet: nein

readZoneShape(value: unknown): ZoneShape | null

ParameterCopy Anchor Link

RückgabewertCopy Anchor Link

Eine saubere ZoneShape (zusätzliche Felder verworfen), oder null, wenn es keine gültige Kugel, kein gültiger Zylinder oder kein gültiges Polygon ist.

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