AI Core

Integrar tu propio script

Cómo funciona tu resource con AI Core - cargar la lib, llamar a las capas en vez de a otros scripts, lo que nunca debes tocar y la lista de comprobación antes de publicar.

Tu script no tiene que ser un script ai-* para funcionar con AI Core. Lo que debes hacer depende de lo que estés escribiendo:

Lo que tienesQué hacer
Un script escrito para ESX, QBCore, Qbox o vRPNada. AI Core provee es_extended, qb-core, qbx_core y vrp y responde su API, así que el script funciona sin cambios. Ver Compatibilidad.
Tu propio resource nuevo (Lua, TypeScript o JavaScript simple)Cargar la lib y llamar a AI Core a través de ella. De eso trata esta página.
Un script que provee algo que otros scripts necesitan (un inventario, un teléfono, un sistema de llaves, un garaje, un script de combustible...)Lo mismo que arriba, más un adaptador en esa capa para que el resto del servidor lo alcance. Ver Scripts recomendados.

El objetivo en una frase: todo lo que tu script comparte con otro script pasa por la lib o por ai-core, nunca por los exports de ese script. Así el propietario puede cambiar el inventario, el sistema de llaves o el teléfono y tu script sigue funcionando.

Cargar la lib

Lua

fxmanifest.lua
fx_version 'cerulean'
game 'gta5'
lua54 'yes'

dependency 'ai-lib'
shared_script '@ai-lib/init.lua'

client_script 'client.lua'
server_script 'server.lua'

aiLib.<name> queda disponible en todos los archivos de tu resource. La instalación completa, qué llamadas esperan y cómo cruzan las tablas y vectores de Lua a TypeScript: La lib para Lua.

TypeScript

server.ts
import { inventory, onClientCallback } from "@aifivem/lib/server";

@aifivem/lib viene de npm: un resource fuera del workspace de AI Core la instala con bun install @aifivem/lib @aifivem/shared. Un resource de JavaScript simple, sin paso de build, carga @ai-lib/dist/server.js y usa el mismo aiLib global.

Orden de arranque

ai-core y ai-lib arrancan antes de tu resource:

server.cfg
ensure ai-core
ensure ai-lib
ensure my-resource

Llama a AI Core, no al otro script

Cada tarea compartida tiene una sola puerta. La llamada de la lib y el export de ai-core hacen lo mismo; usa el que encaje con tu lenguaje.

Lo que necesitasLuaTypeScriptReferencia
Dar, quitar, contar objetosaiLib.inventory.addIteminventory.addItemObjetos, objetos de ai-core
Un objeto usableaiLib.inventory.registerUsableIteminventory.registerUsableItemregisterUsableItem
Un alijo o una tiendaaiLib.inventory.registerStashinventory.registerStashObjetos
Llaves de vehículoaiLib.vehicleKeys.give / .hasvehicleKeys.give / .hasVehículos
Aparecer un vehículo (matrícula, combustible, aspecto, llaves y asientos en una llamada)aiLib.spawnVehiclespawnVehiclespawnVehicle
Guardar en garaje o llevar al depósitoaiLib.garages.storegarages.storegarages.store
El dinero de un jugadorexports['ai-core']:AddMoney(src, 'cash', 50, 'reason')core.AddMoney(...)Dinero
Dinero entre dos cuentas, en una transacciónaiLib.money.transfermoney.transfermoney.transfer
Trabajos, bandas, servicioexports['ai-core']:SetJob(src, 'police', 2)core.SetJob(...)Trabajos y bandas
Quién está en línea, su nombre, su trabajoaiLib.online.nameonline.nameJugadores
Un aviso policialaiLib.dispatch.alertdispatch.alertdispatch.alert
La cárcelaiLib.prison.jailprison.jailprison.jail
Un registro en el MDTaiLib.mdt.recordmdt.recordmdt.record
Revivir, curar, "está muerto"aiLib.medical.revivemedical.revivemedical.revive
El teléfono (número, correo, mensaje, notificación)aiLib.phone.numberphone.numberTeléfono
Un aspecto, un conjunto de ropaaiLib.appearance.applyappearance.applyappearance.apply
Clima y horaaiLib.world.setWeatherworld.setWeatherMundo
Cerrar una puertaaiLib.doors.setLockeddoors.setLockeddoors.setLocked
Notificaciones, barras de progreso, menús, diálogos de entradaaiLib.notify, aiLib.progress, aiLib.menu.shownotify, progress, menuInterfaz común
Una entrada del menú radialaiLib.radial.addradial.addradial.add
Un comando (listado en el panel de administración, comprobado por ACE)aiLib.addCommandaddCommandaddCommand
Una línea de log en los canales del propietarioaiLib.aiLogaiLogaiLog

Qué script responde a cada uno de estos en este servidor, y la lista de adaptadores: Capas y el bridge. Cada función con su firma, parámetros y retorno: Referencia de la API.

