Logo da L&M SYSTEMDocumentação
Sistemas

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:

ModArquivos abertosPara quê
LMCoreconfig.luaConfigurar o webhook
Allowlist/Whitelistconfig.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 Actionconfig.lua e server/actions/ban.lua, kick.lua e unban.luaConfigurar e trocar como o ban, o desban e o kick são aplicados
Métricasconfig.luaConfigurar
Status Realtimeconfig.luaConfigurar

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 LMCore e AllowlistSystem. Os mods chamam o LMCore por exports.LMCore, e os seus resources vão chamar a allowlist por exports.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ção getSettings(). Não espalhe valores fixos pelo código.
  • Os logs de acompanhamento só aparecem com devMode = true. No cliente, use debugscript 3 para 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:

  1. Chamar logIn no seu login próprio, com uma conta do MTA para o jogador. Assim tudo funciona sem editar os mods.
  2. Avisar a allowlist você mesmo, editando o server/main.lua do 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:

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

CampoO que é
allowedUse este para decidir se o jogador entra (true ou false)
statusA situação, para mostrar ou registrar: none, pending, approved, rejected ou revoked
kindverifyId ou verifySerial
requestTagO texto que você mandou, para saber de onde veio
playerO cadastro: gameId, serial, discordId e playerName (este último pode não vir)
allowlistO 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ções setData(payload), setCopiedState(botao, copiado), showToast(mensagem, duracao) e resetCopiedState(), 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) e allowlist: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,
})
CampoO que é
requiresO 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"
onFailA 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:

CampoO que é
ctx.playerO jogador online, se encontrado (pelo serial e depois pelo elementDataID), ou nil
ctx.serialO serial do cadastro, ou o do jogador online
ctx.reasonO motivo informado no Discord
ctx.payload.durationSecondsSó no ban: a duração em segundos. 0 é permanente
ctx.payload.playerO 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 run precisa responder na hora, com true ou false. Se o seu sistema grava no banco de forma assíncrona, devolva true quando 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 run aguentar 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, unban e kick.
  • Se o seu run usa funções restritas (como banPlayer ou o seu próprio resource com ACL), o Game Action continua precisando estar no grupo Admin do acl.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)
kindQuando chegadata
allowlist.updatedA liberação de um jogador mudou no DiscordgameId e/ou serial, e status e allowed (só informativos)
gameaction.queuedUma ação do Player ou da denúncia entrou na filaO 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 onPlayerJoin para as entradas, onPlayerLogin para os logins (veja Login próprio no gamemode) e o getPlayerCount() a cada 10 minutos.
  • O status usa o getServerName(), o getPlayerCount() e o getMaxPlayers() do servidor a cada 1 minuto e meio. Para mudar o nome mostrado no painel, mude o servername do mtaserver.conf.