Logo da L&M SYSTEMDocumentação
Sistemas

Integração MTA

Como o seu servidor MTA conversa com a L&M System. Explica o LMCore, a instalação dos mods, as API Keys, as atualizações em tempo real (webhook), as mensagens do console e a migração do MySQL para a L&M Cloud.

A integração é o que liga o seu servidor de jogo ao bot. Ela é feita por mods (resources) da L&M System instalados no servidor MTA e é exclusiva do MTA Avançado. No bot gratuito ela funciona do mesmo jeito.

Esta página explica a base que todos os mods compartilham: como eles se comunicam com a L&M System, como instalar, como funcionam as API Keys e o que fazer quando algo dá errado. O que cada sistema faz no jogo está na página dele: Allowlist e Whitelist, Player, Denúncia avançada, Métricas e Status Realtime. Para adaptar os mods ao seu gamemode, veja Para desenvolvedores.

Como funciona

A comunicação acontece em dois sentidos:

  • Do servidor para a L&M System. Os mods chamam a API da L&M System com a API Key de cada um. É assim que o servidor consulta se um jogador está liberado, busca as ações de ban e kick pendentes e envia o status e as métricas.
  • Da L&M System para o servidor. Quando algo muda no Discord (um jogador aprovado na whitelist ou um ban aplicado pelo /player), a L&M System avisa o servidor na hora, por um webhook recebido pelo LMCore. Esse aviso é opcional: sem ele, os mods continuam funcionando, só que descobrem a mudança na próxima consulta.
ModEnvia para a L&M SystemRecebe aviso na hora (webhook)
LMCoreFaz as chamadas de todos os outros mods, com limite de tempo e novas tentativasRecebe o webhook e repassa ao mod certo
Allowlist/WhitelistConsulta se o jogador está liberado e gera o código da tela de cadastroSim: o jogador é liberado assim que é aprovado
Game ActionBusca as ações pendentes (ban, unban e kick) e informa o resultadoSim: a ação é aplicada assim que é criada
MétricasEntradas, logins e jogadores onlineNão
Status RealtimeNome do servidor e jogadores onlineNão

Sem o webhook, a allowlist volta a consultar os jogadores pendentes a cada 30 segundos, e o Game Action busca a fila a cada 2 minutos. É por isso que uma ação do /player pode levar até 3 minutos sem ele.

Mods disponíveis

O LMCore é obrigatório: todos os outros mods dependem dele e não funcionam sem ele. Os demais você instala conforme os sistemas que for usar.

ModSistema da API KeyUsado por
LMCoreNenhum (não usa chave)Todos os mods
Allowlist/WhitelistAllowlist/WhitelistWhitelist automática, whitelist semi-automática e allowlist avançado
Game ActionGame ActionPlayer e denúncia avançada
MétricasMetrics MTAMétricas
Status RealtimeStatus RealtimeStatus Realtime

Os mods exigem o servidor MTA na versão 1.5.6-9.18728 ou mais nova.

Instalação

Baixe os mods

No Dashboard, abra o bot, escolha o servidor e vá em Integrações → MTA. O LMCore fica no topo, como base obrigatória, e os outros mods ficam abaixo. As telas de configuração de cada sistema no /config-bot também têm o botão Baixar Mod, que leva para a mesma página.

Instale o LMCore

  1. Extraia na pasta resources do servidor. A pasta precisa se chamar exatamente LMCore, porque os outros mods o procuram por esse nome.
  2. No config.lua, troque o webhook.secret por um valor aleatório e único deste servidor. A página de integrações tem um gerador. Nunca reaproveite o secret de outro servidor.
  3. Adicione resource.LMCore ao grupo Admin no acl.xml. Com isso o LMCore configura sozinho a permissão que o webhook precisa (veja Permissão no acl.xml).
  4. No mtaserver.conf, deixe o LMCore acima dos outros mods, para ele iniciar primeiro.

Gere uma API Key para cada mod

Em Integrações → API Key, clique em Criar API Key e escolha o contexto, que é o sistema do mod: Allowlist/Whitelist, Game Action, Metrics MTA ou Status Realtime. Cada mod usa a chave do próprio contexto. Veja API Keys.

Coloque cada mod no grupo Admin

Assim como o LMCore, cada mod precisa estar no grupo Admin do acl.xml. Sem essa permissão, o MTA bloqueia o que os mods precisam fazer, como banir e kickar jogadores, se desligar quando a chave é inválida e ler os dados do servidor.

No acl.xml, dentro do <group name="Admin">, adicione uma linha para o LMCore e para cada mod que você instalou:

<group name="Admin">
    <!-- ... o que já existe no grupo continua igual ... -->
    <object name="resource.LMCore"></object>
    <object name="resource.AllowlistSystem"></object>
    <object name="resource.GameAction"></object>
    <object name="resource.MetricsSystem"></object>
    <object name="resource.StatusSystem"></object>
</group>

