Script Mod (API): Guida all'uso avanzato

Per modificare gli script del gioco, si prega di fare clic sul link "Script Mod (API)" nella pagina dei dettagli della partita relativa al proprio gioco (lo stesso punto in cui si trovano opzioni quali "storico della chat" e "Copia/Estendi gioco"). Le saranno presentate diverse funzionalità:

• Un elenco di schede nella parte superiore. Il Suo gioco può avere più script per facilitare l'organizzazione. Si prega di notare che tutti gli script continueranno a essere eseguiti nello stesso contesto, pertanto è consigliabile evitare che più script cerchino di sovrascrivere gli stessi valori contemporaneamente, poiché ciò potrebbe causare risultati indesiderati.
• Un editor di codice script. È possibile utilizzare questo editor o modificare gli script in un editor esterno a propria scelta e successivamente incollarli qui.
• Una "Console Mod (API)" situata nella parte inferiore (vedere sotto).

Ogni volta che si fa clic sul pulsante "Salva script", la sandbox del gioco verràriavviata(con la conseguente perdita di tutti i dati in memoria che non sono stati salvati nell'oggettodi statoo negli oggetti Roll20). Ciò vale anche se si aggiunge un nuovo script, si elimina uno script o si attiva/disattiva uno script.

La console Mod (API)

La console Mod (API) rappresenta la "finestra" sui propri script. Poiché gli script Mod (API) vengono eseguiti in un ambiente sandbox, non è possibile accedervi direttamente mentre sono in esecuzione per visualizzare informazioni sui risultati o sugli errori dello script. La console Mod (API) visualizza queste informazioni al di fuori della sandbox, consentendo di visualizzarle mentre si modificano gli script. Qui verranno visualizzati tutti i comandi log(), nonché eventuali errori riscontrati durante l'esecuzione degli script. Per ulteriori informazioni, consultare l'articolo sul debug degli script.

Script reattivi: ascolto degli eventi, modifica degli oggetti

Il primo (e più semplice) tipo di utilizzo della Mod (API) consiste nel reagire ai cambiamenti sul tavolo di gioco e quindi rispondere con funzionalità aggiuntive agli oggetti modificati. Questo tipo di script è composto da una serie di funzioni che monitorano gli eventi che si verificano durante il gioco. Successivamente, modificherà gli oggetti che vengono trasmessi durante tali eventi, alterando ciò che accade sul tavolo di gioco.

Uno script di base che sposta un elemento di ulteriori 5 piedi (considerando le impostazioni predefinite della pagina) potrebbe essere:

        on("change:graphic", function(obj) {
  obj.set({
    left: obj.get("left") + 70    
  });
});

Come si può notare, abbiamo creato una semplice funzione on che verrà eseguita ogni volta che viene rilevato l'evento change:graphic. Alla funzione viene passato l'oggetto grafico obj. Per apportare una modifica, è sufficiente modificare obj utilizzando la funzione set: qualsiasi proprietà venga modificata verrà rilevata e modificata sul tavolo di gioco.

Nota sulle funzioni di strumento

Naturalmente, l'esempio precedente non è particolarmente utile perché aggiunge sempre 70 pixel alla posizione del segnalino. Tuttavia, cosa accade se l'utente ha modificato la scala in modo che 5 piedi corrispondano a 140 pixel? L'API Roll20 offre diversi strumenti utili per facilitare questo (e altri) scenari comuni. Modifichiamo il nostro esempio precedente per utilizzare lafunzione distanceToPixels, che ci indicherà quanti pixel corrispondono a "cinque piedi" (o pollici, metri o qualsiasi altra unità di misura impostata) sul tavolo di gioco.

on("change:graphic", function(obj) {    
  obj.set({        
    left: obj.get("left") + distanceToPixels(5);    
  });
});

Ora, se la pagina corrente è impostata per utilizzare le dimensioni predefinite della griglia,distanceToPixels(5);restituirà comunque 70 pixel, ma se la pagina è impostata per avere una scala doppia rispetto alle dimensioni normali, restituirà 140.

È sempre consigliabile utilizzare le funzioni di strumento, quando disponibili, per evitare che lo script smetta di funzionare in caso di modifica delle impostazioni di una pagina o di un token.

Script proattivi: eseguire operazioni senza l'intervento dell'utente

Oltre a reagire agli eventi degli utenti, è possibile utilizzare l'API per eseguire automaticamente operazioni non legate a un evento specifico dei giocatori. Ad esempio, consideriamo un segnalino che si muove avanti e indietro sulla mappa.

Nota: sebbene questo tipo di script non dipenda dall'interazione dell'utente, gli script Mod (API) per il tuo gioco funzioneranno comunque solo quando almeno una persona è connessa al tuo gioco.

on("ready", function() {
   //Attendere fino all'attivazione dell'evento ready per confermare che il gioco sia stato caricato completamente.
   //Ottenere un riferimento al nostro token di pattugliamento.
   var patroltoken = findObjs({_type: "graphic", name: "Guard A"})[0]; //Siamo consapevoli che nel gioco è presente un segnalino denominato "Guard A".
   var direzione = -1*distanzaInPixel(5); //Spostarsi a sinistra di 70 pixel.
   var stepstaken = 0; //Quanti passi abbiamo compiuto nella direzione attuale?
   setInterval(function() {
     if(passi compiuti > 3) {
       //Cambia direzione!
       direction = direction * -1; //invertirà la direzione in cui ci stiamo muovendo
       stepstaken = 0; //ripristina i passi a 0.
     }
     patroltoken.set("left", patroltoken.get("left") + direzione); //cammina!
     stepstaken++;
   }, 5000); //esegui un'azione ogni 5 secondi
});

Trattato sulle funzioni asincrone

Una funzione asincrona è una funzione che restituisce immediatamente il thread di controllo all'ambito di chiamata ed esegue alcune operazioni in background. Ecco un esempio molto semplice e di facile comprensione che è possibile inserire nella scheda degli script Mod (API):

on('load',function(){
  log('Ambito padre - Prima della chiamata alla funzione asincrona.');

  setTimeout(function(){
    log('Ambito della funzione asincrona - Esecuzione della funzione asincrona.');
  },10 /* 10 millisecondi */);

  log('Ambito padre - Dopo la chiamata alla funzione asincrona.');
});

Nel registro Mod (API), si noterà qualcosa di simile a questo:

"Ambito genitore - Prima della chiamata alla funzione asincrona."
"Ambito genitore - dopo la chiamata alla funzione asincrona."
Ambito della funzione asincrona - Esecuzione della funzione asincrona.

Guardando quel codice, si potrebbe pensare: "È ovvio che succederà più tardi, gli hai detto di eseguire l'operazione in 10 millisecondi, non è forse così?". Ecco un esempio meno evidente che genererà gli stessi messaggi di log:

on('load',function(){
  log('Ambito padre - Prima della chiamata alla funzione asincrona.');

  sendChat('Funzione asincrona','Valuta questo: [[1d6]]',function(msg){
    log('Ambito della funzione asincrona - Esecuzione della funzione asincrona.');
  });

  log('Ambito padre - Dopo la chiamata alla funzione asincrona.');

Le funzioni asincrone sono necessarie per evitare che l'API si blocchi frequentemente. Se ogni lancio di dadi fosse gestito in modo sincrono, l'API risulterebbe estremamente lenta e poco reattiva. Quasi tutte le funzioni che richiedono una richiamata sono asincrone. (Eccezione per alcune delle funzioni _.mappa, _.reduce, ecc., che sono esempi di programmazione funzionale in contrapposizione alla programmazione procedurale a cui la maggior parte delle persone è abituata.)