Scripts de mod: Chat

En esta página se describen los detalles relativos a los scripts de mods en lo que respecta a las funciones de 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», «gmrollresult», «secretrollresult» o «supersecretrollresult», deberá llamar a la función JSON.parse() sobre el contenido del mensaje para obtener un objeto que contenga información sobre los resultados de la tirada.

Si un jugador escribe un mensaje en el chat que comience por !, ese mensaje tiene el tipo «api» y no se muestra en el chat. Los scripts utilizan ese tipo para los comandos. La función sendChat() también activa el evento «chat:message», y dichos mensajes tienen el identificador de jugador «API».

Parámetro de devolución de llamada:

Los roles «secretos» y «súper secretos» utilizan estos comandos (disponibles en ambas versiones de prueba):

• /secretroll o /sr: el tipo es «secretrollresult», «secret» es «true» y «secrecy» es «secret».
• /supersecretroll o /ssr: el tipo es «supersecretrollresult», el secreto es «true» y el nivel de confidencialidad es «super».
• /secret o /s seguido de un mensaje (por ejemplo, /secret [[1d6]]) — el tipo sigue siendo «general», «secret» es verdadero y el nivel de confidencialidad es «secreto». Forma compacta y secreta de realizar una tirada «susurrada al director de juego»: el director de juego ve el resultado; el jugador que realiza la tirada ve que se ha llevado a cabo una tirada secreta.
• /supersecret o /ss seguido de un mensaje: el tipo sigue siendo «general», «secret» es «verdadero» y el nivel de confidencialidad es «super».

/sr y /ssr son comandos de giro. ¡No lo son ! comandos. Un mensaje que empieza con un signo de exclamación ! tiene el tipo «api».

Nota: Probablemente no necesite toda esta información. En la mayoría de los casos, solo le interesará el resultado global de la tirada (véase la parte inferior del primer ejemplo). Sin embargo, todo esto se proporciona si realmente desea profundizar en los resultados de una tirada.

Estructura del resultado del lanzamiento Ej. 1

Tras llamar a JSON.parse sobre la propiedad «content» de un mensaje «rollresult», «gmrollresult», «secretrollresult» o «supersecretrollresult», 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 // Ha salido un 1 en nuestra primera tirada de 2d6
              },
              {
                "v":5 // Ha salido 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 desplegable 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 del resultado de /roll {1d6!!>5}>6 (en la que se muestran las modificaciones por explosión y los éxitos del 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 un tipo de rol personalizado)

on("chat:message", function(msg) {
  // Los jugadores escriben «!d6 3» para lanzar ese número de dados de seis caras con un objetivo de 4.
  if (msg.type !== "api" || msg.content.indexOf("!d6 ") !== 0) return;
  var numdice = parseInt(msg.content.substring(4), 10);
  if (!numdice || numdice < 1) return;
  var who = msg.who.replace(/ \(GM\)$/, "");
  sendChat(who, "/roll " + numdice + "d6>4");
});

sendChat(hablandoComo, entrada [,callback [, opciones]] )

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

«speakingAs» puede ser una de las siguientes opciones:

• 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 «player|-Abc123», donde -Abc123 es el ID del jugador. Si hace esto, se utilizarán automáticamente el avatar y el nombre del jugador.
• El ID de un personaje, con el formato «personaje|-Abc123». Si hace esto, se utilizarán 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. Introduzca texto para enviar un mensaje básico, o utilice comandos con barra, como /roll, /em, /w, /secretroll (/sr), /supersecretroll (/ssr), /secret (/s), /supersecret (/ss), etc. Además:

• Puede utilizar los atributos de carácter con el formato @{CharacterName|AttributeName}.
• Puede utilizar las habilidades de los personajes con el siguiente formato: %{CharacterName|AbilityName}.
• No es posible ejecutar macros desde sendChat del mismo modo en que un jugador escribe #NombreDeLaMacro. Al hacer clic en un botón, se puede ejecutar una macro: [Nombre](!
#MacroName).
• @{selected|...} no se expande dentro de sendChat. Lea «msg.selected» en el controlador «chat:message », en su lugar.
• Los mensajes normales y los mensajes privados pueden incluir las etiquetas HTML que se indican a continuación. /direct <msg> envía el mensaje sin Markdown y sin enlaces automáticos a las URL, y permite utilizar las mismas etiquetas:

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

función de llamada de retorno 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 llamada a sendChat(), en lugar de enviar los comandos al juego. El uso de sendChat() de esta manera es asíncrono. El resultado del comando sendChat() será una MATRIZ de operaciones, y cada objeto individual será idéntico a un objeto que se recibe durante un evento «chat: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á un ARRAY con los resultados del comando.
  var rollresult = ops[0];
  //Ahora haga algo con rollresult, tal y como lo haría durante un evento «chat:message»...
});

