Scrivere script Lua

Inserisci gli script sotto <root>/scripts. Il bootstrap predefinito è init.lua, selezionato da [scripting].bootstrap_file nella configurazione del server. L’host usa Lua 5.2 tramite LuaCSharp; esecuzione e riprese avvengono sul ciclo di gioco. Non serve un’installazione Lua separata.

Primo script e moduli

Questa guida presuppone le basi di Lua: variabili, funzioni e tabelle. Non serve installare Lua. Tutti i percorsi qui sotto sono relativi alla root del server.

Primo messaggio nel log

Aggiungi questa riga al scripts/init.lua esistente; conserva il bootstrap distribuito e le sue registrazioni:

log.info("Hello from my shard")

Avvia il server, oppure inserisci script reload init.lua nella console del server. Il log della console deve contenere Hello from my shard. Se non compare, verifica il percorso del bootstrap configurato e gli errori degli script prima di continuare.

Aggiungere un modulo

Crea scripts/common/greeting.lua:

local greeting = {}

function greeting.for_name(name)
    return "Welcome, " .. name
end

return greeting

Aggiungi a scripts/init.lua:

local greeting = require("common.greeting")
log.info("{Message}", greeting.for_name("Moongate"))

Ricarica di nuovo init.lua dalla console. Cerca Welcome, Moongate. require traduce i nomi dei moduli con punti in percorsi .lua relativi: common.greeting carica common/greeting.lua. Memorizza il risultato del modulo nella cache. La risoluzione resta nella cartella degli script, compresi i controlli sui link simbolici che escono dalla root. Un bootstrap mancante registra un avviso e avvia un motore vuoto. Un bootstrap che esiste ma fallisce la compilazione o l’esecuzione interrompe l’avvio del server.

Aggiungere un timer

Aggiungi questo esempio a scripts/init.lua e ricaricalo:

local pulse = timer.every(30, function()
    log.info("Pulse")
    wait(2)
    log.info("Pulse resumed")
end)

timer.after(95, function()
    log.info("Pulse cancelled: {Cancelled}", timer.cancel(pulse))
end)

Tutti e tre i ritardi sono in secondi: Pulse compare ogni 30 secondi, seguito da Pulse resumed circa 2 secondi dopo; dopo 95 secondi il timer ripetuto viene annullato. wait va dentro la callback, non al livello principale del file. Vedi Eventi e timer per le regole di annullamento e sovrapposizione.

Cosa possono chiamare gli script

La guida di riferimento API Lua ha una pagina per ogni modulo, con firma, parametri e tipo restituito di ogni funzione; viene generata dal codice del server.

L’host predefinito registra log; il motore fornisce engine, timer, events e wait. Il plugin Ultima registra dice, cliloc, localization, npc, item, mobile, world, target, prompt, gump, bank, vendor, trainer, effect, moongates, locations, jail, board, commands, mount, stable, pet, hue_picker, skill, combat, npcguild, guild, schedule, help, book, harvest, craft e carve nelle modalità game e standalone. I livelli di log seguono comunque la politica di logging dell’host, quindi una chiamata log.debug può non apparire nell’output predefinito della console. Usa template invece di concatenare valori variabili nei messaggi.

I moduli npc, item, mobile, effect, world, target, prompt, bank e gump servono agli script dei mobile e degli oggetti. Uno script legge e scrive i numeri e le abilità di un mobile e verifica un mobile in un’abilità con skill.check, che può incrementarla (vedi Abilità). Per esporre comportamento applicativo, associa un modulo C# usando Scrivere un modulo Lua.

Alcuni moduli hanno una pagina di approfondimento:

Modulo	Lettura
events, timer	Eventi e timer
npc	Script dei mobile, con camminare lungo un percorso
item	Script degli oggetti
effect	Effetti
gump	Gump, con gump costruiti in Lua, e Il tuo primo gump
bank	Banca
vendor	Venditori
trainer	Istruttori
dice	Le forme di DiceSpec
localization	Leggere un messaggio da Lua
cliloc	Costanti per i testi del client che molti script pronunciano, come cliloc.TOO_FAR: Script forniti
locations	Luoghi e il comando go
moongates	Moongate
jail	Prigione e il comando jail
board	Bacheche
commands	Comandi: commands.execute ne esegue uno come console, commands.execute_as come giocatore
skill	Abilità: skill.check(mobile, skill, min, max) mette alla prova un mobile in un’abilità, che può aumentare
combat	attack, stop, target, range, armor_rating, weapon, swing, spend_ammo: avvia e termina i combattimenti in mischia e dice chi sta combattendo un mobile; vedi Combattimento
mount	ride_ethereal(player, statuette): mette un giocatore sulla cavalcatura di una statuetta; toggle_stone(player, stone): mette un giocatore sulla cavalcatura di una pietra nel suo zaino, o lo fa scendere; vedi Cavalcature
stable	attend, pets, stable, claim, max_pets, fee: lascia nella stalla gli animali di un giocatore e li riprende
pet	info, lore, corpse, followers, max_followers, tame, hire, hire_period, attend, release, loyalty, control_chance, obey, feed: le creature che un giocatore ha domato o assunto e la doma di una selvatica; vedi Addomesticare animali e Mercenari
hue_picker	open(player, graphic, callback): mostra il selettore di colori del client ed esegue la funzione con il colore scelto
npcguild	of, member, quote, is_join_payment, join, resign: la gilda di un mestiere, come un capogilda accoglie i membri
guild	of, get, is_member, member, leader, roster, wars, allies, declared_war, declared_alliance, create, recruit, resign, eject, set_title, set_charter, set_website, set_hue, set_fealty, declare_war, make_peace, declare_alliance, break_alliance: le gilde dei giocatori, con le loro pietre; vedi Gilde
schedule	is_active, active, events, set_event, next: il calendario di data/schedule.toml
help	Le necessità del gump di aiuto: l’attesa del pulsante I am stuck, la città iniziale più vicina e la coda delle richieste per i game master (create_page, pages, take, answer, close…)
book	give, write, open: crea e legge pergamene e libri personalizzati da templates/books
harvest	has, amount, vein, take: ciò che si raccoglie dal mondo e si esaurisce per area, come i pesci
craft	get, resource: i mestieri di data/crafts, i loro gruppi e ricette, e gli elenchi di risorse che usano
carve	corpse: seziona un cadavere con le tabelle di templates/carves; vedi Smembrare i cadaveri

Cosa leggere dopo

• Lua in Moongate: versione Lua, librerie disponibili a uno script e differenze rispetto al manuale.
• Eventi e timer: eventi del server, wait e timer ripetuti.
• Script dei mobile: funzioni definibili nello script di un NPC e camminata lungo un percorso.
• Script degli oggetti: funzioni definibili nello script di un oggetto e come rifiutare uno spostamento.
• Hook degli script: l’elenco unico di ogni funzione che il server chiama su uno script di NPC o di oggetto, con i suoi argomenti, quando viene eseguita e cosa significa la sua risposta.
• Script forniti: cosa fa ogni script della distribuzione: mostri, porte, luci, cibo, teletrasporti, moongate, orologi e contenitori che si riempiono.
• Effetti: opzioni del modulo effect.
• Ricaricamento, budget ed editor: ricaricare uno script, budget di istruzioni e completamento nell’editor.
• Guida di riferimento API Lua: ogni funzione, con la firma e, per molte, un esempio.