Acceso, blips y NPC de lugares

La mayoría de los lugares que añade un script (una tienda, un almacén, un garaje, un ayuntamiento) tienen las mismas tres partes en el panel: quién puede usarlo, su blip en el mapa y un NPC de pie allí. Cada parte viene en un trío: una especificación de datos para tu schema.ts, campos de panel listos con las propias etiquetas de ai-core, y un lector para el valor guardado. Úsalos para que el panel de cada script se vea y se comporte igual.

import { readAccess, isPublic, decideAccess, ACCESS_FIELDS, accessFields, readBlipStyle, BLIP_STYLE_FIELDS, PLACE_PED_SPEC, placePedFields, readPlacePed } from "@aicore-fivem/lib/shared";

Lua: ninguna de estas tiene equivalente en Lua (el panel de administración es solo para TypeScript).

AccesoCopy Anchor Link

La regla es una AccessRule: uno de los trabajos de la lista (con su rango mínimo, de servicio cuando onDuty está activado) o una de las bandas de la lista (con su rango mínimo). Ambas listas vacías significa todos. La comprobación del cliente (allows(rule), consulta Pertenencia) y la del servidor (online.allows(source, rule), consulta Jugadores) usan la misma decisión, así que lo que ve el jugador coincide con lo que permite el servidor.

readAccessCopy Anchor Link

Lee una regla de acceso de los propios campos de un registro (jobs, gangs, grades, onDuty). Los campos que faltan significan que cualquiera puede usarlo.

Lado: Cliente, servidor y NUI · Espera: no

readAccess(value: unknown): AccessRule

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

AccessRule. Los nombres que no son strings se descartan; los rangos que no son números enteros de 0 o más se descartan.

EjemploCopy Anchor Link

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

readAccess({ label: "Armoury", jobs: ["police"], grades: { police: 2 }, onDuty: true });
// { jobs: ["police"], gangs: [], grades: { police: 2 }, onDuty: true }

isPublicCopy Anchor Link

Si una regla deja entrar a todos (ningún trabajo ni banda en la lista). Úsalo para saltarte comprobaciones y para mostrar un lugar a todos.

Lado: Cliente, servidor y NUI · Espera: no

isPublic(rule: AccessRule): boolean

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

true cuando jobs y gangs están vacíos.

EjemploCopy Anchor Link

import { isPublic, readAccess } from "@aicore-fivem/lib/shared";

isPublic(readAccess({})); // true

decideAccessCopy Anchor Link

La decisión de la regla a partir de las pertenencias de un jugador. allows del cliente y online.allows del servidor lo llaman por ti; llámalo tú mismo solo cuando tienes las pertenencias de otra forma (una página NUI, una prueba).

Lado: Cliente, servidor y NUI · Espera: no

decideAccess(
  rule: AccessRule,
  jobs: ReadonlyArray<{ job: string; grade: number }>,
  gangs: ReadonlyArray<{ gang: string; grade: number }>,
  dutyJob: string | null,
): boolean

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

true cuando la regla es pública, cuando una banda de la lista coincide con su rango mínimo, o cuando un trabajo de la lista coincide con su rango mínimo (y el jugador está de servicio en él cuando onDuty está activado).

EjemploCopy Anchor Link

import { decideAccess, readAccess } from "@aicore-fivem/lib/shared";

const rule = readAccess({ jobs: ["police"], grades: { police: 2 }, onDuty: true });
decideAccess(rule, [{ job: "police", grade: 3 }], [], "police"); // true
decideAccess(rule, [{ job: "police", grade: 3 }], [], null);     // false: fuera de servicio

ACCESS_FIELDSCopy Anchor Link

La especificación de datos de los campos de acceso, para expandirla en las sections de un archivo de registros de tu schema.ts.

Lado: Cliente, servidor y NUI · Espera: no

const ACCESS_FIELDS: Record<string, DataSpec>
// { jobs: nombres con búsqueda de trabajos, opcional; gangs: nombres con búsqueda de bandas, opcional; onDuty: bool, opcional }

EjemploCopy Anchor Link

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

const stashSections = {
  label: { type: "text", min: 1, max: 48 },
  coords: { type: "vec3" },
  ...ACCESS_FIELDS,
};

accessFieldsCopy Anchor Link

Los campos de panel de la regla de acceso (etiquetas de trabajos, etiquetas de bandas, un interruptor de servicio), con las propias etiquetas y ayudas del panel de ai-core ya puestas.

Lado: Cliente, servidor y NUI · Espera: no

accessFields(): WidgetSpec[]

DevuelveCopy Anchor Link

WidgetSpec[]: tres campos en las rutas jobs, gangs y onDuty. Expándelos en los fields de una tarjeta de las tabs de tu panel.

