API: chat

Eventi chat

chat:messaggio

Si attiva ogni volta che si riceve un nuovo messaggio di chat. Si prega di notare che se il messaggio è di tipo "rollresult" o "gmrollresult", sarà necessario richiamareJSON.parse() sul contenuto del messaggio per ottenere un oggetto contenente le informazioni sui risultati del tiro.

Parametro di callback:

Struttura dei risultati del lancio Es. 1

Dopo aver richiamato JSON.parse sul proprietà content di un messaggio "rollresult" o "gmrollresult", si otterrà un oggetto con il seguente formato (questo è il risultato del comando /roll {2d6}+5+1t[weather] Attacco!)

  "type":"V", //"V" = "Validated Roll" (al momento sarà sempre "V")
  "rolls": [
    {
      "type":"G", //"G" indica un roll raggruppato. Un gruppo può essere considerato come una serie di "sottogruppi" all'interno di un gruppo.
      "rolls": [
        [
          {
            "type":"R", //"R" = "Roll"
            "dice":2, // Numero di dadi lanciati (2dX significa 2 dadi)
            "sides":6, //Numero di facce del dado (Xd6 significa 6 facce)
            "mods":{},
            "results": [ //Una serie di risultati di ogni lancio.
             {
               "v":1 // Abbiamo ottenuto un 1 con il nostro primo 2d6
             },
             {
               "v":5 //Abbiamo ottenuto un 5 con il nostro secondo 2d6
             }
            ]
          }
        ]
      ],
      "mods":{},
      "resultType":"sum", //Il risultato è una somma (al contrario di una verifica di successo)
      "results": [
        {
          "v":6 // In questo caso, il risultato complessivo (totale) del gruppo.
        }
      ]
    },
    {
      "type":"M", //"M" = Espressione matematica
      "expr":"+5+"
    },
    {
      "type":"R", //"R" = Tiro
      "dice":1,
      "table":"weather", //La proprietà table è impostata sul nome della tabella utilizzata se questo tiro è stato effettuato rispetto a una tabella
      "mods":{},
      "sides":2, //È possibile ignorare questa impostazione per i tiri da tavolo.
      "risultati": [
        {
          "v":0, //Il "valore" dell'articolo della tabella ottenuto. Per le tabelle di testo questo valore è sempre 0.
          "tableidx":1, //L'indice dell'articolo nella tabella che è stato rullato.
          "tableItem": { //Una copia dell'oggetto dell'articolo della tabella così come era presente al momento della creazione della tabella.
            "name":"rainy", 
            "avatar":"", //Questo sarà un URL a un'immagine se le tabelle di tiro utilizzano icone immagine
            "weight":1,
            "id":"-IpzPx2j_9piP09ceyOv"
          }
        }
      ]
    },
    {
      "type":"C", // "C" = Comment
      "text":"Attacco!"
    
  ],
  "resultType":"sum", //Il tipo di risultato complessivo dell'intero roll
  "total":11 // Il totale complessivo dell'intero roll (compresi tutti i sottogruppi)
}

Struttura dei risultati del lancio Es. 2

Una struttura annotata per il risultato di /roll {1d6!!>5}>6 (che mostra le modifiche esplosive e i successi del bersaglio):

{
  "type":"V",
  "rolls": [
    {
      "type":"G",
      "rolls": [
        [
          {
            "type":"R",
            "dice":1,
            "sides":6,
            "mods": { //Modifiche al lancio
              "compounding": { //"compounding" = "Esplosione composta (!!)"
                "comp":">=", //Tipo di confronto
                "point":5 //Punto di confronto
              }
            },
            "results": [
              {
                "v":13 //Risultato complessivo dei dadi. Si prega di notare che, poiché si tratta di un effetto cumulativo, è previsto un solo risultato del dado.
              }
            ]
          }
        ]
      ],
      "mods": {
        "success": {
          "comp":">=",
          "point":6
        }
      },
      "resultType":"sum",
      "results": [
        {
          "v":13
        }
      ]
    }
  ],
  "resultType":"success", // In questo caso, il risultato è un conteggio dei successi
  "total":1 //Numero totale di successi
}

Esempio di evento chat (implementazione del tipo di roll personalizzato)

on("chat:message", function(msg) {
  //Questo consente ai giocatori di inserire !sr <numero> per tirare un numero di dadi d6 con un obiettivo di 4.
  if(msg.type == "api" && msg.content.indexOf("!sr ") !== -1) {
    var numdice = msg.content.replace("!sr ", "");
    sendChat(msg.who, "/roll " + numdice + "d6>4");
  }
});

sendChat(speakingAs, input [,callback [, options]] )

È possibile utilizzare questa funzione per inviare un messaggio di chat.

parlando può essere uno dei seguenti:

• Qualsiasi stringa, che verrà utilizzata come nome della persona che ha inviato il messaggio. Ad esempio. "Riley"
• L'ID di un giocatore, nel formato"giocatore|-Abc123", dove "-Abc123" rappresenta l'ID del giocatore. In tal caso, verranno utilizzati automaticamente l'avatar e il nome del giocatore.
• L'ID di un personaggio, formattato come"personaggio|-Abc123". In tal caso, verranno utilizzati automaticamente l'avatar e il nome del personaggio.

input dovrebbe essere un'espressione valida, simile a quelle utilizzate nell'app Roll20. È possibile inserire del testo per inviare un messaggio di base o utilizzare comandi slash come "/roll", "/em", "/w", ecc. Inoltre:

• È possibile utilizzare gli attributi dei personaggi con il formato@{CharacterName|AttributeName}.
• È possibile utilizzare le abilità dei personaggi con il formato:%{CharacterName|AbilityName}.
• Nonè possibile utilizzare le macro.
• È possibile utilizzare il comando "/direct <msg>" per inviare un messaggio senza alcuna elaborazione (ad esempio, collegamento automatico degli URL) e utilizzare i seguenti tag HTML nel messaggio:

