Scripts de modificação: Chat

Esta página apresenta informações relativas aos scripts de modificação no que diz respeito às funções de chat.

Eventos de chat

chat:mensagem

É acionado sempre que é recebida uma nova mensagem de chat. Tenha em atenção que, se a mensagem for do tipo «rollresult», «gmrollresult», «secretrollresult» ou «supersecretrollresult», terá de chamar a função JSON.parse() ao conteúdo da mensagem para obter um objeto que contenha informações sobre os resultados do lançamento.

Se um jogador introduzir uma mensagem no chat que comece por !, essa mensagem tem o tipo «api» e não é apresentada no chat. Os scripts utilizam esse tipo para os comandos. A função sendChat() também aciona o evento chat:message, e essas mensagens têm o playerid «API».

Parâmetro de retorno de chamada:

As funções «Secret» e «Super-secret» utilizam estes comandos (disponíveis em ambas as versões de sandbox):

• /secretroll ou /sr — o tipo é «secretrollresult», o segredo é verdadeiro, o nível de sigilo é «secret».
• /supersecretroll ou /ssr — o tipo é «supersecretrollresult», o segredo é verdadeiro e o nível de sigilo é «super».
• /secret ou /s seguido de uma mensagem (por exemplo, /secret [[1d6]]) — o tipo permanece «geral», «secret » é verdadeiro e o nível de confidencialidade é «secreto». Forma compacta e secreta de um lançamento «sussurrado ao GM»: o GM vê o valor; quem lança vê que foi efetuado um lançamento secreto.
• /supersecret ou /ss seguido de uma mensagem — o tipo permanece «geral», o nível de segredo é verdadeiro e o grau de sigilo é «super».

/sr e /ssr são comandos de rotação. Não são ! comandos. Uma mensagem que começa com ! tem o tipo «api».

Nota: Provavelmente não necessita de toda esta informação. Na maioria dos casos, só estará interessado no resultado global do lançamento (ver a parte inferior do primeiro exemplo). No entanto, tudo isso é fornecido caso deseje realmente aprofundar-se nos resultados de um lançamento.

Estrutura do resultado do lançamento Ex. 1

Depois de chamar o método JSON.parse na propriedade «content» de uma mensagem «rollresult», «gmrollresult», «secretrollresult» ou «supersecretrollresult», obterá um objeto com o seguinte formato (este é o resultado do comando /roll {2d6}+5+1t[weather] Ataque!)

{
  "type":"V", //"V" = "Validated Roll" (isto será sempre "V" neste momento)
  "rolls": [
    {
      "type":"G", //"G" indica um lançamento agrupado. Um grupo é semelhante a uma série de "subfunções" dentro de uma função.
      "rolls": [
        [
          {
            "type":"R", //"R" = "Roll"
            "dice":2, // Número de dados lançados (2dX significa 2 dados)
            "sides":6, //Número de lados dos dados (Xd6 significa 6 lados)
            "mods":{},
            "results": [ //Uma matriz com os resultados de cada lançamento.
              {
                "v":1 // Obtivemos um 1 no nosso primeiro lançamento de 2d6
              },
              {
                "v":5 // Obtivemos um 5 no nosso segundo lançamento de 2d6
              }
            ]
          }
        ]
      ],
      "mods":{},
      "resultType":"sum", //O resultado é uma soma (em oposição a uma verificação de sucesso)
      "results": [
        {
          "v":6 // Neste caso, o resultado global (total) do grupo.
        }
      ]
    },
    {
      "type":"M", //"M" = Expressão Matemática
      "expr":"+5+"
    },
    {
      "type":"R", //"R" = Lançamento
      "dice":1,
      "table":"weather", //A propriedade table é definida como o nome da tabela utilizada se este lançamento foi feito contra uma tabela
      "mods":{},
      "sides":2, //Provavelmente pode ignorar isto para lançamentos de tabela.
      "resultados": [
        {
          "v":0, //O "valor" do item da tabela lançado. Para tabelas de texto, este valor é sempre 0.
          "tableidx":1, //O índice do item na tabela que foi rolado.
          "tableItem": { //Uma cópia do objeto do item da tabela tal como existia quando a tabela foi gerada.
            "name":"rainy",
            "avatar":"", //Esta será uma URL para uma imagem, caso a tabela rolante utilize ícones de imagem
            "weight":1,
            "id":"-IpzPx2j_9piP09ceyOv"
          }
        }
      ]
    },
    {
      "type":"C", // "C" = Comentário
      "text":" Ataque!"
    }
  ],
  "resultType":"sum", //O tipo de resultado geral de todo o lançamento
  "total":11 // O total geral de todo o lançamento (incluindo todos os subgrupos)
}

