Logo da L&M SYSTEMDocumentação
Sistemas

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.

Estes sistemas controlam quem pode jogar no seu servidor MTA. O jogador entra no servidor, fica travado numa tela de cadastro, faz o cadastro pelo Discord e é liberado no jogo, sem precisar sair e entrar de novo. São três sistemas exclusivos do MTA Avançado, e todos usam o mesmo mod, o Allowlist/Whitelist.

Esta página explica o caminho inteiro: a parte do jogo (o mod), a parte do Discord (cada sistema), a lista de jogadores liberados e o que fazer quando algo dá errado. A instalação do mod e a API Key estão em Integração MTA.

Qual sistema usar

Os três gravam na mesma lista: um jogador liberado por qualquer um deles está liberado no servidor. O que muda é como o jogador chega lá.

Whitelist automáticaWhitelist semi-automáticaAllowlist avançado
Comando de gestão/whitelist-auto/whitelist-semi/allowlist-avancado
Onde o jogador respondeEm um canal privado criado para eleEm um canal privado criado para eleEm um formulário (modal), no próprio painel
PerguntasDe múltipla escolha (A a D), com tempo por perguntaAbertas, com tempo por perguntaNome, identificação e até 3 perguntas extras
Quem liberaO bot, se o jogador acertar 75% ou maisA sua equipe, depois de ler as respostasNinguém: o jogador é liberado ao enviar
Ideal paraServidores com muitos pedidosAvaliar cada jogador com calmaSó registrar quem entra

Nada impede de publicar o painel de mais de um, mas o comum é escolher um só.

Tipo de identificação

É como o bot sabe qual jogador do jogo é aquele membro do Discord. O tipo é escolhido no /config-bot de cada sistema, na aba Geral → Tipo, e precisa combinar com o campo type do config.lua do mod.

No /config-botNo mod (type)O jogador informa no Discord
CódigoCODE_SERIAL ou CODE_IDO código que aparece na tela do jogo
SerialSERIALO serial do MTA
IDIDO ID do jogador no seu servidor

O Código é o mais seguro, porque o jogador não consegue informar o serial ou o ID de outra pessoa. Ele é gerado pela tela do jogo, vale para o seu servidor só, é de uso único e expira em 15 minutos. Enquanto o jogador fica na tela, o mod gera um código novo antes de o anterior vencer.

Nos dois tipos de código, a tela é a mesma. A diferença é o que o mod usa por trás:

  • CODE_SERIAL: identifica o jogador pelo serial. Se o seu gamemode tiver a element data do ID (elementDataID), ela vai junto, e o ID entra no apelido do Discord.
  • CODE_ID: identifica o jogador pelo ID da element data e envia o serial junto.

Os tipos ID e CODE_ID dependem da element data do ID, que só existe depois do login no seu gamemode. Confira o campo elementDataID do mod (veja Integração MTA).

No jogo: a tela de cadastro

O jogador faz login no servidor

Assim que ele faz login no gamemode, o mod consulta a L&M System. Se ele já está liberado, nada acontece e ele joga normalmente.

O mod usa o login das contas do MTA (onPlayerLogin). Se o seu gamemode tem um login próprio, que não usa essas contas, a verificação não acontece sozinha: veja Login próprio no gamemode.

Fica travado até ser liberado

Se não está liberado, o mod congela o personagem e desativa os controles de lockedControls (por padrão: atirar, mirar e trocar de arma). Esse bloqueio é feito pelo servidor, então não adianta o jogador mexer no próprio jogo para escapar.

Por cima, aparece a tela de cadastro, com o código, o serial ou o ID que ele vai informar no Discord, um botão para copiar e o link do Discord do servidor (linkDc). O jogador não consegue fechar a tela antes de ser liberado: ao tentar, o mod consulta a L&M System de novo e só fecha se ele estiver liberado.

É liberado sem sair do servidor

