API: Chat

Questa pagina illustra i dettagli relativi all'API di Roll20 per quanto riguarda le funzioni di chat.


Eventi in chat

chat:messaggio

Si attiva ogni volta che riceve un nuovo messaggio di chat. Si noti che se il messaggio è di tipo "rollresult" o "gmrollresult", dovrà chiamareJSON.parse() sul contenuto del messaggio per ottenere un oggetto che contenga informazioni sui risultati del rotolo.

Nota:Se un giocatore inserisce un messaggio di chat che inizia con un punto esclamativo (!), quel messaggio avrà il tipo "api" e non verrà mostrato a nessuno. È inteso che questa funzionalità può essere utilizzata per fornire comandi a cui rispondono gli script API. Quindi, se il messaggio è di tipo "api", non è stato mostrato a nessuno e il giocatore che ha inviato il messaggio di chat probabilmente si aspetta che uno script API faccia qualcosa in seguito al messaggio.

Parametro di callback:

Proprietà Valore predefinito Note
che "" Il nome visualizzato del giocatore o del personaggio che ha inviato il messaggio.
playerid   L'ID del giocatore che ha inviato il messaggio.
tipo "generale" Uno tra "generale", "rollresult", "gmrollresult", "emote", "whisper", "desc" o "api".
contenuto "" Il contenuto del messaggio di chat. Se il tipoè "rollresult", questo sarà una stringa JSON di dati sul rotolo.
origRoll   (digitare solo "rollresult" o "gmrollresult")Il testo originale del tiro, ad esempio "2d10+5 danni da fuoco" quando il giocatore digita "2d10+5 danni da fuoco": "2d10+5 danni da fuoco" quando il giocatore digita "/r 2d10+5 danni da fuoco". Questo equivale all'uso del contenuto disui messaggi con tipi diversi da "rollresult" o "gmrollresult".
inlinerolls   (il contenuto contiene solo uno o più rotoli in linea)Un array di oggetti contenenti informazioni su tutti i rotoli in linea nel messaggio.
modello di rotolo   (il contenuto contiene solo uno o più modelli di rotolo)Il nome del modello specificato.
obiettivo   (solo per il tipo "whisper")L'ID giocatore della persona a cui viene inviato il sussurro. Se il sussurro è stato inviato al GM senza utilizzare il suo nome visualizzato (ad esempio, "/w testo gm" invece di "/w testo Riley" quando Riley è il GM), o se il sussurro è stato inviato a un personaggio senza alcun giocatore controllante, il valore sarà "gm".
nome_destinatario   (solo per il tipo "whisper")Il nome visualizzato del giocatore o del personaggio a cui è stato inviato il sussurro.
selezionato   (solo per il tipo "api")Un array di oggetti selezionati dall'utente al momento dell'immissione del comando.

Nota:Probabilmente non ha bisogno di tutte queste informazioni. Nella maggior parte dei casi sarà interessato solo al risultato complessivo del lancio (vedere la parte inferiore del primo esempio). Tuttavia, tutto questo viene fornito se desidera approfondire i risultati di un lancio.

 


Struttura dei risultati dei rotoli Es. 1

Dopo aver chiamatoJSON.parsesulla proprietàcontentdi un messaggio "rollresult" o "gmrollresult", otterrà un oggetto con il seguente formato (questo è il risultato del comando/roll {2d6}+5+1t[weather] Attack!)

{
  "type": "V", //"V" = "Validated Roll" (questo sarà sempre "V" in questo momento)
  "rolls": [
    {
      "tipo": "G", //"G" indica un rotolo raggruppato. Un gruppo è come una serie di "sotto-rotoli" all'interno di un rotolo.
      "rotoli": [
        [
          {
            "type": "R", //"R" = "Roll"
            "dice":2, // Numero di dadi lanciati (2dX significa 2 dadi)
            "sides":6, //Numero di lati per i dadi (Xd6 significa 6 lati)
            "mods":{},
            "results": [ //Array dei risultati di ogni lancio.
             {
               "v":1 // Abbiamo tirato un 1 per il nostro primo 2d6
             },
             {
               "v":5 //Noi abbiamo tirato un 5 per il nostro secondo 2d6
             } }
            ]
          }
        ]
      ],
      "mods":{},
      "resultType": "sum", //Il risultato è una somma (al contrario di un controllo di successo)
      "results": [
        {
          "v":6 // In questo caso, il risultato complessivo (totale) del gruppo.
        }
      ]
    },
    {
      "type": "M", //"M" = Espressione matematica
      "expr": "+5+"
    },
    {
      "type": "R", //"R" = lancio
      "dice":1,
      "table": "weather", //La proprietà table è impostata sul nome della tabella utilizzata se questo lancio è stato effettuato contro una tabella
      "mods":{},
      "sides":2, //Potrebbe probabilmente ignorare questo per i lanci da tabella.
      "risultati": [
        {
          "v":0, //Il "valore" dell'elemento della tabella rotolato. Per le tabelle di testo questo valore è sempre 0.
          "tableidx":1, //l'indice dell'elemento della tabella che è stato lanciato.
          "tableItem": { //A copia dell'oggetto item della tabella come esisteva quando la tabella è stata lanciata.
            "nome": "piovoso", 
            "avatar":", /Questo sarà un URL a un'immagine se la tabella rollabile utilizza icone di immagini
            "peso":1,
            "id":"-IpzPx2j_9piP09ceyOv"
          } }
        }
      ]
    },
    {
      "type": "C", // "C" = Commento
      "text":" Attack!"
    }
  ],
  "resultType": "sum", //Il tipo di risultato complessivo dell'intero rotolo
  "total":11 // Il totale complessivo dell'intero rotolo (compresi tutti i sottogruppi)
}

