Reference

Lua API

Learn what the generated Lua API reference is for.

Published by solever7 solever7
lua poplua api reference

This page is not available in ja yet, so the en version is being shown.

The Lua API is the list of things Macchi lets scripts use. If macchi.reply sends a
message, ctx.user tells you who triggered the script, and a message builder creates
buttons, the API reference is where those names are written down.

You do not need this page to write your first script. Start with
Scripting if you want a gentler explanation. Come back here when
you are thinking, “I know what I want, but what is the exact name for it?”

Why This Page Exists

Macchi’s scripting API is generated from the host code through PopLua. That means the
reference can stay close to what the bot actually exposes instead of being a
hand-written guess.

The generated reference is more technical than the rest of the wiki. That is on purpose.
It is useful when you want to check a property, method, builder, or module name without
digging through source code.

How To Read It

Read it like a shelf, not like a novel. Search for the thing you are trying to do:
reply, build a message, inspect the current author, or work with script context. If a
name looks interesting, try it in a small script before building a whole flow around it.

For example, the scripting page shows:

macchi.reply("Hello " .. ctx.user.username)

The API reference is where you go when you want to know what else macchi or ctx.user
can do.

Current Member Mutation

ctx.member:changeNick("New nickname") is available only for the trusted member already
supplied by the trigger. It rechecks current Discord permissions and role hierarchy
immediately before the request, is durably audited without storing the nickname, and
never accepts a user ID from Lua. See the canonical Lua API
reference for the full contract.

ctx.member:dm("Message") sends one attributed DM to that same trusted member. It uses
the audited member.dm.send operation, recipient quotas, empty allowed mentions, and
guildless output ownership. Member invocation and eligible Server automation may use it.
DM content is not retained in operation audit.

Events Use The Same API

Scripts triggered by Events use the same general scripting surface.
The difference is what starts the script, not a totally separate language. A mention
script and a command script can both reply; they just run at different moments.

Delay Inside One Run

Use next.secs(seconds) for a short non-blocking pause:

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

The maximum delay is 10 seconds and one execution may request 5 delays. Waiting does not
spend the 2-second active-work budget, but it does spend the 30-second total lifetime
and stops promptly on cancellation. It does not schedule future work and does not
survive a restart.

For a short interactive flow, wait for the same member in the same channel:

local answer = next.message(10, "yes")
local reaction = next.reaction(10, "<:kitalua:1497600179472302180>")

Event waits are limited to 15 seconds and still consume the execution’s wall time. They
cannot listen across servers, channels, users, or executions.

Safe reaction changes

Macchi can add or remove only its own reaction on a message already provided by the
trusted context:

if ctx.message ~= nil then
    ctx.message:addReaction("<:kitalua:1497600179472302180>")
    -- ctx.message:removeOwnReaction("<:kitalua:1497600179472302180>")
end

Macchi checks the member, bot permissions, channel, message, and emoji again immediately
before Discord. The operation is durably audited without storing message content.
Arbitrary message IDs and removal of other users’ reactions are not available.

Trigger authority is assigned before event data is exposed. On automatic server events,
ctx.member may be the affected subject; its presence does not make that member an
authorizing actor. Server automation still requires its capabilities, current bot
permissions, scope checks, quotas, and audit.

A confirmed send returns an opaque owned output:

local sent = macchi.reply("Working...")
sent:edit(message.new():text("Done"))
-- sent:delete()

Only the same script and owner can mutate it. Edits rebuild attribution and allowed
mentions, while audit metadata never stores message content.

Trusted role add/remove and timeout set/clear are available only with explicit effective
capabilities, eligible Member or Server authority, current Discord permission and
hierarchy, target quotas, and durable content-free audit. Macchi-owned public threads
can be created, renamed, and archived through an opaque handle. Kick, ban, arbitrary
IDs, broad channel administration, and
third-party thread mutation remain unavailable.

Downloads And Editor Help

If you want files for autocomplete, local reference notes, or tooling, visit Lua API
Downloads. The most useful file for many Lua-aware editors
is poplua.d.lua, because it can help the editor understand Macchi-specific names.

If the generated artifact exists, it is rendered below. If it has not been generated
yet, Macchi shows a short placeholder instead.

PopLua Lua API

Schema poplua.lua-api v2, PopLua 1.0.0-rc.2.

Generated from C# PopLua binding declarations.

Contents

Modules

Module components

Convenience constructors for message component objects.

Component objects are inert until they are added to a message and sent. Macchi does not store durable Lua callbacks; interactive components route to named Lua entry functions in a fresh execution.

Capability: macchi.components

Functions

components.button(entry: string, label: string): Button

Creates an interactive button that can be added to a message.

Parameters:

  • entry — Lua function entry to invoke when clicked.
  • label — Visible button label.

Returns:

  • A Button object. The button is not sent until a message containing it is sent.
components.channelSelect(entry: string, placeholder?: string | nil): EntitySelect

Creates a routed channel select.

Examples:

local select = components.channelSelect("picked", "Choose a channel")
components.gallery(): MediaGallery

Creates an inert Components V2 media gallery.

Returns:

  • An empty gallery. Add one to ten items before adding it to a message.
components.linkButton(label: string, url: string): Button

Creates a link button that opens a URL instead of routing to Lua.