Estrutura do resultado do lançamento Ex. 2

Uma estrutura anotada para o resultado de /roll {1d6!!>5}>6 (mostrando as modificações decorrentes de explosões e os sucessos no alvo):

{
  "type":"V",
  "rolls": [
    {
      "type":"G",
      "rolls": [
        [
          {
            "type":"R",
            "dice":1,
            "sides":6,
            "mods": { //Modificações ao lançamento
              "compounding": { //"compounding" = "Compounding exploding (!!)"
                "comp":">=", //Tipo de comparação
                "point":5 //Ponto de comparação
              }
            },
            "results": [
              {
                "v":13 //Resultado geral dos dados. Observe que, como se trata de uma explosão composta, há apenas um resultado do dado.
              }
            ]
          }
        ]
      ],
      "mods": {
        "success": {
          "comp":">=",
          "point":6
        }
      },
      "resultType":"sum",
      "results": [
        {
          "v":13
        }
      ]
    }
  ],
  "resultType":"success", // Neste caso, o resultado é uma contagem de sucessos
  "total":1 //Número total de sucessos
}

Exemplo de evento de chat (implementação de um tipo de rolo personalizado)

on("chat:message", function(msg) {
  // Os jogadores digitam !d6 3 para lançarem esse número de dados d6 contra um valor-alvo 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");
});

enviarChat(falandoComo, entrada [,retorno de chamada [, opções]] )

É possível utilizar esta função para enviar uma mensagem de chat.

falando como pode ser um dos seguintes:

• Qualquer sequência de caracteres, que será utilizada como o nome da pessoa que enviou a mensagem. Por exemplo. "Riley"
• O ID de um jogador, no formato «player|-Abc123», em que -Abc123 corresponde ao ID do jogador. Se fizer isto, o avatar e o nome do jogador serão utilizados automaticamente.
• O ID de uma personagem, com o formato «personagem|-Abc123». Se fizer isto, o avatar e o nome da personagem serão utilizados automaticamente.

entrada deve ser qualquer expressão válida, tal como as utilizadas na aplicação Roll20. Pode introduzir texto para enviar uma mensagem básica ou utilizar comandos com barra, tais como /roll, /em, /w, /secretroll (/sr), /supersecretroll (/ssr), /secret (/s), /supersecret (/ss), etc. Além disso:

• Pode utilizar os atributos de caracteres no formato @{CharacterName|AttributeName}.
• Pode utilizar as Habilidades das Personagens no seguinte formato: %{CharacterName|AbilityName}.
• Não é possível chamar macros a partir do sendChat da mesma forma que um jogador digita #NomeDaMacro. Um botão pode executar uma macro quando clicado: [Nome](!
#MacroName).
• @{selected|...} não é expandido no interior da função sendChat. Em vez disso, leia ` msg.selected ` no manipulador ` chat:message `.
• As mensagens normais e os mensagens privadas podem incluir as seguintes etiquetas HTML. /direct <msg> envia a mensagem sem Markdown e sem ligação automática de URLs, podendo utilizar as mesmas 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>

função de retorno é um terceiro parâmetro opcional que consiste numa função de retorno de chamada à qual serão passados os resultados da chamada a sendChat(), em vez de enviar os comandos para o jogo. A utilização da função sendChat() desta forma é assíncrona. Os resultados do comando sendChat() serão um ARRAY de operações, e cada objeto individual será idêntico a um objeto que recebe durante um evento «chat:message» (ver acima).

Pode utilizar isto, por exemplo, para realizar um lançamento utilizando o mecanismo de lançamento Roll20 e, em seguida, obter os resultados do lançamento imediatamente. Você poderia então realizar modificações adicionais na jogada antes de enviá-la aos jogadores no jogo.

