Exports Whitelist System

​

Resolva problemas comuns

​

Sobre o sistema

• Verificar manualmente se um player tem whitelist aprovada (útil ao trocar de personagem, reconectar, etc.);
• Aprovar um player na whitelist diretamente via script (útil para sistemas de staff, painéis administrativos, bots externos, etc.);
• Remover/resetar a whitelist de um player para que ele refaça o processo;
• Obter o Discord ID de um player que passou pela whitelist (útil para cruzar dados com sistemas de Discord).

​

Funções Exportadas

​

Server-side

• verifyPlayerAccount -> Verifica se o player tem whitelist e abre o painel caso não tenha
• approveWhitelistPlayer -> Aprova manualmente um player na whitelist
• removeWhitelistPlayer -> Remove/reseta a whitelist de um player
• getPlayerDiscordID -> Retorna o Discord ID do player (se disponível)

​

verifyPlayerAccount

exports['sqh_whitelist']:verifyPlayerAccount(player)

• player (player): jogador a ser verificado.

• Consulta o banco de dados pelo serial do player.
• Se o status for 'approved', executa o callback config.events.onJoinCity.server(player) liberando o acesso.
• Se o status for diferente de 'approved' (ou o player nunca fez whitelist), abre o painel de whitelist para ele.
• Esta função é chamada automaticamente nos eventos onPlayerJoin e onPlayerLogin quando config.events.verifyOnJoin ou config.events.verifyOnLogin são true. Use a export para chamadas manuais.

• Não há retorno explícito. A ação ocorre via callbacks e triggers client-side.

-- SERVER-SIDE (chamar ao trocar de personagem)
addEventHandler('onCharacterSwitch', root, function(player)
    exports['sqh_whitelist']:verifyPlayerAccount(player)
end)

-- SERVER-SIDE (chamar via comando de staff para forçar re-verificação)
addCommandHandler('verificarwl', function(player, _, targetName)
    local target = getPlayerFromName(targetName)
    if target then
        exports['sqh_whitelist']:verifyPlayerAccount(target)
        outputChatBox('Verificação enviada para ' .. targetName, player)
    end
end)

​

approveWhitelistPlayer

exports['sqh_whitelist']:approveWhitelistPlayer(player)

• player (player): jogador a ser aprovado.

• Atualiza o status na tabela whitelist_players para 'approved'.
• Atualiza o status da tentativa (whitelist_attempts) com aditionalInfos.approved_by = 'admin'.
• Fecha o painel de whitelist do player e executa config.events.onJoinCity.server(player).
• Se o player já estiver aprovado ou não tiver registro, envia uma notificação de erro.

• Não há retorno explícito. O resultado é enviado via notificação ao player.

-- SERVER-SIDE (aprovação por comando de staff)
addCommandHandler('aprovarwl', function(player, _, targetName)
    local target = getPlayerFromName(targetName)
    if target then
        exports['sqh_whitelist']:approveWhitelistPlayer(target)
        outputChatBox('Whitelist aprovada para ' .. getPlayerName(target), player)
    else
        outputChatBox('Jogador não encontrado.', player)
    end
end)

-- SERVER-SIDE (aprovação automática por sistema de entrevista próprio)
addEventHandler('onPlayerFinishInterview', root, function(player, approved)
    if approved then
        exports['sqh_whitelist']:approveWhitelistPlayer(player)
    end
end)

​

removeWhitelistPlayer

exports['sqh_whitelist']:removeWhitelistPlayer(player)

• player (player): jogador que terá a whitelist removida/resetada.

• Remove o registro do player da tabela whitelist_players.
• Limpa os dados em memória do player (código de segurança, tentativa ativa, etc.).
• Após remover, chama verifyPlayerAccount automaticamente — o player verá o painel de whitelist novamente como se nunca tivesse feito.
• O histórico de tentativas (whitelist_attempts) não é apagado — apenas o vínculo do player é removido.

• Não há retorno explícito. O player recebe uma notificação e o painel reabre.

-- SERVER-SIDE (remover whitelist por painel de admin)
addCommandHandler('removerwl', function(player, _, targetName)
    local target = getPlayerFromName(targetName)
    if target then
        exports['sqh_whitelist']:removeWhitelistPlayer(target)
        outputChatBox('Whitelist removida de ' .. getPlayerName(target), player)
    else
        outputChatBox('Jogador não encontrado.', player)
    end
end)

​

getPlayerDiscordID

local discordID = exports['sqh_whitelist']:getPlayerDiscordID(player)

• player (player): jogador alvo.

• Retorna o Discord ID armazenado em cache para o player (preenchido no momento da aprovação via bot do Discord).
• O cache é carregado ao iniciar o resource (para players já online) e ao verificar a conta durante o onPlayerLogin/onPlayerJoin.
• Se o player não tiver passado pela whitelist via Discord, ou ainda não tiver sido verificado na sessão atual, retorna false.

• string com o Discord ID do player, ex: "123456789012345678".
• false se o Discord ID não estiver disponível.

-- SERVER-SIDE (cruzar com sistema de Discord)
addCommandHandler('meudiscord', function(player)
    local discordID = exports['sqh_whitelist']:getPlayerDiscordID(player)
    if discordID then
        outputChatBox('Seu Discord ID: ' .. discordID, player)
    else
        outputChatBox('Seu Discord ID não foi encontrado.', player)
    end
end)

-- SERVER-SIDE (dar cargo via bot ao entrar)
addEventHandler('onPlayerLogin', root, function()
    local discordID = exports['sqh_whitelist']:getPlayerDiscordID(source)
    if discordID then
        -- integrar com bot de discord externo
        triggerEvent('onSyncDiscordRole', root, source, discordID, 'membro')
    end
end)

​

Observações

• Todas as exports só funcionam após o resource ser iniciado e a licença validada.
• A export verifyPlayerAccount é chamada automaticamente pelo sistema conforme as configurações verifyOnJoin e verifyOnLogin. Use a export para casos manuais específicos.
• Para aprovar players em lote ou por painel web, prefira usar approveWhitelistPlayer via script server-side no momento em que o player estiver online.
• O Discord ID só fica disponível no cache enquanto o player estiver online. Para consultas offline, acesse diretamente o banco de dados na coluna discordID da tabela whitelist_players.