Hook degli script

Questa pagina fa parte di Scrivere script Lua. È l’unico elenco delle funzioni che il server chiama su uno script dei mobile o su uno script degli oggetti: con che argomenti viene chiamata ciascuna, quando scatta, se viene eseguita dentro l’azione o dopo, e cosa significa la sua risposta. Le due pagine appena citate spiegano ogni funzione con esempi.

Ogni funzione è facoltativa: uno script definisce quelle che vuole, e un hook che nessuno script definisce costa al server una sola ricerca in una cache.

Convenzioni

Il primo argomento è sempre il seriale dell’oggetto che possiede lo script (l’NPC, oppure l’oggetto). Dopo vengono il mobile che ha fatto la cosa, l’attore, e poi i dettagli di ciò che ha fatto:

(serial, actor, payload...)

I nuovi hook chiamano i loro argomenti actor, target, item, container e amount. Gli hook nati prima di questa convenzione mantengono nomi e ordine degli argomenti, perché uno script scritto per loro smetterebbe di funzionare: nella tabella qui sotto sono indicati come “legacy” e il loro ordine non cambierà.

Un hook è di uno di tre tipi:

• can_* è un veto. Viene chiesto prima dell’azione e la risposta è immediata; solo false la rifiuta. Una funzione mancante, un errore, un wait() o qualunque altro valore lasciano proseguire l’azione, così uno script rotto non blocca mai il gioco.
• on_* è una notifica di qualcosa che è successo. La sua risposta viene ignorata.
• Alcuni on_* sono risposte: il server legge il valore restituito, come true per “gestito”.

Un hook gira sync, dentro l’azione, sul game loop, e deve essere rapido; oppure è queued, messo in coda al turno successivo del game loop dopo l’azione e i suoi pacchetti, così lo script vede il mondo come l’azione l’ha lasciato e può eliminare o spostare l’oggetto. Un hook marcato mixed è sync, tranne quando è stato uno script a causare l’azione: uno script in esecuzione non ne può avviare un altro, quindi il server lo mette in coda.

Il server si protegge da uno script che si rompe:

• Un errore in un hook di veto o di risposta vale “nessun hook”: l’azione prosegue. L’errore dello script viene segnalato come ogni altro, e il server scrive nel log una volta al minuto per ogni script e funzione che l’hook è stato trattato come assente.
• Gli hook di veto, quelli con risposta immediata (escluso l’on_use di un oggetto) e on_delete possono girare mentre uno script è in esecuzione, come quando lo script di un incantesimo danneggia un NPC: lo script che agisce viene messo da parte e riprende quando l’hook ha risposto. Un hook che deve rispondere subito non dà una risposta utilizzabile se chiama wait(): l’azione non aspetta il suo valore restituito in seguito.
• Un hook di veto o di risposta non viene richiamato per un oggetto mentre la stessa funzione di quell’oggetto è in esecuzione: un gestore che danneggia, cura o sposta il proprio oggetto ottiene “nessun hook” dalla chiamata annidata. Un’altra funzione dello stesso oggetto gira comunque, quindi un oggetto che si elimina da can_pick_up sente ancora on_delete.
• Un hook chiesto dall’interno di un hook si annida al massimo 8 livelli: quello che sarebbe il nono non viene eseguito e conta come “nessun hook”, registrato una volta al minuto come ogni hook che fallisce. Un branco di NPC che si dividono il danno con combat.harm deve fermarsi prima.
• Ciò che uno script definisce viene cercato una volta per ogni script e funzione, e di nuovo dopo che lo script è stato ricaricato con script reload.

Scrivere gli hook