opciones es un cuarto parámetro opcional que permite configurar las opciones relativas al tratamiento del mensaje. Las opciones se especifican como un objeto de JavaScript cuyas propiedades son los nombres de las opciones que se desean configurar y cuyos valores son los ajustes correspondientes; por lo general, se establecen en «true», ya que su valor predeterminado es «false».

Opciones disponibles:

• noarchive: establezca este parámetro en «true» para evitar que el mensaje se guarde en el historial del chat. Esto resulta especialmente útil para los elementos que no forman parte de la historia, como los menús de los botones de Mod Script y la información sobre el estado.
• use3d – Ahora puede generar tiradas de dados en 3D mediante la función sendChat(). La sintaxis es muy sencilla: sendChat("Nombre", "Tirada [[3d6]]", null, {use3d: true}); Si se introduce un identificador de jugador en el parámetro «nombre», por ejemplo, sendChat("player|-ABC123",...), se utilizará el color de ese jugador para los dados. De lo contrario, se utilizará el color blanco predeterminado.

Nota: Los clientes de « » solo pueden mostrar el resultado de un «3D roll» cada vez, por lo que no resulta útil crear varios «3D roll» por separado seguidos. Tenga en cuenta, asimismo, que el uso de giros 3D supone una carga ligeramente mayor para el servidor de QuantumRoll, por lo que le recomendamos que actúe con criterio y no realice 100 giros 3D en el espacio de un segundo. Utilice tiradas en 3D cuando la tirada sea importante para el jugador y tenga repercusiones en el juego.

Si desea ajustar estas opciones pero no quiere utilizar un parámetro de devolución de llamada (tercer parámetro; véase más arriba), basta con pasar «null» en su lugar:

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

Botones de comandos del script de mod

El formato del chat de texto, tanto en los mensajes de Mod Script como en las macros y habilidades, puede generar botones de comando 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 tienen acceso a ese personaje. 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 funcionan en los mensajes generales, en los mensajes privados y en los mensajes privados dirigidos al GM. El clic se ejecuta en nombre del jugador que hace clic, con el «playerid» de dicho jugador y este seleccionado.

/direct omite el Markdown, por lo que [Tirada de ataque](!attackroll) no se convertirá en un botón.

Introducción de botones de scripts de mods en el chat

También puede escribir en el chat los botones de sintaxis Markdown de Mod Script para que los demás 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}]])

De hecho, puede utilizar los botones de scripts de mods para activar macros o habilidades.

Para ello, basta con comenzar la parte del comando con el código especial «!&#13»; a continuación, añada la llamada a la macro con «#» o la llamada a la función con «% (%)»:

[Macro](!
#MacroName)

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

Nota: En este momento, al volver a abrir una macro guardada en la pestaña «Colecciones» de la barra lateral, las entidades HTML que contiene se revierten; si a continuación se guarda la macro, también se guardan dichas reversiones. Este comportamiento no se da en los botones de «Habilidades» ni en los botones de comando de habilidades.

En el caso de los botones de habilidades, si tanto la habilidad que crea el botón como la habilidad a la que hace referencia se encuentran en la misma hoja, la sintaxis es muy sencilla:

[Habilidad] (~AbilityName)