AI Core

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 temO que fazer
Um script escrito para ESX, QBCore, Qbox ou vRPNada. 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

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> 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

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

A @aicore8/lib vem do npm: um resource fora do workspace do AI Core instala-a com bun install @aicore8/lib @aicore8/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:

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

Chame 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 precisaLuaTypeScriptReferência
Dar, retirar, contar itensaiLib.inventory.addIteminventory.addItemItens, itens do ai-core
Um item usávelaiLib.inventory.registerUsableIteminventory.registerUsableItemregisterUsableItem
Um depósito ou uma lojaaiLib.inventory.registerStashinventory.registerStashItens
Chaves de veículoaiLib.vehicleKeys.give / .hasvehicleKeys.give / .hasVeículos
Fazer aparecer um veículo (matrícula, combustível, aspeto, chaves e lugares numa chamada)aiLib.spawnVehiclespawnVehiclespawnVehicle
Guardar na garagem ou enviar para o depósitoaiLib.garages.storegarages.storegarages.store
O dinheiro de um jogadorexports['ai-core']:AddMoney(src, 'cash', 50, 'reason')core.AddMoney(...)Dinheiro
Dinheiro entre duas contas, numa transaçãoaiLib.money.transfermoney.transfermoney.transfer
Empregos, gangues, serviçoexports['ai-core']:SetJob(src, 'police', 2)core.SetJob(...)Empregos e gangues
Quem está online, o nome, o empregoaiLib.online.nameonline.nameJogadores
Um alerta policialaiLib.dispatch.alertdispatch.alertdispatch.alert
A prisãoaiLib.prison.jailprison.jailprison.jail
Um registo no MDTaiLib.mdt.recordmdt.recordmdt.record
Reanimar, curar, "está morto"aiLib.medical.revivemedical.revivemedical.revive
O telefone (número, mail, mensagem, notificação)aiLib.phone.numberphone.numberTelefone
Um aspeto, uma roupaaiLib.appearance.applyappearance.applyappearance.apply
Tempo e horaaiLib.world.setWeatherworld.setWeatherMundo
Trancar uma portaaiLib.doors.setLockeddoors.setLockeddoors.setLocked
Notificações, barras de progresso, menus, diálogos de entradaaiLib.notify, aiLib.progress, aiLib.menu.shownotify, progress, menuInterface comum
Uma entrada no menu radialaiLib.radial.addradial.addradial.add
Um comando (listado no painel de administração, verificado por ACE)aiLib.addCommandaddCommandaddCommand
Uma linha de log nos canais do donoaiLib.aiLogaiLogaiLog

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

Lua
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.

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
    -- 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:

server.lua
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:

env.cfg
add_convar_permission my-resource read mysql_connection_string

Ver A base de dados.

Antes de publicar

  • ai-lib (ou @aicore8/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 do data/*.json de 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).

Nesta página