Como Implementar Grupos de Subcomandos do Discord Bot com Três Níveis de Aninhamento

Bots do Discord que usam comandos de barra geralmente precisam organizar muitas ações relacionadas. Sem uma estrutura clara, os usuários enfrentam uma lista plana de dezenas de comandos. Grupos de subcomandos resolvem isso agrupando comandos relacionados em menus. O aninhamento de três níveis permite criar uma hierarquia como /mod warn add ou /admin config log set. Este artigo explica a sintaxe exata e as etapas para implementar grupos de subcomandos de três níveis no seu bot do Discord usando discord.py.

Entendendo o Aninhamento de Três Níveis em Comandos de Barra do Discord

O Discord suporta até três níveis de aninhamento para grupos de comandos de barra. A estrutura é: comando de nível superior, depois grupo de subcomando, depois subcomando. Um comando de bot como /settings notifications dm on segue esse padrão. settings é o comando de nível superior, notifications é um grupo de subcomando e dm é um subcomando. O on final é um parâmetro do subcomando.

A biblioteca discord.py implementa isso através da classe discord.app_commands.Group. Cada grupo pode conter subcomandos ou grupos filhos. A biblioteca impõe o limite de três níveis. Você não pode aninhar mais profundamente que isso.

Antes de começar, você precisa de um bot do Discord funcional com a biblioteca discord.py versão 2.0 ou posterior. Seu bot deve ter o escopo applications.commands habilitado no Portal do Desenvolvedor. O bot também precisa da intent message_content se você usar comandos de prefixo junto com comandos de barra, mas os comandos de barra em si não exigem isso.

A Estrutura da Classe Group

A classe discord.app_commands.Group aceita estes parâmetros principais:

• name: O nome do comando que os usuários digitam após a barra.
• description: Mostrado no seletor de comandos.
• parent: Outro objeto Group ao qual este grupo pertence.
• guild_ids: Lista opcional de IDs de servidores para restringir o comando.

Quando você define um parent, o grupo filho aparece como uma opção aninhada sob o comando pai. O grupo pai em si não executa nenhum código. Apenas os subcomandos folha contêm a função de retorno real.

Passos para Criar um Grupo de Subcomandos de Três Níveis

Os passos a seguir usam um exemplo de bot de moderação. A estrutura final do comando será /mod user warn, /mod user ban e /mod user kick. O grupo de nível superior é mod, o segundo nível é user e o terceiro nível é o subcomando real.

1. Importe a classe Group
   Adicione esta importação no topo do seu arquivo de bot:
   from discord.app_commands import Group
2. Crie o grupo de nível superior
   Defina uma instância de Group sem um pai:
   mod_group = Group(name="mod", description="Comandos de moderação")
3. Crie o grupo de segundo nível
   Defina um segundo Group e passe o grupo de nível superior como seu pai:
   user_group = Group(name="user", description="Ações de moderação de usuário", parent=mod_group)
4. Crie o subcomando de terceiro nível
   Use o decorador @user_group.command para registrar um subcomando sob user_group:
   @user_group.command(name="warn", description="Advertir um usuário")
async def warn(interaction: discord.Interaction, member: discord.Member, reason: str):
    await interaction.response.send_message(f"Advertido {member.mention} por {reason}")
5. Adicione mais subcomandos sob o mesmo grupo
   Repita o padrão do decorador para ban e kick:
   @user_group.command(name="ban", description="Banir um usuário")
async def ban(interaction: discord.Interaction, member: discord.Member, reason: str):
    await interaction.response.send_message(f"Banido {member.mention}")

   @user_group.command(name="kick", description="Expulsar um usuário")
async def kick(interaction: discord.Interaction, member: discord.Member, reason: str):
    await interaction.response.send_message(f"Expulso {member.mention}")

6. Registre o grupo de nível superior com o bot
   Adicione esta linha dentro da configuração do seu bot ou evento on_ready:
   await bot.tree.add_command(mod_group)
   Se você usar guild_ids, passe-os ao criar o grupo ou use bot.tree.add_command(mod_group, guild=discord.Object(id=GUILD_ID))
7. Sincronize a árvore de comandos
   Chame await bot.tree.sync() após adicionar comandos. Para comandos globais, isso pode levar até uma hora. Para comandos específicos de servidor, a sincronização é instantânea.

Erros Comuns e Limitações

O aninhamento de três níveis é o máximo

O Discord não permite quatro ou mais níveis. Se você tentar definir um parent em um grupo que já tem um avô, a biblioteca gerará um erro. Planeje sua hierarquia de comandos com cuidado.

Grupos de nível superior não podem ter seu próprio callback

Um objeto Group não executa uma função quando invocado. Apenas subcomandos folha têm callbacks. Se um usuário digitar /mod sozinho, o Discord mostra os grupos de subcomandos e subcomandos disponíveis. Nenhum código é executado.

Nomes de grupo devem ser únicos dentro do mesmo escopo

Você não pode ter dois grupos chamados user sob o mesmo pai. A combinação do nome do pai e do nome do grupo deve ser única. Grupos pais diferentes podem ter grupos filhos com o mesmo nome.

Subcomandos não podem ter o mesmo nome que seu grupo

O nome de um subcomando deve ser diferente do nome do grupo. Por exemplo, sob user_group você não pode ter um subcomando chamado user. O Discord rejeitará o registro do comando.

Comandos específicos de servidor sincronizam mais rápido que os globais

Comandos globais levam até uma hora para propagar. Para testes, use guild_ids ou passe um parâmetro guild para add_command. Remova a restrição de servidor antes de implantar em produção.

Estrutura do Grupo de Subcomandos: Nível Superior vs Segundo Nível vs Terceiro Nível

Item	Grupo de Nível Superior	Grupo de Segundo Nível	Subcomando de Terceiro Nível
Função	Contêiner para grupos relacionados	Contêiner para subcomandos	Comando executável
Tem callback	Não	Não	Sim
Exemplo de uso	/mod	/mod user	/mod user warn
Limite de aninhamento	Pode conter apenas grupos	Pode conter apenas subcomandos	Não pode conter nada
Exibição no Discord	Mostra grupos filhos	Mostra subcomandos	Mostra parâmetros

Agora você pode criar um grupo de subcomandos de três níveis no seu bot do Discord usando discord.py. Comece com um Group de nível superior, anexe um grupo filho e registre subcomandos sob o filho. Lembre-se do limite de três níveis. Teste primeiro com sincronização específica de servidor. Para bots avançados, considere usar Group com default_permissions para restringir comandos apenas a moderadores.