API: Chat

Eventos de chat

chat:mensaje

Se activa cada vez que se recibe un nuevo mensaje de chat. Tenga en cuenta que si el mensaje es de tipo «rollresult» o «gmrollresult», deberá llamar aJSON.parse() en 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 a JSON.parse en el propiedad content de 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" = "Tirada validada" (en este momento siempre será "V")
  "rolls": [
    {
      "type":"G", //"G" indica una tirada agrupada. Un grupo es como una serie de «subfunciones» dentro de una función.
      "rolls": [
        [
          {
            "type":"R", //"R" = "Roll"
            "dice":2, // Número de dados lanzados (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 nuestra primera tirada de 2d6
             },
             {
               "v":5 //Hemos sacado un 5 en nuestra segunda tirada de 2d6
             }
            ]
          }
        ]
      ],
      "mods":{},
      "resultType":"sum", //El resultado es una suma (a diferencia 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" = Tirada
      "dice":1,
      "table":"weather", //La propiedad table se establece con el nombre de la tabla utilizada si esta tirada se ha realizado contra una tabla
      "mods":{},
      "sides":2, //Probablemente pueda ignorar esto para las tiradas de tabla.
      «resultados»: [
        {
          «v»:0, //El «valor» del elemento de la tabla obtenido. En el caso de las tablas de texto, siempre es 0.
          "tableidx":1, //El índice del elemento de la tabla que se ha desplazado.
          "tableItem": { //Una copia del objeto del elemento de la tabla tal y como existía cuando se generó la tabla.
            «name»: «rainy», 
            «avatar»: «», //Esta será una URL a una imagen si la tabla enrollable utiliza iconos de imagen
            "weight":1,
            "id":"-IpzPx2j_9piP09ceyOv"
          }
        }
      ]
    },
    {
      "type":"C", // "C" = Comentario
      "text":" ¡Ataque!"
    }
  ],
  "resultType":"sum", //El tipo de resultado global de toda la tirada
  "total":11 // El total global de toda la tirada (incluidos todos los subgrupos)
}

Estructura del resultado del lanzamiento Ej. 2

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

{
  "type":"V",
  "rolls": [
    {
      "type":"G",
      "rolls": [
        [
          {
            "type":"R",
            "dice":1,
            "sides":6,
            "mods": { //Modificaciones a la tirada
              "compounding": { //"compounding" = "Compounding exploding (!!)"
                "comp":">=", //Tipo de comparación
                "point":5 //Punto de comparación
              }
            },
            "results": [
              {
                "v":13 //Resultado general de los dados. Tenga en cuenta que, dado que se trata de una explosión compuesta, solo hay un resultado del dado.
              }
            ]
          }
        ]
      ],
      "mods": {
        "success": {
          "comp":">=",
          "point":6
        }
      },
      "resultType":"sum",
      "results": [
        {
          "v":13
        }
      ]
    }
  ],
  "resultType":"success", // En este caso, el resultado es un recuento de éxitos
  "total":1 //Número total de éxitos
}

Ejemplo de evento de chat (implementación de tipo de rollo personalizado)

