API: Chat

Eventos de chat

conversa:mensagem

Ativado sempre que uma nova mensagem de chat é recebida. Observe que, se a mensagem for do tipo «rollresult» ou «gmrollresult», será necessário 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

Após chamar JSON.parse no content de uma mensagem "rollresult" ou "gmrollresult", 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 2d6
             },
             {
               "v":5 //Obtivemos um 5 no nosso segundo 2d6
             }
            ]
          }
        ]
      ],
      "mods":{},
      "resultType":"sum", //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" = 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 se a tabela rolante utilizar í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 modificações explosivas e acertos 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 tipo de rolo personalizado)

on("chat:message", function(msg) {
  //Isto permite que os jogadores insiram !sr <number> para lançar um número de dados d6 com um alvo de 4.
  if(msg.type == "api" && msg.content.indexOf("!sr ") !== -1) {
    var numdice = msg.content.replace("!sr ", "");
    sendChat(msg.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 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"
• A identificação de um jogador, formatada como"player|-Abc123", em que "-Abc123" representa a identificação do jogador. Se proceder desta forma, o avatar e o nome do jogador serão utilizados automaticamente.
• A identificação de um personagem, formatada como"personagem|-Abc123". Se proceder desta forma, o avatar e o nome da personagem serão utilizados automaticamente.

entrada deve ser qualquer expressão válida, semelhante às utilizadas na aplicação Roll20. Você insere texto para enviar uma mensagem básica ou utiliza comandos de barra, como "/roll", "/em", "/w", etc. Além disso:

• É possível utilizar atributos de personagem com o formato@{CharacterName|AttributeName}.
• É possível utilizar as Habilidades de Personagem com o seguinte formato:%{CharacterName|AbilityName}.
• Não é possívelutilizar macros.
• É possível utilizar o comando "/direct <msg>" para enviar uma mensagem sem qualquer processamento (por exemplo, ligação automática de URLs), e pode utilizar as seguintes tags HTML na mensagem:

<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 é 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. UtilizarsendChat()desta forma é assíncrono. Os resultados do comandosendChat()serão uma ARRAY de operações, e cada objeto individual será semelhante a um objeto recebido durante um eventochat:message(consulte 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.

enviarChat("Riley", "/roll 1d20+4", função(ops) {
    // ops será uma ARRAY de resultados de comando.
    var rollresult = ops[0];
    //Agora, execute uma ação com rollresult, tal como 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, geralmenteverdadeiras, pois o padrão é falso.

Opções disponíveis:

• noarchive -- defina como verdadeiro para impedir que a mensagem seja armazenada no registo do chat. Isso é particularmente útil para saídas que não fazem parte da história, como menus de botões Mod (API) e informações de estado.

• use3d-- Agora é possível gerar lançamentos de dados 3D utilizando a função sendChat(). A sintaxe é simples:sendChat("Nome", "Lançando [[3d6]]", null, {use3d: true});Se passar um ID de jogador para o parâmetro nome, comosendChat("player|-ABC123",...), a cor do jogador será utilizada para os dados. Caso contrário, será utilizada a cor branca padrão. 

  Observação:Os clientes dopodem exibir apenas o resultado de um lançamento 3D por vez, portanto, realizar vários lançamentos 3D separados consecutivamente não é recomendável. Observe também que o uso de rolos 3D coloca um pouco mais de pressão no servidor QuantumRoll, portanto, use o seu bom senso e não execute 100 rolos 3D em um segundo. Utilize os dados 3D quando o lançamento for relevante para o jogador e tiver impacto no jogo.

  Caso deseje ajustar essas opções, mas não queira utilizar um parâmetrode retorno de chamada(terceiro parâmetro — consulte acima), basta passarnullem seu lugar:

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

Botões de comando Mod (API)

Agora disponível com a atualização do Holding, é possível aproveitar a nova formatação do chat de texto (tanto nas mensagens geradas pela API quanto nas geradas por macros e habilidades) para criar "botões de comando Mod (API)" 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 todos que podem ver a mensagem não têm acesso a esse caractere. 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 funcionarão em todos os tipos de mensagens, mensagens gerais, sussurros, sussurros do GM, etc.

Observe que, se utilizar /direct para enviar uma mensagem, não faremos qualquer análise Markdown nela, portanto, é necessário incluir as suas próprias tags <e> . Aqui está um exemplo disso:

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

Inserindo botões Mod (API) no chat

Também é possível digitar botões Mod (API) de sintaxe Markdown no chat para que outras pessoas 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}]])

É possível utilizar os botões Mod (API) para acionar macros ou habilidades.

Para tal, basta iniciar a parte do comando com o código especial!
em seguida, adicione 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 à qual ele se refere estiverem na mesma folha, a sintaxe é muito simples:

[Habilidade] (~AbilityName)