Eventos

Eventos são scripts que rodam porque alguma coisa aconteceu no Discord. Ninguém precisa
digitar o nome do script. A Macchi percebe o momento, encontra o script certo e executa.

Isso é útil quando você quer que o bot pareça presente sem fazer as pessoas pedirem cada
coisinha. Uma mensagem de boas-vindas, uma resposta por menção ou uma ajudinha com
prefixo pode aparecer exatamente quando o servidor precisa.

Comandos Versus Eventos

Um comando customizado é intencional. Alguém roda porque quer uma resposta. Um evento é
automático. Ele roda porque o Discord mandou uma situação para a Macchi reagir.

Se sua ideia começa com “quando alguém digitar este comando”, use customCommand. Se
começa com “quando isso acontecer”, provavelmente você quer um evento.

customCommand

Esse é o tipo de script para comandos que as pessoas rodam pelo nome. Ele não é
automático, mas entra aqui porque é o ponto de partida mais comum para scripts.

Use para links do servidor, uma resposta de “como participo do evento?”, um ajudante
pequeno de moderação ou uma resposta boba que o pessoal gosta de chamar de propósito.

macchi.reply("O guia do servidor está aqui: https://example.com")

onMention

onMention roda quando uma mensagem menciona qualquer usuário. Ele é útil para fluxos
que se importam com menções de usuários em geral, como lembretes leves ou ajudas
baseadas em menção.

Isto é Automação do servidor. Ela pode pertencer a um script de servidor, não a um
script de usuário ou canal. O autor da mensagem é contexto, não a autoridade que
habilita a automação.

onMentionMe

onMentionMe roda sempre que alguém menciona a Macchi. Ele é independente de uma
automação onMention de servidor ou canal. É útil para uma resposta amigável de “o que
esse bot faz?”, principalmente para quem viu o bot e marcou por curiosidade.

Assim como onMention, esta é Automação do servidor com uma vaga ativa por servidor.
O autor da mensagem aparece como ctx.subject, mas não é ator de autorização e não
empresta suas permissões do Discord ao script.

macchi.reply("Howdy! Meu prefixo é `" .. macchi.prefix .. "`. Tente um comando salvo.")

onMentionMacchi

onMentionMacchi executa o script pessoal do autor quando esse autor menciona a Macchi.
Existe uma vaga ativa por usuário e ela não exige permissão para gerenciar o servidor.
Mencionar outra pessoa, responder sem menção ou usar um prefixo não ativa esse gatilho.
Contas novas recebem um script hello editável com esse gatilho.

onPrefixedMessage

onPrefixedMessage roda para mensagens com prefixo que ainda não são comandos
customizados salvos. Pense nele como um pega-leve para comportamento de prefixo.

Iniciantes podem usar para mensagens de ajuda, reações pequenas ou fluxos tipo “esse
comando ainda não existe, tente isso aqui”. Só vale manter gentil, porque ele pode rodar
justamente quando alguém já está tentando usar comandos.

onMessage

onMessage roda para cada mensagem escrita por uma pessoa. Um script do servidor pode
definir o comportamento padrão, e um script opcional do canal tem prioridade no seu
canal exato. É Automação do servidor: o autor aparece como contexto confiável, mas não
empresta permissões ao script.

A publicação pública u0/honeypot@2 é um exemplo completo. Instale-a em um canal
dedicado já existente, revise as capacidades de moderação e armazenamento compartilhado
e ative a instalação. Ela remove cinco minutos de mensagens do autor antes de expulsá-lo
e mantém um contador persistente de contas capturadas. Siga o tutorial de Automação de
Canal antes de ativá-la.

onMemberJoin

onMemberJoin roda quando alguém entra no servidor. Ele é de servidor porque mensagem
de entrada depende muito da comunidade.

Use para boas-vindas, lembretes de canais iniciais ou um “que bom te ver por aqui” que
não pareça igual a todo bot.

onMemberLeave

onMemberLeave roda quando alguém sai do servidor. Algumas comunidades usam para um
registro discreto, uma despedida ou uma nota de moderação.

Esse é melhor quando fica simples. A pessoa que saiu talvez nem veja a mensagem, então
pense nele mais como organização do servidor do que como um grande momento público.

onReactionAdd E onReactionRemoved

onReactionAdd roda quando uma reação é adicionada a uma mensagem. onReactionRemoved
roda quando uma reação é removida. Scripts de reação podem ver ctx.reaction para
consultar emoji, id da mensagem, id do canal e usuário.

Cada tipo de reação tem um script ativo por servidor. O canal da reação é contexto e
não cria outra vaga de registro.

onKick, onBan E onMuted

onBan roda pelo evento de banimento do Discord. onMuted roda quando uma atualização
de membro mostra que um timeout/restrição de comunicação ficou ativo. onKick roda por
entradas de kick no audit log do Discord, porque um evento normal de remoção de membro
não diferencia de forma confiável expulsão e saída voluntária.

O Que Testar Primeiro

Se você está começando, teste customCommand. Quando isso ficar confortável e um
gerente tiver configurado Automação do servidor, teste uma mensagem de boas-vindas com
onMemberJoin.

Para entender o básico de Lua com calma, leia Scripting. Quando
quiser os nomes exatos disponíveis em scripts de evento, abra a referência da API
Lua.