Events

Events are scripts that run because something happened in Discord. Nobody needs to type
the script name. Macchi notices the moment, finds the matching script, and runs it.

That is useful when you want the bot to feel present without making people ask for every
little thing. A welcome message, a mention answer, or a small prefix helper can happen
right when the server needs it.

Commands Versus Events

A custom command is intentional. Someone runs it because they want a response. An event
is automatic. It runs because Discord sent Macchi a situation to react to.

If your idea starts with “when someone types this command,” use customCommand. If your
idea starts with “when this happens,” you probably want an event.

customCommand

This is the script type for commands people run by name. It is not automatic, but it
belongs here because it is the everyday starting point for most scripts.

Use it for things like server links, a “how do I join the event?” answer, a tiny
moderation helper, or a silly response people like calling on purpose.

macchi.reply("Here is the server guide: https://example.com")

onMention

onMention runs when a message mentions any user. It is useful for workflows that care
about user mentions in general, such as lightweight reminders or mention-based helpers.

This is Server automation. It can be owned by one server script, not a user or
channel script. The message author is context, not the authority granting the automation
permission.

onMentionMe

onMentionMe runs whenever someone mentions Macchi. It is independent from a server or
channel onMention automation. This is useful for a friendly “what can this bot do?”
answer, especially for new users who see the bot and ping it out of curiosity.

Like onMention, this is Server automation with one active guild slot. The message
author is readable as ctx.subject, but is not an authorization actor and lends no
Discord permissions to the script.

macchi.reply("Howdy! My prefix is `" .. macchi.prefix .. "`. Try a saved command.")

onMentionMacchi

onMentionMacchi runs the current message author’s personal script when that author
mentions Macchi. It has one active user-owned slot and does not require server-management
permission. A mention of another user, a reply without a mention, or a prefix does not
match it. New accounts receive one editable hello script with this trigger.

onPrefixedMessage

onPrefixedMessage runs for prefixed messages that are not already saved custom
commands. Think of it as a soft catch-all for prefix behavior.

Beginners can use it for gentle help messages, playful reactions, or “that command does
not exist yet, try this instead” flows. Keep it polite, because it can run in places
where people are already typing commands.

onMessage

onMessage runs for each user-authored message. One server-owned script can provide the
default behavior, and an optional channel-owned script takes precedence in its exact
channel. It is Server automation: the author is available as trusted event context, but
does not lend permissions to the script.

The public u0/honeypot@2 publication is a complete example. Install it into an
existing dedicated channel, review its moderation and shared-storage capabilities, then
enable that installation. It removes five minutes of the author’s messages before
kicking and keeps a persistent caught-account count. Follow the Channel Automation
tutorial before enabling it.

onMemberJoin

onMemberJoin runs when someone joins a server. It is server-scoped because join
messages depend on the community.

Use it for welcome notes, starter channel reminders, or a small “glad you are here”
message that does not sound like every other bot.

onMemberLeave

onMemberLeave runs when someone leaves a server. Some communities use it for a quiet
log, a goodbye message, or a moderation note.

This one is best kept simple. The person who left may not be around to see the message,
so think of it as server housekeeping rather than a big public moment.

onReactionAdd And onReactionRemoved

onReactionAdd runs when a reaction is added to a message. onReactionRemoved runs
when a reaction is removed. Reaction scripts can inspect ctx.reaction for the emoji,
message id, channel id, and user.

Each reaction type has one active script per server. A reaction’s channel remains event
context and does not create another registration slot.

onKick, onBan, And onMuted

onBan runs from Discord’s ban event. onMuted runs when a member update shows that a
timeout/communication restriction became active. onKick runs from Discord audit-log
kick entries, because a normal member-remove event cannot reliably tell a kick from
someone leaving by choice.

What To Try First

If you are new, start with customCommand. Once that feels comfortable and a server
manager has configured Server automation, try a welcome script with onMemberJoin.

For more Lua basics, read Scripting. When you want the exact API
names available to event scripts, open the Lua API reference.