EjemploCopy Anchor Link

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

import type { CardSpec } from "@aicore-fivem/shared";

const accessCard: CardSpec = { icon: "lock", title: "ADMIN_CARD_ACCESS", fields: [...accessFields()] };

BlipsCopy Anchor Link

readBlipStyleCopy Anchor Link

Lee un estilo de blip de los datos del panel. Cada parte ausente o incorrecta viene del valor de reserva; los valores se mantienen en su rango (sprite 0-1000, color 0-100, escala 0.3-2).

Lado: Cliente, servidor y NUI · Espera: no

readBlipStyle(value: unknown, fallback: BlipStyle): BlipStyle

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

Un BlipStyle.

EjemploCopy Anchor Link

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

readBlipStyle({ sprite: 52, color: 500 }, { sprite: 52, color: 2, scale: 0.8 });
// { sprite: 52, color: 100, scale: 0.8 }: color limitado, escala del valor de reserva

BLIP_STYLE_FIELDSCopy Anchor Link

La especificación de datos de los campos de un estilo de blip, para { type: "object", fields: BLIP_STYLE_FIELDS } en tu schema.ts. El panel la muestra con su widget blip.

Lado: Cliente, servidor y NUI · Espera: no

const BLIP_STYLE_FIELDS: Record<string, DataSpec>
// sprite: número entero 0-1000, color: número entero 0-100, scale: número 0.3-2

EjemploCopy Anchor Link

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

const sections = {
  blip: { type: "bool" },
  blipStyle: { type: "object", optional: true, fields: BLIP_STYLE_FIELDS },
};

NPC de lugaresCopy Anchor Link

PLACE_PED_SPECCopy Anchor Link

La especificación de datos de la sección ped de un lugar: modelo, escenario en reposo y posición, todo opcional. Un lugar sin modelo no tiene NPC.

Lado: Cliente, servidor y NUI · Espera: no

const PLACE_PED_SPEC: DataSpec
// { type: "object", optional: true, fields: { model: texto de hasta 64, scenario: uno de los escenarios ofrecidos, coords: vec4 } }

Los escenarios que ofrece el panel: ninguno (se queda quieto), WORLD_HUMAN_STAND_IMPATIENT, WORLD_HUMAN_CLIPBOARD, WORLD_HUMAN_STAND_MOBILE, WORLD_HUMAN_AA_COFFEE, WORLD_HUMAN_SMOKING, WORLD_HUMAN_GUARD_STAND, WORLD_HUMAN_COP_IDLES, WORLD_HUMAN_HANG_OUT_STREET.

EjemploCopy Anchor Link

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

const sections = { ped: PLACE_PED_SPEC, label: { type: "text", min: 1, max: 48 } };

placePedFieldsCopy Anchor Link

Los campos de panel del NPC de un lugar: un selector de modelo de ped, un selector de escenario y una herramienta de punto con heading que se ajusta al suelo. Las etiquetas son las propias de ai-core.

Lado: Cliente, servidor y NUI · Espera: no

placePedFields(path?: string): WidgetSpec[]

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

WidgetSpec[]: tres campos en <path>.model, <path>.scenario y <path>.coords.

EjemploCopy Anchor Link

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

import type { CardSpec } from "@aicore-fivem/shared";

const npcCard: CardSpec = { icon: "user", title: "ADMIN_CARD_NPC", fields: [...placePedFields()] };

readPlacePedCopy Anchor Link

Lee el NPC de un lugar de los datos del panel.

Lado: Cliente, servidor y NUI · Espera: no

readPlacePed(value: unknown): PlacePed | null

ParámetrosCopy Anchor Link

DevuelveCopy Anchor Link

Un PlacePed, o null cuando no hay modelo (el lugar no tiene NPC). coords se deja fuera salvo que x, y, z y heading sean todos números; un escenario vacío se deja fuera.

EjemploCopy Anchor Link

import { readPlacePed, readBlipStyle, readAccess, str, type PlacePed, type BlipStyle, type AccessRule } from "@aicore-fivem/lib/shared";

export interface Shop {
  label: string;
  ped: PlacePed | null;
  blipStyle: BlipStyle;
  access: AccessRule;
}

export function readShop(id: string, v: Record<string, unknown>): Shop {
  return {
    label: str(v.label, id, 48),
    ped: readPlacePed(v.ped),
    blipStyle: readBlipStyle(v.blipStyle, { sprite: 52, color: 2, scale: 0.8 }),
    access: readAccess(v),
  };
}

En el cliente, pasa shop.ped ?? undefined como opción ped de un punto de Points: el punto hace aparecer el NPC y pone su opción de target en él.