Dados do painel

As configurações do seu script ficam em arquivos data/*.json que o dono do servidor edita no painel de administração do ai-core (veja Painel de administração). O painel verifica os valores contra o seu schema.ts, mas um arquivo ainda pode estar antigo, editado à mão ou sem um campo. Os leitores desta página nunca recusam: um valor ausente ou errado dá o valor de reserva que você passa, então o script sempre inicia.

Para valores que um cliente envia, use os leitores rígidos de Ações e entrada do cliente: esses recusam um valor inválido.

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

Lua: nenhum destes tem equivalente em Lua (o painel de administração e os arquivos de dados dele são só TypeScript).

Leitores de valoresCopy Anchor Link

numCopy Anchor Link

Um número finito limitado a [min, max], senão o valor de reserva.

Lado: Cliente, servidor e NUI · Espera: não

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

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

number: o valor limitado à faixa, ou fallback (sem limitar).

ExemploCopy Anchor Link

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

num(25, 2.5, 1, 20);      // 20 (limitado)
num("big", 2.5, 1, 20);   // 2.5 (valor de reserva)

intCopy Anchor Link

Como num, depois arredondado para um número inteiro.

Lado: Cliente, servidor e NUI · Espera: não

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

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

number: um número inteiro (o valor de reserva também é arredondado).

ExemploCopy 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

Um booleano, senão o valor de reserva.

Lado: Cliente, servidor e NUI · Espera: não

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

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

boolean.

ExemploCopy Anchor Link

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

bool(true, false);   // true
bool("yes", false);  // false (valor de reserva)

strCopy Anchor Link

Uma string sem espaços nas pontas, não vazia, cortada em max caracteres, senão o valor de reserva.

Lado: Cliente, servidor e NUI · Espera: não

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

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

string.

ExemploCopy Anchor Link

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

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

recordCopy Anchor Link

O valor como objeto simples, ou um objeto vazio {}. Use antes de ler campos de um valor que pode estar ausente.

Lado: Cliente, servidor e NUI · Espera: não

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

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

O próprio value quando é um objeto simples, senão um novo {} (também para arrays e null).

ExemploCopy Anchor Link

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

function readCoords(raw: unknown) {
  const c = record(raw); // {} quando o campo está ausente
  return { x: num(c.x, 0), y: num(c.y, 0), z: num(c.z, 0) };
}

vec4Copy Anchor Link

Uma posição com heading; cada campo ausente ou errado vem do valor de reserva.

Lado: Cliente, servidor e NUI · Espera: não

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

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

Um novo Vec4.

ExemploCopy 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 }

Helpers de schemaCopy Anchor Link

specCopy Anchor Link

Construtores para campos numéricos no schema.ts do seu painel, para que você não escreva o mesmo objeto DataSpec à mão.

Lado: Cliente, servidor e NUI · Espera: não

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

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

DataSpec: { type: "number", min, max }, mais integer: true para spec.int e optional: true quando pedido.

ExemploCopy 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: [], // o layout do painel (cards e campos), veja Painel de administração
};

withoutSchemaKeyCopy Anchor Link

Remove a chave "$schema" do conteúdo de um arquivo de dados. A chave só existe para que os editores de código possam verificar o arquivo; o seu leitor não deveria vê-la.

Lado: Cliente, servidor e NUI · Espera: não

withoutSchemaKey(value: unknown): unknown

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

Uma cópia sem $schema quando o valor é um objeto que a tem; caso contrário value sem mudanças.

ExemploCopy Anchor Link

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

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

Arquivos de recordsCopy Anchor Link

Um arquivo records guarda muitas entradas por chave ({ "legion": {...}, "pillbox": {...} }): lojas, garagens, prefeituras. Cada entrada é lida pela sua própria função leitora (RecordReader<T> = (key: string, raw: Record<string, unknown>) => T | null), construída com os leitores de valores acima.

readRecordsCopy Anchor Link

Lê um arquivo de records inteiro uma vez para um Map, uma entrada por chave, pelo seu leitor. Entradas que não são objetos, ou para as quais o seu leitor retorna null, ficam de fora.

Lado: Cliente, servidor e NUI · Espera: não

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

ParâmetrosCopy Anchor Link

RetornoCopy Anchor Link

Map<string, T>: as entradas interpretadas por chave.

ExemploCopy 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

Mantém os objetos do mundo de um arquivo de records (pontos, blips, peds, zonas) em sincronia com o painel, uma entrada por vez: uma entrada editada reconstrói só os próprios objetos. É exportado de @aicore-fivem/lib/shared e não tem equivalente em Lua. A referência completa (construtor, função build, rebuild, rebuildAll, exemplo) está em Pontos de interação: RecordObjects.