Parameters:

  • label — Visible button label.
  • url — Absolute http(s) URL.

Returns:

  • A link Button object.
components.mentionableSelect(entry: string, placeholder?: string | nil): EntitySelect

Creates a routed user-or-role select.

Examples:

local select = components.mentionableSelect("picked", "Choose a target")
components.modal(title: string, entry: string, label?: string | nil): Modal

Creates a durable modal opened by a button in an owned message.

Examples:

local form = components.modal("Feedback", "submitFeedback")
form:paragraph("message", "Message")
components.option(label: string, value: string, description?: string | nil): SelectOption

Creates an option for a select menu.

components.roleSelect(entry: string, placeholder?: string | nil): EntitySelect

Creates a routed role select.

Examples:

local select = components.roleSelect("picked", "Choose a role")
components.select(entry: string, placeholder?: string | nil): Select

Creates a select menu that can be added to a message.

Parameters:

  • entry — Lua function entry to invoke when a value is selected.
  • placeholder — Placeholder shown before selection.

Returns:

  • A Select object. The menu is not sent until a message containing it is sent.
components.userSelect(entry: string, placeholder?: string | nil): EntitySelect

Creates a routed user select.

Examples:

local select = components.userSelect("picked", "Choose a user")

Module ctx

Runtime context exposed to Lua as the generated ctx module.

The context is valid only for the current ephemeral script execution. It contains sanitized host data and never exposes raw Discord objects.

Capability: macchi.context

Values

  • ctx.actor: User | nil read-only — Authorization-bearing user for intentional invocations, or nil for server events.
  • ctx.args: string read-only — Raw arguments supplied by the user or event host.
  • ctx.attachment: Attachment | nil read-only — First attachment from the bounded message snapshot, or nil.
  • ctx.authority: string read-only — Trusted authority kind assigned by the host. Missing member data never increases it.
  • ctx.channel: Channel | nil read-only — Channel where the execution happened, or nil when unavailable.
  • ctx.component: Component | nil read-only — Component interaction data, or nil outside component executions.
  • ctx.componentName: string read-only — Name of the component interaction being handled, or an empty string.
  • ctx.entry: string read-only — Internal entry id, such as u123/help@42:run.
  • ctx.executionReference: string read-only — Opaque public execution reference, or an empty string when durable evidence is unavailable.
  • ctx.guild: Guild | nil read-only — Guild/server where the execution happened, or nil in DMs.
  • ctx.isDm: boolean read-only — Whether this execution is running without a guild/server context.
  • ctx.isGuild: boolean read-only — Whether this execution has a guild/server context.
  • ctx.member: Member | nil read-only — Guild member data for the triggering user, or nil when unavailable.
  • ctx.message: MessageContext | nil read-only — Message that triggered the execution, or nil when unavailable.
  • ctx.ownedMessage: OwnedMessage | nil read-only — Owned Macchi output associated with this trusted interaction, or nil.
  • ctx.permissionMode: string read-only — Trusted trigger permission behavior; Lua cannot change it.
  • ctx.prefix: string read-only — Current user prefix resolved by the host.
  • ctx.reaction: Reaction | nil read-only — Reaction event data, or nil outside reaction executions.
  • ctx.script: string read-only — Public draft reference without an entry suffix, such as u123/help@0.
  • ctx.scriptName: string read-only — Current script name.
  • ctx.scriptType: string read-only — Current script type.
  • ctx.scripts: Scripts read-only — Bounded script metadata captured once for this execution.
  • ctx.source: string read-only — Event source that started this execution.
  • ctx.subject: User | nil read-only — Affected event user for automatic server events, or nil for intentional invocations.
  • ctx.user: User read-only — Discord user identity that triggered the current execution.

Module emoji

Creates emoji tokens that can be attached to texts and buttons.

Capability: macchi.components

Functions

emoji.new(name: string): string

Creates an emoji token for usages like Button:emoji(…).

Parameters:

  • name — A custom emoji token or known Macchi emoji name such as kitalua.

Returns:

  • An emoji token accepted by button builders.

Module log

Host logging functions available to Lua scripts.

Log messages are routed through the current Macchi host and do not send Discord messages.

Capability: macchi.log

Functions

log.error(message: string)

Writes an error log message.

Parameters:

  • message — Message to log.
log.info(message: string)

Writes an informational log message.

Parameters:

  • message — Message to log.
log.warn(message: string)

Writes a warning log message.

Parameters:

  • message — Message to log.

Module macchi

Discord/chat output functions available to Macchi scripts.

Methods are async and perform host actions during the current execution. They do not queue responses for a later flush.

Capability: macchi.discord

Values

  • macchi.ask: Ask read-only — Platform-owned, proposal-only script management actions.
  • macchi.prefix: string read-only — Current user prefix resolved by the host for this execution.
  • macchi.storage: Storage read-only — Shared persistent storage and host-local best-effort cache.

Functions

macchi.dm(text: string)

Sends an audited direct message to the trusted member in the current execution context.

Async: yes

Parameters:

  • text — Message text to send privately. Its content is not retained in operation audit.
macchi.reply(text: string): OwnedMessage

Sends a reply in the current runtime surface.

Async: yes

Parameters:

  • text — Message text to send.
macchi.replyMessage(message: MessageBuilder): OwnedMessage

Sends a message object built with message.new().

