Panel data

Your script's settings live in data/*.json files the server owner edits in ai-core's admin panel (see Admin panel). The panel checks values against your schema.ts, but a file can still be old, hand-edited or missing a field. The readers on this page never refuse: a missing or wrong value gives the fallback you pass, so the script always starts.

For values a client sends, use the strict readers on Actions and client input instead: those refuse a bad value.

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

Lua: none of these have a Lua twin (the admin panel and its data files are TypeScript only).

Value readersCopy Anchor Link

numCopy Anchor Link

A finite number clamped to [min, max], else the fallback.

Side: Client, server and NUI · Waits: no

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

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

number: the value clamped into the range, or fallback (not clamped).

ExampleCopy Anchor Link

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

num(25, 2.5, 1, 20);      // 20 (clamped)
num("big", 2.5, 1, 20);   // 2.5 (fallback)

intCopy Anchor Link

Like num, then rounded to a whole number.

Side: Client, server and NUI · Waits: no

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

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

number: a whole number (the fallback is rounded too).

ExampleCopy 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

A boolean, else the fallback.

Side: Client, server and NUI · Waits: no

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

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

boolean.

ExampleCopy Anchor Link

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

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

strCopy Anchor Link

A trimmed, non-empty string cut to max characters, else the fallback.

Side: Client, server and NUI · Waits: no

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

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

string.

ExampleCopy Anchor Link

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

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

recordCopy Anchor Link

The value as a plain object, or an empty object {}. Use it before reading fields of a value that may be missing.

Side: Client, server and NUI · Waits: no

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

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

value itself when it is a plain object, otherwise a new {} (also for arrays and null).

ExampleCopy Anchor Link

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

function readCoords(raw: unknown) {
  const c = record(raw); // {} when the field is missing
  return { x: num(c.x, 0), y: num(c.y, 0), z: num(c.z, 0) };
}

vec4Copy Anchor Link

A position with heading; each missing or wrong field comes from the fallback.

Side: Client, server and NUI · Waits: no

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

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

A new Vec4.

ExampleCopy 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 helpersCopy Anchor Link

specCopy Anchor Link

Builders for number fields in your panel schema.ts, so you do not write the same DataSpec object by hand.

Side: Client, server and NUI · Waits: no

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

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

DataSpec: { type: "number", min, max }, plus integer: true for spec.int and optional: true when asked.

ExampleCopy 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: [], // the panel layout (cards and fields), see Admin panel
};

withoutSchemaKeyCopy Anchor Link

Removes the "$schema" key from a data file's content. The key is only there so code editors can check the file; your reader should not see it.

Side: Client, server and NUI · Waits: no

withoutSchemaKey(value: unknown): unknown

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

A copy without $schema when the value is an object that has it; otherwise value unchanged.

ExampleCopy Anchor Link

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

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

Records filesCopy Anchor Link

A records file holds many entries by key ({ "legion": {...}, "pillbox": {...} }): shops, garages, city halls. Each entry is read by your own reader function (RecordReader<T> = (key: string, raw: Record<string, unknown>) => T | null), built from the value readers above.

readRecordsCopy Anchor Link

Reads a whole records file once into a Map, one entry per key, through your reader. Entries that are not objects, or for which your reader returns null, are left out.

Side: Client, server and NUI · Waits: no

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

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

Map<string, T>: the parsed entries by key.

ExampleCopy 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

Keeps the world objects of a records file (points, blips, peds, zones) in step with the panel, one entry at a time: an edited entry rebuilds only its own objects. It is exported from @aicore-fivem/lib/shared and has no Lua twin. Its full reference (constructor, build function, rebuild, rebuildAll, example) is on Interaction points: RecordObjects.