Corrigir Calculadora de Permissões do Discord Incluindo Bits Obsoletos na Saída

Ao usar a calculadora de permissões do Discord para gerar um inteiro de permissão para um bot ou cargo, a saída às vezes inclui bits para permissões obsoletas. São valores antigos que o Discord não usa mais. Isso faz o inteiro final ficar maior que o esperado e pode gerar avisos ou erros no código do seu bot. Este artigo explica por que bits obsoletos aparecem, como identificá-los e removê-los, e como ajustar seu fluxo de trabalho para evitar esse problema no futuro.

Por que a Calculadora de Permissões do Discord Inclui Bits Obsoletos

O Discord mantém um sistema de permissões baseado em um inteiro de 64 bits. Cada permissão é atribuída a uma posição de bit específica. Com o tempo, o Discord removeu ou renomeou algumas permissões. Por exemplo, a antiga permissão VIEW_CHANNEL (bit 10) foi substituída por VIEW_CHANNEL em uma posição diferente, e a antiga MANAGE_WEBHOOKS (bit 29) foi descontinuada. No entanto, a calculadora de permissões no Portal do Desenvolvedor do Discord e algumas ferramentas de terceiros ainda incluem esses bits obsoletos na lista suspensa. Quando você seleciona uma permissão obsoleta, o bit dela é adicionado ao inteiro calculado. A calculadora não avisa que a permissão não está mais ativa. Isso resulta em um inteiro que contém bits para permissões que o Discord ignora, potencialmente causando confusão quando o inteiro é usado em URLs OAuth2 ou links de convite de bot.

Como Bits Obsoletos Afetam Seu Bot ou Aplicativo

Quando seu bot solicita um inteiro de permissão que inclui bits obsoletos, a API do Discord ainda pode processar o convite ou o fluxo OAuth2. No entanto, os bits extras não fazem nada. Eles inflam o valor do inteiro desnecessariamente. Mais importante, se você depois tentar comparar ou validar o inteiro programaticamente, a presença de bits desconhecidos pode fazer seu código interpretar erroneamente as permissões reais concedidas. Por exemplo, uma verificação de permissão que espera exatamente 0x400 para uma permissão específica pode falhar se o inteiro também contiver um bit obsoleto na posição 10. Isso pode levar a falsos positivos ou negativos na verificação de permissões.

Passos para Remover Bits Obsoletos do Inteiro de Permissão

Siga estes passos para limpar o inteiro de permissão após usar a calculadora do Discord ou para construir um inteiro limpo do zero.

1. Obtenha o inteiro de permissão atual da calculadora
   Abra o Portal do Desenvolvedor do Discord, selecione seu aplicativo, vá para a seção Bot e role até a Calculadora de Permissões. Selecione as permissões desejadas. Copie o inteiro mostrado na parte inferior. Por exemplo, você pode ver 268435456.
2. Aplique uma máscara de bits para remover bits obsoletos
   Realize uma operação AND bitwise entre seu inteiro e a máscara 0x3FFFFFFF (decimal 1073741823). Em muitas linguagens de programação, isso se parece com: cleanInteger = dirtyInteger & 1073741823. Esta máscara mantém apenas os 30 bits inferiores, que correspondem às permissões atualmente válidas. Todos os bits acima de 30 são obsoletos ou reservados. Por exemplo, se seu inteiro era 268435456, o resultado após a máscara ainda é 268435456 porque não inclui bits altos. Mas se incluísse um bit obsoleto na posição 31, esse bit seria limpo.
3. Verifique o inteiro limpo em relação à lista oficial de permissões do Discord
   Visite a Documentação de Permissões do Discord e verifique cada posição de bit que você pretendia incluir. Certifique-se de que o inteiro limpo corresponde à soma apenas das permissões ativas. Você também pode usar uma ferramenta de calculadora de permissões que filtra explicitamente opções obsoletas, como discordapi.com/permissions.html.