Async: yes

Parameters:

  • message — Message object to send.
macchi.send(channelId: string, text: string): OwnedMessage

Sends a message to a channel in the current guild.

Async: yes

Parameters:

  • channelId — Target channel id. The host only resolves channels inside the current guild.
  • text — Message text to send.

Module message

Creates message builders that can be sent with Discord Components V2 controls.

Capability: macchi.discord

Functions

message.new(): MessageBuilder

Creates an empty message builder. The message is not sent until :send() is called.

Returns:

  • A new MessageBuilder.

Module next

Bounded delays inside the current ephemeral execution.

Delays pause PopLua active-time accounting while suspended, but wall-time and cancellation continue to apply. This module is not a durable scheduler.

Functions

next.message(seconds: number, contentPrefix: string): MessageContext

Waits for the triggering actor’s next message in the current channel.

Async: yes

next.reaction(seconds: number, emoji: string): Reaction

Waits for the triggering actor’s next reaction on the triggering message.

Async: yes

next.secs(seconds: number)

Suspends this execution for a bounded number of seconds.

Async: yes

Parameters:

  • seconds — Delay in seconds, from zero through the configured maximum.

Exceptions:

  • ArgumentOutOfRangeException — Thrown when the duration is not finite or is outside the allowed range.

Module threads

Creates bounded Macchi-owned threads from trusted channel context.

Capability: macchi.discord

Functions

threads.create(parent: Channel, title: string): OwnedThread

Creates one owned public thread under a trusted current channel.

Examples:

local thread = threads.create(ctx.channel, "Discussion")

Async: yes

Userdata

Userdata Ask

Creates transport-neutral proposals. Macchi revalidates and applies an accepted action.

Methods

Ask:forAdd(options: ask_add_options)

Proposes a new mutable draft from a strict options table.

Async: yes

Ask:forCapabilities(options: ask_target_options)

Proposes opening the canonical capability manager for a mutable script.

Async: yes

Ask:forDelete(options: ask_target_options)

Proposes deleting one manageable mutable script.

Async: yes

Ask:forDisable(options: ask_target_options)

Proposes disabling one manageable mutable script.

Async: yes

Ask:forEnable(options: ask_target_options)

Proposes enabling one manageable mutable script.

Async: yes

Ask:forInstall(options: ask_install_options)

Proposes installing one exact immutable publication without copying its source.

Async: yes

Ask:forPublish(options: ask_target_options)

Proposes publishing an immutable next revision of a mutable script.

Async: yes

Ask:forUninstall(options: ask_target_options)

Proposes removing an installation after checking its dependents.

Async: yes

Ask:forUpdate(options: ask_update_options)

Proposes changing one manageable mutable script.

Async: yes

Userdata Attachment

Bounded read-only Discord attachment metadata; content is never downloaded.

Properties

  • Attachment.contentType: string read-only
  • Attachment.ephemeral: boolean read-only
  • Attachment.filename: string read-only
  • Attachment.height: integer read-only
  • Attachment.id: string read-only
  • Attachment.size: integer read-only
  • Attachment.url: string read-only
  • Attachment.width: integer read-only

Userdata Button

Discord button object that can be added to a message and routed back to a Lua entry function.

Properties

  • Button.entry: string read-only — Lua entry function name invoked when the button is clicked.
  • Button.label: string read-only — Visible button label.
  • Button.url: string read-only — URL for link buttons. Empty for interactive buttons.

Methods

Button:disabled(disabled: boolean): Button

Marks the button disabled or enabled.

Parameters:

  • disabled — Whether the button should be disabled.

Returns:

  • The same button object for chaining.
Button:emoji(emoji: string): Button

Attaches an emoji token to the button.

Parameters:

  • emoji — Emoji text or custom Discord emoji token.

Returns:

  • The same button object for chaining.
Button:style(style: string): Button

Changes the button style.

Parameters:

  • style — primary, secondary, success, danger, or link.

Returns:

  • The same button object for chaining.

Userdata Channel

Discord channel context for the current execution.

Properties

  • Channel.id: string read-only — Discord channel id as a string.
  • Channel.isNsfw: boolean read-only
  • Channel.isThread: boolean read-only
  • Channel.mention: string read-only — Discord channel mention text.
  • Channel.name: string read-only — Channel display name.
  • Channel.parentId: string read-only
  • Channel.position: integer read-only
  • Channel.topic: string read-only
  • Channel.type: string read-only

Methods

Channel:delete(options: moderation_options)

Deletes the current trusted channel after live Manage Channels checks.

Capability: macchi.discord

Async: yes

Channel:edit(options: channel_edit_options)

Edits the current trusted channel after live Manage Channels checks.

Capability: macchi.discord

Async: yes

Channel:purge(options: purge_options): deletion_result

Deletes a bounded set of messages matching all selected filter categories.

Capability: macchi.discord

Async: yes

Userdata Component

Component interaction context for the current execution.

Properties

  • Component.id: string read-only — Component route id/name.
  • Component.name: string read-only — Component entry name.
  • Component.value: string read-only — Selected value or modal value, when available.
  • Component.valueCount: integer read-only — Number of selected dropdown values or submitted fields.
  • Component.values: string read-only — Selected dropdown values or submitted field values joined by newlines.

Methods

Component:field(key: string): string

