El Charactermancer es un sistema de Roll20 para guiar a un usuario a través de un proceso de toma de decisiones en el Tablero Virtual. Se ha implementado en las hojas de personajeRoll20 Official DND 5eyRoll20 Official Pathfinder.
Traducción
Al igual que en el resto de las áreas de la Hoja de Personaje, se deben seguir los estándares de la Hoja de Personaje en el Charactermancer. Esto incluye las claves de traducción para la internacionalización (o i18n). Cualquier elemento se puede designar para traducción agregando un elemento a la etiqueta html. Lee más sobre cómo funciona la traducción aquí.
Máscaras
Máscara de introducción
<charmancer class="sheet-charmancer-intro">
El Charactermancer funciona cargando una serie de máscaras en orden. Las máscaras son bloques de HTML incluidos en el archivo HTML de la hoja de personaje. Están designados con una etiqueta<charmancer>. Cada diapositiva debe tener un nombre para poder ser llamada o referenciada, lo cual se hace desde el interior de la etiqueta <charmancer> agregando una clase precedida por "sheet-charmancer-" seguida del nombre de la diapositiva. Las diapositivas pueden contener todos los mismos elementos HTML e inputs que la hoja de personaje, junto con algunas adiciones y excepciones notables que se describen a continuación. Las diapositivas son llamadas por un trabajador de la hoja mediante la función startCharactermancer(<slide name>) o por otra diapositiva a través del botón "siguiente".
iFrame del Compendio
<div class="sheet-compendium-page sheet-example" accept="CategoryIndex:Backgrounds"></div>
Disponibles dentro de las diapositivas se encuentra el iFrame del Compendio que te permite mostrar páginas del Compendio de la hoja de personaje. Si una etiqueta dentro de una diapositiva recibe la clase "sheet-compendium-page" y también recibe un parámetro accept, cuando se renderice la diapositiva también se incluirá el iFrame del Compendio incrustado en ella. El parámetro accept debe coincidir con una página del Compendio del libro utilizado por la hoja de personaje o no se mostrará la información. El iFrame del Compendio puede ser actualizado dinámicamente por el trabajador de la hoja utilizando la función changeCompendiumPage.
Conducir de diapositivas
Botón siguiente
<button type="submit" value="example">Siguiente</button>
El botón Siguiente transiciona el Charactermancer a la siguiente diapositiva. El tipo de botón debe ser "submit" y el parámetro de valor debe coincidir con el nombre de otra diapositiva. Además, se realizará una comprobación para verificar que todos los campos de entrada del Charactermancer que sean visibles y requeridos tengan un valor. La operación devolverá resaltando los campos requeridos sin valores y no avanzará a la siguiente diapositiva.
Botón atrás
<button type="back" value="example">Atrás</button>
Los botones Atrás funcionan de manera idéntica a los botones Siguiente, con las excepciones de requerir "back" como tipo y no validar campos requeridos.
Botón cancelar
<button type="cancel" value="example">Cancelar Charactermancer</button>
Los botones Cancelar cierran el Charactermancer, devolviendo al usuario a la Hoja de Personaje. El tipo de botón debe ser "cancelar". Puede pasar su valor a través de un evento que se activa al hacer clic en el botón, el cual puede ser escuchado por el oyente on "mancer:cancel".
Botón Finalizar
<button type="finish" value="example">Aplicar cambios</button>
El botón Finalizar cierra el Charactermancer, volviendo a la Hoja de Personaje. El tipo de botón debe ser "finalizar". Al hacer clic en el botón Finalizar se crea un evento que puede ser escuchado con el oyente on "mancerfinish:name", el cual contiene el Objeto de Datos del Charactermancer como argumento.
Máscara Final
El nombre "final" está reservado para una máscara especial. La Máscara Final actúa como una transición entre el Charactermancer y la Hoja de Personaje. El Charactermancer se desactiva una vez que se llama a la Diapositiva Final pero seguirá visible mostrando el contenido de la Diapositiva Final hasta que se llame afinishCharactermancer(). Esta diapositiva permite que la Hoja de Personaje y los Trabajadores tomen todos los resultados del Objeto de Datos del Charactermancer y los apliquen antes de devolver el control al jugador.
Entradas del Charactermancer
0
Los Atributos en el Charactermancer utilizan una convención de nomenclatura diferente que la Hoja de Personaje. Charactermancer Las entradas comienzan por"comp_". Las Entradas y Selects nombrados con la convención pasarán automáticamente sus valores al Objeto de Datos del Charactermancer. Se puede hacer referencia al objeto de datos en las diapositivas actuales y futuras llamando a la funcióngetCharmancerData()y también se mostrará para su uso en la hoja de personaje en el eventomancerfinish.
Objeto de Datos del Charactermancer
{
"primera-diapositiva":
{
"datos":
{},
"valores":
{}
},
"segunda-diapositiva":
{
"datos":
{
"eleccion1":
{
"Número de Widgets":
{
"Widgets": 2
},
"Tipo de Widgets":
{
"Tipo": "Esponjoso"
}
}
},
"valores":
{
"eleccion1": "Widget:Ejemplo"
},
"repetición": ["<repeating_id1>", "<repeating_id2>"]
}
}
El Objeto de Datos del Charactermancer almacena automáticamente los datos de las entradas y selecciones en cada diapositiva a lo largo del proceso. Los valores de esos inputs y selects se guardan en formato JSON bajo el nombre de la diapositiva y la clave "values". Además, se puede pasar "data" al espacio de nombres de la diapositiva del objeto de datos desde la función getCompendiumData. Si se utilizan secciones repetitivas en la diapositiva, los ids repetitivos se guardan bajo la clave "repeating" de esa diapositiva. El objeto completo se puede obtener en cualquier momento utilizando la función getCharmancerData.
Requisito
<input type="text" name="comp_example" required>
Los inputs y selects marcados como "required" en su etiqueta no permitirán a los usuarios completar la diapositiva actual y pasar a la siguiente hasta que se les dé un valor a ese campo. Los campos obligatorios que se hayan dejado en blanco al utilizar el botón siguiente recibirán la clase"hoja-hilito"y el usuario no avanzará a la siguiente diapositiva. Los inputs requeridos no cumplen con el requisito si se han ocultado dentro de una sección condicional. Se pueden hacer grupos de elementos requeridos. Si se agrega el atributo Required a la etiqueta de un div padre, todos los inputs y selects hijos también se vuelven requeridos.
Selects poblados del Compendio
<select name="comp_race" accept="Category:Items">
Las selecciones dentro de las diapositivas pueden ser auto-populadas con opciones del Compendio de Roll20. El select necesita el parámetro Accept, que incluye una cadena de búsqueda compatible con el Compendio. Se pueden utilizar búsquedas complejas de múltiples atributos para proporcionar resultados filtrados específicos. Las opciones pobladas de esta manera tendrán la expansión de origen incluida después del resultado entre paréntesis.
Secciones Condicionales
<div class="sheet-choice sheet-example">
Las Secciones Condicionales son etiquetas HTML con la etiqueta "sheet-choice". Estas secciones están ocultas de forma predeterminada cuando se renderiza la diapositiva. Se pueden mostrar u ocultar con las funciones showChoices(<class name>) y hideChoices(<class name>) respectivamente.
Botón de Acción
<button type="action" name="act_starting_gold"></button>
Introducidos en la actualización de Charactermancer son los botones de acción. Estos botones pueden ser escuchados con el evento "clicked". No están limitados al Charactermancer y también se pueden usar en la Hoja de Personaje. El botón debe ser de tipo "acción" y el nombre del botón debe tener el prefijoact_para que se escuche.
Oyentes de Charactermancer
Estos oyentes funcionan para los cambios de Charactermancer y tienen acceso a las funciones de Charactermancer.
mancerchange
on("mancerchange:choice_1 mancerchange:choice_3", function(eventinfo) {...});
El oyente mancerchange se activa cuando se cambian los valores de los inputs de Charactermancer. Pasa un argumento que contiene las siguientes propiedades:
- currentStep:"charmancer-intro" La diapositiva actual en la que se encuentra el usuario
- newValue:"Races:Elf" El valor al que se cambió el input de Charactermancer
- sourceType:"player" Si el cambio fue desencadenado por un "trabajador" o el "jugador"
- triggerName:"race" El nombre de la entrada Charactermancer que se cambió
page:<slide name>
on("page:charmancer-intro", function(eventinfo) {...});
El listener de página se activa al abrir la diapositiva cuando se llama desde un botón siguiente o la función startCharmancer. Pasa un argumento que contiene las siguientes propiedades:
- sourceType:"player" Si el cambio fue desencadenado por un "trabajador" o el "jugador"
- triggerName:"charactermancer-intro" El nombre de la diapositiva Charactermancer que acaba de abrirse
clicked:<action button name>
on("clicked:action_button", function(eventinfo) {...});
El listener de clic se activa cuando se hace clic en un botón de acción. Pasa un argumento que contiene las siguientes propiedades:
- triggerName:"clicked:action_button" El nombre del botón de acción que se hizo clic
mancerroll:<roll button name>
on("mancerroll:roll_stats", function(eventinfo) {...});
Este listener se activa cuando se hace clic en un botón de lanzamiento en el Charactermancer. Pasa un argumento que contiene las siguientes propiedades:
-
currentStep:"charmancer-intro"La diapositiva actual en la que se encuentra el usuario - roll: Un objeto JSON que contiene los resultados del lanzamiento.
- triggerName:"roll_stats" El nombre del lanzamiento de Charactermancer que activó el listener
Escuchas de la hoja de personaje
Estos listeners se activarán después de que el Charactermancer salga, y tendrán acceso al conjunto normal de trabajadores de hojas.
mancer:cancel
on("mancer:cancel", function(eventinfo) {...});
El listener mancer:cancel se activa cuando un jugador sale del Charactermancer a través del botón Cancelar, esto se puede usar cuando un usuario reinicia el Charactermancer. Pasa un objeto como argumento con un valor del nombre de la diapositiva en la que el usuario salió del Charactermancer:
- valor: "slide1"
mancerfinish:<name>
on("mancerfinish:l1-mancer", function(eventinfo) {...});
El listener mancerfinish se activa cuando un jugador sale del Charactermancer a través del botón Finalizar. Pasa un objeto como argumento con el mismo valor que el Objeto de Datos del Charactermancer. Aquí es donde se aplicarán las elecciones del Charactermancer a la propia hoja. La función setCharmancerText() está disponible aquí para permitirte actualizar la diapositiva "final" mientras se aplican los cambios.
Funciones
Los trabajadores normales de hojas están desactivados mientras el Charactermancer está activo, con las siguientes excepciones:
setAttrs() todavía es utilizable mientras el Charactermancer está activo, aunque su función es diferente, solo podrá establecer valores para la diapositiva actual de Charactermancer. Las funciones que acceden a los atributos de la hoja sin modificarlos (como getAttrs() y getSectionIDs()) funcionarán normalmente. getCompendiumPage() y getCompendiumQuery() funcionan tanto para la hoja como para el Charactermancer.
Una nota sobre los selectores: Muchas de estas funciones utilizan un selector CSS para encontrar el elemento HTML relevante en la diapositiva. La primera parte de este selector debe ser una clase, pero el resto de este selector puede utilizar cualquier sintaxis válida de selector JQuery.
Estas funciones solo están disponibles cuando el Charactermancer está activo:
startCharactermancer(<slide name>)
startCharactermancer("first-slide");
La función startCharactermancer inicia el Charactermancer. Esto oculta la hoja de personaje y carga el Charactermancer. Cargará el HTML de la diapositiva nombrada que se pasa como primer argumento y activará el escucha de apertura de página para esa diapositiva.
setCharmancerText(<update object>);
setCharmancerText({"class_example":"¡Hola mundo!"});
La función setCharmancerText permite actualizar secciones de la diapositiva actual con nuevo texto. Como argumento de la función se pasa un objeto donde las claves son selectores para los elementos que se actualizarán y los valores serán el texto para reemplazar el contenido existente de esas secciones. Esta función permite el uso de etiquetas HTML, todo el texto se pasa a través de la misma función de saneamiento que se utiliza en el resto de la hoja de personaje (que, por ejemplo, agrega sheet- a los nombres de clase).
changeCompendiumPage(<IFrame selector>, <Compendium Page Name>)
changeCompendiumPage("sheet-iframe", "Página de Bienvenida");
La función changeCompendiumPage te permite cambiar dinámicamente la página del compendio cargada en un iFrame de Compendium en tu diapositiva actual. El primer argumento debe coincidir con el nombre de la clase del iFrame y el segundo argumento pasa la página del Compendium que se va a renderizar. Se recomienda usar la categoría de la página para asegurar una coincidencia única. Por ejemplo, "Druida" puede coincidir con una página en la categoría "Clases" y en la categoría "NPC", pero "Clases:Druida" será una página única.
changeCharmancerPage(<slide name>, <callback>)
changeCharmancerPage("options_slide", function() {...});
Esta función cambia la diapositiva actual del Charactermancer. El primer argumento es el nombre de la diapositiva. Acepta un callback, que se llama después de que se cargue la diapositiva.
setAttrs(<update object>)
setAttrs({"test_attribute": 2})
La función setAttrs funciona de la misma manera para las entradas de Charactermancer como lo hace para las Atributos de la Hoja de Personaje con las siguientes excepciones. Mientras el Charactermancer está activo, solo se puede usar para actualizar las entradas de Charactermancer y eliminará las entradas de radio y casillas de verificación si el valor al que están establecidas no coincide con su(s) valor(es) dado(s). Estos atributos deben tener una entrada en la diapositiva, de lo contrario sus valores se eliminarán del objeto de datos de Charactermancer al pasar a la siguiente página.
setCharmancerOptions(<Class Name>, <Select Options>, <Settings>, <Callback>); </pre>
setCharmancerOptions("select-class", "Categoría: Tipo de Ítems: Armas", {add:["Espada Larga Mágica","Hacha de Asombrosidad"], category:"Ítems"});
La función setCharmancerOptions te permite actualizar las selecciones o entradas de radio de Charactermancer con opciones dinámicas según sea necesario. La función requiere los dos primeros argumentos pero puede aceptar hasta cuatro. El primer argumento es el nombre de la clase de la selección de Charactermancer que deseas poblar con opciones. El segundo argumento puede recibir una matriz de opciones predefinidas o puede recibir una cadena de búsqueda del Compendio para generar una lista dinámica de opciones desde el Compendio. El tercer argumento acepta varias opciones opcionales diferentes detalladas a continuación. El argumento final es un callback que se ejecutará después de que setCharmancerOptions devuelva. Este callback recibe un parámetro que es una matriz de los valores que se encontraron/llenaron. Cuando se utiliza con type='radio' Inputs la función funciona de la misma manera, pero si encuentra todas las spans con ese nombre en la diapositiva y las llena con contenido<label><input type="checkbox"></label>en su lugar.
- categoría: Nombre de la categoría de opciones
- disable: Matriz de opciones para desactivar, que deben coincidir con los valores
- selected: Valor de la opción seleccionada inicialmente
- add: Matriz de opciones adicionales o diversas para incluir en la parte inferior de las opciones de selección
- show_source: Muestra opciones con iniciales de Expansión de Compendio entre paréntesis (solo disponible al usar una consulta de compendio como opción de selección)
disableCharmancerOptions(<Class Name>, <Select Options>, <Settings>);
disableCharmancerOptions("select-class", ["uno","dos"]);
EldisableCharmancerOptionsfunciona de forma similar asetCharmancerOptions. Solo acepta una matriz de opciones para deshabilitar Charactermancer Selects o Radio Inputs. La función no deshabilitará una opción seleccionada actualmente. Si dos o más selects tienen los mismos valores, los deshabilita todos a la vez. Pasando una matriz vacía volverá a habilitar todo.
showChoices([<class name>]);
showChoices(["sheet-test","sheet-test2]);
La función mostrarOpciones revela las Secciones Condicionales ocultas con la clasehoja-opción. Acepta un argumento como una matriz de nombres de clase para revelar secciones condicionales.
hideChoices([<class name>]);
ocultarOpciones(["hoja-prueba","hoja-prueba2]);
La función ocultarOpciones oculta las Secciones Condicionales actualmente visibles con la clase hoja-opción . Acepta un argumento como un array de nombres de clase para ocultar las Secciones Condicionales. Si no se proporciona ningún argumento, ocultará todas las opciones en la diapositiva actual.
obtenerPaginaCompendio(<Compendium Page Name>, [<Values>], <Callback>)
obtenerPaginaCompendio(<code> Nombre del Compendio", function(data) {...});
La función obtenerPaginaCompendio extrae los atributos de datos de una Página de Compendio y te permite pasar esos datos tanto al Objeto de Datos Charactermancer como a una función de devolución de llamada. El primer argumento que toma la función es el nombre de la Página de Compendio de la que deseas extraer los datos, o un array de páginas. Nuevamente, se recomienda utilizar el formato <category>:<pagename> para asegurar el resultado correcto. La tercera opción es una devolución de llamada que pasa el objeto de datos como argumento.
Si esta función se llama en el evento de cambio demancerchange:para un atributo, todos los datos se guardarán en la sección "data" del objeto JSON de la diapositiva actual, bajo una clave que coincida con el nombre de ese atributo. Para asegurarse de que los datos se guarden correctamente, se recomienda asegurarse de quegetCompendiumPagesea el primer trabajador de hoja asíncrono llamado en ese evento. Si se recuperan varias páginas con esta función, solo se guardará la primera. Si se utiliza una cadena vacía como primer argumento, se borrarán los datos guardados actualmente para ese atributo (pero no el valor del atributo).
Estos datos no se guardan en Firebase. En cambio, todos los campos de datos se recuperan de una vez desde el compendio cuando se abre el Charactermancer por primera vez.
getCompendiumQuery(<Compendium Query String>, <Callback>)
getCompendiumQuery("Categoría: Hechizos Nivel: 1|2|3 Clase:*Bardo", function(data) {...});
Esta función funciona de manera similar a getCompendiumPage, excepto que utiliza una cadena de consulta (o una matriz de consultas) para obtener resultados y no guardará ningún dato en el objeto Charactermancer.
getCharmancerData()
var data = getCharmancerData();
El getCharmancerData devuelve el valor actual del objeto Charactermancer Data.
deleteCharmancerData([<pages>], <Callback>)
deleteCharmancerData(["slide1","slide3","slide4"], function(data) {...})
La función deleteCharmancerData acepta dos argumentos. El primer argumento es una matriz de nombres de diapositivas para eliminar todos los datos y valores del objeto Charactermancer Data asociados, eliminando la diapositiva como si nunca se hubiera visitado. Si no se pasan diapositivas como argumento, la función eliminará todos los datos y opciones. El segundo argumento es una devolución de llamada realizada después de que se complete la función deleteCharmancerData.
finishCharactermancer() =
finishCharactermancer()
La función finishCharactermancer() en casos especiales transiciona la diapositiva final de nuevo a la Hoja de Personaje.
setSectionOrder(<Repeating Section Name>, <Section Array>, <Callback>);
(Función regular del trabajador de la hoja, no una función del Charactermancer)
setSectionOrder("proficiencies", final-array, callbackFunction);
La función setSectionOrder permite ordenar las secciones repetitivas según tu preferencia. La función acepta una sección de repetición (repeating_se antepone a este valor), el método en el que ordenar basándose en los datos del elemento de repetición y una función de devolución de llamada opcional.
Secciones Repetitivas del Charactermancer
Las secciones repetitivas en la función Charactermancer funcionan de manera diferente a las secciones repetitivas en las hojas de personaje. En lugar de estar definidas para un elemento específico en la página (el <fieldset>), las secciones repetitivas en el Charactermancer son fragmentos de código HTML que se pueden agregar a cualquier elemento en la diapositiva activa del Charactermancer (incluido dentro de otra sección repetitiva). Este HTML se sanitiza de la misma manera que el resto de la hoja.
Cuando se agrega una sección a la diapositiva, se genera un id de fila único para esa fila. Este id se aplica como una clase al elemento padre de esta sección y se utiliza para cambiar el nombre de cualquier entrada, botón de acción o botón de lanzamiento dentro de esa sección. La convención de nomenclatura es: "repeating_123456789_row_input", donde "row" es el nombre de la sección repetitiva y "input" es el nombre de la entrada. Los valores de las entradas en las secciones repetitivas se guardan bajo la clave "values" en el objeto de datos del Charactermancer junto con los demás valores de esa diapositiva. El nombre de la sección repetitiva (el nombre de la sección padre, no cada valor interno) se agrega a la matriz "repeating" para cada diapositiva.
Elmancerchange,mancerroll,y los listeners de clic pueden escuchar los cambios en una sección repetitiva. Para un cambio enrepeating_123456789_row_input, se desencadenará un cambio para el atributo en sí mismo,mancerchange:repeating_row_input, y la sección en la que se encuentra,mancerchange:repeating_row. Si esa sección está dentro de otra sección repetitiva, también se disparará un evento para la sección repetitiva principal. La información del evento para un cambio en la sección repetitiva contendrá un par de elementos nuevos, además de los normales mencionados anteriormente:
-
sourceAttribute:"repeating_123456789_row_input"El atributo específico que se cambió -
sourceSection:"repeating_row"El nombre de la sección repetitiva en la que se encuentra el sourceAttribute -
triggerName:"repeating_row"El nombre del listener que se activó
Estas secciones no son persistentes, lo que significa que cuando el usuario abandona la diapositiva y vuelve a visitarla, la diapositiva se cargará sin las secciones repetitivas y dependerá de los eventos de cambio automáticos para agregar estas secciones nuevamente a la página (consulte la sección a continuación sobre cómo volver a visitar diapositivas).
Definición de sección
<charmancer class="sheet-repeating-row">
<charmancer class="sheet-repeating-row">
Para definir una sección repetitiva, coloca el fragmento de código dentro de una etiqueta <charmancer> , usando una clase que comience con las palabras clave "sheet-repeating-". En el ejemplo anterior, el código dentro de las etiquetas <charmancer> se definirá como una sección repetitiva llamada "fila".
addRepeatingSection(<class_name>, <section_name>, <new_name>, <callback>)
addRepeatingSection("sheet-class", "row", "spellrow", function(sectionid) {...});
Esta función agrega la sección repetitiva especificada al elemento de destino especificado. El primer argumento es el selector para el elemento de destino, el segundo especifica qué sección repetitiva agregar. El tercer argumento es opcional, define un nuevo nombre de sección para esta sección específica, si se omite, el nombre de la sección usará el segundo parámetro como su nombre. La devolución de llamada para esta sección recibe el id de sección que se asignó a la sección.
clearRepeatingSections(<target>, <callback>)
clearRepeatingSections("sheet-class", function() {...});
Esta función borra todas las secciones repetidas del elemento especificado por el primer argumento. Elimina el propio HTML, junto con cualquier valor correspondiente en el objeto de datos de Charactermancer.
clearRepeatingSectionById([<section_ids>], <callback>)
clearRepeatingSectionById([<id1>, <id2>, ...], function() {...});
Esta función es similar a la función clearRepeatingSections, pero solo borra secciones repetidas específicas, definidas por el array en el primer argumento. También borrará cualquier sección repetida dentro de las especificadas.
getRepeatingSections(<target>, <callback>)
getRepeatingSections("sheet-class", function(repeating) {...});
Esta función devuelve información más detallada sobre las secciones repetidas en la diapositiva actual. El primer argumento es un selector para el elemento objetivo. Esto se utiliza para obtener una lista de las secciones repetidas dentro de ese elemento. Si se omite, la función devuelve todas las secciones repetidas en esta diapositiva. Los datos devueltos a la devolución de llamada también contienen un objeto JSON que muestra la estructura de las secciones repetidas, detallando qué secciones están dentro de otras secciones.
Revisando Diapositivas
Si el usuario abandona una diapositiva y luego la vuelve a visitar más tarde, el Charactermancer activará automáticamente eventos de cambio para los valores guardados en la página. Esto es para permitir que los trabajadores de la hoja disparen y reconstruyan la diapositiva a su estado anterior. Esto es necesario porque los cambios realizados por las funciones que manipulan HTML (como setCharmancerText y addRepeatingSection ) no persisten. Es importante tener en cuenta que estos trabajadores pueden estar disparando al volver a visitar la diapositiva. Planifica los trabajadores en consecuencia. Ten en cuenta que al volver a visitar una diapositiva, se reutilizan los ID de secciones anteriores repetidas para secciones con nombres coincidentes, por lo que estos ID deben permanecer constantes.
Atributo Pseudo charactermancer_step
El atributocharactermancer_stepes un atributo pseudo como character_name. Esto te permite establecer el paso al que se abrirá el Charactermancer la próxima vez que se lance. Este atributo se puede establecer mediante una función normalsetAttrsy no se puede establecer mientras el Charactermancer está activo.