API: Chat

Eventos de Chat

chat:message

Acionado sempre que uma nova mensagem de chat é recebida. Observe que se a mensagem for do tipo "rollresult" ou "gmrollresult", você precisará chamarJSON.parse() no conteúdo da mensagem para obter um objeto que contenha informações sobre os resultados do lançamento.

Parâmetro de retorno de chamada:

Estrutura do Resultado do Lançamento Ex. 1

Depois de chamarJSON.parsena propriedadecontentde uma mensagem "rollresult" ou "gmrollresult", obterá um objeto com o seguinte formato (este é o resultado do comando/roll {2d6}+5+1t[weather] Attack!)

{
  "type":"V", //"V" = "Validated Roll" (isso sempre será "V" agora)
  "rolls": [
    {
      "type":"G", //"G" indica um grupo de rolagem. Um grupo é como uma série de "sub-rolos" dentro de uma rolagem.
      "rolls": [
        [
          {
            "type":"R", //"R" = "Roll"
            "dice":2, // Número de dados rolados (2dX significa 2 dados)
            "sides":6, //Número de lados dos dados (Xd6 significa 6 lados)
            "mods":{},
            "results": [ //Um array com os resultados de cada rolagem.
             {
               "v":1 // Nós rolamos um 1 para nossos primeiros 2d6
             },
             {
               "v":5 // Nós rolamos um 5 para nossos segundos 2d6
             }
            ]
          }
        ]
      ],
      "mods":{},
      "resultType":"soma", //O resultado é uma soma (em oposição a uma verificação de sucesso)
      "results": [
        {
          "v":6 // Neste caso, o resultado geral (total) do grupo.
        }
      ]
    },
    {
      "type":"M", //"M" = Expressão Matemática
      "expr":"+5+"
    },
    {
      "type":"R", //"R" = Rolagem
      "dice":1,
      "table":"clima", //A propriedade da tabela é definida com o nome da tabela usada se essa rolagem foi feita contra uma tabela
      "mods":{},
      "sides":2, //Você provavelmente pode ignorar isso para rolagens de tabela.
      "results": [
        {
          "v":0, //O "valor" do item da tabela rolada. Para tabelas de texto, isso é sempre 0.
          "tableidx":1, //O índice do item na tabela que foi rolado.
          "tableItem": { //Uma cópia do objeto do item da tabela como ele existia quando a tabela foi rolada.
            "name":"chuvoso", 
            "avatar":"", //Isso será uma URL para uma imagem se a tabela rolável usar ícones de imagem
            "weight":1,
            "id":"-IpzPx2j_9piP09ceyOv"
          }
        }
      ]
    },
    {
      "type":"C", // "C" = Comentário
      "text":" Ataque!"
    }
  ],
  "resultType":"soma", //O tipo de resultado geral de todo o rolamento
  "total":11 // O total geral de todo o rolamento (incluindo todos os subgrupos)
}

Estrutura do Resultado do Rolamento Ex. 2

Uma estrutura anotada para o resultado do /rolar {1d6!!>5}>6 (mostrando modificações explosivas e sucessos alvo):