<codice><span><div><label><a><br><br /><p><b><i><del><strike><u><img>
<blockquote><mark><cite><small><ul><ol><li><hr><dl><dt><dd><sup>
<sub><big><pre><figure><figcaption><strong><em><table><tr><td><th>
<tbody><thead><tfoot><h1><h2><h3><h4><h5><h6>

callback è un terzo parametro opzionale costituito da una funzione di callback a cui verranno passati i risultati della chiamatasendChat()invece di inviare i comandi al gioco. L'utilizzo disendChat()in questo modo è asincrono. I risultati del comandosendChat()saranno un ARRAY di operazioni e ogni singolo oggetto sarà simile a un oggetto ricevuto durante un eventochat:message(vedere sopra).

È possibile utilizzare questa funzione, ad esempio, per eseguire un tiro utilizzando il motore di tiro Roll20 e ottenere immediatamente i risultati del tiro. È quindi possibile apportare ulteriori modifiche al tiro prima di inviarlo ai giocatori nel gioco.

sendChat("Riley", "/roll 1d20+4", function(ops) {
    // ops sarà un ARRAY dei risultati del comando.
    var rollresult = ops[0];
    //Ora si procede con rollresult, proprio come si farebbe durante un evento chat:message...
});

options è un quarto parametro opzionale che consente di impostare le opzioni relative alla gestione del messaggio. Le opzioni sono specificate come oggetto javascript le cui proprietà sono i nomi delle opzioni da impostare e i cui valori sono le relative impostazioni, generalmentetruepoiché il valore predefinito è false.

Opzioni disponibili:

• noarchive: impostare questo valore su true per impedire che il messaggio venga memorizzato nel registro della chat. Ciò è particolarmente utile per le uscite che non fanno parte della storia, come i menu dei pulsanti Mod (API) e le informazioni sullo stato.

• use3d-- È ora possibile generare tiri di dadi 3D utilizzando la funzione sendChat(). La sintassi è la seguente:sendChat("Nome", "Rolling [[3d6]]", null, {use3d: true});Se si passa un ID giocatore al parametro nome, ad esempiosendChat("player|-ABC123",...), il colore del giocatore verrà utilizzato per i dadi. In caso contrario, verrà utilizzato il colore bianco predefinito. 

  Nota: I clienti possono visualizzare solo il risultato di un lancio 3D alla volta, pertanto effettuare una serie di lanci 3D separati in sequenza non è consigliabile. Si prega inoltre di notare che l'utilizzo dei tiri 3D comporta un carico leggermente maggiore sul server Quantum Roll, pertanto si raccomanda di agire con discrezione ed evitare di effettuare 100 tiri 3D nell'arco di un secondo. Utilizzare i tiri 3D quando il tiro è rilevante per il giocatore e ha un impatto sul gioco.

  Se si desidera regolare queste opzioni ma non si intende utilizzare un parametrodi callback(terzo parametro - vedere sopra), è possibile semplicemente inserirenullal suo posto:

sendChat("Stato", "Tutti i giocatori sono connessi.", null, {noarchive:true});

Pulsanti di comando Mod (API)

Con l'aggiornamento di Holding, è ora possibile usufruire della nuova formattazione della chat testuale (sia nei messaggi generati dall'API che in quelli generati da macro e abilità) per creare "pulsanti di comando Mod (API)" nella chat.

Per farlo utilizzando la formattazione Markdown:

[Tiro per attaccare](!attackroll)

Il testo tra parentesi quadre apparirà nel pulsante, mentre la parte tra parentesi tonde rappresenta il comando da eseguire. È possibile includere qualsiasi elemento in un normale roll (macro, abilità, query, ecc.), ma si prega di tenere presente che il comando stesso verrà eseguito dal giocatore che fa clic su di esso. Ad esempio, si prega di non includere @{Character|AC} se tutti coloro che possono visualizzare il messaggio non hanno accesso a quel personaggio. Invece, si prega di includere il valore effettivo così come era al momento dell'invio del comando, inserendolo manualmente prima di inviare il messaggio di chat. Questi pulsanti sono applicabili a tutti i tipi di messaggi, inclusi messaggi generali, sussurri, sussurri al GM, ecc.

Si prega di notare che se si utilizza /direct per inviare un messaggio, non verrà eseguita alcuna analisi Markdown, pertanto è necessario includere i propri tag <e> . Ecco un esempio:

<a href="!attackroll">Tiro per colpire</a>

Inserimento dei pulsanti Mod (API) nella chat

È inoltre possibile inserire i pulsanti Mod (API) della sintassi Markdown nella chat affinché altri possano utilizzarli. Poiché saranno interpretati dal parser della chat, se si desidera che gli attributi, le query e i roll vengano espansi quando si fa clic sul pulsante, è necessario inserire parti del comando con una sintassi speciale (entità HTML):

Questo pulsante di esempio ne utilizza alcuni:

[Tiro per attaccare](!attackroll @{target|token_id} [[1d6+?{Bonus|0}]])

È possibile utilizzare i pulsanti Mod (API) per richiamare macro o abilità.

Per procedere, è sufficiente iniziare la porzione di comando con il codice speciale!
quindi aggiungere la chiamata macro con#o la chiamata abilità con%(%):

[Macro](!
#MacroName)

[Abilità] (!
%{CharName|AbilityName})

Per pulsanti di comando delle abilità, se l'abilità che crea il pulsante e l'abilità a cui fa riferimento si trovano entrambe sulla stessa scheda, la sintassi è molto semplice:

[Abilità] (~AbilityName)