Struttura dei risultati dei rotoli Es. 2

Una struttura annotata per il risultato di/rotola {1d6!!!>5}>6(che mostra le modifiche che esplodono e i successi degli obiettivi):

{
  "tipo": "V",
  "rotoli": [
    {
      "tipo": "G",
      "rulli": [
        [
          {
            "tipo": "R",
            "dado":1,
            "lati":6,
            "mods": { //Modifiche al lancio
              "compounding": { //"compounding" = "Compounding che esplode (!!)"
                "comp":">=", //Tipo di confronto
                "punto":5 //Punto di confronto
              } } }, "risultati":5 //Punto di confronto.
            },
            "risultati": [
              {
                "v":13 //Risultato complessivo dei dadi. Si noti che, trattandosi di un'esplosione composta, il risultato dei dadi è uno solo.
              }
            ]
          }
        ]
      ],
      "mods": {
        "successo": {
          "comp":">=",
          "punto":6
        } }, "tipo di risultato": "somma", "risultati": "somma".
      },
      "resultType": "sum",
      "results": [
        {
          "v":13
        }
      ]
    }
  ],
  "resultType": "success", // In questo caso, il risultato è un conteggio di successi
  "total":1 //Numero totale di successi
}

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

on("chat:message", function(msg) {
  //Questo consente ai giocatori di inserire !sr <number> per lanciare 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 [, opzioni]] )

Può utilizzare questa funzione per inviare un messaggio di chat.

parlareAspuò essere uno dei seguenti:

  • Qualsiasi stringa, in questo caso verrà utilizzata come nome della persona che ha inviato il messaggio. Ad esempio. "Riley"
  • L'ID di un giocatore, formattato come"player|-Abc123"dove "-Abc123" è l'ID del giocatore. Se lo fa, utilizzerà automaticamente l'avatar e il nome del giocatore.
  • L'ID di un personaggio, formattato come"personaggio|-Abc123". Se lo fa, utilizzerà automaticamente l'avatar e il nome del personaggio.


L'inputdeve essere qualsiasi espressione valida, come quelle utilizzate nell'App Roll20. Può inserire del testo per inviare un messaggio di base, oppure utilizzare i comandi slash come "/roll", "/em", "/w", ecc. Inoltre:

  • Può utilizzare gli Attributi di carattere con il formato@{CharacterName|AttributeName}.
  • Può utilizzare le Abilità del personaggio con il formato:%{CharacterName|AbilityName}.
  • Leinon puòutilizzare le macro.
  • Può utilizzare il comando "/direct <msg>" per inviare un messaggio senza alcuna elaborazione (ad esempio, l'autolink degli URL) e può utilizzare i seguenti tag HTML nel messaggio:

 

<code><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 che consiste in 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à proprio come un oggetto ricevuto durante un eventochat:message(veda sopra).

Può utilizzarlo, ad esempio, per eseguire un lancio utilizzando il motore di lancio Roll20, per poi ottenere immediatamente i risultati del lancio. Potrà quindi apportare ulteriori modifiche al rotolo prima di inviarlo ai giocatori del gioco.

sendChat("Riley", "/rotola 1d20+4", function(ops) {
    // ops sarà un ARRAY di risultati di comandi.
    var rollresult = ops[0];
    //Ora faccia qualcosa con rollresult, proprio come farebbe durante un evento chat:message...
});

opzioniè un quarto parametro opzionale per impostare le opzioni per la gestione del messaggio. Le opzioni sono specificate come un oggetto javascript con le cui proprietà sono i nomi delle opzioni da impostare e i cui valori sono le impostazioni per esse, generalmentetruepoiché sono predefinite a false.

Opzioni disponibili:

  • noarchive-- imposti questo valore a true per evitare che il messaggio venga memorizzato nel log della chat. Questo è particolarmente utile per gli output che non fanno parte della storia, come i menu dei pulsanti API e le informazioni sullo stato.
  • use3d-- Ora può generare rotoli di Dadi 3D utilizzando la funzione sendChat(). La sintassi è semplicemente:sendChat("Name", "Rolling [[3d6]]", null, {use3d: true});Se passa un ID giocatore al parametro name, comesendChat("player|-ABC123",...)il colore del giocatore sarà utilizzato per i dadi. Altrimenti, verrà utilizzato un colore bianco predefinito. 

    Nota: i client dipossono mostrare solo il risultato di un tiro 3D alla volta, per cui non è utile effettuare una serie di tiri 3D separati in fila. Tenga presente che l'utilizzo di rotoli 3D mette un po' più a dura prova il server QuantumRoll, quindi usi il suo giudizio e non esegua 100 rotoli 3D nello spazio di un secondo. Utilizzi i tiri 3D quando il tiro è "importante" per il giocatore e ha un impatto sul gioco.

    Se desidera regolare queste opzioni ma non vuole utilizzare il parametrocallback(terzo parametro - vedere sopra), può semplicemente passarenullal suo posto:

 

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

Pulsanti di comando API

Ora disponibile con l'Aggiornamento della Custodia, puoi sfruttare la nuova formattazione della chat di testo (sia nei messaggi generati dall'API che in quelli generati da macro e abilità) per creare "pulsanti di comando API" nella chat.

Per farlo usando il Markdown formatting:

[Lancio dell'Attacco](!attaccolancio)

Il testo tra parentesi quadre apparirà nel pulsante, mentre la parte tra parentesi è il comando da eseguire. Puoi includere qualsiasi cosa in un normale lancio (macro, abilità, query, ecc.), ma tieni presente che il comando stesso sarà eseguito dal giocatore che fa clic su di esso. Ad esempio, non includere @{Character|AC} se tutti coloro che possono vedere il messaggio non possono accedere a quel personaggio. Invece, includi il valore effettivo com'era quando hai inviato il comando compilandolo tu stesso prima di inviare il messaggio di chat. Questi pulsanti funzioneranno in tutti i tipi di messaggi, messaggi generali, sussurri, gmwhispers, ecc.

Tieni presente che se utilizzi /direct per inviare un messaggio, non effettueremo alcun parsing Markdown su di esso, quindi devi includere i tuoi tag <a>. Ecco un esempio di ciò:

<a href="!attackroll">Tiro d'Attacco</a>

Inserisci Pulsanti API nella Chat

Puoi anche digitare la sintassi Markdown dei pulsanti API nella chat per farli usare dagli altri. Poiché verranno interpretati dall'analizzatore della chat, se desideri che gli attributi, le query e i tiri siano espansi quando si fa clic sul pulsante, devi inserire parti del comando con una sintassi speciale (Entità HTML):

Personaggio Sostituzione
 % &#37;
) &#41;
 ? &#63;
@ &#64;
[ &#91; or &lbrack;
] &#93; or &rbrack;

Questo pulsante di esempio ne utilizza alcuni:

[Tiro di Attacco](!lanciodadi &#64;{target|token_id} &#91;[1d6+&#63;{Bonus|0}]&#93;)

In realtà, può utilizzare i pulsanti API per chiamare le macro o le abilità.

Carattere Sostituzione
<carriage return> &#13;

Per farlo, deve semplicemente iniziare la parte di comando con il codice speciale!&#13;poi aggiungere la chiamata macro con#o la chiamata di abilità con&#37;(%):

[Macro](!&#13;#MacroNome)

[Capacità](!&#13;&#37;{CharName|AbilityName})

Nota: In questo momento, riaprire una Macro salvata nella scheda Collezioni della Sidebar comporta il ripristino delle entità HTML al suo interno; se la Macro viene poi salvata, lo stesso avviene per tali ripristini. Questo comportamento non è presente all'interno diAbilitào Pulsanti di Comando delle Abilità.

PerPulsanti di Comando delle Abilità, se l'Abilità che crea il pulsante e l'Abilità a cui fa riferimento sono entrambe nella stessa scheda, la sintassi è molto semplice:

[Abilità](~AbilityName)

Questo articolo ti è stato utile?
Utenti che ritengono sia utile: 14 su 20