Returns a submitted modal field by its schema key.

Component:fieldAt(key: string, index: integer): string

Returns one value from a multi-value modal field by 1-based index.

Parameters:

  • key — Modal schema key.
  • index — One-based value index.

Returns:

  • The selected value or uploaded file URL, or an empty string when absent.
Component:fieldCount(key: string): integer

Returns how many scalar values a submitted modal field contains.

Parameters:

  • key — Modal schema key.

Returns:

  • The number of values submitted for that field.
Component:valueAt(index: integer): string

Returns a selected value by 1-based index.

Userdata EntitySelect

Discord typed entity select whose selected values are handler targets, never authorization principals.

Properties

  • EntitySelect.entry: string read-only
  • EntitySelect.placeholder: string read-only

Methods

EntitySelect:disabled(disabled: boolean): EntitySelect

Userdata Guild

Discord guild/server context for the current execution.

Properties

  • Guild.bannerUrl: string read-only — Guild banner URL.
  • Guild.channelCount: integer read-only — Number of channels in the guild.
  • Guild.description: string read-only — Guild description, if any.
  • Guild.iconUrl: string read-only — Guild icon URL.
  • Guild.id: string read-only — Discord guild id as a string.
  • Guild.memberCount: integer read-only — Number of members in the guild.
  • Guild.name: string read-only — Guild display name.
  • Guild.ownerId: string read-only — Guild owner id as a string.
  • Guild.preferredLocale: string read-only — Guild preferred locale.
  • Guild.roleCount: integer read-only — Number of roles in the guild.

Methods

Guild:ban(target: User, options: ban_options): moderation_result

Bans one trusted user with an optional native previous-message deletion window.

Capability: macchi.discord

Async: yes

Guild:banMany(options: bulk_ban_options): bulk_ban_result

Bans a bounded set of trusted users without hiding partial failures.

Capability: macchi.discord

Async: yes

Guild:purgeMessages(options: purge_options): deletion_result

Deletes matching messages across a bounded set of visible authorized channels.

Capability: macchi.discord

Async: yes

Guild:unban(target: User, options: ban_options): moderation_result

Removes a ban for one trusted user.

Capability: macchi.discord

Async: yes

Userdata MediaGallery

An inert Components V2 media gallery assembled before a message is sent.

Methods

MediaGallery:item(url: string, description?: string | nil, spoiler?: boolean): MediaGallery

Adds remote image or video media with optional accessible alt text.

Parameters:

  • url — Direct absolute HTTP or HTTPS media URL.
  • description — Optional accessible description, up to 1024 characters.
  • spoiler — Whether Discord should hide the media behind a spoiler.

Returns:

  • The same gallery for chaining.

Userdata Member

Guild-specific member data with tightly scoped audited actions.

Properties

  • Member.displayName: string read-only — Display name for this user inside the guild.
  • Member.guildAvatarUrl: string read-only
  • Member.id: string read-only
  • Member.isOwner: boolean read-only
  • Member.joinedAt: string read-only — ISO timestamp for when this member joined the guild, or an empty string.
  • Member.nickname: string read-only
  • Member.roleCount: integer read-only
  • Member.timedOutUntil: string read-only — ISO timestamp for the active Discord timeout, or an empty string.
  • Member.user: User read-only — Discord user identity for this member.

Methods

Member:addRole(role: Role)

Adds one trusted same-guild role after live permission and hierarchy checks.

Capability: macchi.discord

Async: yes

Member:changeNick(nickname: string)

Changes this trusted member’s nickname through live host checks.

Capability: macchi.discord

Async: yes

Member:clearTimeout()

Clears the current timeout from this trusted member.

Examples:

ctx.member:clearTimeout()

Capability: macchi.discord

Async: yes

Member:disconnectVoice(options: moderation_options): moderation_result

Disconnects this trusted member from voice.

Capability: macchi.discord

Async: yes

Member:dm(text: string): OwnedMessage

Sends an audited direct message to this trusted guild member.

Examples:

local sent = ctx.member:dm("Your request was received.")

Capability: macchi.discord

Async: yes

Member:hasPermission(name: string): boolean

Checks one documented permission in this event snapshot.

Member:hasRole(role: Role): boolean

Checks whether this member’s bounded snapshot contains a role.

Member:kick(options: kick_options): moderation_result

Kicks this trusted member after current permission and hierarchy checks.

Capability: macchi.discord

Async: yes

Member:moveVoice(channel: Channel, options: moderation_options): moderation_result

Moves this trusted member to a trusted voice channel.

Capability: macchi.discord

Async: yes

Member:removeRole(role: Role)

Removes one trusted same-guild role after live permission and hierarchy checks.

Examples:

local role = ctx.member:roleAt(1)
if role ~= nil then ctx.member:removeRole(role) end

Capability: macchi.discord

Async: yes

Member:roleAt(index: integer): Role | nil

Returns a role from the bounded event snapshot by 1-based index.

Member:roleNameAt(index: integer): string

Returns a role name from the bounded event snapshot by 1-based index.

Member:setServerDeaf(enabled: boolean, options: moderation_options): moderation_result

Sets or clears this trusted member’s server deaf state.

Capability: macchi.discord

Async: yes

Member:setServerMute(enabled: boolean, options: moderation_options): moderation_result

