Datos del panel

Los ajustes de tu script viven en archivos data/*.json que el dueño del servidor edita en el panel de administración de ai-core (consulta Panel de administración). El panel comprueba los valores contra tu schema.ts, pero un archivo aún puede ser antiguo, estar editado a mano o no tener un campo. Los lectores de esta página nunca rechazan: un valor ausente o incorrecto da el valor de reserva que pasas, así que el script siempre arranca.

Para los valores que envía un cliente, usa en su lugar los lectores estrictos de Acciones y entrada del cliente: esos rechazan un valor incorrecto.

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

Lua: ninguna de estas tiene equivalente en Lua (el panel de administración y sus archivos de datos son solo para TypeScript).

Lectores de valoresCopy Anchor Link

numCopy Anchor Link

Un número finito limitado a [min, max], o si no el valor de reserva.

Lado: Cliente, servidor y NUI · Espera: no

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

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

number: el valor limitado al rango, o fallback (sin limitar).

EjemploCopy 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, y después redondeado a un número entero.

Lado: Cliente, servidor y NUI · Espera: no

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

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

number: un número entero (el valor de reserva también se redondea).

EjemploCopy 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

Un booleano, o si no el valor de reserva.

Lado: Cliente, servidor y NUI · Espera: no

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

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

boolean.

EjemploCopy Anchor Link

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

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

strCopy Anchor Link

Un string recortado y no vacío, cortado a max caracteres, o si no el valor de reserva.

Lado: Cliente, servidor y NUI · Espera: no

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

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

string.

EjemploCopy Anchor Link

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

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

recordCopy Anchor Link

El valor como objeto simple, o un objeto vacío {}. Úsalo antes de leer campos de un valor que puede faltar.

Lado: Cliente, servidor y NUI · Espera: no

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

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

El propio value cuando es un objeto simple; en otro caso, un {} nuevo (también para arrays y null).

EjemploCopy Anchor Link

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

function readCoords(raw: unknown) {
  const c = record(raw); // {} cuando falta el campo
  return { x: num(c.x, 0), y: num(c.y, 0), z: num(c.z, 0) };
}

vec4Copy Anchor Link

Una posición con heading; cada campo ausente o incorrecto viene del valor de reserva.

Lado: Cliente, servidor y NUI · Espera: no

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

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

Un Vec4 nuevo.

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

Utilidades de esquemaCopy Anchor Link

specCopy Anchor Link

Constructores para los campos numéricos de tu schema.ts del panel, para que no escribas a mano el mismo objeto DataSpec.

Lado: Cliente, servidor y NUI · Espera: no

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

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

DataSpec: { type: "number", min, max }, más integer: true para spec.int y optional: true cuando se pide.

EjemploCopy 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: [], // la disposición del panel (tarjetas y campos), consulta Admin panel
};

withoutSchemaKeyCopy Anchor Link

Quita la clave "$schema" del contenido de un archivo de datos. La clave solo está ahí para que los editores de código puedan comprobar el archivo; tu lector no debería verla.

Lado: Cliente, servidor y NUI · Espera: no

withoutSchemaKey(value: unknown): unknown

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

Una copia sin $schema cuando el valor es un objeto que la tiene; en otro caso, value sin cambios.

EjemploCopy Anchor Link

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

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

Archivos de registrosCopy Anchor Link

Un archivo de registros guarda muchas entradas por clave ({ "legion": {...}, "pillbox": {...} }): tiendas, garajes, ayuntamientos. Cada entrada la lee tu propia función lectora (RecordReader<T> = (key: string, raw: Record<string, unknown>) => T | null), construida con los lectores de valores de arriba.

readRecordsCopy Anchor Link

Lee un archivo de registros entero una sola vez en un Map, una entrada por clave, mediante tu lector. Las entradas que no son objetos, o para las que tu lector devuelve null, se dejan fuera.

Lado: Cliente, servidor y NUI · Espera: no

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

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

Map<string, T>: las entradas procesadas por clave.

EjemploCopy 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

Mantiene los objetos del mundo de un archivo de registros (puntos, blips, peds, zonas) al día con el panel, entrada a entrada: una entrada editada solo reconstruye sus propios objetos. Se exporta desde @aicore-fivem/lib/shared y no tiene equivalente en Lua. Su referencia completa (constructor, función build, rebuild, rebuildAll, ejemplo) está en Puntos de interacción: RecordObjects.