Quando o cadastro é aprovado no Discord, o mod descongela o personagem, reativa os controles e fecha a tela. Com o webhook funcionando, isso acontece na hora. Sem ele, em até 30 segundos, que é o intervalo em que o mod volta a consultar os jogadores travados.

A tela muda conforme a situação do jogador:

SituaçãoO que a tela mostra
Sem cadastroAs instruções para fazer o cadastro e o código, o serial ou o ID
Em análiseQue o cadastro foi enviado e está com a equipe (na whitelist semi-automática, no tipo código)
ReprovadoQue o cadastro foi reprovado e como tentar de novo
RevogadoQue a liberação foi removida pela equipe e como refazer o cadastro

Os jogadores que já estão jogando também são conferidos a cada 30 minutos. Se a liberação de alguém for removida no meio da partida, ele volta a ficar travado na próxima conferência.

Se a L&M System não responder

O mod não libera ninguém sem confirmação. Se a consulta falhar (servidor sem internet ou L&M System fora do ar), o jogador fica travado na tela até a próxima consulta dar certo.

Personalizar no config.lua

CampoO que faz
typeO tipo de identificação (veja acima)
elementDataIDA element data do ID do jogador. Padrão: ID
apiKeyA API Key do contexto Allowlist/Whitelist
linkDcO link do Discord mostrado na tela e na mensagem de expulsão
syncPlayerNameTroca o nome do jogador no MTA pelo nome do personagem cadastrado no Discord
noAllowlistKickDelayMsTempo, em milissegundos, que um jogador sem cadastro pode ficar travado antes de ser expulso. 0 desativa. Quem aparece como em análise nunca é expulso, mas isso só existe na whitelist semi-automática no tipo Código: nos tipos ID e Serial, quem espera a equipe aparece como sem cadastro e pode ser expulso
lockedControlsOs controles desativados enquanto o jogador não é liberado. {} deixa só o personagem congelado
ui.enabledfalse não abre a tela padrão, para você usar uma tela sua. O bloqueio continua
ui.themeO visual da tela: default (escuro), red (vermelho e preto), aurora (roxo e azul) ou light (claro)
ui.title, ui.instructions e os blocos ui.pending, ui.rejected e ui.revokedOs textos de cada situação da tela
ui.toastO aviso mostrado quando o jogador tenta fechar a tela sem estar liberado

Nos textos, {valor} vira o nome do dado (por exemplo Código) e {valorLower} vira o mesmo nome em minúsculas.

Com o syncPlayerName, o nome vai sem acentos, com os espaços e símbolos trocados por _ e cortado em 22 caracteres, para caber no limite do MTA. João Vitor vira Joao_Vitor.

Para quem desenvolve

Para consultar a lista em outros resources, mudar o momento da verificação (por exemplo, se o seu gamemode tem login próprio) ou fazer uma tela própria, veja Para desenvolvedores.

Whitelist automática

O jogador responde um questionário de múltipla escolha e o bot aprova ou reprova sozinho, pela nota.

Configuração

Em /config-bot → MTA Avançado → Whitelist Automática:

AbaO que você configura
GeralO tipo de identificação, o tempo de resposta de cada pergunta (padrão: 60 segundos), o formato do apelido, o IP do servidor enviado na DM e as imagens. Também tem o botão de deletar registros
PermissõesA categoria onde os canais de whitelist são criados, o canal de resultados e os cargos dados e removidos na aprovação
ConteúdoAs perguntas e o painel
RelatóriosQuantas whitelists foram finalizadas, aprovadas e reprovadas na semana e no mês

Cada pergunta tem o texto (com as alternativas que você escrever) e a resposta correta (A, B, C ou D). As perguntas podem ser editadas, removidas e trocadas de posição.