Sets or clears this trusted member’s server mute.

Capability: macchi.discord

Async: yes

Member:setTimeout(seconds: integer)

Applies a bounded timeout duration in seconds to this trusted member.

Capability: macchi.discord

Async: yes

Userdata MessageBuilder

Message builder that can collect text and interactive Components V2 controls before it is sent.

Message builders are inert until message:send() is called. They do not edit or send Discord messages while they are being built.

Methods

MessageBuilder:accent(hex: string): MessageBuilder

Sets the Components V2 container accent using a hexadecimal RGB value.

Parameters:

  • hex — Six hexadecimal digits, optionally prefixed with #.

Returns:

  • The same message object for chaining.
MessageBuilder:addButton(button: Button): MessageBuilder

Adds an existing button object to the message.

Parameters:

  • button — Button object created by components.button.

Returns:

  • The same message object for chaining.
MessageBuilder:addEntitySelect(select: EntitySelect): MessageBuilder

Adds a typed Discord entity select routed through the message’s durable ownership record.

Examples:

local select = components.userSelect("choose", "Choose a user")
message.new():addEntitySelect(select):send()
MessageBuilder:addGallery(gallery: MediaGallery): MessageBuilder

Adds an existing Components V2 media gallery.

Parameters:

  • gallery — Gallery created by components.gallery().

Returns:

  • The same message object for chaining.
MessageBuilder:addModal(modal: Modal): MessageBuilder

Adds a button that opens a durable, single-use modal.

MessageBuilder:addSelect(select: Select): MessageBuilder

Adds an existing select menu object to the message.

Parameters:

  • select — Select object created by select.new or components.select.

Returns:

  • The same message object for chaining.
MessageBuilder:allowRole(role: Role): MessageBuilder

Allows one current-context role mention to notify its target.

Parameters:

  • role — The role to mention.

Returns:

  • The same message object for chaining.
MessageBuilder:allowUser(user: User): MessageBuilder

Allows one context-related user mention to notify its target.

Parameters:

  • user — The user to mention.

Returns:

  • The same message object for chaining.
MessageBuilder:button(entry: string, label: string): MessageBuilder

Adds a button by entry name and label.

Parameters:

  • entry — Lua function entry to call when clicked.
  • label — Button label.

Returns:

  • The same message object for chaining.
MessageBuilder:display(text: string): MessageBuilder

Adds one inert typed Text Display to the message body.

MessageBuilder:section(text: string, thumbnailUrl?: string | nil, description?: string | nil): MessageBuilder

Adds a text section with a thumbnail accessory.

Parameters:

  • text — Section text, up to 1000 characters.
  • thumbnailUrl — Optional absolute HTTP or HTTPS image URL.
  • description — Optional thumbnail alt text, up to 256 characters.

Returns:

  • The same message object for chaining.
MessageBuilder:sectionButton(text: string, button: Button): MessageBuilder

Adds a text section with a button accessory.

Parameters:

  • text — Section text, up to 1000 characters.
  • button — Routed or link button displayed beside the text.

Returns:

  • The same message object for chaining.
MessageBuilder:select(entry: string, placeholder?: string | nil): Select

Adds a select menu by entry name and placeholder.

Parameters:

  • entry — Lua function entry to call when a value is selected.
  • placeholder — Placeholder shown before the user selects an option.

Returns:

  • A select builder that was also added to this message.
MessageBuilder:send(): OwnedMessage

Sends the built message through the current host.

Capability: macchi.discord

Async: yes

MessageBuilder:separator(divider?: boolean, spacing?: string): MessageBuilder

Adds a Components V2 visual separator.

Parameters:

  • divider — Whether Discord draws a visible line.
  • spacing — Either small or large vertical spacing.

Returns:

  • The same message object for chaining.
MessageBuilder:spoiler(spoiler?: boolean): MessageBuilder

Controls whether Discord hides the whole Components V2 container as a spoiler.

Parameters:

  • spoiler — Whether the container is spoilered.

Returns:

  • The same message object for chaining.
MessageBuilder:text(text: string): MessageBuilder

Adds or replaces the main text body for this message.

Parameters:

  • text — Text to show in the Discord Components V2 message.

Returns:

  • The same message object for chaining.
MessageBuilder:title(title: string): MessageBuilder

Adds a title line to the message.

Parameters:

  • title — Title text.

Returns:

  • The same message object for chaining.

Userdata MessageContext

Message event context with context-bound reaction actions.

Properties

  • MessageContext.attachmentCount: integer read-only
  • MessageContext.author: User | nil read-only
  • MessageContext.channelId: string read-only
  • MessageContext.channelMentionCount: integer read-only
  • MessageContext.createdAt: string read-only
  • MessageContext.editedAt: string read-only
  • MessageContext.guildId: string read-only
  • MessageContext.id: string read-only — Discord message id as a string.
  • MessageContext.isReply: boolean read-only
  • MessageContext.mentionedUserCount: integer read-only — Number of users mentioned by this message.
  • MessageContext.mentionsBot: boolean read-only — Whether this message mentioned the current Macchi bot account.
  • MessageContext.roleMentionCount: integer read-only
  • MessageContext.text: string read-only — Message text visible to the bot.

Methods

MessageContext:addReaction(emoji: string)

Adds one audited reaction to this context-bound message.