O nome depois de resource. é o nome da pasta do mod. Se você renomeou alguma pasta, use o nome novo. Edite o acl.xml com o servidor desligado: com ele ligado, o MTA pode sobrescrever o arquivo e a mudança se perde.

Configure e inicie os mods

Extraia cada mod na pasta resources, cole a chave no campo apiKey do config.lua e inicie o mod (start NomeDoMod no console, ou pelo mtaserver.conf). Confira também o campo elementDataID dos mods que identificam jogadores (veja abaixo).

Confira o console

Ao iniciar, cada mod valida a chave e escreve no console do servidor:

  • "Sistema iniciado e autorizado com sucesso.": está tudo certo;
  • qualquer outra mensagem: veja Mensagens do console.

O campo elementDataID

Os mods Allowlist/Whitelist, Game Action e Métricas têm o campo elementDataID, que por padrão é ID. Ele é o nome da element data em que o seu gamemode guarda o ID do jogador depois do login, e serve para os mods saberem o ID de cada jogador.

Se o seu servidor usa outro nome (por exemplo id ou playerID), troque nos três mods. Se ele estiver errado, a allowlist pelo tipo ID não encontra ninguém, o Game Action não acha jogadores sem serial conhecido e as métricas registram os logins sem o ID.

Essa element data só existe depois do login no seu gamemode. Por isso a allowlist faz a verificação no login, e não na entrada do jogador no servidor.

API Keys

A API Key é a senha que identifica o seu servidor para a L&M System. Cada chave pertence a um servidor do Discord e a um contexto, e só funciona nos endereços daquele contexto. A chave da allowlist, por exemplo, é recusada pelo Game Action.

A tabela em Integrações → API Key mostra cada chave mascarada (com o botão de copiar), o contexto, o status e a data de criação.

StatusO que significa
InativoA chave foi criada, mas nenhum mod usou ainda
AtivoUm mod já usou a chave. Ela muda sozinha para ativo na primeira chamada
RevogadaA chave foi bloqueada pela administração da L&M System e não funciona mais. Gere uma nova

Também dá para trocar o contexto de uma chave pela própria tabela e excluir uma chave. Ao excluir, as chamadas do mod que usava a chave passam a ser recusadas, e ele se desliga na próxima validação (o Game Action fica inativo).

Chaves criadas para sistemas antigos (Whitelist Automática, Whitelist Semi-Automática, Allowlist Avançado, Ban In Game e Denúncia Avançada, todos marcados como legacy) continuam aparecendo com o contexto antigo. As versões atuais dos mods usam só os quatro contextos da instalação.

Trate a API Key como senha

Quem tiver a chave pode agir em nome do seu servidor, por exemplo liberando jogadores ou enviando dados falsos. Não compartilhe nem publique o config.lua com a chave preenchida. Se ela vazar, exclua a chave, gere uma nova e troque no mod.

Validação da chave

Cada mod valida a sua chave ao iniciar e depois a cada 12 horas:

  • Chave ausente, inválida, revogada ou de outro contexto: o mod se desliga sozinho e registra o motivo no console. O Game Action é a exceção: ele continua carregado, mas fica inativo e não executa nenhuma ação até a chave ser corrigida e o mod reiniciado.
  • L&M System fora do ar ou sem conexão: o mod não se desliga. Ele registra o erro e tenta de novo depois.

Aviso de mod desatualizado

A cada chamada, o mod informa a versão dele. Quando essa versão fica abaixo da mínima aceita pela L&M System, aparece no console:

O resource 'NomeDoMod' está desatualizado. Atualize para a versão X.

O mod continua funcionando: o aviso é só para você atualizar. Baixe a versão nova em Integrações → MTA, use o config.lua novo (ele pode ter campos que não existiam) e copie para ele os seus valores, como a apiKey e o elementDataID.

Atualizações em tempo real (webhook)

Como o servidor é registrado

Quando o Allowlist/Whitelist e o Game Action validam a chave (ao iniciar e a cada 12 horas), eles informam à L&M System a porta HTTP do servidor e o caminho do webhook. O IP é sempre o de onde a chamada partiu, nunca um valor informado pelo mod. Antes de salvar, a L&M System envia um teste para esse endereço. Se o teste falhar, o webhook não é ativado e os mods seguem só com as consultas periódicas.

Se você corrigiu a porta, o firewall ou o secret, reinicie os mods (ou espere a próxima validação) para o servidor ser registrado de novo.

Requisitos

  • Servidor HTTP do MTA ativo: httpserver ligado no mtaserver.conf, que é o padrão.
  • Porta HTTP acessível pela internet: a httpport do mtaserver.conf (padrão 22005) precisa estar liberada no firewall e na hospedagem.
  • webhook.secret configurado: com o valor de exemplo do pacote, o LMCore recusa todo aviso e não ativa o webhook.
  • webhook.enabled em true no config.lua do LMCore, que é o padrão.

Segurança