4. Construa o inteiro manualmente usando apenas constantes atuais
   Em vez de confiar na calculadora, construa o inteiro em seu código usando as constantes de permissão atuais do Discord. Por exemplo, em JavaScript: const permissions = (1 << 0) | (1 << 5) | (1 << 10); para CREATE_INSTANT_INVITE, BAN_MEMBERS e VIEW_CHANNEL. Use apenas as posições de bit listadas na documentação oficial. Este método garante que nenhum bit obsoleto seja incluído.
5. Teste o inteiro com um convite de bot ou URL OAuth2
   Gere uma URL de convite usando o inteiro limpo. Por exemplo: https://discord.com/api/oauth2/authorize?client_id=SEU_CLIENT_ID&permissions=INTEIRO_LIMPO&scope=bot. Abra a URL em um navegador e verifique se apenas as permissões esperadas aparecem na tela de consentimento. Se você vir alguma permissão que não selecionou, o inteiro ainda contém um bit obsoleto. Repita o passo da máscara.

Se a Calculadora de Permissões do Discord Ainda Mostrar Bits Obsoletos

Lista Suspensa da Calculadora Inclui Permissões Antigas

A lista suspensa da calculadora de permissões do Portal do Desenvolvedor do Discord pode listar permissões que não são mais válidas. Isso é um problema conhecido da interface. Para evitar selecioná-las, verifique cada permissão que você planeja marcar com a documentação oficial. Não selecione nenhuma permissão marcada como “obsoleta” ou que não apareça na referência atual da API. Se você selecionar acidentalmente uma permissão obsoleta, o inteiro incluirá o bit dela. A única solução é refazer o cálculo sem essa permissão.

Calculadoras de Permissões de Terceiros Mostram Resultados Diferentes

Algumas calculadoras de terceiros usam listas de permissões desatualizadas. Elas podem incluir bits que o Discord aposentou. Sempre verifique o resultado usando o Portal do Desenvolvedor oficial do Discord ou uma ferramenta confiável como discordapi.com/permissions.html, que é mantida pela comunidade da API do Discord e geralmente fica atualizada. Se você obtiver um inteiro diferente de duas calculadoras, compare as posições dos bits manualmente. O inteiro correto deve incluir apenas bits para permissões que existem na documentação atual da API.

Link de Convite do Bot Mostra Permissões Extras

Se o link de convite do seu bot exibir permissões que você não pretendia solicitar, o inteiro provavelmente contém bits obsoletos que o Discord ainda interpreta como permissões válidas. Por exemplo, o antigo bit MANAGE_WEBHOOKS (posição 29) pode ser interpretado como uma permissão diferente na interface de convite. Para corrigir, recalcule o inteiro usando apenas as constantes de permissão atuais e aplique a máscara 0x3FFFFFFF antes de usá-lo. Em seguida, regenere a URL de convite.

Item	Bits Obsoletos Incluídos	Bits Obsoletos Removidos
Método	Usando calculadora do Portal do Desenvolvedor do Discord como está	Aplicando máscara 0x3FFFFFFF ou construindo manualmente
Exemplo de Inteiro	268435456 (sem bits obsoletos neste caso)	268435456 (mesmo, mas seguro)
Risco	Incluir acidentalmente um bit obsoleto da lista suspensa	Nenhum risco de bits obsoletos
Esforço	Baixo — apenas selecione permissões	Médio — requer máscara manual ou codificação

Após aplicar esses passos, seu inteiro de permissão conterá apenas bits atualmente válidos. Isso garante que seu bot solicite exatamente as permissões que você pretende e que seu código possa verificar permissões com precisão posteriormente. Para projetos futuros, considere construir o inteiro programaticamente usando as constantes de permissão oficiais para evitar completamente o problema de bits obsoletos. Se você mantém uma ferramenta de calculadora de permissões, atualize sua lista de permissões para corresponder à documentação mais recente da API do Discord.