Installare e gestire i plugin

Un plugin aggiunge codice al tuo server: nuovi servizi, comandi, moduli Lua o impostazioni. Il server carica i plugin che trova sotto <root>/plugins/ una sola volta, all’avvio. Questa pagina è per chi gestisce uno shard e vuole aggiungere, aggiornare o rimuovere un plugin. Per provarne uno passo per passo, segui Il tuo primo plugin. Per scriverne uno, leggi Scrivere un plugin.

Da dove vengono i plugin

I plugin della community stanno in moongate/moongate-plugins. Ogni release lì contiene un pacchetto .nupkg, la pagina del plugin e la versione di Moongate per cui è stato compilato.

Plugin	Cosa fa
Moongate.Plugins.OpenAi	Dialoghi degli NPC risposti da OpenAI, da un modulo Lua; spento finché non lo abiliti e non gli dai una chiave
Moongate.Plugins.Notifications	Avvisa lo staff fuori dal gioco, da Lua con notify.send o da un plugin: Discord, un webhook o il log; spento finché non lo abiliti e non aggiungi un canale
Moongate.Plugins.Notifications.Telegram	Aggiunge un canale telegram a quello qui sopra, che va installato prima
Moongate.Plugins.Notifications.Smtp	Aggiunge un canale smtp (e-mail) a quello qui sopra, che va installato prima, versione 0.2.0 o successiva

Un plugin è compilato per una versione esatta di Moongate. Il server rifiuta un bundle compilato per un’altra, e mgctl lo rifiuta prima, con un messaggio più chiaro. Dopo aver aggiornato il server, installa la build di ogni plugin fatta per la nuova versione.

Prima di installare

1. Fidati della fonte. Un plugin gira dentro il processo del server con tutti i suoi permessi: può leggere i database, gli account e i file della radice. Installane uno solo da un autore di cui ti fidi, e confronta lo SHA-256 che stampa mgctl con quello che la pagina della release mostra accanto all’asset.
2. Ferma il server. Legge plugins/ solo all’avvio: i file sostituiti sotto un server in esecuzione possono non copiarsi (Windows blocca le DLL) e hanno effetto solo al riavvio successivo.
3. Controlla la versione. mgctl --version e la nota “Built for Moongate” della release del plugin devono coincidere.
4. Fai un backup dei database se il plugin distribuisce migrazioni SQL: vanno solo avanti.

Installare

mgctl plugin install Moongate.Plugins.OpenAi --root-directory /srv/moongate
mgctl plugin install https://codeberg.org/moongate/moongate-plugins/releases/download/Moongate.Plugins.OpenAi-v0.2.1/Moongate.Plugins.OpenAi.0.2.1.nupkg --root-directory /srv/moongate
mgctl plugin install ./Moongate.Plugins.OpenAi.0.2.1.nupkg --root-directory /srv/moongate

Il comando accetta un id di plugin, un indirizzo https o un file, controlla il pacchetto, mostra id, versione e SHA-256, e chiede Install it? [y/N]; --yes risponde al posto tuo in uno script. I controlli e le protezioni che esegue sono elencati in Installare un pacchetto plugin. Il risultato è <root>/plugins/<PackageId>/.

Con un id, mgctl cerca il plugin nel repository della community e installa la build più recente fatta per la versione di Moongate che esegui: non ti serve l’indirizzo della release.

Dal tuo repository

Un plugin scritto da te, o di un autore di cui ti fidi, può stare in un repository suo. Allega il pacchetto (dotnet pack lo chiama <PackageId>.<version>.nupkg) a una release su Codeberg o GitHub, oppure tieni i pacchetti in una cartella, e punta mgctl lì:

mgctl plugin install MyPlugin --repo myuser/my-plugins --root-directory /srv/moongate
mgctl plugin install MyPlugin --repo ./my-packages --version 1.2.0 --root-directory /srv/moongate

Un repository può contenere molti plugin e molte versioni: mgctl sceglie la build più recente fatta per il tuo Moongate, oppure dice quali versioni esistono. Per un repository privato metti un token in CODEBERG_TOKEN (GITHUB_TOKEN su GitHub). Le regole sono in Installare per id da un repository.

