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.
| Mod | Envia para a L&M System | Recebe aviso na hora (webhook) |
|---|---|---|
| LMCore | Faz as chamadas de todos os outros mods, com limite de tempo e novas tentativas | Recebe o webhook e repassa ao mod certo |
| Allowlist/Whitelist | Consulta se o jogador está liberado e gera o código da tela de cadastro | Sim: o jogador é liberado assim que é aprovado |
| Game Action | Busca as ações pendentes (ban, unban e kick) e informa o resultado | Sim: a ação é aplicada assim que é criada |
| Métricas | Entradas, logins e jogadores online | Não |
| Status Realtime | Nome do servidor e jogadores online | Nã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.
| Mod | Sistema da API Key | Usado por |
|---|---|---|
| LMCore | Nenhum (não usa chave) | Todos os mods |
| Allowlist/Whitelist | Allowlist/Whitelist | Whitelist automática, whitelist semi-automática e allowlist avançado |
| Game Action | Game Action | Player e denúncia avançada |
| Métricas | Metrics MTA | Métricas |
| Status Realtime | Status Realtime | Status 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
- Extraia na pasta
resourcesdo servidor. A pasta precisa se chamar exatamenteLMCore, porque os outros mods o procuram por esse nome. - No
config.lua, troque owebhook.secretpor um valor aleatório e único deste servidor. A página de integrações tem um gerador. Nunca reaproveite o secret de outro servidor. - Adicione
resource.LMCoreao grupo Admin noacl.xml. Com isso o LMCore configura sozinho a permissão que o webhook precisa (veja Permissão no acl.xml). - 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.
| Status | O que significa |
|---|---|
| Inativo | A chave foi criada, mas nenhum mod usou ainda |
| Ativo | Um mod já usou a chave. Ela muda sozinha para ativo na primeira chamada |
| Revogada | A 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:
httpserverligado nomtaserver.conf, que é o padrão. - Porta HTTP acessível pela internet: a
httpportdomtaserver.conf(padrão22005) precisa estar liberada no firewall e na hospedagem. webhook.secretconfigurado: com o valor de exemplo do pacote, o LMCore recusa todo aviso e não ativa o webhook.webhook.enabledemtruenoconfig.luado 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.
| Mensagem | O 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álida | A chave não existe (foi digitada errada ou excluída). Confira em Integrações → API Key |
| API Key foi revogada pela administração | Gere uma nova chave e troque no mod |
| Sistema "..." não permitido para essa rota | A 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ível | A 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.
Anúncios
Como montar, publicar e agendar anúncios com o /anuncio. Inclui os limites do bot gratuito e dos planos pagos, variáveis, dias da semana, limite de envios, publicar nos seguidores, fixar a mensagem e envio em vários canais.
Allowlist e Whitelist
Como liberar a entrada dos jogadores no servidor MTA pelo Discord. Explica a whitelist automática, a whitelist semi-automática e a allowlist avançado, a tela de cadastro no jogo, os tipos de identificação e como gerenciar a lista.