Nunca consultes las tablas de AI Core. ai_core_characters, ai_core_accounts, ai_core_character_jobs, ai_vehicles_owned y las demás tablas ai_* son internas: los personajes, el dinero, los trabajos y los vehículos viven en memoria y se escriben según el calendario de ai-core, así que un SELECT directo puede estar desactualizado y una columna puede cambiar en cualquier versión. Pregúntale a ai-core - responde igual para un jugador cargado que para un personaje guardado (personajes, dinero, trabajos). Lo mismo vale para los archivos de datos de otro script ai-* (data/*.json de su panel de administración): son el contenido del panel, no una interfaz.

Un citizenid no es un id de personaje. Hay dos ids: el id del personaje (charId, un número) y el citizenid (texto) que usan los scripts de otros frameworks. Nunca conviertas uno en el otro por tu cuenta - pregúntale a ai-core (GetCharIdByCitizenId, GetSourceByCitizenId, GetSourceByCharId): Personajes.

Detectar AI Core

Lua
local onAiCore = GetResourceState('ai-core') == 'started'

En TypeScript la lib lo hace por ti: isResourceStarted("ai-core"), o optionalExport("ai-core"), que es null mientras el resource está detenido (exports).

Un script que soporta varios frameworks también encuentra qbx_core, qb-core y es_extended arrancados, porque ai-core los provee. Ese camino funciona, pero solo alcanza lo que esas API pueden decir. Comprueba ai-core antes que los nombres de los frameworks y toma el camino de AI Core cuando esté; deja el código del framework como respaldo para otros servidores.

Las reglas con las que se juzga tu script

Son las mismas reglas que sigue cada script ai-* (Visión general), y lo que mira una revisión:

El servidor decide

Cada petición del cliente pasa por la puerta de la lib: un límite de frecuencia, una llamada a la vez (lock), una comprobación ACE y, en TypeScript, además guardas (admin, tiene personaje, cerca de un punto) y un analizador de argumentos. El dinero, los objetos y los permisos nunca cambian en el cliente, y un valor del cliente nunca se usa tal como llega: en Lua compruebas cada argumento tú mismo.

server.lua
aiLib.onClientCallback('myshop:buy', function(source, item)
    if type(item) ~= 'string' or #item > 32 then return aiLib.fail('CORE_ERR_ARGS') end
    if not aiLib.inventory.canCarryItem(source, item, 1) then return aiLib.fail('INVENTORY_FULL') end
    -- cobra el dinero y entrega el objeto aquí, en el servidor
    return { ok = true }
end, { rate = { count = 5, windowMs = 10000 }, lock = true })

Entrada del cliente, los lectores estrictos de TypeScript (readText, oneArg) y los rechazos (fail, ActionResult).

Snapshot y luego deltas

Los datos vivos van una vez completos a un cliente, luego solo lo que cambió, y solo a los jugadores que lo necesitan. Sin sondeo, sin señales de "algo cambió, vuelve a pedirlo", sin tráfico en cada tick. State bags para valores por entidad y por jugador, AreaStream para objetos del mundo, state bags para el resto.

Los ajustes en el panel de administración

El propietario de un servidor no debería editar Lua. La pantalla de ajustes de tu script consigue una tarjeta en el panel de ai-core con una sola llamada, así el propietario encuentra los ajustes de todos los scripts en un solo lugar:

server.lua
exports['ai-core']:RegisterExternalPanel({
    label = 'My script',
    icon = 'gear',
    description = 'Shops, prices and rewards',
    command = 'myscriptconfig',
})

Un script que no puedes modificar se lista con las líneas ai_admin_label / ai_admin_command de su fxmanifest.lua: RegisterExternalPanel. Los comandos registrados con aiLib.addCommand y las teclas creadas con aiLib.Keybind aparecen por sí solos en las listas de comandos y teclas del panel.

Tus propios datos son tuyos

Las tablas de tu resource son tu asunto: nómbralas según tu resource (myscript_*) y créalas al arrancar. Los resources Lua usan ai-mysql, que sustituye a oxmysql, mysql-async y ghmattimysql (MySQL.query.await, MySQL.single.await), así que tus consultas actuales siguen funcionando. Un resource que lee la cadena de conexión por su cuenta necesita además una línea en env.cfg:

env.cfg
add_convar_permission my-resource read mysql_connection_string

Ver La base de datos.

Antes de publicar

  • ai-lib (o @aifivem/lib) cargada, dependency 'ai-lib' en el manifest.
  • Ningún export de otro script para objetos, llaves, dinero, trabajos, teléfono, avisos, ropa, combustible, puertas, garajes o la cárcel.
  • Ninguna consulta contra una tabla ai_* de AI Core, y ninguna lectura del data/*.json de otro script.
  • Cada petición del cliente con límite de frecuencia y comprobada en el servidor.
  • Datos vivos como snapshot y deltas.
  • Ajustes en el panel, textos en tus propios archivos de idioma (locale).
  • Probado con los scripts ai-* que toca la función y, cuando hay una capa en juego, también con la elección del servidor cambiada (otro inventario, otro sistema de llaves).

En esta página