mgctl plugin arriva con le release successive alla 0.16.0. Con la 0.16.0, estrai a mano la cartella plugin/ del .nupkg (è un file zip) in <root>/plugins/<PackageId>/: la cartella deve contenere <PackageId>.dll e <PackageId>.deps.json.

In Docker

L’immagine contiene mgctl accanto al server e tiene la radice nel volume /data. Ferma il container, esegui il comando sul volume, riavvia il container:

docker stop moongate        # the name of your container
docker run --rm --entrypoint /app/mgctl \
  --mount type=volume,source=moongate-data,target=/data \
  docker.io/tgiachi/moongate:latest \
  plugin install https://codeberg.org/moongate/moongate-plugins/releases/download/Moongate.Plugins.OpenAi-v0.2.1/Moongate.Plugins.OpenAi.0.2.1.nupkg \
  --root-directory /data --yes
docker start moongate

Usa l’immagine della stessa versione del container: mgctl controlla il plugin rispetto alla propria versione.

Configurare e avviare

1. Configuralo. Le impostazioni di un plugin sono una tabella di config/moongate.toml. Il plugin aggiunge la propria tabella con i valori predefiniti al primo avvio, di solito spenta: avvia una volta, ferma, modificala, avvia di nuovo. Leggi la pagina del plugin (plugins/<PackageId>/README.md nel suo repository) per le chiavi, e imposta ciò che serve. Tieni un segreto come una chiave API in una variabile d’ambiente, non nel file. Vedi Sezioni dei plugin.
2. Applica il suo SQL, se ne distribuisce: mgctl migrate apply --target world, oppure lascia fare al server con persistence.auto_apply_migrations; l’SQL dei bundle sotto plugins/ è incluso. Vedi Migrazioni della persistenza.
3. Avvia il server e leggi il log: Loaded N disk plugins li conta e una riga Disk plugin <id>: <name> <version> - <description> per ciascuno li nomina; Plugin '<id>' registered segue man mano che ognuno parte.

Vedere cosa è installato

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

Plugin                   Version  Built for  Origin
Moongate.Plugins.OpenAi  0.2.1    0.17.0     package

Origin è package per ciò che ha installato mgctl e by hand per un bundle copiato lì a mano, la cui versione è letta dal suo assembly.

Aggiornare

Installa il pacchetto più recente sopra quello più vecchio con lo stesso comando. Il vecchio bundle viene sostituito solo quando il nuovo è al suo posto; le impostazioni in config/moongate.toml restano. Leggi le note di release del plugin per le impostazioni cambiate, poi avvia il server.

Rimuovere

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

Cancella <root>/plugins/<PackageId>/. Due cose restano di proposito, e sta a te pulirle se vuoi che spariscano:

• la tabella del plugin in config/moongate.toml, che il server ignora finché il plugin non è installato;
• le tabelle del database del plugin, perché le migrazioni vanno solo avanti.

Se il server non parte

Un bundle che non si carica rifiuta l’avvio con un messaggio che lo nomina. Le cause più comuni:

Messaggio o sintomo	Causa e rimedio
The plugin entry assembly is missing.	Il nome della cartella e quello della sua DLL differiscono; la DLL deve essere <folder>.dll. Reinstalla con mgctl
Failed to load plugin bundle con un’eccezione interna su un assembly o la sua versione	Il plugin è stato compilato per un’altra versione di Moongate, o ha perso un file: installa la build fatta per la tua
Plugin '<id>' failed during registration.	L’avvio del plugin stesso ha lanciato un’eccezione, spesso un valore non valido nella sua tabella di config/moongate.toml; l’eccezione interna dice quale
Una cartella di plugins/ che non è un plugin	Rimuovila: il loader tratta come bundle ogni cartella di plugins/, tranne quelle il cui nome inizia con un punto

L’elenco completo è in Errori che impediscono l’avvio. Per tornare a un server funzionante, esegui mgctl plugin remove <id> sul plugin e avvia di nuovo.