Scripting

User-invoked scripts can inspect the bounded ctx.scripts snapshot. Metadata,
management state, and source visibility remain separate; private source is never
included merely because a script can run. macchi.ask can propose an explicit
script-management action in a private confirmation, but the proposal has no authority
and expires quickly. Macchi rechecks the current user, context, dependencies, and
permissions after Accept.

For the complete Add versus Install lifecycle and strict Ask table examples, see
Scripts and installations.

A Macchi script is a small piece of Lua that tells the bot what to do. It can be as
simple as “reply with this message,” or it can grow into something more interactive with
buttons, context, checks, and server-specific behavior.

The point is not to become a programmer overnight. The point is to give your server a
way to say, “actually, I want the bot to do this little thing our way.”

Scripts Start Small

The easiest script is a reply:

macchi.reply("Pong!")

That is already useful. You can turn it into a custom command, give it a name, and run
it when someone needs it. Later, you can make the answer mention the person who
triggered it:

macchi.reply("Hi " .. ctx.user.username .. "!")

ctx is the current context. It tells the script what is happening right now, like who
triggered it. macchi is the friendly API for doing bot things, like replying.

Commands Are For “Someone Asked”

Custom commands are the most comfortable place to begin. Someone runs a command, Macchi
runs the script, and the script replies. That is great for server links, FAQ answers,
little jokes, setup notes, or “please read this before asking” helpers.

If you have ever wanted a bot command that says exactly the sentence your server needs,
custom commands are probably the first thing to try.

Events Are For “Something Happened”

Some scripts should run even when nobody typed the script name. That is what
Events are for. A mention event can answer when someone pings Macchi. A member
join event can say hello. A prefixed message event can catch messages that use your
prefix but are not saved commands.

Commands are a button someone presses. Events are Macchi noticing the room.

Replies Can Stay Simple

For most beginner scripts, macchi.reply(text) is enough. It sends a normal response
and lets you focus on the words instead of message formatting.

When you want something more interactive, use the message builder:

message.new()
  :text("Choose an action.")
  :button("help", "Help")
  :send()

You do not need builders on day one. They are there when a plain reply starts to feel
too small.

Published Scripts

Activation and publication are separate. An active script can run; an inactive script
stays saved but cannot run. Publishing creates an immutable public version. Editing an
active script afterward creates unpublished changes without changing the exact
publication installed elsewhere. An installation keeps that publication identity and
does not copy source into a new draft.

When you publish a script, Macchi exposes only the typed owner/name/version reference,
such as u123/welcome@1. Internal short IDs are not script identity.

Published metadata has a short description for cards and Discord selects, optional
icon_url, and readme_markdown source for public details. readme_markdown is
limited to 4000 characters because it can be entered from a Discord modal. Icon URLs
must be http:// or https://; Macchi does not fetch the URL or verify the remote
image.

Published scripts can receive Hypes from Discord. Hype is a daily boost, not a classic
permanent like relationship: each user can give one hype per day total.

The public website also has a script library at /library. It lets you search published
scripts, open /library/<typed_owner_id>/<script_name>@<version>, read the published
readme_markdown, pick a published version, inspect source, and open a scoped
installation review. Hype counts are visible there, but giving a hype still happens
through the Discord bot.

A Useful Pattern

Try writing scripts like a short conversation:

local prefix = macchi.prefix

macchi.reply(
  "Need help? My prefix is `" .. prefix .. "`. Try `" .. prefix .. "hello`."
)

This keeps the script readable. A future you, or someone else on the server, can open it
later and understand what it was supposed to do.

For a short pause inside the same run, use:

next.secs(1)
macchi.reply("One second passed.")

The wait is bounded by the same 30-second execution lifetime. It is not durable
scheduling and does not survive cancellation or a restart.

When You Need Exact Names

This page keeps things gentle on purpose. When you want the exact list of modules,
properties, and builders available to Lua, open the Lua API
reference. If you want editor files for autocomplete or tooling, use
Lua API Downloads.