Scripting

Scripts iniciados por uma pessoa podem consultar o snapshot limitado ctx.scripts.
Metadados, gerenciamento e acesso ao código-fonte são estados separados. macchi.ask
pode propor uma ação explícita em uma confirmação privada, mas a proposta não concede
autoridade e expira rapidamente. Depois de Aceitar, a Macchi verifica novamente a
pessoa, o contexto, as dependências e as permissões atuais.

Para o ciclo completo de Adicionar versus Instalar e exemplos das tabelas Ask, veja
Scripts e instalações.

Um script da Macchi é um pedacinho de Lua que diz ao bot o que fazer. Pode ser algo
simples como “responda esta mensagem”, ou pode crescer para algo mais interativo com
botões, contexto, verificações e comportamento específico do servidor.

A ideia não é virar dev do dia pra noite. A ideia é dar ao seu servidor um jeito de
dizer: “na real, eu queria que o bot fizesse essa coisinha do nosso jeito”.

Scripts Começam Pequenos

O script mais fácil é uma resposta:

macchi.reply("Pong!")

Isso já é útil. Você pode transformar em um comando customizado, dar um nome e rodar
quando alguém precisar. Depois, dá para fazer a resposta mencionar a pessoa que acionou
o script:

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

ctx é o contexto atual. Ele mostra o que está acontecendo agora, como quem acionou o
script. macchi é a API amigável para fazer coisas de bot, como responder.

Comandos São Para “Alguém Pediu”

Comandos customizados são o começo mais confortável. Alguém roda um comando, a Macchi
roda o script e o script responde. Isso é ótimo para links do servidor, respostas de
FAQ, piadinhas, notas de configuração ou aquele “lê isso antes de perguntar” sem ficar
repetindo toda hora.

Se você já quis um comando de bot que fala exatamente a frase que seu servidor precisa,
comandos customizados provavelmente são o primeiro lugar para testar.

Eventos São Para “Algo Aconteceu”

Alguns scripts devem rodar mesmo quando ninguém digitou o nome deles. É para isso que
servem os
Eventos. Um evento de menção pode responder quando alguém marca a Macchi. Um
evento de entrada pode dar boas-vindas. Um evento de mensagem com prefixo pode observar
mensagens que usam seu prefixo, mas não são comandos salvos.

Comando é como apertar um botão. Evento é a Macchi percebendo o ambiente.

Respostas Podem Continuar Simples

Para a maioria dos scripts iniciais, macchi.reply(text) basta. Ele envia uma resposta
normal e deixa você pensar nas palavras em vez de ficar brigando com formatação de
mensagem.

Quando quiser algo mais interativo, use o construtor de mensagens:

message.new()
  :text("Escolha uma ação.")
  :button("help", "Ajuda")
  :send()

Você não precisa disso no primeiro dia. Está ali para quando uma resposta simples
começar a ficar pequena.

Scripts Publicados

Ativação e publicação são coisas separadas. Um script ativo pode rodar; um script
desativado continua salvo, mas não roda. Publicar cria uma versão pública imutável.
Editar um script ativo depois disso cria alterações não publicadas sem mudar a
publicação exata instalada em outro contexto. Uma instalação preserva essa identidade e
não copia o código para um novo rascunho.

Quando você publica um script, a Macchi expõe apenas a referência tipada de
autor/nome/versão, como u123/boas-vindas@1. IDs curtos internos não são a identidade
pública do script.

Os metadados publicados têm uma descrição curta para cards e selects do Discord, um
icon_url opcional e o readme_markdown em Markdown fonte para detalhes públicos.
readme_markdown é limitado a 4000 caracteres porque pode ser preenchido por modal do
Discord. URLs de ícone precisam usar http:// ou https://; a Macchi não baixa a URL
nem verifica a imagem remota.

Scripts publicados podem receber Hypes pelo Discord. Hype é um impulso diário, não uma
relação permanente de like: cada usuário pode dar um hype por dia no total.

O site público também tem uma biblioteca de scripts em /library. Ela permite buscar
scripts publicados, abrir /library/<typed_owner_id>/<script_name>@<version>, ler o
readme_markdown publicado, escolher uma versão, inspecionar o código e abrir uma
revisão de instalação por escopo. A contagem de hypes aparece ali, mas dar hype ainda
acontece pelo bot no Discord.

Um Padrão Útil

Tente escrever scripts como uma conversa curta:

local prefix = macchi.prefix

macchi.reply(
  "Precisa de ajuda? Meu prefixo é `" .. prefix .. "`. Tente `" .. prefix .. "hello`."
)

Isso deixa o script legível. Você no futuro, ou outra pessoa do servidor, pode abrir e
entender o que ele deveria fazer.

Para fazer uma pausa curta dentro da mesma execução, use:

next.secs(1)
macchi.reply("Passou um segundo.")

A espera continua limitada pelos mesmos 30 segundos da execução. Ela não é agendamento
durável e não sobrevive a cancelamento ou reinicialização.

Quando Precisar dos Nomes Exatos

Esta página é leve de propósito. Quando quiser a lista exata de módulos, propriedades e
builders disponíveis no Lua, abra a referência da API Lua. Se quiser
arquivos para autocomplete ou ferramentas, use Downloads da API
Lua.