Данные панели

Настройки вашего скрипта хранятся в файлах data/*.json, которые владелец сервера редактирует в админ-панели ai-core (см. Админ-панель). Панель проверяет значения по вашему schema.ts, но файл всё равно может быть старым, отредактированным вручную или без какого-то поля. Функции чтения на этой странице никогда не отказывают: отсутствующее или неверное значение даёт переданное вами запасное значение, поэтому скрипт всегда запускается.

Для значений, которые отправляет клиент, используйте строгие функции чтения со страницы Действия и ввод от клиента: они отклоняют неверное значение.

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

Lua: ни у одной из них нет Lua-аналога (админ-панель и её файлы данных есть только в TypeScript).

Функции чтения значенийCopy Anchor Link

numCopy Anchor Link

Конечное число, ограниченное диапазоном [min, max], иначе запасное значение.

Сторона: Клиент, сервер и NUI · Ждёт: нет

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

ПараметрыCopy Anchor Link

ВозвращаетCopy Anchor Link

number: значение, ограниченное диапазоном, или fallback (без ограничения).

ПримерCopy Anchor Link

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

num(25, 2.5, 1, 20);      // 20 (ограничено)
num("big", 2.5, 1, 20);   // 2.5 (запасное значение)

intCopy Anchor Link

Как num, затем округляется до целого.

Сторона: Клиент, сервер и NUI · Ждёт: нет

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

ПараметрыCopy Anchor Link

ВозвращаетCopy Anchor Link

number: целое число (запасное значение тоже округляется).

ПримерCopy 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

Булево значение, иначе запасное значение.

Сторона: Клиент, сервер и NUI · Ждёт: нет

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

ПараметрыCopy Anchor Link

ВозвращаетCopy Anchor Link

boolean.

ПримерCopy Anchor Link

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

bool(true, false);   // true
bool("yes", false);  // false (запасное значение)

strCopy Anchor Link

Обрезанная по краям непустая строка, урезанная до max символов, иначе запасное значение.

Сторона: Клиент, сервер и NUI · Ждёт: нет

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

ПараметрыCopy Anchor Link

ВозвращаетCopy Anchor Link

string.

ПримерCopy Anchor Link

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

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

recordCopy Anchor Link

Значение как простой объект или пустой объект {}. Используйте перед чтением полей значения, которого может не быть.

Сторона: Клиент, сервер и NUI · Ждёт: нет

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

ПараметрыCopy Anchor Link

ВозвращаетCopy Anchor Link

Сам value, если это простой объект, иначе новый {} (в том числе для массивов и null).

ПримерCopy Anchor Link

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

function readCoords(raw: unknown) {
  const c = record(raw); // {}, если поля нет
  return { x: num(c.x, 0), y: num(c.y, 0), z: num(c.z, 0) };
}

vec4Copy Anchor Link

Позиция с направлением; каждое отсутствующее или неверное поле берётся из запасного значения.

Сторона: Клиент, сервер и NUI · Ждёт: нет

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

ПараметрыCopy Anchor Link

ВозвращаетCopy Anchor Link

Новый Vec4.

ПримерCopy 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 }

Помощники для схемыCopy Anchor Link

specCopy Anchor Link

Конструкторы числовых полей для schema.ts вашей панели, чтобы не писать один и тот же объект DataSpec вручную.

Сторона: Клиент, сервер и NUI · Ждёт: нет

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

ПараметрыCopy Anchor Link

ВозвращаетCopy Anchor Link

DataSpec: { type: "number", min, max }, плюс integer: true для spec.int и optional: true, если запрошено.

ПримерCopy 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: [], // раскладка панели (карточки и поля), см. Админ-панель
};

withoutSchemaKeyCopy Anchor Link

Удаляет ключ "$schema" из содержимого файла данных. Ключ нужен только для того, чтобы редакторы кода могли проверять файл; ваша функция чтения не должна его видеть.

Сторона: Клиент, сервер и NUI · Ждёт: нет

withoutSchemaKey(value: unknown): unknown

ПараметрыCopy Anchor Link

ВозвращаетCopy Anchor Link

Копия без $schema, если значение является объектом с этим ключом; иначе value без изменений.

ПримерCopy Anchor Link

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

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

Файлы записейCopy Anchor Link

Файл записей хранит много записей по ключу ({ "legion": {...}, "pillbox": {...} }): магазины, гаражи, мэрии. Каждую запись читает ваша собственная функция чтения (RecordReader<T> = (key: string, raw: Record<string, unknown>) => T | null), построенная из функций чтения значений выше.

readRecordsCopy Anchor Link

Читает весь файл записей один раз в Map, одна запись на ключ, через вашу функцию чтения. Записи, которые не являются объектами или для которых ваша функция возвращает null, пропускаются.

Сторона: Клиент, сервер и NUI · Ждёт: нет

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

ПараметрыCopy Anchor Link

ВозвращаетCopy Anchor Link

Map<string, T>: разобранные записи по ключу.

ПримерCopy 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

Поддерживает объекты мира из файла записей (точки, блипы, педы, зоны) в соответствии с панелью, по одной записи за раз: изменённая запись перестраивает только свои объекты. Он экспортируется из @aicore-fivem/lib/shared и не имеет Lua-аналога. Полный справочник (конструктор, функция build, rebuild, rebuildAll, пример) находится на странице Точки взаимодействия: RecordObjects.