• Scegli il momento in base a ciò che l’hook deve fare. Un hook sync gira dentro l’azione, quindi è l’unico tipo che può rifiutare (can_die, can_buy) o cambiare un numero (on_damage); tienilo breve, perché il game loop lo aspetta. Un hook queued gira dopo l’azione, quando il mondo mostra già il risultato, quindi può fare la cosa lenta o distruttiva, come eliminare l’oggetto.
• Una funzione non definita costa una ricerca, e una definita viene chiamata ogni volta: non aggiungere una funzione vuota “per sicurezza”, e fai prima il controllo economico (if kind ~= "melee" then return end).
• La protezione dalla ricorsione difende il server, non la tua logica: un hook di veto o di risposta che cambia il proprio oggetto, come on_damage che chiama combat.harm sullo stesso NPC, ottiene “nessun hook” dalla chiamata annidata, quindi il secondo colpo non viene cambiato. Scrivi il gestore in modo che non serva interpellarlo due volte.
• In on_delete l’oggetto c’è ancora e si può leggere, ma sta per andarsene: leggi ciò che ti serve, ferma i suoi timer con item.stop_timer e pulisci ciò che possiede. Non eliminare né spostare l’oggetto o il suo contenitore, e non metterci nulla dentro. Ogni oggetto dentro un contenitore sente il proprio on_delete prima del contenitore: quando un contenitore decade, viene rimosso con .remove o ripulito insieme al suo cadavere, è già vuoto quando gira il suo on_delete. Quando un NPC viene rimosso, il suo equipaggiamento e ciò che porta vanno prima il contenuto, ma tutto il suo inventario resta dov’era finché non sono girati tutti gli on_delete. Un oggetto viene avvisato una sola volta: uno che un altro gestore ha eliminato nel frattempo non viene avvisato di nuovo.
• Usa la colonna Wait qui sotto, non soltanto l’etichetta temporale. sync descrive quando inizia la prima chiamata; non significa che ogni hook di questo tipo vieti la sospensione. Le notifiche accodate e quelle eseguite come coroutine possono chiamare wait(seconds). Anche l’on_use di un oggetto può aspettare: conta subito come gestito e il valore restituito in seguito non cambia l’azione predefinita.
• Ogni veto e hook con risposta immediata deve restituire prima di aspettare; anche on_think deve finire subito (aspettare registra un avviso), e on_delete deve ripulire prima che l’oggetto sparisca. on_death deve terminare senza aspettare, perché la rimozione dell’NPC segue il primo ritorno o la prima sospensione; usa un timer per lavorare in seguito sul suo cadavere. Lo scheduler può comunque riprendere un gestore che viola queste regole, ma la sua risposta tardiva non può influenzare l’azione conclusa. Dopo qualsiasi attesa consentita, verifica che l’oggetto o il mobile esista ancora e che proprietario, posizione e altre assunzioni siano ancora validi.
• can_buy e can_sell vengono chiesti prima della transazione, con la finestra aperta: non devono aprire o chiudere una finestra del venditore, spostare o consumare merce, né spostare il giocatore. Uno script che lo fa non è creduto: un acquisto la cui finestra è stata sostituita viene scartato, e una vendita la cui merce è cambiata o il cui giocatore si è allontanato dal venditore non paga nulla.

Gli hook