{
  "type": "V",
  "rolls": [
    {
      "type": "G",
      "rolls": [
        [
          {
            "type": "R",
            "dice":1,
            "sides":6,
            "mods": { //Modificações ao lançamento
              "compounding": { //"compounding" = "Composto a explodir (!!)"
                "comp":">=", //Tipo de comparação
                "point":5 //Ponto de comparação
              }
            },
            "results": [
              {
                "v":13 //O resultado geral do dado. Note que, como se trata de uma explosão composta, só há 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 Bate-Papo (Implementando um Tipo de Rolagem Personalizado)

on("chat:message", function(msg) {
  //Isso permite que os jogadores digitem !sr <number> para rolar um número de dados d6 com um alvo de 4.
  se (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]] )

Você pode usar essa função para enviar uma mensagem de chat.

speakingAspode ser um dos:

• Qualquer string, nesse caso será usado como o nome da pessoa que enviou a mensagem. Por exemplo, "Riley"
• O ID de um jogador, formatado como"player|-Abc123"onde "-Abc123" é o ID do jogador. Se você fizer isso, ele usará automaticamente o avatar e o nome do jogador.
• O ID de um personagem, formatado como"personagem|-Abc123". Se você fizer isso, ele usará automaticamente o avatar e o nome do Personagem.

entradadeve ser qualquer expressão válida, assim como as usadas no aplicativo Roll20. Você insere texto para enviar uma mensagem básica ou usa comandos de barra, como "/roll", "/em", "/w", etc. Além disso:

• Você pode usar Atributos de Personagem com o formato@{CharacterName|AttributeName}.
• Você pode usar Habilidades de Personagem com o formato:%{CharacterName|AbilityName}.
• Vocênãopode usar macros.
• Você pode usar o comando "/direct <msg>" para enviar uma mensagem sem nenhum processamento (por exemplo, autolink de URLs), e você pode usar as seguintes tags HTML na mensagem:

<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é um terceiro parâmetro opcional que consiste numa função de retorno de chamada que receberá os resultados da chamadasendChat()em vez de enviar os comandos para o jogo. UsarsendChat()desta forma é assíncrono. Os resultados do comandosendChat()serão uma ARRAY de operações, e cada objeto individual será exatamente como um objeto que recebe durante um eventochat:message(ver acima).

Você pode usar isso, por exemplo, para realizar um lançamento usando o mecanismo de lançamento do Roll20 e, em seguida, obter imediatamente os resultados do lançamento. Você poderia então fazer modificações adicionais no lançamento antes de enviá-lo para os jogadores no jogo.

sendChat("Riley", "/roll 1d20+4", function(ops) {
    // ops será um ARRAY de resultados de comandos.
    var rollresult = ops[0];
    //Agora faça algo com rollresult, assim como você faria durante um evento chat:message...
});

opções é um quarto parâmetro opcional para definir opções sobre como a mensagem é tratada. As opções são especificadas como um objeto JavaScript cujas propriedades são os nomes das opções a serem definidas e cujos valores são as configurações para elas, geralmente verdadeiro pois elas têm o valor padrão falso.

Opções disponíveis:

• noarchive -- defina isso como verdadeiro para impedir que a mensagem seja armazenada no registo de chat. Isto é particularmente útil para a saída que não faz parte da história, como Menus de Botões Mod (API) e informações de estado.

• use3d - Agora você pode gerar rolagens de dados em 3D usando a função sendChat(). A sintaxe é simplesmente: sendChat("Nome", "Rolando [[3d6]]", null, {use3d: true}); Se você passar um ID de jogador para o parâmetro de nome, como sendChat("jogador|-ABC123",...) a cor do jogador será usada para os dados. Caso contrário, será usada uma cor branca padrão. 

  Nota: Os clientes só podem mostrar o resultado de um único lançamento 3D de cada vez, portanto, fazer vários lançamentos 3D separados seguidos não é útil. Também observe que o uso de lançamentos 3D coloca um pouco mais de pressão no servidor QuantumRoll, portanto, use seu julgamento e não faça 100 lançamentos 3D em um segundo. Use lançamentos 3D quando o lançamento "importar" para o jogador e tiver um impacto no jogo.

  Se quiser ajustar estas opções mas não quiser utilizar um parâmetrocallback(terceiro parâmetro - ver acima), pode simplesmente passarnullno seu lugar:

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

Botões de Comando Mod (API)

Agora disponível com a Atualização de Holding, você pode aproveitar a nova formatação de chat de texto (tanto em suas mensagens geradas por API quanto naquelas geradas por macros e habilidades) para criar "botões de comando Mod (API)" no chat.

Para fazer isso usando a formatação Markdown:

[Ataque](!attackroll)

O texto entre os colchetes aparecerá no botão, e a parte entre parênteses é o comando a ser executado. Você pode incluir qualquer coisa em um rolagem normal (macros, habilidades, consultas, etc.), mas lembre-se de que o próprio comando será executado pelo jogador que clicar nele. Por exemplo, não inclua @{Character|AC} se todos que puderem ver a mensagem não tiverem acesso a esse personagem. Em vez disso, inclua o valor real conforme existia quando você enviou o comando, preenchendo-o antes de enviar a mensagem de chat. Esses botões funcionarão em todos os tipos de mensagens, mensagens gerais, sussurros, gmwhispers, etc.

Observe que se você usar /direct para enviar uma mensagem, não faremos nenhuma análise de Markdown nela, então você precisa incluir suas próprias tags <a> . Aqui está um exemplo disso:

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

Introduzindo Botões Mod (API) no Chat

Você também pode digitar a sintaxe Markdown de botões Mod (API) no chat para que outros utilizem. Porque eles serão interpretados pelo analisador de chat, se você quiser que os atributos, consultas e rolagens sejam expandidos quando o botão for clicado, você deve inserir partes do comando com uma sintaxe especial (HTML Entities):

Este botão de exemplo usa alguns deles:

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

Na verdade, você pode usar os Botões Mod (API) para chamar Macros ou Habilidades.

Para fazer isso, basta começar a parte do comando com o código especial !
 e adicionar a chamada de macro com # ou a chamada de habilidade com % (%):

[Macro](!
#MacroName)

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

Para  Botões de Comando de Habilidade, se a Habilidade que cria o botão e a Habilidade que ela referencia estão na mesma ficha, a sintaxe é muito simples:

[Habilidade](~NomeHabilidade)