State bags
Los valores de estado compartido que publican ai-core y los scripts ai-* - bags de jugador, bags de vehículo y claves de GlobalState - qué contiene cada uno, quién lo escribe y cómo leerlo y seguirlo.
Un state bag es un valor que FiveM mantiene sincronizado para todo el mundo: en GlobalState (un valor para todo el servidor), en un jugador o en una entidad (un vehículo). Cualquier recurso de cualquier lado puede leerlo, y sigue los cambios sin ningún evento propio. ai-core y los scripts ai-* los usan para el estado que necesita todo el mundo, nunca para datos privados.
Solo lectura. Cada clave de abajo tiene un recurso dueño, que es el único que la escribe, siempre desde el servidor. Nunca escribas tú estas claves, ni desde el servidor ni desde el cliente: el dueño te sobrescribiría y los demás scripts verían un estado erróneo. Para cambiar el estado, llama al export del dueño (por ejemplo la reanimación de ai-death, el export de servicio de ai-core).
Cómo leerlos
La lib tiene una clase por tipo. Cada una mantiene una copia local, así que get no cuesta nada, y onChange ejecuta tu listener después de un cambio.
| Tipo | TypeScript (lib) | Lua |
|---|---|---|
| Una clave de GlobalState | new GlobalKey(key, parse): .get(), .onChange((_, value, old) => ...) | GlobalState[key], AddStateBagChangeHandler(key, 'global', fn) |
| Muchas claves de GlobalState con un mismo prefijo | new GlobalGroup(prefix, parse): .get(id), .ids(), .onChange((id, value, old) => ...) | GlobalState[prefix .. id] |
| El bag de un jugador | new PlayerState(key, parse): .get(serverId), .onChange((serverId, value, old) => ...) | Player(serverId).state[key], LocalPlayer.state[key] en el cliente |
| El bag de una entidad | new EntityState(key, parse): .get(entity), .getByNetId(netId), .onChange((netId, value, old) => ...) | Entity(entity).state[key] |
parse comprueba el valor en bruto: stateNumber, stateBoolean, stateString de la lib, o tu propia función que devuelve undefined para un valor erróneo. Todos vienen de @aicore-fivem/lib/client o @aicore-fivem/lib/server.
import { cache, GlobalKey, PlayerState, stateBoolean, stateNumber } from "@aicore-fivem/lib/client";
import { dutyCountKey, PLAYER_BAGS } from "@aicore-fivem/shared";
const policeOnDuty = new GlobalKey(dutyCountKey("police"), stateNumber);
const cuffed = new PlayerState(PLAYER_BAGS.cuffed, stateBoolean);
console.log(`police on duty: ${policeOnDuty.get() ?? 0}`);
policeOnDuty.onChange((_, count) => console.log(`police on duty now: ${count ?? 0}`));
cuffed.onChange((serverId, value) => {
if (serverId === cache.serverId) console.log(value ? "you are cuffed" : "you are free");
});Bags de jugador (PLAYER_BAGS)
Claves que leen varios recursos en un jugador. Constante: PLAYER_BAGS en @aicore-fivem/shared.
| Clave | Constante | Dueño | Valor |
|---|---|---|---|
dead | PLAYER_BAGS.dead | ai-death | true mientras el jugador está caído. Ausente o false en otro caso. Con otro script de muerte, usa la capa médica (export IsDead, medical de la lib) en su lugar: los demás scripts de muerte usan sus propias claves. |
cuffed | PLAYER_BAGS.cuffed | ai-police | true mientras el jugador está esposado. |
proximity | PLAYER_BAGS.proximity | ai-voice | El alcance de la voz, con la forma de pma-voice: { index, distance, mode }. |
Bags de vehículo (VEHICLE_BAGS)
Claves en entidades de vehículo. Constante: VEHICLE_BAGS en @aicore-fivem/shared.
| Clave | Constante | Dueño | Valor |
|---|---|---|---|
ai:owned | VEHICLE_BAGS.owned | ai-vehicles | true en un vehículo en propiedad que ha aparecido. |
ai:vid | VEHICLE_BAGS.id | ai-vehicles | El id del vehículo en ai-vehicles (número). |
ai:props | VEHICLE_BAGS.props | ai-vehicles | El aspecto y el tuning del vehículo (VehicleProps). ai-core lo aplica en el cliente dueño de la entidad. |
ai:setup | VEHICLE_BAGS.setup | ai-vehicles | Una configuración de aparición (VehicleSetup, por ejemplo un color elegido en una tienda). ai-core la aplica una vez en el cliente dueño. |
fuel | VEHICLE_BAGS.fuel | el script de combustible (ai-fuel; ai-core lo mantiene para los scripts de combustible del lado del cliente) | Nivel de combustible, 0-100. |
Para leer el combustible, usa la capa fuel de la lib: funciona con cualquier script de combustible, también con los que no escriben ellos mismos el bag fuel.
Claves de GlobalState de ai-core
| Clave | Constante | Valor |
|---|---|---|
ai:duty:<job> | dutyCountKey(job) (prefijo DUTY_COUNT_PREFIX) | Cuántos jugadores están de servicio en ese trabajo (número). Solo recuentos, nunca quién. |
ai:interaction | CORE.interactionStateKey | "prompt" o "target": cómo dejan interactuar a los jugadores los Points de la lib (ajuste del panel de ai-core). |
ai:pvp | CORE.pvpStateKey | true cuando los jugadores pueden hacerse daño entre sí (ajuste pvp del panel, comando /togglepvp). |
ai:inventory | INVENTORY_STATE_KEY | Nombre de recurso del inventario que hay detrás de la capa de inventario de ai-core. Sin definir mientras no hay ninguno en marcha. |
ai:vehicleKeys | VEHICLE_KEYS_STATE_KEY | Nombre de recurso del script de llaves de vehículos activo. Sin definir mientras no hay ninguno en marcha. |
ai:appearance | APPEARANCE_STATE_KEY | Nombre de recurso del script de ropa activo. Sin definir mientras no hay ninguno en marcha. |
ai:medical | CORE.medicalStateKey | Nombre de recurso del script de muerte activo. |
ai:mdt | CORE.mdtStateKey | Nombre de recurso del MDT activo. |
ai:notify | CORE.notifyStateKey | Nombre de recurso de la interfaz de notificaciones a la que van las tarjetas de ai-lib. Sin definir: ai-lib dibuja sus propias tarjetas. |
ai:fuel | FUEL_STATE_KEY | Nombre de recurso del script de combustible activo. Sin definir mientras no hay ninguno en marcha. |
ai:garages | GARAGES_STATE_KEY | Nombre de recurso del script de garajes activo. Sin definir mientras no hay ninguno en marcha. |
Las claves con nombres de recurso indican a las mitades de cliente de ai-core con qué script hablar. Léelas cuando necesites saber qué script está en marcha (para una línea de log, una ayuda al jugador), no para llamar directamente a ese script: llama a la capa de ai-core en su lugar.
import { GlobalKey, stateBoolean } from "@aicore-fivem/lib/server";
import { CORE } from "@aicore-fivem/shared";
const pvp = new GlobalKey(CORE.pvpStateKey, stateBoolean);
pvp.onChange((_, on) => console.log(on ? "PvP is on" : "PvP is off"));Claves de otros scripts ai-*
Estado compartido que publican algunos scripts ai-*, para los scripts que trabajan con ellos. La página para desarrolladores de cada script tiene los detalles.
| Clave | Dónde | Dueño | Valor |
|---|---|---|---|
door:<id> | GlobalState | ai-doorlock | true mientras la puerta está cerrada con llave. |
ai:clock | GlobalState | ai-weathersync | { base, at, scale, frozen }: minutos de juego del día en la hora del servidor at (ms), avanzando scale minutos de juego por cada minuto real. Los clientes llevan el reloj ellos mismos a partir de esto. |
ai:weather | GlobalState | ai-weathersync | { type, blackout }: el clima actual. |
ai:rweather:<id> | GlobalState | ai-weathersync | El clima actual de una región de clima. |
prop:<id> | GlobalState | ai-properties | true cuando la propiedad tiene dueño. |
rob:<id> | GlobalState | ai-robberies | true mientras un objetivo de robo está vaciado y espera su tiempo de recarga. |
siren:lx | Vehículo | ai-sirens | Tono principal de la sirena: 0 apagada, 1-3 un tono. |
siren:manu | Vehículo | ai-sirens | Bocina / sirena manual: 0 apagada, 1 bocina, 2 manual, 3 ambas. |
siren:lightbar | Vehículo | ai-sirens | El modelo de barra de luces montado en el vehículo; ausente si no hay ninguno. |
Eventos de la interfaz de ai-lib
Los eventos de cliente que dispara ai-lib cuando un jugador responde a un menú, un diálogo de entrada, el selector de objetos, un minijuego o un aviso, o cancela una barra de progreso - para scripts que llaman ellos mismos a los exports de ai-lib.
Eventos del puente de frameworks
Los eventos de ESX, QB / Qbox y vRP que dispara ai-core para que los scripts escritos para esos frameworks sigan funcionando, con sus argumentos exactos, y los eventos de framework a los que responde ai-core.