Hook	Proprietario	Tipo	Argomenti	Esecuzione	Wait	Quando	Restituisce
can_die	NPC	veto	serial, killer	sync	No	Un colpo o un tick di veleno, dopo on_damage, lascerebbe l’NPC senza punti ferita, prima della sua morte. Non viene chiesto per .kill e mobile.kill, che sono uccisioni esplicite, né per i giocatori.	false tiene l’NPC in vita con 1 punto ferita: il colpo vale come uno che non ha ucciso (l’NPC risponde al colpo, on_health_low può scattare) e il prossimo colpo letale lo chiede di nuovo.
on_attack	NPC	risposta	serial, target	sync	No	L’NPC sta per colpire il suo bersaglio, quando il ritardo del colpo è scaduto. Non deve chiamare wait.	false annulla questo colpo: il suo ritardo è speso, quindi l’hook viene richiesto di nuovo solo quando è dovuto il colpo successivo, non viene mostrato né ferito nulla, non c’è on_miss, e il tempo del combattimento non viene rinnovato dal colpo.
on_combat_end	NPC	notifica	serial, target, reason	queued	Sì	L’NPC ha perso il suo bersaglio. reason è killed (il bersaglio è morto), lost (ha lasciato il mondo o la mappa), expired (ultima.combat.combatant_seconds senza un colpo), fled (il combattimento è stato chiuso con combat.stop mentre l’NPC scappa dai colpi, combat.flees o combat.passive) o stopped (ogni altro caso: combat.stop, un errore nel combattimento). Non viene attivato quando muore l’NPC stesso, lo dice on_death.	Ignorato.
on_combat_start	NPC	notifica	serial, target	queued	Sì	L’NPC ha ottenuto un bersaglio quando non ne aveva: ha attaccato, oppure è stato colpito o aggredito e risponde. Cambiare bersaglio durante un combattimento non attiva nulla.	Ignorato.
on_context_menu	NPC	risposta	serial, player	sync	No	Un giocatore ha chiesto il menu contestuale dell’NPC. Non deve chiamare wait.	Le voci da aggiungere, una tabella di { id, cliloc, range, enabled }, oppure niente.
on_context_menu_select	NPC	notifica	serial, player, id	queued	Sì	Il giocatore ha scelto una delle voci aggiunte dallo script.	Ignorato.
on_damage	NPC	risposta	serial, attacker, amount, kind	sync	No	L’NPC sta per perdere punti ferita, prima che cambino: un colpo (melee, oppure ranged per un arco), un danno fatto con combat.harm (spell per default, other per un campo, un’esplosione o una trappola), un tick di veleno (poison) o la parte di un colpo che Reactive Armor rimanda indietro (other). attacker è 0 quando nessuno l’ha causato; per un tick di veleno è il mobile che ha applicato il veleno, o 0 quando non lo si sa. Anche quando è uno script, come un incantesimo, a fare il danno.	Un numero sostituisce il danno (intero, 0 o più); false è nessun danno; nil, true o qualunque altro valore lo lascia com’è. Un danno di 0 ferisce per niente: l’animazione di colpo subìto parte, non c’è sangue e nessun on_hit.
on_death	NPC	notifica	serial, corpse, killer	mixed	No	L’NPC è morto, dopo che il suo cadavere esiste e prima che lasci il mondo. Legacy: il cadavere viene prima dell’uccisore.	Ignorato.
on_drag_drop	NPC	risposta	serial, giver, item	sync	No	Un giocatore ha rilasciato un oggetto sull’NPC da 2 caselle o meno.	true: lo script ha preso l’oggetto. Qualunque altro valore lo restituisce.
on_enter_region	NPC	notifica	serial, region	queued	Sì	L’NPC ha fatto un passo, è stato teletrasportato o è apparso (generato, riportato in vita) dentro una regione con nome diversa da quella in cui era; region è il suo nome, come lo dà world.region. Una regione senza nome non attiva nulla, e un NPC il cui script non definisce né questo né on_leave_region non costa nulla a ogni passo.	Ignorato.
on_heal	NPC	risposta	serial, healer, amount	sync	No	L’NPC sta per riavere punti ferita tramite mobile.heal(patient, amount, healer), usata dalle bende (anche la veterinaria) e dagli incantesimi di cura; healer è 0 quando non c’è. Non per la rigenerazione, che non è una cura, né per mobile.set_stats, né per le pozioni, che bevono solo i giocatori.	Come on_damage: un numero sostituisce la quantità (intera, 0 o più), false non ne dà, qualunque altro valore la lascia.
on_health_low	NPC	notifica	serial, hits, hits_max, attacker	queued	Sì	I punti ferita sono scesi sotto la percentuale low_health_at del template, per un danno che non ha ucciso. Legacy: l’attaccante viene per ultimo.	Ignorato.
on_hit	NPC	notifica	serial, target, damage	queued	Sì	Il colpo dell’NPC è andato a segno e ha ferito, con il danno inflitto dopo on_damage del bersaglio. Un colpo assorbito fino a zero non attiva né questo né on_miss.	Ignorato.
on_leave_region	NPC	notifica	serial, region	queued	Sì	L’NPC ha fatto un passo o è stato teletrasportato fuori da una regione con nome; region è il nome di quella che ha lasciato. Viene attivato prima di on_enter_region di quella in cui è entrato. Togliere l’NPC dal mondo non attiva nulla.	Ignorato.
on_mana_low	NPC	notifica	serial, mana, mana_max, needed	queued	Sì	Il mana di un NPC che lancia incantesimi è sceso sotto il costo del suo incantesimo più economico.	Ignorato.
on_miss	NPC	notifica	serial, target	queued	Sì	Il colpo dell’NPC è andato a vuoto.	Ignorato.
on_mobile_in_range	NPC	notifica	serial, other	queued	Sì	Un altro mobile è entrato entro ultima.npcs.sense_range, con un passo o entrando nel mondo; una volta per arrivo.	Ignorato.
on_mobile_killed	NPC	notifica	serial, killed, killer	queued	Sì	Un mobile è stato ucciso entro il raggio di percezione; chi è morto non viene avvisato. Legacy: l’uccisore viene per ultimo.	Ignorato.
on_release	NPC	notifica	serial, owner	queued	Sì	Un animale non è più di nessuno: il padrone l’ha lasciato andare (pet.release), ha disobbedito fino a non avere più lealtà ed è tornato selvatico, oppure ha disertato. Lo script lo vede già selvatico; owner è chi lo aveva. Stalla, morte e lo staff che lo assegna a un altro non attivano nulla.	Ignorato.
on_resurrect	NPC	notifica	serial, healer	queued	Sì	Un NPC è tornato dal suo cadavere: una benda sul cadavere di un animale legato, mobile.resurrect(corpse, healer) e .resurrect. L’NPC che si rialza è un NPC nuovo, nato dove giaceva il cadavere, con un suo serial; healer è 0 quando non c’è. I giocatori resuscitati da un ankh, un guaritore o un incantesimo non attivano nulla.	Ignorato.
on_spawn	NPC	notifica	serial	queued	Sì	Una volta, dopo che l’NPC è stato generato con .spawn, nel mondo e mostrato. Non per gli NPC salvati caricati all’avvio.	Ignorato.
on_speech	NPC	notifica	serial, speaker, text, keywords, type	sync	Sì	Un giocatore ha parlato a portata d’orecchio dell’NPC; i comandi non vengono ascoltati.	Ignorato.
on_tame	NPC	notifica	serial, tamer	queued	Sì	Una creatura è diventata di un giocatore: pet.tame è riuscito, oppure lo staff l’ha assegnata con .tame. Lo script la vede già posseduta.	Ignorato.
on_think	NPC	notifica	serial	sync	No	A ogni think dell’NPC (ultima.npcs.think_interval_ms) finché un giocatore è entro i settori 5×5 intorno a lui. Non deve chiamare wait: il server avvisa una volta per script.	Ignorato.
can_decay	Item	veto	serial	sync	No	Scade il tempo di decadimento di un oggetto a terra, prima che decada. Viene chiesto all’oggetto che decade, non a ciò che contiene. Nessuno script gira durante un salvataggio del mondo. Non viene chiesto per un oggetto che non decade mai.	false tiene l’oggetto, e viene richiesto dopo un altro tempo di decadimento (decay_minutes del suo template, 60 di default).
can_drop	Item	veto	serial, dropper, destination	sync	No	Un giocatore sta per posare l’oggetto che tiene, ovunque.	false rimanda l’oggetto da dove era stato sollevato.
can_drop_on	Item	veto	serial, dropper, item	sync	No	Chiesto a un oggetto che non è un contenitore: un giocatore sta per lasciarvi sopra l’item tenuto in mano, da 2 caselle o meno se sta a terra, o portandolo con sé. serial è il bersaglio. Chiesto dopo can_drop dell’oggetto e prima di ogni altra regola, compresa la fusione di una pila e il posizionamento accanto. I contenitori usano can_insert.	false rimanda l’oggetto dov’era stato sollevato; non scatta nulla.
can_equip	Item	veto	serial, wearer	sync	No	L’oggetto che si tiene sta per essere indossato da wearer.	false rimanda indietro l’oggetto.
can_insert	Item	veto	serial, mobile, item	sync	No	Chiesto a un contenitore: un giocatore sta per metterci item, o su una pila che vi giace direttamente.	false rimanda indietro l’oggetto.
can_pick_up	Item	veto	serial, picker	sync	No	Un giocatore sta per sollevare l’oggetto, quando ogni regola del server lo permette.	false rifiuta.
on_added	Item	notifica	serial, container, actor	queued	Sì	L’oggetto è entrato in un contenitore o nello zaino di un mobile, per qualunque via: un trascinamento, item.move_into, item.give, un oggetto creato direttamente dentro (bottino, un acquisto, un pezzo costruito, il contenuto di uno scrigno, l’equipaggiamento nello zaino di un NPC generato). actor è il mobile che l’ha causato: il giocatore che ha lasciato l’oggetto, l’acquirente di un acquisto, il mobile a cui item.give l’ha dato; 0 quando nessuno l’ha fatto, come per il bottino messo in un cadavere, un item.move_into da uno script, il contenuto di uno scrigno o l’equipaggiamento di un NPC generato. Non per un oggetto indossato (lo copre on_equip), non per una pila che cresce o si divide, non per gli oggetti caricati all’avvio o al login, piazzati dal .decorate dello staff o creati da un allegato di libro (gli allegati al portatore di una lettera), che entrano nello zaino in silenzio. Scartato se l’oggetto è stato eliminato nel frattempo.	Ignorato.
on_carving	Item	risposta	serial, carver, items	sync	No	Un coltello sta per togliere degli oggetti dal cadavere, quando il cadavere risulta lavorabile (di un NPC che non è un animale domestico, a terra, non ancora lavorato) e la sua tabella di smembramento è stata tirata; il cadavere viene valutato di nuovo dopo la risposta; chiesto allo script del cadavere (scripts/items/corpse.lua), prima che venga creato qualsiasi oggetto. items è il tiro, un array di { item = template id, amount = n }, vuoto per un cadavere senza tabella. Non deve chiamare wait.	false annulla: non viene creato nulla, il cadavere non viene segnato come lavorato e chi lo lavora si sente dire che non può usare la lama su quello. Una tabella della stessa forma sostituisce il tiro: una voce mal formata o che nomina un template di oggetto inesistente viene scartata. Qualsiasi altra cosa lo lascia.
on_context_menu	Item	risposta	serial, player	sync	No	Un giocatore ha chiesto il menu contestuale di un oggetto in vista. Non deve chiamare wait.	Le voci da aggiungere, come per un NPC.
on_context_menu_select	Item	notifica	serial, player, id	queued	Sì	Il giocatore ha scelto una delle voci aggiunte dallo script.	Ignorato.
on_create	Item	notifica	serial	queued	Sì	Un nuovo oggetto è entrato nel mondo: l’equipaggiamento e il bottino di un NPC generato, o il contenuto di uno scrigno creato da una regione di spawn.	Ignorato.
on_darkness	Item	notifica	serial, dark	queued	Sì	Il punto di un lampione è diventato buio (true) o chiaro (false).	Ignorato.
on_delete	Item	notifica	serial	sync	No	L’oggetto viene eliminato, in qualunque modo: decadimento, fusione in una pila, item.delete, item.consume, .remove, eliminazione del suo contenitore con il contenuto, l’equipaggiamento di un NPC rimosso, la pulizia di un cadavere. Viene chiesto una volta per oggetto, prima che esca dal mondo: l’oggetto, le sue proprietà e il suo contenitore si possono ancora leggere. Un oggetto che non è nel mondo, come uno scrigno che uno spawn non ha potuto completare, non viene chiesto, e uno che un gestore ha eliminato dall’interno di un proprio hook (can_pick_up, can_decay) o dall’on_delete di un altro oggetto viene chiesto una sola volta. Serve a ripulire timer e proprietà. Un gestore non deve eliminare né spostare l’oggetto o il suo contenitore: se lo fa non può fermare l’eliminazione. Il logout non scatta nulla.	Ignorato.
on_drop	Item	notifica	serial, dropper	queued	Sì	Un giocatore ha posato l’oggetto che teneva; non quando torna indietro o viene indossato.	Ignorato.
on_dropped_on	Item	notifica	serial, dropper, item	queued	Sì	Il bersaglio di un rilascio dell’item tenuto in mano su un oggetto che non è un contenitore, una volta che can_drop_on lo ha consentito: dopo che il rilascio è avvenuto (l’oggetto è stato messo accanto al bersaglio nel suo contenitore, o fuso nel bersaglio, e in tal caso non esiste più), o quando nient’altro lo ha preso e nessun contenitore lo ha rifiutato; allora l’oggetto è tornato dov’era stato sollevato e lo script può prenderlo da lì (per esempio item.consume o item.delete, poi dare qualcosa in cambio). Un rilascio rifiutato dal peso o dallo spazio di un contenitore non attiva nulla. Scartato se il bersaglio è stato eliminato nel frattempo.	Ignorato.
on_equip	Item	notifica	serial, wearer	queued	Sì	L’oggetto è passato su un layer di wearer. Gli oggetti caricati o generati già indossati non attivano nulla.	Ignorato.
on_ghost_use	Item	notifica	serial, user	sync	Sì	Un giocatore morto ha fatto doppio clic sull’oggetto. Senza di esso il giocatore legge che i morti non possono usarlo.	Ignorato.
on_item_added	Item	notifica	serial, item, actor	queued	Sì	Chiesto a un contenitore: un oggetto è entrato, per una qualunque delle vie di on_added. serial è il contenitore; item potrebbe essersi già spostato quando la funzione gira. Un contenitore il cui script non ha la funzione non costa nulla, e lo zaino di un mobile non ha uno script. Scartato se il contenitore è stato eliminato nel frattempo.	Ignorato.
on_item_removed	Item	notifica	serial, item, actor	queued	Sì	Chiesto a un contenitore: un oggetto è uscito (spostato, messo a terra, indossato) o è stato eliminato mentre era dentro (decadimento, una pila che lo ha assorbito, item.delete, item.consume); in quel caso actor è 0. serial è il contenitore. Scartato se il contenitore è stato eliminato nel frattempo.	Ignorato.
on_mobile_near	Item	notifica	serial, mobile, distance	queued	Sì	Un giocatore o un NPC è entrato nel watch_range dell’oggetto (un campo del template, da 0 a 8 caselle; 0 o assente non osserva nulla e non costa nulla): con un passo, un teletrasporto o entrando nel mondo. Scatta una volta per ingresso, da fuori dal raggio, non a ogni passo dentro; distance è la maggiore tra le distanze sui due assi. I mobile nascosti e i fantasmi non vengono notati, e un oggetto che compare dove un mobile già si trova non avvisa finché quel mobile non si muove. Osservano solo gli oggetti a terra. Scartato se l’oggetto è stato raccolto nel frattempo.	Ignorato.
on_move_off	Item	notifica	serial, mobile	queued	Sì	Un giocatore o un NPC è sceso dalla cella dell’oggetto, camminando o correndo; è il contrario di on_move_over, con la stessa regola per l’altezza. Non per teletrasporto. Scatta per il passo che ha lasciato la cella, prima di on_move_over dell’oggetto sulla cella in cui è entrato, anche per un giocatore, i cui due hook girano subito, in quest’ordine, dentro il passo. Per un NPC viene accodato e scartato se l’oggetto ha lasciato la cella nel frattempo. Il mobile è già sulla nuova cella.	Ignorato.
on_move_over	Item	notifica	serial, mobile	sync	Sì	Un giocatore è entrato nella casella dell’oggetto; non per teletrasporto.	Ignorato.
on_npc_move_over	Item	notifica	serial, npc	queued	Sì	Un NPC è entrato nella casella dell’oggetto. Potrebbe essere già andato oltre.	Ignorato.
on_npc_use	Item	notifica	serial, npc	queued	Sì	Un NPC che cammina lungo un percorso ha trovato l’oggetto sulla sua strada, come una porta, fino a tre tentativi.	Ignorato: la chiamata è in coda, quindi l’NPC non sa se ha funzionato.
on_pickup	Item	notifica	serial, picker	queued	Sì	Un giocatore ha sollevato l’oggetto da un contenitore, dal paperdoll o da terra.	Ignorato.
on_removed	Item	notifica	serial, container, actor	queued	Sì	L’oggetto è uscito da un contenitore o da uno zaino senza essere eliminato: spostato in un altro contenitore, messo a terra, indossato. Sollevarlo non lo attiva, perché un oggetto sollevato resta dov’è finché non viene lasciato (on_pickup). Un oggetto eliminato attiva invece on_delete. Scartato se l’oggetto è stato eliminato nel frattempo.	Ignorato.
on_speech	Item	notifica	serial, speaker, text, keywords, type	sync	Sì	Un giocatore ha parlato a portata d’orecchio di un oggetto a terra.	Ignorato.
on_timer	Item	notifica	serial, name	sync	Sì	Un timer avviato con item.start_timer è scaduto; il timer non esiste più quando la funzione gira.	Ignorato.
on_tooltip	Item	risposta	serial, viewer	sync	No	La lista delle proprietà dell’oggetto viene costruita per il giocatore viewer, quando il client la chiede. Deve essere rapida e non deve chiamare wait. Le righe vengono chieste ogni volta, mai messe in cache, e solo per un oggetto il cui script definisce la funzione; la lista che il server invia per gli altri oggetti è condivisa. Il client la chiede di nuovo ogni volta che l’oggetto viene mostrato o cambia (la revisione che gli viene comunicata è quella delle righe che scrive il server stesso).	Un elenco di righe da aggiungere dopo quelle del server: una stringa, o una tabella { cliloc = number, args = "text" } (args può contenere più argomenti separati da un tab). Se ne prendono al massimo 16, e al massimo cinque di esse stringhe semplici, perché il client mostra solo cinque righe di testo libero (meno quando le righe del server ne usano già alcune); le righe cliloc hanno solo il limite di 16. Una riga malformata viene scartata; un errore o nessuna risposta non aggiunge nulla. L’hook gira una volta per ogni oggetto con script ogni volta che si apre un contenitore, perché la revisione comunicata al client è quella delle righe del server; un clic singolo mostra solo il nome e non lo esegue.
on_unequip	Item	notifica	serial, wearer	queued	Sì	L’oggetto ha lasciato il layer di wearer: messo in un contenitore o a terra, unito a una pila, o tolto dal mondo mentre era indossato (decadimento, item.delete, item.consume, .remove, una statuetta di cavalcatura, l’equipaggiamento di un NPC che finisce nel suo cadavere). Disconnettersi o rimuovere l’NPC non attivano nulla.	Ignorato.
on_use	Item	risposta	serial, user	sync	Sì	Un giocatore ha fatto doppio clic sull’oggetto, anche con Telekinesis.	true, o un wait(): gestito, nessuna azione predefinita.
can_buy	Vendor	veto	serial, actor, item, amount, price	sync	No	Chiesto allo script di un NPC venditore per ogni riga di un acquisto, dopo i controlli sulle righe della finestra e prima che si muovano oro o merce. item è l’id del template della merce e price l’oro dell’intera riga (amount pezzi). I giocatori non vengono mai interpellati. Non deve aprire una finestra né spostare merce.	false rifiuta quella riga: non spende e non sposta nulla, il venditore lo dice una volta e le altre righe proseguono; se non ne resta nessuna la finestra si chiude.
can_sell	Vendor	veto	serial, actor, item, amount, price	sync	No	Come can_buy, per ogni riga di ciò che un giocatore vende, prima che l’oro sia pagato e la merce tolta.	false rifiuta quella riga, come can_buy: resta al giocatore.
on_bought	Vendor	notifica	serial, actor, item, amount, price	queued	Sì	Una riga di un acquisto è conclusa: la merce è consegnata e l’oro tolto. Una volta per ogni riga, dopo l’intero acquisto; un acquisto rifiutato non scatena nulla.	Ignorato.
on_sold	Vendor	notifica	serial, actor, item, amount, price	queued	Sì	Una riga venduta da un giocatore è conclusa: l’oro pagato e la merce tolta. Una volta per ogni riga.	Ignorato.