Como funciona para o jogador

  1. Clica em Iniciar Whitelist no painel. O bot cria o canal whitelist-nome, que só ele (e os administradores) enxerga, na categoria configurada.
  2. No canal, clica em Iniciar agora ou em Cancelar Whitelist. Se não começar em 1 minuto, o canal é apagado.
  3. Responde, digitando no canal, o código, o serial ou o ID e depois o nome e sobrenome do personagem. O bot confere o dado na hora: um ID ou serial que já está liberado, um serial inválido ou um código vencido cancela a whitelist.
  4. Responde as perguntas pelos botões A, B, C e D. Cada pergunta tem o tempo configurado. Se o tempo acabar, a whitelist é cancelada e o canal fecha em 15 segundos.
  5. No fim, o bot calcula a nota. Com 75% ou mais de acertos, o jogador é aprovado.

Se o bot reiniciar no meio, a whitelist continua de onde parou, com a mensagem "Continuando de onde parou". Uma whitelist parada há mais de 1 hora é descartada.

Resultado

  • Aprovado: o jogador entra na lista e é liberado no jogo, recebe os cargos de aprovação, perde os cargos de remoção e tem o apelido ajustado.
  • Reprovado: nada muda na lista, e ele pode tentar de novo quando quiser.

Nos dois casos, o jogador recebe na DM o resultado com a nota (por exemplo aprovada (8/10)), com o IP do servidor se for aprovado. O resultado também vai para o canal de resultados, e o canal da whitelist é apagado.

Whitelist semi-automática

O jogador responde perguntas abertas e a sua equipe decide.

Configuração

Em /config-bot → MTA Avançado → Whitelist Semi-Automática:

AbaO que você configura
GeralO tipo de identificação, o tempo de resposta de cada pergunta, o formato do apelido, o IP do servidor e as imagens. Também tem o botão de deletar registros
PermissõesOs cargos dados e removidos na aprovação, a categoria de criação (dos canais dos jogadores), as categorias de envio (até 5, onde as respostas chegam para a equipe) e os canais de aprovação e reprovação
ConteúdoAs perguntas e o painel
RelatóriosAs whitelists finalizadas, aprovadas e reprovadas na semana e no mês, e quem mais aprovou e reprovou no mês

Como funciona para o jogador

  1. Clica em Iniciar Whitelist e, no canal criado para ele, em Iniciar Agora.
  2. Responde o código, o serial ou o ID e o nome do personagem. Se ficar sem responder uma dessas duas, a whitelist é cancelada.
  3. Responde as perguntas abertas, digitando no canal. Se o tempo de uma delas acabar, a resposta fica como "Tempo Esgotado" e a whitelist segue para a próxima.
  4. As respostas são enviadas para a equipe e o jogador é avisado de que vai receber o resultado na DM. No tipo Código, a tela do jogo passa a mostrar em análise.

Um jogador só pode ter uma whitelist em análise por vez. Se tentar de novo antes da resposta da equipe, recebe "Sua whitelist já foi enviada anteriormente".

Como a equipe analisa

As respostas chegam num canal novo, resposta-whitelist-nome, criado na primeira categoria de envio que ainda tiver espaço. Como o Discord limita 50 canais por categoria, o bot pula para a próxima quando uma enche. Por isso dá para configurar até 5.

No canal, a equipe vê as respostas, os dados do membro e os botões Aprovar Whitelist e Reprovar Whitelist:

  • Aprovar: o jogador entra na lista e é liberado no jogo, recebe os cargos, tem o apelido ajustado e recebe a aprovação na DM, com o IP do servidor. O registro vai para o canal de aprovação.
  • Reprovar: o jogador fica como reprovado (a tela do jogo mostra isso) e recebe a reprovação na DM. O registro vai para o canal de reprovação, e ele pode tentar de novo.

Depois da decisão, o canal das respostas é apagado em 10 segundos.

Quem vê o canal, decide

Os canais de respostas seguem as permissões da categoria de envio, e os botões não pedem nenhum cargo extra: quem consegue ver o canal consegue aprovar e reprovar. Deixe as categorias de envio visíveis só para a equipe que analisa as whitelists.

