AI Core
Referência da APIAI Core: exports de servidor

Exports de servidor

Como chamar os exports de servidor do ai-core de Lua e TypeScript, e a lista de cada grupo de exports.

O ai-core é o recurso do framework. Os outros recursos pedem a ele o personagem, o dinheiro, os empregos e os itens de um jogador, e mandam trabalho para ele como "dê uma chave a este jogador" ou "envie um alerta à polícia". Eles fazem isso por exports: funções que o ai-core torna chamáveis por qualquer outro recurso do servidor.

Estas páginas listam cada export de servidor que o ai-core registra, agrupados por tema. Cada entrada mostra o que o export faz, a assinatura exata, cada parâmetro, o que ele retorna em cada caso e um exemplo funcional em TypeScript e Lua.

Chamando um export

Um export é chamado pelo nome do recurso que o possui (ai-core) e pelo nome do export.

import { resourceExport } from "@aicore8/lib/server";

// Um handle tipado por arquivo, no topo. Aqui é seguro: o FiveM procura cada
// export no primeiro uso e o esquece quando o ai-core reinicia.
const core = resourceExport("ai-core");

export function cashOf(source: number): number {
  return core.GetMoney(source, "cash") ?? 0;
}

O que saber antes de começar:

  • Tipos de TypeScript. resourceExport("ai-core") é tipado a partir de AiCoreServerExports em @aicore8/shared, então seu editor conhece cada nome, parâmetro e tipo de retorno. Nunca escreva resourceExport("ai-core").GetMoney(...) dentro de uma função: mantenha o único handle no topo do arquivo.
  • Lua usa dois-pontos. Escreva exports['ai-core']:GetMoney(source, 'cash'), não um ponto. Uma resposta null chega em Lua como nil, um array como uma lista Lua (índice 1 primeiro), um objeto como uma table.
  • Duas grafias. Cada export também responde com a primeira letra na caixa trocada: GetMoney e getMoney são a mesma função.
  • Exports nunca esperam. Cada export responde na hora com um valor pequeno. Quando a resposta precisa do banco de dados (um visual salvo, uma lista de faturas), o export recebe um callback done em vez de retornar uma Promise, porque uma Promise não consegue passar de um recurso para outro.
  • Fora dos caminhos quentes. Uma chamada de export copia os argumentos e a resposta. Não chame exports a cada frame ou para cada jogador num loop. Para "quem está em serviço", o nome ou os empregos de um personagem em muitos jogadores, use o espelho online da lib, que segue os eventos do ai-core (Lib: servidor).
  • O ai-core precisa rodar primeiro. Coloque dependency 'ai-core' no seu fxmanifest.lua (um recurso ai-* o lista em fxDependencies no package.json), para que seu recurso inicie depois do ai-core.
  • source é o id de servidor do jogador. É o número que o FiveM dá a um jogador conectado. Um id de personagem (charId) é outro número: o id da linha do personagem no banco de dados.

A lib ou o export?

A maioria dos exports tem um wrapper em @aicore8/lib/server (e muitos no aiLib do Lua). O wrapper chama o mesmo export, então o comportamento é idêntico; ele só fica mais legível (inventory.addItem(source, "water") em vez de core.AddItem(source, "water")) e transforma callbacks em Promises onde isso é seguro. Cada entrada nomeia o seu wrapper na linha Lib. Use o que preferir; um recurso em Lua sem o ai-lib chama o export diretamente.

Exemplos nestas páginas

Os exemplos são arquivos de servidor completos. Os exemplos em TypeScript usam addCommand e onClientCallback da lib; os exemplos em Lua usam aiLib.addCommand e aiLib.onClientCallback do ai-lib, que precisam destas linhas no seu fxmanifest.lua:

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

Chamadas de Lua que esperam (aiLib.progressFor, Wait) só funcionam dentro de uma thread; handlers de comandos e callbacks já rodam numa.

Tipos

Os tipos que aparecem em várias páginas (CharacterInfo, InventoryRef, DispatchAlert...) são documentados uma vez com cada campo na página Tipos e linkados a partir de cada entrada que os usa.

Grupos de exports

Personagens e jogadores

Dados do jogador, personagens, busca por id de servidor, troca de personagem, posições offline, jogadores no escopo.

Personagens guardadas

Qualquer personagem, carregada ou não: encontrá-la, lê-la, o seu dinheiro, empregos, gangues, metadados, nome, tempo de jogo, guardá-la, apagá-la.

Dinheiro e contas

Saldos, adicionar e remover dinheiro, contas de empregos e gangues, transferências, tipos de conta.

Empregos e gangues

Vínculos, serviço, cargos, contagens de quem está em serviço, horário nobre, definições de empregos e gangues.

Metadata e configurações

O saco de metadata de um personagem, a identidade visual do servidor, scripts desatualizados.

Itens

Adicionar, remover, contar e verificar itens, baús, lojas de scripts, itens usáveis, definições de itens.

Chaves de veículos

Dar, remover e verificar chaves de veículos pelo script de chaves que estiver rodando.

Combustível

Ler e definir o combustível de um veículo pelo script de combustível que estiver rodando.

Fechaduras de portas

Trancar, destrancar e ler portas pelo script de fechaduras que estiver rodando.

Garagens

Apreender, guardar, abrir um menu de garagem, listar os veículos guardados de um jogador.

Médico

Reviver, curar e verificar se um jogador está caído.

EMS

Quantos médicos estão livres, chamados de socorro.

Aparência

O visual salvo de um personagem a partir do script de roupas que estiver rodando.

Celular

Números de celular, e-mails, mensagens de texto e notificações do celular.

Dispatch

Alertas para a polícia e para empregos pelo sistema de alertas que estiver rodando.

MDT

Multas, mandados, prisões e registros de cadeia no MDT da polícia.

Prisão

Prender, soltar e tempo restante.

Banco

Abrir uma tela de banco, o saldo da sociedade de um emprego.

Faturas

Enviar faturas, listar e pagar as faturas em aberto de um jogador.

Estresse e necessidades

Adicionar ou aliviar estresse, repor fome e sede.

Hora e clima

Clima, hora do jogo, blackout e hora congelada.

Routing buckets

Pegar e devolver um routing bucket livre para um mundo separado.

Logs

Enviar logs ao Discord, Fivemanage, FiveM Stats e ao console.

Verificações de conexão

Verificações que todo jogador que conecta passa, scripts que substituem outros.

Painel de administração e comandos

Registro de painéis, a aba Commands, listas de consulta, telas de configuração externas.

Ponte vRP

Exports que a ponte vRP embutida do ai-core usa.

Páginas relacionadas

  • Exports de cliente: o que o ai-core responde no próprio jogo do jogador.
  • Eventos e estado: os eventos que o ai-core dispara (ai-core:playerLoaded, ai-core:moneyChanged...), que deixam seu recurso seguir as mudanças em vez de perguntar de novo.
  • Lib: servidor: os wrappers nomeados em cada entrada.

Nesta página