Eventi sul bus

Alcune cose non vengono chieste a un solo script ma comunicate a ogni script in ascolto, con events.on (vedi Eventi e timer). Sono notifiche, non sono nella tabella qui sopra e il catalogo non le elenca; uno script le riceve solo se si è iscritto, e un evento che nessuno ascolta costa al server una sola ricerca.

Evento	Campi	Quando
item_created	serial, template	Un nuovo oggetto è entrato nel mondo: creato da uno script, da un venditore, da uno spawn, da un mestiere o da un comando. Gli oggetti caricati all’avvio o a un login, il resto di una pila divisa, gli oggetti che il .decorate dello staff piazza e quelli che un allegato di libro sistema non scatenano nulla.
item_deleted	serial, template	Un oggetto è stato eliminato, in uno qualsiasi dei modi di on_delete; il gestore gira in un turno successivo, quando l’oggetto non c’è più. L’uscita di un giocatore non scatena nulla.
mobile_created	serial, template	Un NPC è stato generato: una regione di spawn, .spawn, uno script, una guardia, un animale uscito da una stalla, un animale cavalcato che è stato smontato, un animale legato riportato in vita dal suo cadavere. La creatura ha ogni volta un nuovo serial. Quelli caricati all’avvio non scatenano nulla, e una statuetta eterea non crea nessuna creatura.
mobile_deleted	serial, template	Un NPC è stato tolto dal mondo: dopo la sua morte, .remove, uno script, un animale entrato in una stalla, oppure un animale cavalcato che è diventato l’oggetto cavalcatura indossato dal suo cavaliere. Un animale che torna ha un nuovo serial ed è un nuovo mobile_created.
mobile_died	serial, killer, corpse	Un giocatore o un NPC è morto. killer e corpse valgono 0 quando non ci sono. Per un corpo umano segue la caduta, come on_death; per un NPC è seguito da mobile_deleted.
pet_tamed	serial, tamer	Una creatura è diventata di un giocatore, con pet.tame o .tame.
corpse_carved	serial, carver, items	Un cadavere ha dato oggetti a un coltello (carve.corpse); serial è il cadavere e items quanti oggetti sono stati creati, dentro il cadavere o accanto a esso, una pila contando come uno. Uno smembramento che non ha dato nulla non scatena nulla.
craft_succeeded	actor, craft, item	Un mestiere ha prodotto un oggetto. craft è l’id del mestiere e item il seriale di ciò che ha prodotto, che può essere la pila a cui si è unito. I tentativi falliti non scatenano nulla.
party_invite	party_id, leader, invitee	Un capo ha invitato un giocatore nel gruppo.
party_joined	party_id, member	Un giocatore invitato ha accettato ed è entrato nel gruppo.
party_left	party_id, member, reason	Un membro non è più nel gruppo; reason è left, kicked o logout. Viene avvisato anche il membro la cui uscita scioglie il gruppo.
party_disbanded	party_id, reason	Un gruppo non esiste più: too_small quando restavano meno di due membri, emptied quando è terminato l’ultimo invito dell’unico membro.

