Panel-Daten

Die Einstellungen deines Skripts liegen in data/*.json-Dateien, die der Serverbetreiber im Admin-Panel von ai-core bearbeitet (siehe Admin-Panel). Das Panel prüft Werte gegen dein schema.ts, aber eine Datei kann trotzdem alt, von Hand bearbeitet sein oder ein Feld vermissen. Die Leser auf dieser Seite lehnen nie ab: Ein fehlender oder falscher Wert ergibt den Fallback, den du übergibst, sodass das Skript immer startet.

Für Werte, die ein Client sendet, nutze stattdessen die strikten Leser unter Aktionen und Client-Eingaben: Diese lehnen einen fehlerhaften Wert ab.

import { num, int, bool, str, record, vec4, spec, readRecords, withoutSchemaKey } from "@aicore-fivem/lib/shared";

Lua: Keiner davon hat einen Lua-Zwilling (das Admin-Panel und seine Datendateien gibt es nur in TypeScript).

WertleserCopy Anchor Link

numCopy Anchor Link

Eine endliche Zahl, auf [min, max] begrenzt, sonst der Fallback.

Seite: Client, Server und NUI · Wartet: nein

num(value: unknown, fallback: number, min?: number, max?: number): number

ParameterCopy Anchor Link

RückgabewertCopy Anchor Link

number: der Wert, in den Bereich begrenzt, oder fallback (nicht begrenzt).

BeispielCopy Anchor Link

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

num(25, 2.5, 1, 20);      // 20 (begrenzt)
num("big", 2.5, 1, 20);   // 2.5 (Fallback)

intCopy Anchor Link

Wie num, dann auf eine ganze Zahl gerundet.

Seite: Client, Server und NUI · Wartet: nein

int(value: unknown, fallback: number, min?: number, max?: number): number

ParameterCopy Anchor Link

RückgabewertCopy Anchor Link

number: eine ganze Zahl (der Fallback wird ebenfalls gerundet).

BeispielCopy Anchor Link

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

int(12.6, 10, 0, 100); // 13
int(null, 10, 0, 100); // 10

boolCopy Anchor Link

Ein Boolean, sonst der Fallback.

Seite: Client, Server und NUI · Wartet: nein

bool(value: unknown, fallback: boolean): boolean

ParameterCopy Anchor Link

RückgabewertCopy Anchor Link

boolean.

BeispielCopy Anchor Link

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

bool(true, false);   // true
bool("yes", false);  // false (Fallback)

strCopy Anchor Link

Ein getrimmter, nicht leerer String, auf max Zeichen gekürzt, sonst der Fallback.

Seite: Client, Server und NUI · Wartet: nein

str(value: unknown, fallback: string, max?: number): string

ParameterCopy Anchor Link

RückgabewertCopy Anchor Link

string.

BeispielCopy Anchor Link

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

str("  City Hall ", "Hall", 48); // "City Hall"
str("", "Hall", 48);             // "Hall"

recordCopy Anchor Link

Der Wert als einfaches Objekt, oder ein leeres Objekt {}. Nutze es, bevor du Felder eines Werts liest, der fehlen kann.

Seite: Client, Server und NUI · Wartet: nein

record(value: unknown): Record<string, unknown>

ParameterCopy Anchor Link

RückgabewertCopy Anchor Link

value selbst, wenn es ein einfaches Objekt ist, sonst ein neues {} (auch für Arrays und null).

BeispielCopy Anchor Link

import { num, record } from "@aicore-fivem/lib/shared";

function readCoords(raw: unknown) {
  const c = record(raw); // {}, wenn das Feld fehlt
  return { x: num(c.x, 0), y: num(c.y, 0), z: num(c.z, 0) };
}

vec4Copy Anchor Link

Eine Position mit Heading; jedes fehlende oder falsche Feld kommt aus dem Fallback.

Seite: Client, Server und NUI · Wartet: nein

vec4(value: unknown, fallback: Vec4): Vec4

ParameterCopy Anchor Link

RückgabewertCopy Anchor Link

Ein neues Vec4.

BeispielCopy Anchor Link

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

vec4({ x: 10, y: 20, z: 30 }, { x: 0, y: 0, z: 0, heading: 90 }); // { x: 10, y: 20, z: 30, heading: 90 }

Schema-HelferCopy Anchor Link

specCopy Anchor Link

Builder für Zahlenfelder in deinem Panel-schema.ts, damit du nicht dasselbe DataSpec-Objekt von Hand schreibst.

Seite: Client, Server und NUI · Wartet: nein

spec.int(min: number, max: number, optional?: boolean): DataSpec
spec.num(min: number, max: number, optional?: boolean): DataSpec

ParameterCopy Anchor Link

RückgabewertCopy Anchor Link

DataSpec: { type: "number", min, max }, plus integer: true bei spec.int und optional: true, wenn verlangt.

BeispielCopy Anchor Link

import { spec } from "@aicore-fivem/lib/shared";
import type { PanelSchema } from "@aicore-fivem/shared";

export const schema: PanelSchema = {
  title: "ADMIN_TITLE",
  icon: "store",
  files: {
    settings: {
      kind: "settings",
      sync: "admin",
      sections: {
        prices: { type: "object", fields: { water: spec.int(0, 1_000_000), tax: spec.num(0, 0.5) } },
      },
    },
  },
  tabs: [], // das Panel-Layout (Karten und Felder), siehe Admin-Panel
};

withoutSchemaKeyCopy Anchor Link

Entfernt den Schlüssel "$schema" aus dem Inhalt einer Datendatei. Der Schlüssel ist nur da, damit Code-Editoren die Datei prüfen können; dein Reader soll ihn nicht sehen.

Seite: Client, Server und NUI · Wartet: nein

withoutSchemaKey(value: unknown): unknown

ParameterCopy Anchor Link

RückgabewertCopy Anchor Link

Eine Kopie ohne $schema, wenn der Wert ein Objekt ist, das ihn hat; sonst value unverändert.

BeispielCopy Anchor Link

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

withoutSchemaKey({ $schema: "./schemas/shops.schema.json", legion: { label: "Legion" } });
// { legion: { label: "Legion" } }

Records-DateienCopy Anchor Link

Eine Records-Datei hält viele Einträge nach Schlüssel ({ "legion": {...}, "pillbox": {...} }): Shops, Garagen, Rathäuser. Jeder Eintrag wird von deiner eigenen Reader-Funktion gelesen (RecordReader<T> = (key: string, raw: Record<string, unknown>) => T | null), gebaut aus den Wertlesern oben.

readRecordsCopy Anchor Link

Liest eine ganze Records-Datei einmal in eine Map, ein Eintrag pro Schlüssel, über deinen Reader. Einträge, die keine Objekte sind oder für die dein Reader null zurückgibt, werden weggelassen.

Seite: Client, Server und NUI · Wartet: nein

readRecords<T>(raw: unknown, readOne: RecordReader<T>): Map<string, T>

ParameterCopy Anchor Link

RückgabewertCopy Anchor Link

Map<string, T>: die geparsten Einträge nach Schlüssel.

BeispielCopy Anchor Link

import { readRecords, str, num, record } from "@aicore-fivem/lib/shared";

type Shop = { label: string; x: number; y: number; z: number };

const readShop = (key: string, v: Record<string, unknown>): Shop => {
  const c = record(v.coords);
  return { label: str(v.label, key, 48), x: num(c.x, 0), y: num(c.y, 0), z: num(c.z, 0) };
};

const shops = readRecords({ legion: { label: "Legion", coords: { x: 25.7, y: -1347.3, z: 29.5 } } }, readShop);
shops.get("legion"); // { label: "Legion", x: 25.7, y: -1347.3, z: 29.5 }

RecordObjectsCopy Anchor Link

Hält die Weltobjekte einer Records-Datei (Punkte, Blips, Peds, Zonen) Eintrag für Eintrag im Gleichschritt mit dem Panel: Ein bearbeiteter Eintrag baut nur seine eigenen Objekte neu. Es wird aus @aicore-fivem/lib/shared exportiert und hat keinen Lua-Zwilling. Seine vollständige Referenz (Konstruktor, build-Funktion, rebuild, rebuildAll, Beispiel) steht unter Interaktionspunkte: RecordObjects.