Dadas las diferencias entre la infraestructura de hojas heredada & y la infraestructura de hojas Beacon, no todos los scripts Mod existentes son compatibles de forma inmediata. Afortunadamente, hemos recopilado la siguiente documentación para ayudarle a actualizar sus scripts para que puedan funcionar con las hojas Beacon (por ejemplo, D&D 2024). También hemos actualizado los scripts principales para que haya ejemplos disponibles y scripts listos para usar con sus juegos. Scripts que se han actualizado:
- Iniciativa de grupo
- TokenMod
- GroupCheck
- Información de estado
Para muchos scripts, actualizarlos para que sean compatibles con la hoja 2024 se reduce a cambiar dos cosas: cómo se obtienen y se configuran los atributos y cómo se analizan las plantillas de tiradas/mensajes de chat. Este documento le guiará a través de ambos, además de resolver algunos problemas comunes para que pueda actualizar cualquier script y que sea compatible tanto con la hoja D&D2014 como con la hoja D&D2024.
Cuando su script se actualice de esta forma, en juegos con hojas Beacon como D&D2024, los GM tendrán que utilizar el servidor API experimental para poder usar todas las últimas funciones. El servidor experimental tiene las mismas funciones que el servidor predeterminado, por lo que este cambio no debería afectar a ningún otro script, pero quizá sea conveniente indicarlo en la descripción del script para que sus usuarios lo sepan. Si no hay una hoja Beacon, el servidor predeterminado seguirá funcionando con estas funciones, ya que recurrirá a las funciones heredadas de obtención y configuración de atributos.
Actualización de la configuración/Obtención
El principal cambio entre el acceso a los datos de la hoja de 2014 y la hoja de 2024, en lo que respecta al código, es la forma de obtener y establecer los atributos. Ahora hay un nuevo conjunto de funciones asíncronas llamadas getSheetItem y setSheetItem. Aquí tiene un ejemplo del uso de las nuevas funciones:
const getDeathSaveSuccess = async (id) => {
const firstSuccess = await getSheetItem(characterId, "deathsave_succ1");
log(`First success is ${firstSuccess}`)
}
Si desea obtener el valor máximo de un atributo (si existe un máximo), puede pasar la propiedad max, como getSheetItem(characterId, "deathsave_succ1",
«max»);.
Observará en el código anterior que getDeathSaveSuccess está marcado como async. Todas las funciones que utilicen getSheetItem tendrán que usar este patrón async/await o promesas. Aquí tiene la misma función anterior, reescrita como una promesa:
const getDeathSaveSuccess = (id) => {
getSheetItem(characterId, "deathsave_succ1").then((firstSuccess) => {
log(`First success is ${firstSuccess}`);
});
}
Si está intentando obtener varios valores a la vez o uno tras otro y el resto de su código depende de esos datos, puede esperar cada valor individualmente o utilizar Promise.all para resolver todas las promesas a la vez y obtener el valor final. Si no lo hace, el valor que obtendrá será solo una promesa pendiente, no el valor real del atributo.
const getSuccesses = (id) => {
const promises = [];
promises.push(getSheetItem(characterId, "deathsave_succ1"));
promises.push(getSheetItem(characterId, "deathsave_succ2"));
promises.push(getSheetItem(characterId, "deathsave_succ3"));
Promise.all(promises).then((results) => {
log(`El primer éxito es ${results[0]}, el segundo éxito es ${results[1]}, el tercer éxito es ${results[2]}`);
}
}
El código asíncrono puede tener muchas ramificaciones en la forma de escribir un script, dependiendo de cómo lo haya estructurado. Por ejemplo, si hay un script que actualmente utiliza getAttrByName dentro de un replace o map, será necesario dividirlo en un bucle más compatible con la asincronía, ya que esas funciones no esperarán a que se devuelva un valor antes de continuar.
Retrocedamos al momento en que escribí «Si está intentando obtener varios valores a la vez o uno tras otro y el resto de su código depende de esos datos». El resto de su código no siempre depende de ese valor. La mayoría de las veces, se basará en ese valor si utiliza getSheetItem, porque querrá hacer algo con cualquier atributo que obtenga. Sin embargo, a menudo, para el caso contrario, setSheetItem, no es necesario esperar a que termine. En ese caso, puede ignorar las ramificaciones de que estas funciones sean asíncronas y simplemente llamarlas como de costumbre. El atributo se actualizará en segundo plano mientras su script continúa.
La función setSheetItem funciona igual que getSheetItem, pero incluye un argumento adicional para determinar el valor que se le asignará al atributo.
setSheetItem(characterId, "hp", 10);
setSheetItem(characterId, "hp", 20, "max");
Actualización del análisis de rollos
Otra cosa que hacen muchos scripts de 5e y que hay que actualizar es el análisis de las tiradas. Los mensajes que se envían al chat tienen un formato completamente diferente y deberán analizarse de otra manera para obtener resultados u obtener información detallada sobre el contenido. El equipo de desarrollo ha añadido algunos atributos de datos al HTML que minimizarán la necesidad de un análisis HTML exhaustivo, pero si necesita datos más complejos, es posible que aún tenga que analizarlos a partir del mensaje enviado al chat. A continuación, describimos algunas necesidades comunes para ayudarle a empezar.
Para obtener el resultado de una tirada en nuestra plantilla de tiradas estándar:
const rollResultMatch = msg.content.match(/data-result="(.+?)"/);
Para comprobar qué tipo de rollo es según el título:
const deathSaveMatch = msgContent.match(/header__title">Insertar encabezado aquí<\/div>/);
Para comprobar el subtítulo del rollo y averiguar cosas como el nivel de hechizo o el tipo de daño:
const spellLevelMatch = msgContent.match(/header__subtitle">Level (.+?) /);
Dado que la hoja de 2024 aún se encuentra en fase de desarrollo activo, existe la posibilidad de que se produzcan cambios en las plantillas de rollo que requieran nuevas actualizaciones de sus scripts. No podemos prometer que el análisis sintáctico del HTML se mantenga estable para siempre, pero estamos trabajando para crear plantillas más estandarizadas a medida que desarrollamos la hoja. Los ejemplos anteriores son algo rígidos en su expresión regular para simplificar, pero recomendamos utilizar la coincidencia difusa y los comodines para que la coincidencia sea más sólida mientras las plantillas de rollo siguen en proceso de cambio.
Problemas comunes
Error: No se ha encontrado ningún atributo o campo de hoja para character_id (SU ID AQUÍ) denominado (SU ATRIBUTO AQUÍ).
Causa probable: probablemente esté utilizando la API predeterminada en lugar de la API experimental y esté intentando acceder a una propiedad calculada de Beacon. Cuando haga clic en «Reiniciar servidor», asegúrese de que el mensaje de reinicio de la API incluye la palabra EXPERIMENTAL y no DEFAULT. Si el menú desplegable está configurado en Experimental, pero los registros de reinicio indican DEFAULT, vuelva a cambiar a Default, reinicie y, a continuación, vuelva a cambiar a Experimental y reinicie de nuevo. Este es un problema conocido relacionado con el cambio entre Predeterminado y Experimental que estamos investigando actualmente.
El resultado de getSheetItem registra un objeto vacío en lugar de un valor.
Causa probable: no se espera ni se utiliza .then en la función getSheetItem. Debe esperar a que se devuelva el valor antes de continuar con el código.