sendChat("Riley", "/roll 1d20+4", function(ops) {
  // ops será um ARRAY com os resultados do comando.
  var rollresult = ops[0];
  //Agora faça algo com rollresult, tal como faria durante um evento «chat:message»...
});

opções é um quarto parâmetro opcional que permite definir opções relativas ao tratamento da mensagem. As opções são especificadas como um objeto JavaScript cujas propriedades correspondem aos nomes das opções a definir e cujos valores correspondem às respetivas configurações; geralmente, o valor é «true», uma vez que o valor por predefinição é «false».

Opções disponíveis:

• noarchive – defina este valor como «true» para impedir que a mensagem seja guardada no registo do chat. Isto é particularmente útil para elementos que não fazem parte da história, tais como os menus do botão «Mod Script» e as informações sobre o estado.
• use3d – Já é possível gerar lançamentos de dados 3D utilizando a função sendChat(). A sintaxe é simples: sendChat("Nome", "Lançar [[3d6]]", null, {use3d: true}); Se passar um ID de jogador para o parâmetro «nome», como por exemplo sendChat("player|-ABC123",...), a cor do jogador será utilizada para os dados. Caso contrário, será utilizada a cor branca padrão.

Nota: Os clientes do só podem apresentar o resultado de um rolo 3D de cada vez, pelo que não faz sentido criar vários rolos 3D separados seguidos. Tenha também em atenção que a utilização de rotações 3D exerce um pouco mais de pressão sobre o servidor QuantumRoll; por isso, use o seu bom senso e não execute 100 rotações 3D no espaço de um segundo. Utilize lançamentos em 3D quando o lançamento for importante para o jogador e tiver impacto no jogo.

Se pretender ajustar estas opções, mas não quiser utilizar um parâmetro de retorno de chamada (terceiro parâmetro – ver acima), pode simplesmente passar «null» no seu lugar:

enviarChat("Status", "Todos os jogadores estão conectados.", null, {noarchive:true});

Botões de comandos do script de modificação

A formatação do chat de texto, nas mensagens do Mod Script, bem como nas macros e habilidades, pode criar botões de comando no chat.

Para realizar isso utilizando a formatação Markdown:

[Rolagem de Ataque](!attackroll)

O texto entre colchetes será exibido no botão, e a parte entre parênteses é o comando a ser executado. É possível incluir qualquer elemento num comando normal (macros, habilidades, consultas, etc.), mas tenha em consideração que o comando em si será executado pelo jogador que clicar nele. Por exemplo, não inclua @{Character|AC} se todas as pessoas que podem ver a mensagem não tiverem acesso a essa personagem. Em vez disso, inclua o valor real tal como existia quando enviou o comando, preenchendo-o você mesmo antes de enviar a mensagem de chat. Estes botões funcionam em mensagens gerais, mensagens privadas e mensagens privadas enviadas ao GM. O clique é atribuído ao jogador que clica, com o ID desse jogador e o jogador selecionado.

/direct ignora o Markdown, pelo que [Jogo de Ataque](!attackroll) não se transformará num botão.

Introdução de botões de scripts de mod no chat

Também pode escrever sintaxe Markdown nos botões «Mod Script» no chat para que outras pessoas os possam utilizar. Como serão interpretados pelo analisador de chat, se desejar que os atributos, consultas e rolagens sejam expandidos quando o botão for clicado, é necessário inserir partes do comando com uma sintaxe especial (entidades HTML):

Este botão de amostra utiliza alguns deles:

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

Na verdade, pode utilizar os botões de scripts de mod para ativar macros ou habilidades.

Para tal, basta iniciar a parte do comando com o código especial !
 e, em seguida, adicionar a chamada à macro com # ou a chamada à função com % (%):

[Macro](!
#MacroName)

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

Nota: Neste momento, ao reabrir uma macro guardada no separador «Coleções» da barra lateral, as entidades HTML nela contidas são revertidas; se a macro for posteriormente guardada, essas reversões também serão guardadas. Este comportamento não se verifica em Abilidades nem nos botões de comando de habilidades.

No caso dos botões de habilidade, se a habilidade que cria o botão e a habilidade a que este faz referência se encontrarem ambas na mesma folha, a sintaxe é muito simples:

[Habilidade] (~AbilityName)