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 tienes | Qué hacer |
|---|---|
| Un script escrito para ESX, QBCore, Qbox o vRP | Nada. 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
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
import { inventory, onClientCallback } from "@aicore8/lib/server";@aicore8/lib viene de npm: un resource fuera del workspace de AI Core la instala con bun install @aicore8/lib @aicore8/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:
ensure ai-core
ensure ai-lib
ensure my-resourceLlama 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 necesitas | Lua | TypeScript | Referencia |
|---|---|---|---|
| Dar, quitar, contar objetos | aiLib.inventory.addItem | inventory.addItem | Objetos, objetos de ai-core |
| Un objeto usable | aiLib.inventory.registerUsableItem | inventory.registerUsableItem | registerUsableItem |
| Un alijo o una tienda | aiLib.inventory.registerStash | inventory.registerStash | Objetos |
| Llaves de vehículo | aiLib.vehicleKeys.give / .has | vehicleKeys.give / .has | Vehículos |
| Aparecer un vehículo (matrícula, combustible, aspecto, llaves y asientos en una llamada) | aiLib.spawnVehicle | spawnVehicle | spawnVehicle |
| Guardar en garaje o llevar al depósito | aiLib.garages.store | garages.store | garages.store |
| El dinero de un jugador | exports['ai-core']:AddMoney(src, 'cash', 50, 'reason') | core.AddMoney(...) | Dinero |
| Dinero entre dos cuentas, en una transacción | aiLib.money.transfer | money.transfer | money.transfer |
| Trabajos, bandas, servicio | exports['ai-core']:SetJob(src, 'police', 2) | core.SetJob(...) | Trabajos y bandas |
| Quién está en línea, su nombre, su trabajo | aiLib.online.name | online.name | Jugadores |
| Un aviso policial | aiLib.dispatch.alert | dispatch.alert | dispatch.alert |
| La cárcel | aiLib.prison.jail | prison.jail | prison.jail |
| Un registro en el MDT | aiLib.mdt.record | mdt.record | mdt.record |
| Revivir, curar, "está muerto" | aiLib.medical.revive | medical.revive | medical.revive |
| El teléfono (número, correo, mensaje, notificación) | aiLib.phone.number | phone.number | Teléfono |
| Un aspecto, un conjunto de ropa | aiLib.appearance.apply | appearance.apply | appearance.apply |
| Clima y hora | aiLib.world.setWeather | world.setWeather | Mundo |
| Cerrar una puerta | aiLib.doors.setLocked | doors.setLocked | doors.setLocked |
| Notificaciones, barras de progreso, menús, diálogos de entrada | aiLib.notify, aiLib.progress, aiLib.menu.show | notify, progress, menu | Interfaz común |
| Una entrada del menú radial | aiLib.radial.add | radial.add | radial.add |
| Un comando (listado en el panel de administración, comprobado por ACE) | aiLib.addCommand | addCommand | addCommand |
| Una línea de log en los canales del propietario | aiLib.aiLog | aiLog | aiLog |
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
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.
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:
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:
add_convar_permission my-resource read mysql_connection_stringVer La base de datos.
Antes de publicar
ai-lib(o@aicore8/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 deldata/*.jsonde 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).
Referencia de la API
Cada export, evento y función de la lib con su firma, parámetros y retorno.
La lib para Lua
aiLib: instalación, las llamadas que esperan, tablas y vectores de Lua cruzando la frontera del resource.
Capas y el bridge
Qué script responde a cada capa y cómo funciona el bridge de ESX / QB / Qbox.
Scripts recomendados
Conseguir que un script gratuito se liste en el panel y escribir el adaptador de su capa.