Para desenvolvedores
Guia técnico para quem desenvolve o servidor MTA e quer integrar ou adaptar os mods da L&M System ao seu gamemode. Mostra o que pode ser editado, os exports e eventos da allowlist, como usar uma tela própria, como trocar o sistema de ban do Game Action e como ouvir o webhook do LMCore.
Esta página é para quem desenvolve o servidor MTA: quem escreve o gamemode, tem resources próprios e quer que os mods da L&M System conversem com eles. Ela mostra o que dá para editar em cada mod, o que os mods oferecem para outros resources e os cuidados para não quebrar nada.
Se você só quer instalar e configurar, a página certa é a Integração MTA.
O que pode ser editado
Os mods são distribuídos compilados: a maior parte do código vem criptografada, e editar esses arquivos não funciona. Ficam abertos, de propósito, os arquivos pensados para você adaptar:
| Mod | Arquivos abertos | Para quê |
|---|---|---|
| LMCore | config.lua | Configurar o webhook |
| Allowlist/Whitelist | config.lua, server/main.lua e os temas em client/themes/* (HTML, CSS e JS) | Configurar, decidir quando o jogador é verificado e mudar o visual da tela |
| Game Action | config.lua e server/actions/ban.lua, kick.lua e unban.lua | Configurar e trocar como o ban, o desban e o kick são aplicados |
| Métricas | config.lua | Configurar |
| Status Realtime | config.lua | Configurar |
Atualizar o mod apaga as suas mudanças
Ao atualizar um mod, a versão nova substitui os arquivos, inclusive os que você editou. Guarde uma cópia das suas mudanças e aplique de novo na versão nova, comparando os arquivos, porque eles podem ter mudado.
Regras que valem para todos
- Não renomeie as pastas
LMCoreeAllowlistSystem. Os mods chamam o LMCore porexports.LMCore, e os seus resources vão chamar a allowlist porexports.AllowlistSystem. - Não mude a ordem dos scripts no
meta.xml. Os arquivos de cada mod dependem uns dos outros na ordem em que carregam. - Toda configuração passa pelo
config.lua, pela funçãogetSettings(). Não espalhe valores fixos pelo código. - Os logs de acompanhamento só aparecem com
devMode = true. No cliente, usedebugscript 3para ver os da tela.
Login próprio no gamemode
Este é o ponto que mais exige atenção. A allowlist e as métricas usam o evento onPlayerLogin do MTA, que só dispara quando o gamemode usa as contas do MTA (a função logIn).
Muitos gamemodes de roleplay têm um login próprio, com banco de dados e tela de personagem, e nunca chamam logIn. Nesse caso:
- a allowlist nunca verifica o jogador ao entrar, e a conferência a cada 30 minutos ignora quem está como convidado (guest);
- as métricas não registram os logins (as entradas continuam).
Há duas saídas:
- Chamar
logInno seu login próprio, com uma conta do MTA para o jogador. Assim tudo funciona sem editar os mods. - Avisar a allowlist você mesmo, editando o
server/main.luado AllowlistSystem (veja abaixo). Essa saída não resolve os logins das métricas.
Em qualquer caso, a element data do ID (elementDataID) precisa estar preenchida antes da verificação nos tipos ID e CODE_ID.
Allowlist/Whitelist
Mudar quando o jogador é verificado
O server/main.lua liga os eventos do servidor ao fluxo da allowlist. Por padrão, ele verifica o jogador no onPlayerLogin:
addEventHandler("onPlayerLogin", root, function()
AllowlistFlow.verifyPlayer(source)
end)Se o seu gamemode tem outro momento certo para isso (por exemplo, depois de escolher o personagem), troque o evento pelo seu. O AllowlistFlow.verifyPlayer(player) faz tudo: consulta a L&M System, trava ou libera o jogador e abre ou fecha a tela.
-- exemplo: o seu gamemode dispara "meuGamemode:personagemCarregado" no servidor
addEvent("meuGamemode:personagemCarregado")
addEventHandler("meuGamemode:personagemCarregado", root, function()
AllowlistFlow.verifyPlayer(source)
end)O mesmo arquivo tem a conferência a cada 30 minutos de quem já está jogando, que pula as contas de convidado (isGuestAccount). Com login próprio, ajuste essa condição para o jeito como o seu gamemode sabe que o jogador está logado. Mantenha também o onPlayerQuit, que limpa o estado do jogador, e o handler de allowlist:attemptClose, usado pela tela.
Consultar a lista em outros resources
O mod tem três exports no servidor, para os seus resources consultarem a lista sem mexer na allowlist:
| Export | O que faz |
|---|---|
requestAllowlistVerifyById(id, requestTag, serial) | Consulta pelo ID do jogo. O serial é opcional |
requestAllowlistVerifyBySerial(serial, requestTag, gameId) | Consulta pelo serial. O gameId é opcional |
requestAllowlistGenerateCode(serial, requestTag, gameId) | Gera um código de cadastro. Precisa do serial ou do gameId |
Os três retornam na hora um requestId. A resposta chega depois, no evento de servidor allowlistcore:result, disparado em root. Filtre pelo requestId e remova o handler quando a resposta chegar:
local requestId = exports.AllowlistSystem:requestAllowlistVerifyBySerial(getPlayerSerial(player), "meu-resource")
local handler
handler = function(result)
if not result or result.requestId ~= requestId then
return
end
removeEventHandler("allowlistcore:result", root, handler)
if result.allowed then
-- jogador liberado
elseif result.status == "pending" then
-- cadastro em análise
else
-- "none", "rejected" ou "revoked": sem liberação
end
end
addEventHandler("allowlistcore:result", root, handler)A resposta da verificação traz:
| Campo | O que é |
|---|---|
allowed | Use este para decidir se o jogador entra (true ou false) |
status | A situação, para mostrar ou registrar: none, pending, approved, rejected ou revoked |
kind | verifyId ou verifySerial |
requestTag | O texto que você mandou, para saber de onde veio |
player | O cadastro: gameId, serial, discordId e playerName (este último pode não vir) |
allowlist | O registro da liberação, com o status |
Na geração de código, a resposta tem kind = "generateCode", ok e code. O código vale só no seu servidor, é de uso único e expira em 15 minutos: gere de novo se o jogador continuar esperando. Gere código só quando o status for none, rejected ou revoked.
O arquivo doc.md, que vem junto com o mod, tem mais exemplos, incluindo o fluxo completo do tipo código.
Usar uma tela própria
Há dois caminhos, conforme o quanto você quer mudar.
Mudar o visual da tela atual. Os quatro temas ficam em client/themes/<tema>/ (default, red, aurora e light), cada um com ui.html, ui.css e ui.js, e são abertos no navegador do MTA (CEF). Edite os arquivos do tema escolhido no config.lua. Não dá para criar um tema com nome novo: personalize um dos quatro. Para a tela continuar funcionando, mantenha no ui.js:
- o objeto
window.AllowlistUI, com as funçõessetData(payload),setCopiedState(botao, copiado),showToast(mensagem, duracao)eresetCopiedState(), que o mod chama; - as chamadas
window.mta.triggerEvent(...)dos botões:allowlist:copyValue(copiar o código, serial ou ID),allowlist:copyLink(copiar o link do Discord) eallowlist:close(tentar fechar).
O setData recebe title, subtitle, instructionsTitle, instructions (lista), mainLabel, value, status, discordLink, showValue, showCopyValue, showDiscordButton e copyValueLabel.
Fazer a tela do zero, no seu resource. Coloque ui.enabled = false no config.lua. A tela padrão para de abrir, mas o bloqueio continua: o servidor segue congelando o personagem e desativando os controles até a liberação. O servidor continua enviando ao jogador os eventos de cliente allowlist:showUi e allowlist:hideUi, que a sua tela pode ouvir. O allowlist:showUi traz type (o tipo de identificação), status, value (o código ou o ID a mostrar, vazio no tipo SERIAL), showValue, showCopyValue e, nas situações em análise, reprovado e revogado, os textos title, subtitle, instructionsTitle e instructions do config.lua. Os textos da situação sem cadastro e o link do Discord ficam no config.lua (ui.* e linkDc). Para pedir o fechamento, dispare allowlist:attemptClose no servidor, a partir do elemento raiz do AllowlistSystem. A resposta volta nos eventos allowlist:closeAllowed ou allowlist:closeDenied.
A liberação é sempre decidida pelo servidor, com a resposta da L&M System. A tela só mostra. Mesmo que o cliente seja alterado para fechar a tela, o personagem continua travado.
Game Action: usar o seu sistema de ban
Por padrão, o Game Action usa os bans nativos do MTA (banPlayer, addBan e removeBan) e o kickPlayer. Se o seu servidor tem um sistema de ban próprio (por exemplo, com banco de dados e painel admin), edite os arquivos de server/actions/ para chamar o seu sistema.
Cada arquivo define uma ação com GameActionActions.define. Este é o kick.lua original:
GameActionActions.define("kick", {
requires = "player",
onFail = "Falha ao expulsar o player",
run = function(ctx)
return kickPlayer(ctx.player, "GameAction", ctx.reason) == true
end,
})| Campo | O que é |
|---|---|
requires | O que precisa existir antes de rodar: "player" (jogador online), "serial" ou "playerOrSerial". Sem isso, a ação falha com "Player não encontrado no servidor" |
onFail | A mensagem mostrada no Discord quando o run devolve false |
run(ctx) | Aplica a ação. Devolva true se deu certo e false se falhou |
O ctx traz:
| Campo | O que é |
|---|---|
ctx.player | O jogador online, se encontrado (pelo serial e depois pelo elementDataID), ou nil |
ctx.serial | O serial do cadastro, ou o do jogador online |
ctx.reason | O motivo informado no Discord |
ctx.payload.durationSeconds | Só no ban: a duração em segundos. 0 é permanente |
ctx.payload.player | O cadastro do jogador: gameId, serial, playerName e discordId |
Exemplo de ban usando um sistema próprio:
GameActionActions.define("ban", {
requires = "playerOrSerial",
onFail = "Falha ao efetuar o banimento",
run = function(ctx)
local gameId = ctx.payload.player and ctx.payload.player.gameId
local seconds = tonumber(ctx.payload.durationSeconds) or 0
-- troque pela função do seu sistema de ban
local ok = exports.MeuSistemaDeBan:banir(gameId, ctx.serial, ctx.reason, seconds)
if ok and ctx.player then
kickPlayer(ctx.player, "GameAction", ctx.reason)
end
return ok == true
end,
})Cuidados:
- O
runprecisa responder na hora, comtrueoufalse. Se o seu sistema grava no banco de forma assíncrona, devolvatruequando a gravação for disparada com sucesso. - A mesma ação pode chegar duas vezes (pelo webhook e pela busca a cada 2 minutos, se o aviso atrasar). Faça o
runaguentar isso: banir quem já está banido não deve dar erro. - Não dá para criar tipos de ação novos. A L&M System só envia
ban,unbanekick. - Se o seu
runusa funções restritas (comobanPlayerou o seu próprio resource com ACL), o Game Action continua precisando estar no grupo Admin doacl.xml.
LMCore: ouvir os avisos em tempo real
Quando o webhook está ativo, todo aviso recebido pelo LMCore vira o evento de servidor lmcore:webhookReceived, disparado em root, depois de a assinatura ser conferida. Os seus resources podem ouvi-lo, por exemplo para registrar num log ou avisar a staff no jogo:
addEventHandler("lmcore:webhookReceived", root, function(payload)
if payload.kind == "allowlist.updated" then
-- payload.data.gameId e/ou payload.data.serial: a liberação desse jogador mudou
elseif payload.kind == "gameaction.queued" then
-- payload.data.payload.type: "ban", "unban" ou "kick", que o Game Action já vai aplicar
end
end)kind | Quando chega | data |
|---|---|---|
allowlist.updated | A liberação de um jogador mudou no Discord | gameId e/ou serial, e status e allowed (só informativos) |
gameaction.queued | Uma ação do Player ou da denúncia entrou na fila | O item da fila: id, status e payload (o mesmo ctx.payload das ações) |
Use o webhook só como aviso. Não libere nem bloqueie ninguém pelo
status que vem nele: confirme com os exports da allowlist, que consultam a
L&M System. E não aplique as ações do gameaction.queued no seu resource,
porque o Game Action já faz isso e informa o resultado.
O LMCore também tem o export lmcoreHttpRequest, mas ele só fala com a API da L&M System, e cada rota exige a API Key do sistema certo. Ele não serve para chamar outras APIs.
Métricas e Status Realtime
Esses dois mods só têm o config.lua aberto, e não há o que integrar:
- As métricas usam
onPlayerJoinpara as entradas,onPlayerLoginpara os logins (veja Login próprio no gamemode) e ogetPlayerCount()a cada 10 minutos. - O status usa o
getServerName(), ogetPlayerCount()e ogetMaxPlayers()do servidor a cada 1 minuto e meio. Para mudar o nome mostrado no painel, mude oservernamedomtaserver.conf.
Status Realtime
Como funciona o painel de status em tempo real do servidor MTA. Explica o que o mod envia, como o painel é atualizado, quando o servidor aparece como offline, a configuração e a diferença para o Status MTA.
Planos e cobrança
Renovação, saldo, troca de planos, Multi Guild e o que acontece quando a assinatura vence.
