Integrar o seu próprio script
Como o seu resource funciona com o AI Core - carregar a lib, chamar as camadas em vez de outros scripts, o que nunca se deve tocar e a lista de verificação antes de publicar.
O seu script não precisa de ser um script ai-* para funcionar com o AI Core. O que tem de fazer depende do que está a escrever:
| O que tem | O que fazer |
|---|---|
| Um script escrito para ESX, QBCore, Qbox ou vRP | Nada. O AI Core fornece es_extended, qb-core, qbx_core e vrp e responde à API deles, por isso o script corre sem alterações. Ver Compatibilidade. |
| O seu próprio resource novo (Lua, TypeScript ou JavaScript simples) | Carregar a lib e chamar o AI Core através dela. É disso que trata esta página. |
| Um script que fornece algo de que outros scripts precisam (um inventário, um telefone, um sistema de chaves, uma garagem, um script de combustível...) | O mesmo que acima, mais um adaptador nessa camada para que o resto do servidor o alcance. Ver Scripts recomendados. |
O objetivo numa frase: tudo o que o seu script partilha com outro script passa pela lib ou pelo ai-core, nunca pelos exports desse script. Assim o dono pode trocar o inventário, o sistema de chaves ou o telefone e o seu script continua a funcionar.
Carregar a 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> fica depois disponível em todos os ficheiros do seu resource. A instalação completa, quais as chamadas que esperam, e como as tabelas e vetores de Lua passam para TypeScript: A lib para Lua.
TypeScript
import { inventory, onClientCallback } from "@aifivem/lib/server";A @aifivem/lib vem do npm: um resource fora do workspace do AI Core instala-a com bun install @aifivem/lib @aifivem/shared. Um resource de JavaScript simples, sem passo de build, carrega @ai-lib/dist/server.js e usa o mesmo aiLib global.
Ordem de arranque
O ai-core e o ai-lib arrancam antes do seu resource:
ensure ai-core
ensure ai-lib
ensure my-resourceChame o AI Core, não o outro script
Cada tarefa partilhada tem uma só porta. A chamada da lib e o export do ai-core fazem o mesmo; use o que servir a sua linguagem.
| O que precisa | Lua | TypeScript | Referência |
|---|---|---|---|
| Dar, retirar, contar itens | aiLib.inventory.addItem | inventory.addItem | Itens, itens do ai-core |
| Um item usável | aiLib.inventory.registerUsableItem | inventory.registerUsableItem | registerUsableItem |
| Um depósito ou uma loja | aiLib.inventory.registerStash | inventory.registerStash | Itens |
| Chaves de veículo | aiLib.vehicleKeys.give / .has | vehicleKeys.give / .has | Veículos |
| Fazer aparecer um veículo (matrícula, combustível, aspeto, chaves e lugares numa chamada) | aiLib.spawnVehicle | spawnVehicle | spawnVehicle |
| Guardar na garagem ou enviar para o depósito | aiLib.garages.store | garages.store | garages.store |
| O dinheiro de um jogador | exports['ai-core']:AddMoney(src, 'cash', 50, 'reason') | core.AddMoney(...) | Dinheiro |
| Dinheiro entre duas contas, numa transação | aiLib.money.transfer | money.transfer | money.transfer |
| Empregos, gangues, serviço | exports['ai-core']:SetJob(src, 'police', 2) | core.SetJob(...) | Empregos e gangues |
| Quem está online, o nome, o emprego | aiLib.online.name | online.name | Jogadores |
| Um alerta policial | aiLib.dispatch.alert | dispatch.alert | dispatch.alert |
| A prisão | aiLib.prison.jail | prison.jail | prison.jail |
| Um registo no MDT | aiLib.mdt.record | mdt.record | mdt.record |
| Reanimar, curar, "está morto" | aiLib.medical.revive | medical.revive | medical.revive |
| O telefone (número, mail, mensagem, notificação) | aiLib.phone.number | phone.number | Telefone |
| Um aspeto, uma roupa | aiLib.appearance.apply | appearance.apply | appearance.apply |
| Tempo e hora | aiLib.world.setWeather | world.setWeather | Mundo |
| Trancar uma porta | aiLib.doors.setLocked | doors.setLocked | doors.setLocked |
| Notificações, barras de progresso, menus, diálogos de entrada | aiLib.notify, aiLib.progress, aiLib.menu.show | notify, progress, menu | Interface comum |
| Uma entrada no menu radial | aiLib.radial.add | radial.add | radial.add |
| Um comando (listado no painel de administração, verificado por ACE) | aiLib.addCommand | addCommand | addCommand |
| Uma linha de log nos canais do dono | aiLib.aiLog | aiLog | aiLog |
Qual script responde a cada um destes neste servidor, e a lista de adaptadores: Camadas e a bridge. Cada função com a sua assinatura, parâmetros e retorno: Referência da API.
Nunca consulte as tabelas do AI Core. ai_core_characters, ai_core_accounts, ai_core_character_jobs, ai_vehicles_owned e as outras tabelas ai_* são internas: personagens, dinheiro, empregos e veículos vivem em memória e são escritos no calendário do próprio ai-core, por isso um SELECT direto pode estar desatualizado e uma coluna pode mudar em qualquer versão. Pergunte ao ai-core - ele responde tanto para um jogador carregado como para uma personagem guardada (personagens, dinheiro, empregos). O mesmo vale para os ficheiros de dados de outro script ai-* (data/*.json do painel dele): são o conteúdo do painel, não uma interface.
Um citizenid não é um id de personagem. Existem dois ids: o id da personagem (charId, um número) e o citizenid (texto) que os scripts de outras frameworks usam. Nunca converta um no outro por conta própria - pergunte ao ai-core (GetCharIdByCitizenId, GetSourceByCitizenId, GetSourceByCharId): Personagens.
Detetar o AI Core
local onAiCore = GetResourceState('ai-core') == 'started'Em TypeScript a lib faz isso por você: isResourceStarted("ai-core"), ou optionalExport("ai-core"), que é null enquanto o resource está parado (exports).
Um script que suporta várias frameworks encontra também qbx_core, qb-core e es_extended arrancados, porque o ai-core os fornece. Esse caminho funciona, mas só alcança o que essas API conseguem dizer. Verifique o ai-core antes dos nomes das frameworks e siga o caminho do AI Core quando ele existir; guarde o código da framework como recurso para outros servidores.
As regras pelas quais o seu script é avaliado
São as mesmas regras que cada script ai-* segue (Visão geral), e o que uma revisão olha:
O servidor decide
Cada pedido do cliente passa pela porta da lib: um limite de ritmo, uma chamada de cada vez (lock), uma verificação ACE e, em TypeScript, também guardas (admin, tem personagem, perto de um ponto) e um analisador de argumentos. Dinheiro, itens e permissões nunca mudam no cliente, e um valor do cliente nunca é usado como chega - em Lua verifica cada argumento você mesmo.
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
-- cobre o dinheiro e entregue o item aqui, no servidor
return { ok = true }
end, { rate = { count = 5, windowMs = 10000 }, lock = true })Entrada do cliente, os leitores estritos do TypeScript (readText, oneArg) e as recusas (fail, ActionResult).
Snapshot e depois deltas
Os dados vivos vão uma vez completos para um cliente, depois só o que mudou, e só para os jogadores que precisam. Sem sondagem, sem sinal de "algo mudou, busca outra vez", sem tráfego a cada tick. State bags para valores por entidade e por jogador, AreaStream para objetos do mundo, state bags para o resto.
Configurações no painel de administração
O dono de um servidor não devia editar Lua. O ecrã de configurações do seu script ganha um cartão no painel do ai-core com uma só chamada, para que o dono encontre as configurações de todos os scripts num só lugar:
exports['ai-core']:RegisterExternalPanel({
label = 'My script',
icon = 'gear',
description = 'Shops, prices and rewards',
command = 'myscriptconfig',
})Um script que não pode alterar é listado com as linhas ai_admin_label / ai_admin_command no fxmanifest.lua dele: RegisterExternalPanel. Os comandos registados com aiLib.addCommand e as teclas feitas com aiLib.Keybind aparecem por si nas listas de comandos e teclas do painel.
Os seus dados são seus
As tabelas do seu resource são assunto seu: dê-lhes o nome do seu resource (myscript_*) e crie-as no arranque. Os resources Lua usam o ai-mysql, que substitui o oxmysql, o mysql-async e o ghmattimysql (MySQL.query.await, MySQL.single.await), por isso as consultas que já tem continuam a funcionar. Um resource que lê a string de ligação por si precisa também de uma linha no env.cfg:
add_convar_permission my-resource read mysql_connection_stringVer A base de dados.
Antes de publicar
ai-lib(ou@aifivem/lib) carregada,dependency 'ai-lib'no manifest.- Nenhum export de outro script para itens, chaves, dinheiro, empregos, telefone, alertas, roupa, combustível, portas, garagens ou a prisão.
- Nenhuma consulta a uma tabela
ai_*do AI Core e nenhuma leitura dodata/*.jsonde outro script. - Cada pedido do cliente com limite de ritmo e verificado no servidor.
- Dados vivos como snapshot e deltas.
- Configurações no painel, textos nos seus próprios ficheiros de idioma (locale).
- Testado com os scripts
ai-*que a funcionalidade toca e, quando há uma camada envolvida, também com a escolha do servidor trocada (outro inventário, outro sistema de chaves).
Referência da API
Cada export, evento e função da lib com a sua assinatura, parâmetros e retorno.
A lib para Lua
aiLib: instalação, as chamadas que esperam, tabelas e vetores de Lua a atravessar a fronteira do resource.
Camadas e a bridge
Qual script responde a cada camada e como funciona a bridge ESX / QB / Qbox.
Scripts recomendados
Conseguir que um script gratuito seja listado no painel e escrever o adaptador da sua camada.