Capability: macchi.discord

Async: yes

MessageContext:channelMentionAt(index: integer): string
MessageContext:delete(reason?: string): deletion_result

Deletes this trusted message after current channel permission checks.

Capability: macchi.discord

Async: yes

MessageContext:mentionedUserAt(index: integer): User | nil

Returns a mentioned user by 1-based index, or nil outside the list.

MessageContext:removeOwnReaction(emoji: string)

Removes only Macchi’s own audited reaction from this context-bound message.

Capability: macchi.discord

Async: yes

MessageContext:roleMentionAt(index: integer): string

Userdata Modal

A bounded modal schema routed to a named Lua entry.

Properties

  • Modal.entry: string read-only
  • Modal.label: string read-only
  • Modal.title: string read-only

Methods

Modal:actor(policy: string): Modal

Sets who may open the modal: invoker or any_member.

Modal:channels(key: string, label: string, description?: string | nil, required?: boolean, min?: integer, max?: integer): Modal

Adds a channel picker to the modal.

Parameters:

  • key — Stable schema key.
  • label — User-facing label.
  • description — Optional field help.
  • required — Whether at least one channel must be selected.
  • min — Minimum selected channels.
  • max — Maximum selected channels.

Returns:

  • The same modal for chaining.
Modal:check(key: string, label: string, description?: string | nil, selected?: boolean): Modal

Adds a single yes/no checkbox.

Parameters:

  • key — Stable schema key.
  • label — User-facing label.
  • description — Optional field help.
  • selected — Whether the checkbox starts selected.

Returns:

  • The same modal for chaining.
Modal:checks(key: string, label: string, description?: string | nil, required?: boolean, min?: integer, max?: integer): ModalChoices

Adds a multi-choice checkbox group and returns its option builder.

Parameters:

  • key — Stable schema key.
  • label — User-facing label.
  • description — Optional field help.
  • required — Whether a selection is required.
  • min — Minimum selected checkboxes.
  • max — Maximum selected checkboxes.

Returns:

  • The option builder for this checkbox group.
Modal:display(text: string): Modal

Adds non-interactive Markdown help text to the modal.

Parameters:

  • text — Markdown text displayed between fields.

Returns:

  • The same modal for chaining.
Modal:mentionables(key: string, label: string, description?: string | nil, required?: boolean, min?: integer, max?: integer): Modal

Adds a user-or-role picker to the modal.

Parameters:

  • key — Stable schema key.
  • label — User-facing label.
  • description — Optional field help.
  • required — Whether at least one target must be selected.
  • min — Minimum selected targets.
  • max — Maximum selected targets.

Returns:

  • The same modal for chaining.
Modal:paragraph(key: string, label: string, placeholder?: string, required?: boolean, min?: integer, max?: integer, description?: string | nil): Modal

Adds a paragraph text field.

Parameters:

  • key — Stable schema key.
  • label — User-facing label.
  • placeholder — Optional input hint.
  • required — Whether a value is required.
  • min — Minimum text length.
  • max — Maximum text length.
  • description — Optional field help.

Returns:

  • The same modal for chaining.
Modal:radio(key: string, label: string, description?: string | nil, required?: boolean): ModalChoices

Adds a single-choice radio group and returns its option builder.

Parameters:

  • key — Stable schema key.
  • label — User-facing label.
  • description — Optional field help.
  • required — Whether one option must be selected.

Returns:

  • The option builder for this radio group.
Modal:roles(key: string, label: string, description?: string | nil, required?: boolean, min?: integer, max?: integer): Modal

Adds a role picker to the modal.

Parameters:

  • key — Stable schema key.
  • label — User-facing label.
  • description — Optional field help.
  • required — Whether at least one role must be selected.
  • min — Minimum selected roles.
  • max — Maximum selected roles.

Returns:

  • The same modal for chaining.
Modal:select(key: string, label: string, description?: string | nil, required?: boolean, min?: integer, max?: integer): ModalChoices

Adds a string select and returns its option builder.

Parameters:

  • key — Stable schema key.
  • label — User-facing label.
  • description — Optional field help.
  • required — Whether a selection is required.
  • min — Minimum selected options.
  • max — Maximum selected options.

Returns:

  • The option builder for this select.
Modal:text(key: string, label: string, placeholder?: string, required?: boolean, min?: integer, max?: integer, description?: string | nil): Modal

Adds a one-line text field.

Parameters:

  • key — Stable schema key.
  • label — User-facing label.
  • placeholder — Optional input hint.
  • required — Whether a value is required.
  • min — Minimum text length.
  • max — Maximum text length.
  • description — Optional field help.

Returns:

  • The same modal for chaining.
Modal:upload(key: string, label: string, description?: string | nil, required?: boolean, min?: integer, max?: integer): Modal

Adds a Discord file upload. Submitted file URLs are exposed as newline-separated scalars.

Parameters:

  • key — Stable schema key.
  • label — User-facing label.
  • description — Optional field help.
  • required — Whether an upload is required.
  • min — Minimum uploaded files.
  • max — Maximum uploaded files.

Returns:

  • The same modal for chaining.
Modal:users(key: string, label: string, description?: string | nil, required?: boolean, min?: integer, max?: integer): Modal

Adds a user picker to the modal.

