API: Chat

Eventos de Chat

chat:message

Se activa cuando se recibe un nuevo mensaje de chat. Tenga en cuenta que si el mensaje es del tipo "rollresult" o "gmrollresult", tendrá que llamar aJSON.parse() sobre el contenido del mensaje para obtener un objeto que contenga información sobre los resultados de la tirada.

Parámetro de devolución de llamada:

Estructura del resultado del lanzamiento Ej. 1

Después de llamar aJSON.parsesobre la propiedadcontentde un mensaje "rollresult" o "gmrollresult", obtendrá un objeto con el siguiente formato (este es el resultado del comando/roll {2d6}+5+1t[weather] ¡Ataque!)

{
  "type": "V", //"V" = "Validated Roll" (esto siempre será "V" por ahora)
  "rolls": [
    {
      "type": "G", //"G" indica una tirada agrupada. Un grupo es como una serie de "sub-rollos" dentro de un rollo.
      "tiradas" [
        [
          {
            "type": "R", //"R" = "Tirada"
            "dice":2, //Número de dados tirados (2dX significa 2 dados)
            "sides":6, //Número de caras del dado (Xd6 significa 6 caras)
            "mods":{},
            "results": [ /Una matriz con los resultados de cada tirada.
             {
               "v":1 // Hemos sacado un 1 en nuestro primer 2d6
             },
             {
               "v":5 // Hemos sacado un 5 en nuestro segundo 2d6
             }
            ]
          }
        ]
      ],
      "mods":{},
      "resultType":"suma", // El resultado es la suma (en lugar de una comprobación de éxito)
      "results": [
        {
          "v":6 // En este caso, el resultado global (total) del grupo.
        }
      ]
    },
    {
      "type":"M", //"M" = Expresión Matemática
      "expr":"+5+"
    },
    {
      "type":"R", //"R" = Lanzamiento
      "dice":1,
      "table":"clima", // La propiedad de la tabla se establece en el nombre de la tabla usada si este lanzamiento se hizo contra una tabla
      "mods":{},
      "sides":2, // Probablemente puedas ignorar esto para lanzamientos de tabla.
      "results": [
        {
          "v":0, // El "valor" del elemento de la tabla lanzado. Para tablas de texto, esto siempre es 0.
          "tableidx":1, //El índice del elemento en la tabla que se lanzó.
          "tableItem": { //Una copia del objeto de elemento de tabla tal como existía cuando se lanzó la tabla.
            "name":"lluvioso", 
            "avatar":"", //Esto será una URL a una imagen si la tabla desplegable utiliza iconos de imagen
            "weight":1,
            "id":"-IpzPx2j_9piP09ceyOv"
          }
        }
      ]
    },
    {
      "type":"C", // "C" = Comentario
      "text":" ¡Atacar!"
    }
  ],
  "resultType":"suma", //El tipo de resultado general del lanzamiento completo
  "total":11 // El total general del lanzamiento completo (incluyendo todos los subgrupos)
}

Estructura del Resultado del Lanzamiento Ej. 2

Una estructura anotada para el resultado del/roll {1d6!!>5}>6 (mostrando modificaciones explosivas y éxitos objetivo):

{
  "tipo": "V",
  "rollos": [
    {
      "tipo": "G",
      "tiradas": [
        [
          {
            "tipo": "R",
            "dado":1,
            "lados":6,
            "mods": { //Modificaciones de la tirada
              "compounding": { //"compounding" = "Compounding exploding (!!)"
                "comp":">=", //Tipo de comparación
                "point":5 //Punto de comparación
              }
            },
            "resultados": [
              {
                "v":13 //Resultado del dado global. Tenga en cuenta que como se trata de una explosión compuesta sólo hay un resultado de dados.
              }
            ]
          }
        ]
      ],
      "mods": {
        "success": {
          "comp":">=",
          "point":6
        }
      },
      "resultType":"sum",
      "results": [
        {
          "v":13
        }
      ]
    }
  ],
  "resultType":"success", // En este caso, el resultado es una cuenta de éxitos
  "total":1 //Número total de éxitos
}

Chat Event Ejemplo (Implementando Tipo de Lanzamiento Personalizado)