on("chat:message", function(msg) {
  //Esto permite a los jugadores introducir !sr <number> para tirar varios 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(hablandoComo, entrada [,callback [, opciones]] )

Puede utilizar esta función para enviar un mensaje de chat.

hablarComo puede ser uno de los siguientes:

• Cualquier cadena, en cuyo caso se utilizará como nombre de la persona que envió el mensaje. Por ejemplo. «Riley»
• El ID de un jugador, con el formato «jugador|-Abc123»,donde «-Abc123» es el ID del jugador. Si hace esto, se utilizará automáticamente el avatar y el nombre del jugador.
• El ID de un personaje, con el formato «personaje|-Abc123». Si hace esto, se utilizará automáticamente el avatar y el nombre del personaje.

entrada debe ser cualquier expresión válida, igual que las que se utilizan en la aplicación Roll20. Introduce texto para enviar un mensaje básico o utiliza comandos de barra inclinada como «/roll», «/em», «/w», etc. Además:

• Puede utilizar los atributos de carácter con el formato@{CharacterName|AttributeName}.
• Puede utilizar las habilidades de los personajes con el formato:%{CharacterName|AbilityName}.
• Nopuede utilizar macros.
• Puede utilizar el comando «/direct <msg>» para enviar un mensaje sin ningún tipo de procesamiento (por ejemplo, enlaces automáticos de URL) y puede utilizar las siguientes etiquetas HTML en el mensaje:

<código><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 es un tercer parámetro opcional que consiste en una función de devolución de llamada a la que se le pasarán los resultados de la llamadaa sendChat()en lugar de enviar los comandos al juego. El uso desendChat()de esta manera es asíncrono. El resultado del comandosendChat()será una MATRIZ de operaciones, y cada objeto individual será igual que un objeto que recibe durante un eventochat:message(véase más arriba).

Puede utilizar esto, por ejemplo, para realizar una tirada con el motor de tiradas Roll20 y obtener los resultados de la tirada inmediatamente. A continuación, podría realizar modificaciones adicionales al rollo antes de enviarlo a los jugadores en el juego.

sendChat("Riley", "/roll 1d20+4", function(ops) {
    // ops será una MATRIZ con los resultados del comando.
    var rollresult = ops[0];
    //Ahora haga algo con rollresult, tal y como haría durante un evento chat:message...
});

options es un cuarto parámetro opcional que permite configurar opciones sobre cómo se gestiona el mensaje. Las opciones se especifican como un objeto javascript cuyas propiedades son los nombres de las opciones que se van a configurar y cuyos valores son los ajustes para ellas, generalmenteverdaderos, ya que por defecto son falsos.

Opciones disponibles:

• noarchive: establezca este valor en verdadero para evitar que el mensaje se almacene en el registro del chat. Esto resulta especialmente útil para salidas que no forman parte de la historia, como los menús del botón Mod (API) y la información de estado.

• use3d: ahora puede generar tiradas de dados en 3D utilizando la función sendChat(). La sintaxis es muy sencilla:sendChat("Nombre", "Tirando [[3d6]]", null, {use3d: true});Si pasa un ID de jugador al parámetro «nombre», comosendChat("jugador|-ABC123",...), se utilizará el color del jugador para los dados. De lo contrario, se utilizará el color blanco predeterminado. 

  Nota: Los clientes solo pueden mostrar el resultado de una tirada 3D a la vez, por lo que no sirve de nada realizar varias tiradas 3D seguidas. Tenga en cuenta también que el uso de tiradas 3D supone una mayor carga para el servidor de QuantumRoll, por lo que le recomendamos que utilice su criterio y no realice 100 tiradas 3D en un segundo. Utilice tiradas 3D cuando la tirada sea «importante» para el jugador y tenga un impacto en el juego.

  Si desea ajustar estas opciones pero no quiere utilizar un parámetrode devolución de llamada(tercer parámetro, véase más arriba), simplemente puede pasarnullen su lugar:

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

Botones de comando Mod (API)

Ahora, con la actualización de Holding, puede aprovechar el nuevo formato de chat de texto (tanto en los mensajes generados por la API como en los generados por macros y habilidades) para crear «botones de comando Mod (API)» en el chat.

Para hacerlo utilizando el formato Markdown:

[Tirada de ataque] (!attackroll)

El texto entre corchetes aparecerá en el botón, y la parte entre paréntesis es el comando que se ejecutará. Puede incluir cualquier cosa en un rollo normal (macros, habilidades, consultas, etc.), pero tenga en cuenta que el comando en sí será ejecutado por el jugador que haga clic en él. Por ejemplo, no incluya @{Character|AC} si todas las personas que pueden ver el mensaje no pueden acceder a ese carácter. En su lugar, incluya el valor real tal y como existía cuando envió el comando, rellenándolo usted mismo antes de enviar el mensaje de chat. Estos botones funcionarán en todos los tipos de mensajes, mensajes generales, susurros, susurros al administrador, etc.

Tenga en cuenta que si utiliza /direct para enviar un mensaje, no realizaremos ningún análisis Markdown en él, por lo que deberá incluir sus propias etiquetas <a> . Aquí tiene un ejemplo:

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

Introducción de botones Mod (API) en el chat

También puede escribir botones Mod (API) con sintaxis Markdown en el chat para que otros los utilicen. Dado que serán interpretados por el analizador del chat, si usted desea que los atributos, consultas y tiradas se expandan al hacer clic en el botón, debe introducir partes del comando con una sintaxis especial (entidades HTML):

Este botón de muestra utiliza algunos de ellos:

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

En realidad, puede utilizar los botones Mod (API) para activar macros o habilidades.

Para ello, simplemente comience la parte del comando con el código especial!
y luego añada la llamada a la macro con#o la llamada a la habilidad con %(%):

[Macro](!
#MacroName)

[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 se encuentran en la misma hoja, la sintaxis es muy sencilla:

[Habilidad] (~AbilityName)