Non realizzato: resource_harvested (la raccolta è divisa tra gli script di piccone, ascia e canna da pesca e il server non sa mai chi ha raccolto), e nessun evento sul bus per un mestiere fallito.

Ordine degli argomenti legacy

Questi hook sono stati costruiti prima della convenzione e mantengono il loro ordine; un nuovo hook segue la convenzione:

• on_death mette il cadavere prima dell’uccisore, e on_mobile_killed mette l’uccisore per ultimo.
• on_health_low mette l’attaccante dopo i punti ferita.
• Il nome dell’attore cambia con l’hook: giver, dropper, picker, wearer, user, speaker, mobile, other, player e npc. Sono tutti il seriale di un mobile.
• L’on_use e l’on_snoop di uno script di abilità, l’on_close e l’on_button di un gump e l’on_start, l’on_end e l’on_login di un evento stagionale non iniziano con il seriale di un oggetto; non sono in questa tabella, che elenca solo gli hook degli script di NPC e oggetti.

Cosa definiscono gli script forniti

Gli hook che il server chiama e nessuno script fornito definisce sono quelli che uno script tuo può usare per primo: on_mobile_killed, on_health_low, on_mana_low, on_damage, can_die, on_heal, on_attack, on_hit, on_miss, on_combat_start, on_combat_end, on_resurrect, on_tame, on_release, on_enter_region, on_leave_region, on_equip, on_unequip, on_pickup, on_drop, can_equip, on_delete, can_decay, on_added, on_removed, on_item_added, on_item_removed, on_move_off, on_mobile_near, on_tooltip, can_drop_on, on_dropped_on, on_carving, can_buy, can_sell, on_bought e on_sold.

