General

Getting Started

Meet Macchi and find the friendliest place to begin.

Published by solever7 solever7
intro discord scripts events

Macchi is a Discord bot for servers that have their own little way of doing things. You
know when a server keeps repeating the same joke, the same answer, the same welcome
message, or the same “please check this channel first” reminder? Macchi is made for that
kind of moment.

Instead of waiting for a built-in setting to fit your exact idea, you can write a small
Lua script and let the bot answer in your server’s voice. That script can be a command
someone runs on purpose, or it can run automatically when something happens.

Kita Lua

The nice part is that you do not have to start with something impressive. A single line
that replies “hi” is already a real script. From there, you can make it more personal,
add buttons, react to a mention, or turn it into a helper your server actually uses.

What This Wiki Is For

This wiki is the cozy version of the documentation. It explains Macchi in the way you
would explain it to someone in a server: what it does, why scripts are useful, and where
to click when you want the next bit.

If you want to write your first reply, start with Your First Script.
It walks through the complete create, edit, and run loop. If you
are curious about things that happen automatically, read Events.
Events are how Macchi can answer mentions, welcome members, or react to prefixed
messages without someone manually running a command.

When you are ready to check the exact names available inside Lua, the Lua
API page is the reference. The Lua API
Downloads page is mostly for editor help and generated
files.

A Tiny First Idea

Try making a command that simply answers people:

macchi.reply("Hey " .. ctx.user.username .. ", I am alive.")

That is enough to learn the loop: write something small, test it, change the words, and
run it again. Use /check source:macchi.reply('hello') to validate private transient
Lua source, /new with an explicit scope to create a saved script, and /run to run a
precise typed script reference directly.

Published scripts can be found from Discord search. Open an exact revision with:

/search script:u123/welcome@1

Each published script can also receive Hypes from Discord. A hype is a small star boost,
and each user can give one hype per day total.

You can also browse published scripts on /library, open a canonical typed reference,
inspect its readme and source, and copy the same reference for Discord.

Commands, Events, and “Wait, Which One Do I Need?”

Use a command when someone should choose to run the script. A custom command is good for
things like server links, a FAQ answer, a silly quote, or a tiny helper that people call
when they need it.

Use an event when the bot should react by itself. If someone mentions Macchi,
their personal onMentionMacchi script can answer with a friendly “here is what I do.”
If any user mention
matters, onMention can watch that broader case. If someone joins, onMemberJoin can
welcome them. If someone leaves, onMemberLeave can help you log or react to that
moment. If someone sends a prefixed message that is not a saved command,
onPrefixedMessage can decide what to do next.

onMentionMe and the other automatic guild events are Server automation. A server
manager configures one active script for each concrete event. New users receive an
editable personal hello script using onMentionMacchi; it runs only when that user
mentions Macchi.

You do not need to memorize the names right now. Start with the situation you want to
improve. “I want people to type something and get an answer” points to a command. “I
want Macchi to notice something happened” points to an event.

Documentation Map

Script references use u123/name@0, g123/name@1, or c123/name@2. Drafts use revision
@0; published revisions are immutable. Entry names are execution details and do not
appear in ordinary references.

And if all of this still feels a little new, that is fine. The best Macchi scripts
usually start as “I just want the bot to say this one thing my way.”

Explore with agents
ChatGPT