on("chat:message", function(msg) {
  //Esto permite a los jugadores ingresar !sr <number> para lanzar un número de dados d6 con un objetivo de 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]] )

Puedes usar esta función para enviar un mensaje de chat.

speakingAspuede ser uno de:

• Cualquier cadena, en cuyo caso se usará como nombre de la persona que envió el mensaje. Por ejemplo, "Riley"
• El ID de un jugador, formateado como"jugador|-Abc123"donde "-Abc123" es el ID del jugador. Si haces esto, automáticamente usará el avatar y el nombre del jugador.
• La ID de un personaje, formateada como "personaje|-Abc123". Si haces esto, automáticamente usará el avatar y el nombre del personaje.

Entrada debería ser una expresión válida, al igual que las utilizadas en la aplicación Roll20. Ingresa texto para enviar un mensaje básico, o usa comandos con barra como "/roll", "/em", "/w", etc. Además:

• Puedes usar Atributos de Personaje con el formato @{CharacterName|AttributeName}.
• Puedes usar Habilidades de Personaje con el formato: %{CharacterName|AbilityName}.
• no puedes usar macros.
• Puede utilizar el comando "/direct <msg>" para enviar un mensaje sin ningún tipo de procesamiento (por ejemplo, autolinking de URLs), y puede utilizar las siguientes etiquetas HTML en el mensaje:

<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>

callbackes un tercer parámetro opcional que consiste en una función callback a la que se pasarán los resultados de la llamada asendChat()en lugar de enviar los comandos al juego. Usar sendChat() de esta manera es asíncrono. Los resultados del comandosendChat()serán un ARRAY de operaciones, y cada objeto individual será igual que un objeto que reciba durante un eventochat:message(véase más arriba).

Puedes usar esto, por ejemplo, para realizar una tirada utilizando el motor de tiradas de Roll20, y luego obtener los resultados de la tirada inmediatamente. Luego podrías realizar modificaciones adicionales en la tirada antes de enviarla a los jugadores del juego.

sendChat("Riley", "/roll 1d20+4", function(ops) {
    // ops será una SERIE de resultados de comandos.
    var rollresult = ops[0];
    //Ahora haz algo con rollresult, igual como lo harías durante un evento chat:message...
});

opcioneses un cuarto parámetro opcional para configurar las opciones de cómo se maneja el mensaje. Las opciones se especifican como un objeto JavaScript cuyas propiedades son los nombres de las opciones a configurar y cuyos valores son la configuración para ellos, generalmente true ya que su valor predeterminado es false.

Opciones disponibles:

• noarchive -- configúralo en true para evitar que el mensaje se guarde en el registro de chat. Esto es particularmente útil para la salida que no forma parte de la historia, como los menús de botones Mod (API) y la información de estado.

• use3d -- ahora puedes generar tiradas de dados en 3D usando la función sendChat(). La sintaxis es simplemente: sendChat("Nombre", "Lanzando [[3d6]]", null, {use3d: true}); Si pasas un ID de jugador al parámetro de nombre, como sendChat("jugador|-ABC123",...), se usará el color del jugador para los dados. De lo contrario se usará un color blanco predeterminado. 

  Nota: Los clientes solo pueden mostrar el resultado de un lanzamiento 3D a la vez, por lo que realizar varios lanzamientos 3D seguidos no es útil. También ten en cuenta que el uso de lanzamientos 3D ejerce más presión en el servidor QuantumRoll, por lo que debes usar tu criterio y no realizar 100 lanzamientos 3D en el espacio de un segundo. Utiliza lanzamientos 3D cuando el lanzamiento "importe" al jugador y tenga un impacto en el juego.

  Si quieres ajustar estas opciones pero no quieres usar unparámetro de retorno(tercer parámetro - ver arriba), simplemente puedes pasarnullen su lugar:

sendChat("Estado", "Todos los jugadores están conectados.", null, {noarchive:true} );

Botones de Comando Mod (API)

Ahora disponible con la Actualización de Holding puedes aprovechar el nuevo formato de chat de texto (tanto en tus mensajes generados por API como en aquellos generados por macros y habilidades) para crear "botones de comando Mod (API)" en el chat.

Para hacerlo utilizando el formato Markdown:

[Lanzamiento de Ataque](!attackroll)

El texto entre corchetes se mostrará en el botón, y la parte entre paréntesis es el comando que se ejecutará. Puedes incluir cualquier cosa en un rol normal (macros, habilidades, consultas, etc.), pero ten en cuenta que el propio comando será ejecutado por el jugador que haga clic en él. Por ejemplo, no incluyas @{Character|AC} si todos los que pueden ver el mensaje no pueden acceder a ese personaje. En su lugar, incluye el valor real tal como existía cuando enviaste el comando, completándolo tú mismo antes de enviar el mensaje de chat. Estos botones funcionarán en todos los tipos de mensajes, mensajes generales, susurros, susurros de GM, etc.

Ten en cuenta que si usas /direct para enviar un mensaje, no realizaremos ningún análisis de Markdown, por lo que debes incluir tus propias etiquetas <a> . Aquí tienes un ejemplo de ello:

<a href="!attackroll">Tirada de Ataque</a>

Ingresando Botones Mod (API) en el Chat

También puedes escribir sintaxis de Markdown de botones Mod (API) en el chat para que otros la usen. Debido a que serán interpretados por el analizador de chat, si quieres que los atributos, consultas y tiradas se expandan cuando se haga clic en el botón, debes ingresar partes del comando con una sintaxis especial (Entidades HTML):

Este botón de ejemplo los utiliza:

[Tirada de ataque](!tirada de ataque @{target|token_id} [[1d6+?{Bonus|0}]])

De hecho, puedes utilizar los Botones Mod (API) para llamar a Macros o Habilidades.

Para hacerlo, simplemente comienza la parte del comando con el código especial !
 luego agrega la llamada a la macro con # o la llamada a la habilidad con % (%):

[Macro](!
#NombreMacro)

[Habilidad](!
%{CharName|AbilityName})

Para Botones de Comando de Habilidad, si la Habilidad que crea el botón y la Habilidad a la que hace referencia están en la misma hoja, la sintaxis es muy simple:

[Habilidad](~NombreHabilidad)