Il tuo primo plugin

Questo tutorial installa un plugin della community, lo configura e lo usa da uno script Lua, dall’inizio alla fine. La parte 1 usa Moongate.Plugins.Notifications con il suo canale log: non serve nessun account e non manda nulla fuori dalla tua macchina. La parte 2 ripete i passi con Moongate.Plugins.OpenAi, che richiede una chiave API.

Ti serve:

una root del server preparata (mgctl init, vedi Primo avvio) e un account game master con un personaggio nel mondo;
mgctl della stessa release del server: mgctl --version stampa la versione, e un plugin è compilato per una sola;
una connessione a internet perché mgctl raggiunga Codeberg.

I comandi qui sotto usano /srv/moongate come root. Sostituiscila con la tua.

Parte 1: Notifications

1. Ferma il server e installa

Il server legge plugins/ una sola volta, all’avvio, quindi fermalo prima. Poi:

mgctl plugin install Moongate.Plugins.Notifications --root-directory /srv/moongate

Con un id di plugin, mgctl cerca nel repository della community e sceglie la build più recente fatta per il tuo Moongate. Mostra cosa ha trovato e chiede conferma prima di installare:

Plugin     Moongate.Plugins.Notifications 0.2.0
Built for  Moongate 0.17.0
Found in   Codeberg moongate/moongate-plugins
SHA-256    a483f510ed545d1bdcee50a0874e8d518375e60aaaeddf7c85a18381f263a268
A plugin runs inside the server with all its permissions: install it only from a source you trust.
Install it? [y/N]

Rispondi y. Controlla il risultato:

mgctl plugin list --root-directory /srv/moongate

Plugin                          Version  Built for  Origin
Moongate.Plugins.Notifications  0.2.0    0.17.0     package

Il plugin ora è la cartella /srv/moongate/plugins/Moongate.Plugins.Notifications/.

2. Avvia una volta, poi configura

Avvia il server e fermalo di nuovo. Al primo avvio il plugin aggiunge in fondo a config/moongate.toml la sua tabella [notifications], spenta. Apri il file e fai dire alla tabella questo, tenendo ciò che il plugin ha aggiunto se è diverso:

[notifications]
enabled = true

[notifications.channels.audit]
type = "log"

Un canale è il posto dove vanno le notifiche. log scrive una riga del log del server per ogni notifica; i canali Discord e webhook si configurano allo stesso modo, con un indirizzo che tieni in una variabile d’ambiente (Telegram e SMTP vengono da plugin a parte). Le chiavi stanno nella pagina del plugin, nel suo repository.

3. Pubblica una notifica da Lua

Il plugin aggiunge un modulo Lua, notify. Per provarlo serve qualcosa che esegua uno script: un piccolo NPC che suona il campanello dello staff quando un giocatore dice “alarm”.

Crea templates/mobiles/tutorial_bell.toml:

[[mobile]]
id = "tutorial_bell"
base_id = "male"
name = "Bell Ringer"
script_id = "tutorial_bell"
notoriety = "invulnerable"

Crea scripts/mobiles/tutorial_bell.lua:

tutorial_bell = {}

function tutorial_bell.on_speech(serial, speaker, text)
    if not text:lower():find("alarm", 1, true) then
        return
    end

    local sent = notify.send{
        topic   = "staff.tutorial",
        level   = "info",
        title   = "The bell rang",
        message = "A player said the word to the bell ringer.",
    }

    if sent then
        npc.say(serial, "The staff has been told.")
    else
        npc.say(serial, "Nobody wanted that notification.")
    end
end

Il messaggio non porta ciò che il giocatore ha scritto: una notifica lascia il server verso chi possiede il canale, quindi pubblica ciò che lo script sa, non ciò che scrivono i giocatori.

4. Provalo

Avvia il server e cerca nel log Disk plugin Moongate.Plugins.Notifications: ...: è la riga che ti dice che il plugin è stato caricato.
Entra con il tuo personaggio game master, esegui .spawn tutorial_bell e indica un punto.
Di’ “alarm” entro 15 celle dall’NPC.
L’NPC risponde “The staff has been told.” e il log del server contiene la notifica: Notification staff.tutorial: The bell rang - A player said the word to the bell ringer.

Quando l’NPC risponde “Nobody wanted that notification.”, notify.send ha restituito false:

Causa	Rimedio
`enabled = false`	Imposta `enabled = true` e riavvia
Nessun canale vuole la notifica	Aggiungi un canale; con `topics` o `min_level` sul canale, controlla che `staff.tutorial` e `info` passino
Un argomento non è valido	Il log ha un avviso che lo nomina

Parte 2: OpenAI

Gli stessi quattro passi, per un NPC che risponde a un giocatore restando nel personaggio. Ciò che i giocatori scrivono va a OpenAI, o al server a cui punti il plugin: il plugin è spento finché non lo accendi.

Installa. Con il server fermo:

mgctl plugin install Moongate.Plugins.OpenAi --root-directory /srv/moongate

Configura. Avvia una volta e ferma, poi modifica la tabella [openai]. Metti la chiave in una variabile d’ambiente del server, non nel file, e indica il nome della variabile:
```
[openai]
enabled = true
api_key_env = "OPENAI_API_KEY"
model = "your-model"            # required: the model your provider offers

[openai.personas.fabbro]
prompt = "You are Mario, the blacksmith of Britain. You are gruff and proud of your work."
```
Una persona è un prompt a cui dai un nome; lo script ne sceglie una con il suo id. base_url punta il plugin a qualsiasi server compatibile con OpenAI, anche un modello locale.

Usalo. Crea templates/mobiles/tutorial_mario.toml con id = "tutorial_mario", name = "Mario" e script_id = "tutorial_mario", come nella parte 1, e scripts/mobiles/tutorial_mario.lua:

tutorial_mario = {}

function tutorial_mario.on_speech(serial, speaker, text)
    if not text:lower():find("mario", 1, true) then
        return
    end

    npc.look_at(serial, speaker)

    openai.ask{
        persona  = "fabbro",
        npc      = serial,
        player   = speaker,
        text     = text,
        callback = function(answer, reason)
            if answer then
                npc.say(serial, answer)
            else
                npc.say(serial, "(no answer: " .. tostring(reason) .. ")")
            end
        end
    }
end

La callback gira più tardi, in un turno del game loop, con la riga da dire oppure nil e un motivo. Il plugin non dice nulla da solo: cosa fa l’NPC senza una risposta lo decide lo script. Stampare il motivo, come qui, serve per la prova; uno shard resterebbe in silenzio.

Provalo. Avvia il server, esegui .spawn tutorial_mario, indica un punto e di’ “Mario, what do you forge?” entro 15 celle. I motivi che puoi incontrare (disabled, persona, cooldown, rate, budget, timeout, empty, tra gli altri) sono elencati nella pagina del plugin.

Aggiornare e rimuovere

Installa sopra la vecchia per aggiornare, e remove per eliminare; entrambi lasciano le impostazioni in config/moongate.toml:

mgctl plugin install Moongate.Plugins.OpenAi --root-directory /srv/moongate
mgctl plugin remove Moongate.Plugins.OpenAi --root-directory /srv/moongate

Dopo un aggiornamento del server, installa la build di ciascun plugin fatta per la nuova versione: il server rifiuta quella compilata per un’altra.

Dove andare dopo

Installare e gestire i plugin: Docker, il tuo repository, le migrazioni SQL e cosa fare quando il server non parte.
mgctl: cosa controlla plugin install.
Script dei mobile: gli hook che lo script di un NPC può definire.
Scrivere un plugin: costruiscine uno tu.

Creato con ❤️ da Tom