Hook	Script forniti
on_think	wander, guard, healer, orione, vega, hireling, e gli script creati con common/creature.lua (animal, monster, scared_animal, guard, guard_outsider)
on_spawn	wander, e gli script creati con common/creature.lua
on_speech (NPC)	banker, healer, hireling, quest_giver, shopkeeper, stablemaster, vega, wander, e gli script creati con common/creature.lua
on_speech (oggetto)	keyword_teleport
on_mobile_in_range	wander, quest_giver
on_death	hireling, e gli script creati con common/creature.lua
on_release	hireling
on_drag_drop	banker, healer, hireling, quest_giver, shopkeeper, stablemaster, e gli script creati con common/creature.lua
on_context_menu, on_context_menu_select (NPC)	banker, healer, hireling, quest_giver, shopkeeper, stablemaster
on_use	la maggior parte degli script di scripts/items/, tra cui strumenti, cibo, pozioni, porte e cancelli
on_ghost_use	ankh
on_npc_use	door
on_move_over	teleporter, magic_field, moongate, public_moongate
on_npc_move_over	teleporter, magic_field
can_pick_up, can_drop	engraved_stone
on_tooltip	engraved_ring
can_insert	treasure_chest
on_timer	door, magic_field, moongate
on_darkness	light
on_create	treasure_chest

Le funzioni Lua che uno script chiama dentro un hook sono nel riferimento.