Cada aviso é assinado com o seu webhook.secret (HMAC SHA-256). O LMCore recusa avisos sem assinatura, com assinatura errada, fora da janela de 5 minutos ou repetidos. Por isso o secret precisa ser único por servidor e não pode vazar: quem o tiver consegue forjar avisos.

Mesmo com um aviso válido, o mod não confia no conteúdo dele. O aviso da allowlist só faz o mod consultar a L&M System de novo antes de liberar o jogador, e as ações do Game Action seguem as mesmas regras da fila.

Permissão no acl.xml

Para receber o webhook pela porta HTTP, o LMCore precisa que o acesso HTTP anônimo do MTA (a conta user.http_guest) possa abrir o hook.htm. Com autoProvisionAcl = true, que é o padrão no pacote, e com o LMCore no grupo Admin, ele cria sozinho este trecho no acl.xml:

<acl name="LMCore">
    <right name="general.http" access="true" />
    <right name="resource.LMCore.http" access="true" />
</acl>
<group name="LMCore">
    <acl name="LMCore" />
    <object name="user.http_guest" />
</group>

O general.http vale para o servidor todo

O general.http não é exclusivo do LMCore: ele libera o acesso HTTP anônimo ao servidor como um todo. Se algum outro resource seu tem resource.Nome.http liberado e contava com o general.http negado para ficar fechado, ele volta a ficar acessível pela porta HTTP. Se não quiser que o LMCore mexa na ACL, coloque autoProvisionAcl = false: ele passa a mostrar no console o trecho acima para você avaliar e colar à mão.

Mensagens do console

Os mods escrevem no console do servidor com o nome deles entre colchetes, por exemplo [AllowlistSystem] ou [GameAction]. As mensagens importantes sempre aparecem. As de acompanhamento só aparecem com devMode = true no config.lua, que é útil enquanto você testa e pode ser desligado depois.

MensagemO que fazer
Sistema iniciado e autorizado com sucesso.Nada, está funcionando
API Key não foi encontrada.O campo apiKey do config.lua está vazio. Cole a chave e reinicie o mod
API Key inválidaA chave não existe (foi digitada errada ou excluída). Confira em Integrações → API Key
API Key foi revogada pela administraçãoGere uma nova chave e troque no mod
Sistema "..." não permitido para essa rotaA chave é de outro contexto. Gere uma chave do contexto do mod
Sistema não autorizado...A chave não foi aceita. Confira se é a chave certa, do contexto certo
ElementData ID não foi encontrada.O campo elementDataID está vazio no config.lua
Erro ao se comunicar com a API. Servidor indisponívelA L&M System não respondeu ou o servidor está sem internet. O mod continua ligado e tenta de novo depois
O resource '...' está desatualizado.Baixe a versão nova do mod. Ele continua funcionando até lá
webhook.enabled=true mas webhook.secret está vazio ou com o placeholder.Gere um secret e coloque no config.lua do LMCore
Não foi possível criar a ACL LMCore.Adicione resource.LMCore ao grupo Admin no acl.xml
webhook.enabled=true mas autoProvisionAcl não está true.Cole à mão o trecho de ACL mostrado no console, ou ligue o autoProvisionAcl
Access denied (com o nome de uma função do MTA, como banPlayer)O mod não está no grupo Admin. Veja Coloque cada mod no grupo Admin

Se nada aparece no console depois de iniciar um mod, confira se o LMCore está rodando: os outros mods dependem dele para qualquer chamada.

Migração do MySQL para a L&M Cloud

As versões antigas da whitelist, da allowlist avançado e das métricas guardavam os dados no MySQL do seu servidor. Quem configurou assim continua funcionando, mas pode migrar para a L&M Cloud, onde os dados ficam com a L&M System e aparecem no dashboard.

A migração fica na aba Migração da tela de cada sistema, no /config-bot. Ela só aparece enquanto o sistema ainda usa o MySQL.

Entenda o que muda

A migração copia todos os registros do seu MySQL para a L&M Cloud. Na whitelist e na allowlist, ela também conecta os jogadores ao cadastro de players da L&M, usado pelo Player. No fim, ela apaga daqui as credenciais do seu banco. O seu banco não é alterado: ele só deixa de ser usado pelo bot.

Gere uma nova API Key (whitelist e allowlist)

As versões novas usam uma chave só para todo o contexto Allowlist/Whitelist, em vez de uma por sistema. Gere essa chave em Integrações → API Key antes de instalar o mod novo.

Atualize o mod (whitelist e allowlist)

Instale a versão 3 do mod Allowlist/Whitelist com a chave nova. A versão antiga lê o MySQL direto e para de funcionar depois da migração.

Confirme

Clique em Migrar e confirme no modal. No fim, o bot mostra quantos registros foram migrados do total.

A migração é feita na hora e não pode ser desfeita. Nas métricas, os relatórios de jogadores novos, recorrentes e de retenção e o alerta de queda só valem para os dados registrados depois da migração.