Parameters:

  • key — Stable schema key.
  • label — User-facing label.
  • description — Optional field help.
  • required — Whether at least one user must be selected.
  • min — Minimum selected users.
  • max — Maximum selected users.

Returns:

  • The same modal for chaining.

Userdata ModalChoices

Options for a string select, radio group, or checkbox group in a modal.

Methods

ModalChoices:done(): Modal

Returns to the owning modal so more fields can be added.

Returns:

  • The modal that owns this choice group.
ModalChoices:option(label: string, value: string, description?: string | nil, selected?: boolean): ModalChoices

Adds one choice.

Parameters:

  • label — User-facing choice label.
  • value — Stable scalar returned to the Lua handler.
  • description — Optional help text for the choice.
  • selected — Whether the choice starts selected.

Returns:

  • The same choices object for chaining.

Userdata OwnedMessage

A host-created reference to one confirmed Macchi Discord output.

Properties

  • OwnedMessage.channelId: string read-only
  • OwnedMessage.createdAt: string read-only
  • OwnedMessage.guildId: string read-only
  • OwnedMessage.id: string read-only
  • OwnedMessage.isDeleted: boolean read-only

Methods

OwnedMessage:delete()

Deletes this owned output while preserving its audit evidence.

Capability: macchi.discord

Async: yes

OwnedMessage:edit(message: MessageBuilder)

Replaces this owned output through Macchi’s trusted renderer.

Capability: macchi.discord

Async: yes

Userdata OwnedThread

Opaque handle for a thread created and durably owned by Macchi.

Properties

  • OwnedThread.state: string read-only

Methods

OwnedThread:archive()

Archives this exact Macchi-owned thread.

Examples:

thread:archive()

Capability: macchi.discord

Async: yes

OwnedThread:rename(title: string)

Renames this exact Macchi-owned thread.

Examples:

thread:rename("Reviewed discussion")

Capability: macchi.discord

Async: yes

OwnedThread:reopen()

Reopens this exact Macchi-owned thread when it is archived.

Examples:

thread:reopen()

Capability: macchi.discord

Async: yes

OwnedThread:send(text: string): OwnedMessage

Sends one attributed owned message through this exact thread.

Examples:

local message = thread:send("Update")

Capability: macchi.discord

Async: yes

Userdata Reaction

Reaction event context for the current execution.

Properties

  • Reaction.added: boolean read-only
  • Reaction.channelId: string read-only — Channel id the reaction belongs to.
  • Reaction.emoji: string read-only — Emoji text supplied by Discord for the reaction.
  • Reaction.emojiId: string read-only
  • Reaction.emojiName: string read-only
  • Reaction.guildId: string read-only
  • Reaction.isCustom: boolean read-only
  • Reaction.messageId: string read-only — Message id the reaction belongs to.
  • Reaction.user: User read-only — User who added or removed the reaction.

Userdata Role

Bounded read-only role metadata.

Properties

  • Role.color: string read-only
  • Role.everyone: boolean read-only
  • Role.id: string read-only
  • Role.managed: boolean read-only
  • Role.mention: string read-only
  • Role.name: string read-only
  • Role.position: integer read-only

Userdata Script

Read-only script metadata with an opaque execution-bound target handle.

Properties

  • Script.active: boolean read-only
  • Script.available: boolean read-only
  • Script.capabilityUrl: string read-only
  • Script.dependencies: StringList read-only
  • Script.description: string read-only
  • Script.effectiveCapabilities: StringList read-only
  • Script.executable: boolean read-only
  • Script.grantedCapabilities: StringList read-only
  • Script.kind: string read-only
  • Script.manageable: boolean read-only
  • Script.managementUrl: string read-only
  • Script.name: string read-only
  • Script.ownerKind: string read-only
  • Script.reference: string read-only
  • Script.requestedCapabilities: StringList read-only
  • Script.scope: string read-only
  • Script.source: string read-only
  • Script.sourceReadable: boolean read-only
  • Script.visible: boolean read-only

Userdata ScriptList

An indexable, bounded script list.

Properties

  • ScriptList.count: integer read-only

Methods

ScriptList:at(index: integer): Script | nil

Returns one item by one-based index, or nil.

Userdata Scripts

A stable, bounded script snapshot for this execution.

Properties

  • Scripts.count: integer read-only
  • Scripts.truncated: boolean read-only

Methods

Scripts:all(): ScriptList

Returns all items in deterministic snapshot order.

Scripts:at(index: integer): Script | nil

Returns one item by one-based index, or nil.

Scripts:channel(): ScriptList

Returns channel-owned items visible in the current channel.

Scripts:find(name: string): Script | nil

Finds the first deterministically ordered script with this name.

Scripts:findRef(reference: string): Script | nil

Finds an exact canonical script reference.

Scripts:installations(): ScriptList

Returns immutable publication installations visible in this execution.

Scripts:server(): ScriptList

Returns server-owned items visible in the current guild.

Scripts:user(): ScriptList

Returns user-owned items visible to this execution.

Userdata Select

Discord select menu object that can be added to a message and routed back to a Lua entry function.

Properties

  • Select.entry: string read-only — Lua entry function name invoked when a value is selected.
  • Select.placeholder: string read-only — Placeholder shown before a value is selected.

Methods

Select:addOption(option: SelectOption): Select

Adds an existing option object to this select menu.