Allowlist avançado

É o mais simples: o jogador preenche um formulário e é liberado na hora, sem prova e sem análise. Serve para registrar quem entra e ligar cada jogador ao Discord dele.

Configuração

Em /config-bot → MTA Avançado → Allowlist Avançado:

AbaO que você configura
GeralO tipo de identificação, o formato do apelido, o IP do servidor enviado na DM e as imagens. Também tem o botão de deletar registros
PermissõesO canal de log e os cargos dados e removidos ao concluir
ConteúdoAs perguntas extras e o painel

As perguntas extras (Pergunta 3, 4 e 5) aparecem no formulário depois do nome e da identificação. Cada uma tem título, descrição, estilo (curta ou parágrafo) e se é obrigatória.

Como funciona para o jogador

  1. Clica em Realizar Allowlist no painel.
  2. Preenche o nome e sobrenome do personagem, o código, o serial ou o ID e as perguntas extras.
  3. Se os dados estiverem certos, ele é liberado no jogo na hora, recebe os cargos, tem o apelido ajustado e, se você configurou o IP, recebe o IP do servidor na DM.

O registro, com o membro, o nome, a identificação, as respostas e a data, vai para o canal de log.

MensagemPor quê
O ID que você digitou não é um número.No tipo ID, o campo aceita só números
O código não foi encontrado ou expirou.O código foi digitado errado ou passou dos 15 minutos. O jogador copia o código novo da tela
Esse ID (ou número de serial) já está cadastradoEsse jogador já está liberado

Apelido no Discord

Nos três sistemas, o apelido do membro aprovado segue o formato configurado na aba Geral. Use {{name}} para o nome do personagem e {{id}} para o ID do jogo. O padrão é {{name}}|{{id}}.

Quando não existe ID (no tipo Serial, ou no tipo Código sem a element data do ID), o {{id}} sai do apelido junto com o separador. {{name}}|{{id}} vira só o nome, em vez de João Vitor|.

Gerenciar a lista

Pelos comandos

/whitelist-auto, /whitelist-semi e /allowlist-avancado abrem um formulário para adicionar ou remover um jogador da lista à mão, pelo ID (no tipo ID) ou pelo serial (nos tipos Serial e Código). Só administradores do servidor usam esses comandos.

  • Adicionar libera o jogador no jogo.
  • Remover marca a liberação como revogada. Se ele estiver jogando, volta a ficar travado em até 30 minutos.

Como a lista é a mesma, tanto faz qual dos três comandos você usa.

Pelo dashboard

No Dashboard, em Sistemas → MTA:

  • Allowlist mostra cada liberação, com o Game ID, o serial, o status (Nenhum, Pendente, Aprovado, Rejeitado ou Revogado) e a data, e permite excluir um registro.
  • Players mostra o cadastro dos jogadores (nome, Game ID, serial e Discord), usado também pelo Player. Dá para vincular o Discord de um jogador que ainda não tem e excluir jogadores.

Deletar registros em massa

O botão Deletar Registros, na aba Geral de qualquer um dos três sistemas, apaga de uma vez:

  • somente as liberações: todos os jogadores voltam a ficar sem cadastro, mas o cadastro de players continua; ou
  • players e liberações: apaga também o cadastro de players, inclusive o vínculo com o Discord.

A exclusão vale para o servidor inteiro, não só para o sistema em que você clicou, porque os três (e o Player) usam a mesma lista. Ela não pode ser desfeita.

Usava a versão com MySQL?

Se a sua whitelist ou allowlist foi configurada com o MySQL do seu servidor, ela continua funcionando, mas a lista não aparece no dashboard e o /player não encontra esses jogadores. A tela de cada sistema ganha a aba Migração, que leva tudo para a L&M Cloud. Veja o passo a passo em Migração do MySQL para a L&M Cloud.

Problemas comuns