O Charactermancer é um sistema Roll20 para guiar um utilizador através de um processo de tomada de decisão na Mesa Virtual. Foi implementado noRoll20 Official DND 5eeRoll20 Official Pathfinderfichas de personagem.
Tradução
Assim como o resto das áreas da Ficha de Personagem, os Padrões da Ficha devem ser seguidos no Charactermancer. Isso inclui Chaves de Internacionalização (ou i18n translation keys). Qualquer elemento pode ser designado para traduzir adicionando um elemento à tag html. Leia mais sobre como funciona a tradução aqui.
Slides
Slide de Introdução
<charmancer class="sheet-charmancer-intro">
O Charactermancer funciona carregando uma série de suaves em ordem. Os suaves são blocos de HTML incluídos no arquivo HTML da ficha de personagem. Eles são designados com uma tag<charmancer>. Cada slide precisa ser nomeado para ser chamado ou referenciado, o que é feito de dentro da tag <charmancer> adicionando uma classe com o prefixo "sheet-charmancer-" seguido do nome do slide. Os slides podem conter todos os mesmos elementos HTML e inputs da ficha de personagem, juntamente com algumas adições e exceções notáveis descritas abaixo. Os slides são chamados por um Sheet Worker através da função startCharactermancer(<slide name>) ou por outro slide através do botão "next".
Quadro do Compendium
<div class="sheet-compendium-page sheet-example" accept="CategoryIndex:Backgrounds"></div>
Disponível dentro dos slides está o Quadro do Compendium, que permite exibir páginas do Compendium da ficha de personagem. Se uma tag dentro de um slide receber a classe "sheet-compendium-page" e também receber um parâmetro de aceitação, quando o slide for renderizado, ele também incluirá o Quadro do Compendium incorporado nele. O parâmetro de aceitação deve corresponder a uma página do Compendium do livro usado pela ficha de personagem, caso contrário, os dados não serão exibidos. O Quadro do Compendium pode ser atualizado dinamicamente pelo Sheet Worker usando a função changeCompendiumPage.
Navegação de Slide
Botão Próximo
<button type="submit" value="example">Próximo</button>
O botão Próximo faz a transição do Charactermancer para o próximo slide. O tipo do botão deve ser "submit" e o parâmetro de valor deve corresponder ao nome de outro slide. Além disso, será feita uma verificação para verificar se todos os Inputs do Charactermancer que estão visíveis e são obrigatórios têm um valor. A operação retornará destacando os inputs obrigatórios sem valores e não avançará para o próximo slide.
Botão Voltar
<button type="back" value="example">Voltar</button>
Os Botões Voltar funcionam de forma idêntica aos Botões Próximo, com exceção de exigir "voltar" como tipo e não validar campos obrigatórios.
Botão Cancelar
<button type="cancel" value="example">Cancelar Charactermancer</button>
Os botões Cancelar fecham o Charactermancer, retornando o usuário para a Ficha de Personagem. O tipo de botão deve ser "cancelar". Ele pode passar seu valor através de um evento que é disparado ao clicar no botão, que pode ser ouvido pelo ouvinte em "mancer:cancel".
Botão de Finalização
<button type="finish" value="example">Aplicar Alterações</button>
O botão Finalizar fecha o Charactermancer, retornando para a Ficha de Personagem. O tipo de botão deve ser "finalizar". Ao clicar no botão Finalizar, é criado um evento que pode ser ouvido com o ouvinte em "mancerfinish:name", que contém o Objeto de Dados do Charactermancer como argumento.
Suave Final
O nome "final" é reservado para um slide especial. O Suave Final atua como uma transição entre o Charactermancer e a Ficha de Personagem. O Charactermancer é desativado uma vez que o Slide Final é chamado, mas ainda será visível exibindo o conteúdo do Slide Final até quefinishCharactermancer()seja chamado. Este slide permite que a Ficha de Personagem e os Trabalhadores peguem todos os resultados do Objeto de Dados do Charactermancer e os apliquem antes de devolver o controle ao jogador.
Entradas do Charactermancer
<input type="text" name="comp_example">
Atributos no Charactermancer usam uma convenção de nomenclatura diferente da Ficha de Personagem. As entradas do Charactermancer começam com"comp_". Entradas e Seleções nomeadas com a convenção passarão automaticamente seus valores para o Objeto de Dados do Charactermancer. O Objeto de Dados pode ser referenciado em slides atuais e futuros chamando a funçãogetCharmancerData()e também será gerado para uso na ficha de personagem no eventomancerfinish.
Objeto de Dados do Charactermancer
{
"primeiro-slide":
{
"dados":
{},
"valores":
{}
},
"segundo-slide":
{
"dados":
{
"escolha1":
{
"Número de Widgets":
{
"Widgets": 2
},
"Tipo de Widgets":
{
"Tipo": "Esponjoso"
}
}
},
"valores":
{
"escolha1": "Widget:Exemplo"
},
"repetindo": ["<repeating_id1>", "<repeating_id2>"]
}
}
O Objeto de Dados do Charactermancer armazena automaticamente os dados das entradas e seleções em cada slide durante o processo. Os valores dessas entradas e seleções são salvos em formato JSON sob o nome do slide e a chave "values". Além disso, "data" pode ser passado para o namespace do slide do Objeto de Dados pela função getCompendiumData. Se alguma seção repetitiva for usada no slide, os ids repetitivos são salvos sob a chave "repeating" desse slide. O objeto inteiro pode ser obtido a qualquer momento usando a função getCharmancerData.
Requisitos
<input type="text" name="comp_example" required>
Entradas e seleções marcadas como "requeridas" em suas tags não permitirão que os usuários completem o slide atual e passem para o próximo até que esse campo receba um valor. Os campos obrigatórios que foram deixados em branco quando o botão seguinte foi utilizado receberão a classe"sheet-hilite"e o utilizador não avançará para o diapositivo seguinte. As entradas requeridas não impõem o requisito se estiverem ocultas dentro de uma Seção Condicional. Grupos de elementos podem ser tornados requeridos. Se o Requerido for adicionado à tag de uma div pai, todas as entradas e seleções filhas também se tornam requeridas.
Seleções Populadas do Compendium
<select name="comp_race" accept="Category:Items">
As seleções dentro dos slides podem ser preenchidas automaticamente com opções do Compendium do Roll20. O select precisa do parâmetro Accept, que inclui uma string de pesquisa compatível com o Compendium. Pesquisas complexas de vários atributos podem ser usadas para fornecer resultados filtrados específicos. As opções preenchidas desta forma terão a expansão de origem incluída após o resultado entre parênteses.
Seções Condicionais
<div class="sheet-choice sheet-example">
As Seções Condicionais são tags HTML com a tag "sheet-choice". Essas seções são ocultas por padrão sempre que o slide é renderizado. Elas podem ser mostradas ou ocultadas com as funções showChoices(<class name>) e hideChoices(<class name>)respectivamente.
Botão de Ação
<button type="action" name="act_starting_gold"></button>
Introduzidos na atualização do Charactermancer estão os Botões de Ação. Esses botões podem ser ouvidos com o ouvinte de evento "clicado". Eles não estão limitados ao Charactermancer e também podem ser usados na Ficha de Personagem. O botão deve ser do tipo "ação" e o nome do botão deve ser prefixado comact_para ser ouvido.
Ouvintes do Charactermancer
Esses ouvintes funcionam para alterações do Charactermancer e têm acesso às funções do Charactermancer.
mancerchange
on("mancerchange:choice_1 mancerchange:choice_3", function(eventinfo) {...});
O ouvinte mancerchange é acionado quando os valores dos Inputs do Charactermancer são alterados. Ele passa um argumento contendo as seguintes propriedades:
- currentStep:"charmancer-intro" O slide atual em que o usuário está
- newValue:"Races:Elf" O valor para o qual o Input do Charactermancer foi alterado
- sourceType:"player" Se a mudança foi acionada por um "trabalhador" ou pelo "jogador"
- triggerName:"race" O nome da Entrada do Charactermancer que foi alterada
page:<slide name>
on("page:charmancer-intro", function(eventinfo) {...});
O ouvinte da página é acionado quando o slide é aberto quando chamado por um botão próximo ou pela função startCharmancer. Ele passa um argumento contendo as seguintes propriedades:
- sourceType:"player" Se a mudança foi acionada por um "trabalhador" ou pelo "jogador"
- triggerName:"charactermancer-intro" O nome do Slide do Charactermancer que acabou de ser aberto
clicked:<action button name>
on("clicked:action_button", function(eventinfo) {...});
O ouvinte de clique dispara quando um botão de ação é clicado. Ele passa um argumento contendo as seguintes propriedades:
- triggerName:"clicked:action_button" O nome do botão de ação que foi clicado
mancerroll:<roll button name>
on("mancerroll:roll_stats", function(eventinfo) {...});
Este ouvinte dispara quando um botão de rolagem é clicado no Charactermancer. Ele passa um argumento contendo as seguintes propriedades:
-
currentStep:"charmancer-intro"O slide atual em que o usuário está - roll: Um objeto JSON contendo os resultados da rolagem.
- triggerName:"roll_stats" O nome da rolagem do Charactermancer que disparou o ouvinte
Ouvintes da Ficha
Esses ouvintes serão ativados após o Charactermancer sair e terão acesso ao conjunto normal de trabalhadores de ficha.
mancer:cancel
on("mancer:cancel", function(eventinfo) {...});
O ouvinte mancer:cancel é acionado quando um jogador sai do Charactermancer através do botão Cancelar, isso pode ser usado quando um usuário reinicia o Charactermancer. Ele passa um objeto como argumento com um valor correspondente ao nome do slide em que o usuário saiu do Charactermancer:
- value: "slide1"
mancerfinish:<name>
on("mancerfinish:l1-mancer", function(eventinfo) {...});
O ouvinte mancerfinish é acionado quando um jogador sai do Charactermancer através do botão Concluir. Ele passa um objeto como argumento com o mesmo valor do Objeto de Dados do Charactermancer. Aqui é onde as escolhas do Charactermancer serão aplicadas à própria ficha. A funçãosetCharmancerText()está disponível aqui para lhe permitir atualizar o diapositivo "final" enquanto as alterações estão a ser aplicadas.
Funções
Os trabalhadores de planilha normais estão desativados enquanto o Charactermancer está ativo, com as seguintes exceções:
setAttrs() ainda é utilizável enquanto o Charactermancer está ativo, embora sua função seja diferente, ele só poderá definir valores para a tela atual do Charactermancer Funções que acessam atributos da planilha sem modificá-los (como getAttrs() e getSectionIDs()) funcionarão normalmente. getCompendiumPage() e getCompendiumQuery() funcionam tanto para a planilha quanto para o Charactermancer.
Uma observação sobre os seletores: Muitas dessas funções usam um seletor css para encontrar o elemento html relevante no slide. A primeira parte desse seletor deve ser uma classe, mas o restante desse seletor pode usar qualquer sintaxe válida de seletor JQuery.
Essas funções estão disponíveis apenas quando o Charactermancer está ativo:
startCharactermancer(<slide name>)
startCharactermancer("first-slide");
A função startCharactermancer inicia o Charactermancer. Isso oculta a ficha do personagem e carrega o Charactermancer. Ele carregará o HTML do slide nomeado passado como o primeiro argumento e acionará o ouvinte de abertura da página para esse slide.
setCharmancerText(<update object>);
setCharmancerText({"class_example":"Olá mundo!"});
A função setCharmancerText permite atualizar seções do seu slide atual com um novo texto. Passado como argumento para a função está um objeto onde as chaves são seletores para os elementos a serem atualizados e os valores são o texto que substituirá o conteúdo existente dessas seções. Essa função permite o uso de tags html, todo o texto é passado pela mesma função de sanitização que é usada no restante da ficha do personagem (que, por exemplo, adiciona sheet- aos nomes das classes).
changeCompendiumPage(<IFrame selector>, <Compendium Page Name>)
changeCompendiumPage("sheet-iframe", "Página de Boas-vindas");
A função changeCompendiumPage permite alterar dinamicamente a página do compêndio carregada em um iFrame de Compendium no seu slide atual. O primeiro argumento deve corresponder ao nome da classe do iFrame e o segundo argumento passa a página do Compendium a ser renderizada. É recomendado usar a categoria da página para garantir uma correspondência única. Por exemplo, "Druida" pode corresponder a uma página tanto na categoria "Classes" quanto na categoria "NPC", mas "Classes:Druida" será uma página única.
changeCharmancerPage(<slide name>, <callback>)
changeCharmancerPage("options_slide", function() {...});
Esta função altera o slide atual do Charactermancer. O primeiro argumento é o nome do slide. Ele aceita um callback, que é chamado após o carregamento do slide.
setAttrs(<update object>)
setAttrs({"test_attribute": 2})
A função setAttrs funciona da mesma forma para as entradas do Charactermancer como funciona para os Atributos da Ficha de Personagem, com as seguintes exceções. Enquanto o Charactermancer estiver ativo, ele só pode ser usado para atualizar as entradas do Charactermancer e ele limpará as entradas de rádio e caixa de seleção se o valor ao qual elas estão definidas não corresponderem aos seus valores fornecidos. Esses atributos devem ter uma entrada no slide, ou seus valores serão removidos do objeto de dados do Charactermancer ao passar para a próxima página.
setCharmancerOptions(<Class Name>, <Select Options>, <Settings>, <Callback>); </pre>
setCharmancerOptions("select-class", "Categoria:Itens Tipo:Armas", {add:["Espada Longa Mágica","Machado da Incrível",], category:"Itens"});
A função setCharmancerOptions permite atualizar Seleções do Charactermancer ou Entradas de Rádio com opções dinâmicas conforme necessário. A função requer os dois primeiros argumentos, mas pode aceitar até quatro. O primeiro argumento é o nome da classe do Select do Charactermancer que você deseja preencher com opções. O segundo argumento pode receber uma matriz de opções pré-definidas ou ser passado com uma string de pesquisa do Compendium para gerar uma lista dinâmica de opções do Compendium. O terceiro argumento aceita várias configurações opcionais detalhadas abaixo. O argumento final é uma função de retorno a ser executada após setCharmancerOptions retornar. Esta função de retorno recebe um parâmetro que é uma matriz dos valores que foram encontrados/preenchidos. Quando usado com type='radio' Inputs, a função funciona da mesma forma, mas se ele encontrar todas as spans com esse nome no slide e preenchê-las com<label><input type="checkbox">conteúdo</label>em vez disso.
- categoria: Nome da categoria das opções
- desabilitar: Matriz de opções para desabilitar, que devem corresponder aos valores
- selecionado: Valor da opção selecionada inicialmente
- adicionar: Matriz de opções de adição ou várias para incluir na parte inferior das opções de seleção
- show_source: Exibe opções com iniciais de Expansão do Compendium entre parênteses (disponível apenas ao usar uma consulta de compêndio como opção de seleção)
disableCharmancerOptions(<Class Name>, <Select Options>, <Settings>);
disableCharmancerOptions("select-class", ["um","dois"]);
OdisableCharmancerOptionsfunciona de forma semelhante aosetCharmancerOptions. Ele aceita apenas uma matriz de opções para desabilitar Charactermancer Selects ou Radio Inputs. A função não desabilitará uma opção atualmente selecionada. Se dois ou mais selects tiverem os mesmos valores, ele desabilitará todos eles de uma vez. Passar uma matriz vazia reabilitará tudo.
showChoices([<class name>]);
showChoices(["sheet-test","sheet-test2]);
A função showChoices revela secções condicionais ocultas com a classesheet-choice. Ele aceita um argumento como uma matriz de nomes de classe para revelar Conditional Sections.
hideChoices([<class name>]);
hideChoices(["sheet-test","sheet-test2]);
A função hideChoices oculta as Seções Condicionais atualmente visíveis com a classesheet-choice. Aceita um argumento como uma matriz de nomes de classe para as Seções Condicionais a serem ocultadas. Se nenhum argumento for fornecido, todas as escolhas no slide atual serão ocultadas.
getCompendiumPage(<Compendium Page Name>, [<Values>], <Callback>)
getCompendiumPage(<code> Compendium Name", function(data) {...});
A função getCompendiumPage recupera os atributos de dados de uma Página do Compendium e permite que você passe esses dados tanto para o Objeto de Dados do Charactermancer quanto para uma função de retorno de chamada. O primeiro argumento que a função recebe é o nome da Página do Compendium da qual você deseja recuperar os dados, ou uma matriz de páginas. Novamente, é recomendado usar o formato<category>:<pagename>para garantir o resultado correto. A terceira opção é uma chamada de retorno que passa o objeto de dados como argumento.
Se essa função for chamada no evento de troca de atributosmancerchange:para um atributo, todos os dados serão salvos na seção "data" do objeto JSON do slide atual, sob uma chave correspondente ao nome desse atributo. Para garantir que os dados sejam salvos corretamente, é recomendado garantir quegetCompendiumPageseja o primeiro worker de planilha assíncrona chamado nesse evento. Se várias páginas forem buscadas com essa função, apenas a primeira será salva nos dados. Se uma string vazia for usada para o primeiro argumento, ela limpará os dados atualmente salvos para esse atributo (mas não o valor do atributo).
Esses dados não são salvos no Firebase. Em vez disso, todos os campos de dados são buscados de uma vez no compêndio quando o Charactermancer é aberto pela primeira vez.
getCompendiumQuery(<Compendium Query String>, <Callback>)
getCompendiumQuery("Category:Spells Level:1|2|3 Class:*Bard", function(data) {...});
Esta função funciona de forma semelhante ao getCompendiumPage, exceto que usa uma string de consulta (ou um array de consultas) para buscar resultados e não salvará nenhum dado no objeto Charactermancer.
getCharmancerData()
var data = getCharmancerData();
A função getCharmancerData retorna o valor atual do objeto Charactermancer Data.
deleteCharmancerData([<pages>], <Callback>)
deleteCharmancerData(["slide1","slide3","slide4"], function(data) {...})
A função deleteCharmancerData aceita dois argumentos. O primeiro argumento é um array de nomes de slides para excluir todos os dados e valores do objeto Charactermancer Data associados, limpando o slide como se nunca tivesse sido visitado. Se nenhum slide for passado como argumento, a função removerá todos os dados e escolhas. O segundo argumento é um callback executado após a conclusão da função deleteCharmancerData .
finishCharactermancer() =
finishCharactermancer()
A função especial finishCharactermancer() faz a transição do Slide Final de volta para a Ficha de Personagem.
setSectionOrder(<Repeating Section Name>, <Section Array>, <Callback>);
(Função do trabalhador da ficha regular, não uma função do Charactermancer)
setSectionOrder("proficiencies", final-array, callbackFunction);
A função setSectionOrder permite a ordenação de seções repetidas de acordo com sua preferência. A função aceita uma secção de repetição (repeating_é anexada a este valor), o método de ordenação com base nos dados do item de repetição e uma função de retorno de chamada opcional.
Seções Repetidas do Charactermancer
As seções repetidas no Charactermancer funcionam de forma diferente das seções repetidas nas fichas de personagem. Em vez de ser definido para um elemento específico na página (o <fieldset>), as seções repetidas no Charactermancer são trechos de código HTML que podem ser anexados a qualquer elemento no slide ativo do Charactermancer (incluindo dentro de outra seção repetida). Este HTML é sanitizado da mesma forma que o restante da planilha.
Quando uma seção é adicionada ao slide, um id de linha único é gerado para essa linha. Esse id é aplicado como uma classe ao elemento pai desta seção e é usado para renomear quaisquer inputs, botões de ação ou botões de rolagem dentro dessa seção. A convenção de nomenclatura é: "repeating_123456789_row_input", onde "row" é o nome da seção repetida e "input" é o nome do input. Os valores dos inputs nas seções repetidas são salvos sob a chave "values" no objeto de dados do Charactermancer junto com os demais valores desse slide. O nome da seção repetida (o nome da seção pai, não cada valor dentro), é adicionado ao array "repeating" para cada slide.
Os ouvintesmancerchange,mancerroll,e clicked podem ouvir as alterações a uma secção repetida. Para uma mudança emrepeating_123456789_row_input, uma mudança será acionada para o próprio atributo,mancerchange:repeating_row_input, e a seção em que está contido,mancerchange:repeating_row. Se essa seção estiver dentro de outra seção repetida, um evento será disparado também para a seção repetida pai. As informações do evento para uma mudança na seção repetida conterão alguns novos elementos, além dos mencionados acima.
-
sourceAttribute:"repeating_123456789_row_input"O atributo específico que foi alterado -
sourceSection:"repeating_row"O nome da seção repetida em que o sourceAttribute está -
triggerName:"repeating_row"O nome do ouvinte que foi acionado
Essas seções não são persistentes, o que significa que, quando o usuário sai do slide e o revisita, o slide será carregado sem as seções repetidas e dependerá dos eventos de mudança automáticos para adicionar essas seções de volta à página (consulte a seção abaixo sobre revisitar slides).
Definição de Seção
<charmancer class="sheet-repeating-row">
<charmancer class="sheet-repeating-row">
Para definir uma seção repetida, coloque o trecho de código dentro de uma tag <charmancer> , usando uma classe que comece com as palavras-chave "sheet-repeating-". No exemplo acima, o código dentro das tags <charmancer> será definido como uma seção repetida chamada "row".
addRepeatingSection(<class_name>, <section_name>, <new_name>, <callback>)
addRepeatingSection("sheet-class", "row", "spellrow", function(sectionid) {...});
Esta função anexa a seção repetida especificada ao elemento de destino especificado. O primeiro argumento é o seletor para o elemento de destino, o segundo especifica qual seção repetida adicionar. O terceiro argumento é opcional, ele define um novo nome de seção para esta seção específica, se omitido, o nome da seção usará apenas o segundo parâmetro como seu nome. A função de retorno para esta seção recebe o ID da seção que foi atribuído à seção.
clearRepeatingSections(<target>, <callback>)
clearRepeatingSections("sheet-class", function() {...});
Esta função limpa todas as seções repetidas do elemento especificado pelo primeiro argumento. Ele remove o próprio HTML, juntamente com quaisquer valores correspondentes no objeto de dados do Charactermancer.
clearRepeatingSectionById([<section_ids>], <callback>)
clearRepeatingSectionById([<id1>, <id2>, ...], function() {...});
Esta função é semelhante à função clearRepeatingSections, mas ela só limpa seções repetidas específicas, definidas pelo array no primeiro argumento. Ele também limpará quaisquer seções repetidas dentro das especificadas.
getRepeatingSections(<target>, <callback>)
getRepeatingSections("sheet-class", function(repeating) {...});
Esta função retorna informações mais detalhadas sobre as seções repetidas no slide atual. O primeiro argumento é um seletor para o elemento alvo. Isso é usado para obter uma lista das seções repetidas dentro desse elemento. Se isso for omitido, a função retornará todas as seções repetidas neste slide. Os dados retornados para o retorno de chamada também contém um objeto JSON que mostra a estrutura das seções repetidas, detalhando quais seções estão dentro de outras seções.
Revisitando Slides
Se o usuário sair de um slide e depois revisitá-lo, o Charactermancer irá automaticamente acionar eventos de alteração para os valores salvos na página. Isso é para permitir que os workers da planilha disparem e reconstruam o slide para seu estado anterior. Isso é necessário, porque as alterações feitas pelas funções que manipulam HTML (como setCharmancerText e addRepeatingSection ) não persistem. É importante ter em mente que esses workers podem ser acionados ao revisitar o slide. Planeje os workers de acordo. Note que ao revisitar um slide, os IDs de seções repetidas anteriores são reutilizados para seções com nomes correspondentes, então esses IDs devem permanecer constantes.
Atributo Pseudo charactermancer_step
O atributocharactermancer_stepé um atributo pseudo como character_name. Isso permite definir o passo que o Charactermancer abrirá na próxima vez que for lançado. Este atributo pode ser definido por uma função normalsetAttrse não pode ser definido enquanto o Charactermancer estiver ativo.