Select:disabled(disabled: boolean): Select

Marks the select menu disabled or enabled.

Select:option(label: string, value: string, description?: string | nil): Select

Adds an option to this select menu.

Parameters:

  • label — Visible option label.
  • value — Value delivered to ctx.component.value when selected.
  • description — Optional short description.

Returns:

  • The same select object for chaining.

Userdata SelectOption

Discord select menu option object.

Properties

  • SelectOption.description: string read-only
  • SelectOption.label: string read-only
  • SelectOption.value: string read-only

Methods

SelectOption:default(selected?: boolean): SelectOption
SelectOption:emoji(emoji: string): SelectOption

Userdata Storage

Methods

Storage:cache(scope: string): Store
Storage:open(scope: string): Store

Userdata Store

Properties

  • Store.persistent: boolean read-only
  • Store.scope: string read-only

Methods

Store:batch(options: storage_batch_options): storage_result[]

Applies 1-20 same-scope actions atomically for persistent storage.

Async: yes

Store:compareDelete(key: string, expected: string): storage_result

Async: yes

Store:compareSet(key: string, expected: string, value: string, ttlSeconds?: integer): storage_result

Async: yes

Store:delete(key: string): storage_result

Async: yes

Store:get(key: string): storage_result

Async: yes

Store:increment(key: string, delta?: integer): storage_result

Async: yes

Store:set(key: string, value: string, ttlSeconds?: integer): storage_result

Async: yes

Userdata StringList

An indexable, bounded string list.

Properties

  • StringList.count: integer read-only

Methods

StringList:at(index: integer): string | nil
StringList:contains(value: string): boolean

Userdata User

Discord user identity that triggered a script execution.

Properties

  • User.avatarUrl: string read-only — Current event-snapshot avatar URL, or an empty string.
  • User.createdAt: string read-only — ISO timestamp derived from the Discord snowflake.
  • User.displayName: string read-only — Display name for the user.
  • User.id: string read-only — Discord user id as a string.
  • User.isBot: boolean read-only — Whether the user is a bot account.
  • User.isSystem: boolean read-only — Whether Discord marks this as a system account.
  • User.mention: string read-only — Discord mention text for the user.
  • User.username: string read-only — Best available username for display.

Descriptors

Descriptor ask_add_options

Field Type Description
capabilities string[]
dependencies string[]
description string
enable boolean
name string
scope string
source string
trigger string

Descriptor ask_install_options

Field Type Description
capabilities string[]
enable boolean
scope string
script string

Descriptor ask_target_options

Field Type Description
script Script

Descriptor ask_update_options

Field Type Description
capabilities string[]
dependencies string[]
description `string nil`
script Script
source string

Descriptor ban_options

Field Type Description
deleteMessages `delete_messages_options nil`
reason string

Descriptor ban_target

Field Type Description
user User

Descriptor bulk_ban_options

Field Type Description
deleteMessages `delete_messages_options nil`
reason string
targets ban_target[]

Descriptor bulk_ban_result

Describes the applied and failed targets of one bulk ban operation.

Field Type Description
actionId string
appliedAt string
appliedCount integer Gets the number of targets that were banned.
appliedTargets string[]
deletion deletion_result
failedCount integer Gets the number of targets that failed.
failedTargets string[]

Descriptor channel_edit_options

Field Type Description
name `string nil`
nsfw `boolean nil`
reason string
slowmodeSeconds `integer nil`
topic `string nil`

Descriptor delete_messages_options

Field Type Description
channels string
ignorePinned boolean
onFailure string
withinSeconds integer

Descriptor deletion_result

Summarizes one bounded message deletion operation.

Field Type Description
bulkDeleted integer
channels integer
deleted integer
dryRun boolean
effectiveSeconds integer
failed integer
individuallyDeleted integer
matched integer
mode string
requestedSeconds integer
scanned integer
skippedPinned integer
skippedTooOld integer
threads integer
truncated boolean

Descriptor kick_options

Field Type Description
deleteMessages `delete_messages_options nil`
reason string

Descriptor moderation_options

Field Type Description
reason string

Descriptor moderation_result

Describes the outcome of one moderation action.

Field Type Description
actionId string
applied boolean
appliedAt string
deletion `deletion_result nil`
targetId string

Descriptor purge_author

Field Type Description
user User

Descriptor purge_options

Field Type Description
after `MessageContext nil`
author `User nil`
authorType string
authors purge_author[]
before `MessageContext nil`
channelLimit integer
contains string
deleteOldIndividually boolean
dryRun boolean
endsWith string
hasAttachments `boolean nil`
hasEmbeds `boolean nil`
hasLinks `boolean nil`
hasMentions `boolean nil`
hasReactions `boolean nil`
includeThreads boolean
limit integer
messageTypes string[]
pinned string
reason string
scanLimit integer
startsWith string
withinSeconds integer

Descriptor storage_batch_item

Field Type Description
delta integer
expected `string nil`
key string
operation string
value `string nil`

Descriptor storage_batch_options

Field Type Description
items storage_batch_item[]
ttlSeconds integer

Descriptor storage_result

Describes the outcome of one storage operation.

Field Type Description
applied boolean
found boolean
value string Gets the Lua-visible value, or an empty string when the key was not found.
version integer
Explore with agents
ChatGPT