Cómo actualizar los scripts de mods para D&D 2024/Beacon

Debido a las diferencias entre la infraestructura de hojas heredada y la infraestructura de hojas de Beacon, no todos los scripts de Mod existentes funcionan con las hojas de Beacon tal y como están de fábrica. Las notas que figuran a continuación le ayudarán a actualizar los scripts para que funcionen con las hojas Beacon (por ejemplo, D&D 2024). Asimismo, hemos actualizado varios scripts básicos, de modo que ahora dispone de ejemplos y scripts listos para usar en sus juegos. Scripts que se han actualizado:

• Iniciativa de grupo
• TokenMod
• Comprobación de grupo
• Información de estado

En el caso de muchos scripts, para que sean compatibles con la hoja de 2024 basta con realizar dos cambios: la forma de obtener y establecer los atributos, y la forma de analizar las plantillas de tiradas y los mensajes de chat. Este documento explica ambos casos y aborda, además, los problemas más habituales, de modo que pueda actualizar un script para que funcione tanto con la hoja D&D 2014 como con la hoja D&D 2024.

Las propiedades calculadas de Beacon y los atributos personalizados «user.*» requieren Mod Script Sandbox v1.5 (Campaign().sandboxVersion === "1.5"). La versión 1.5 es el entorno de pruebas predeterminado actual. Los métodos `getSheetItem ` y `setSheetItem ` están disponibles tanto en la versión 1.0 como en la 1.5. En la versión 1.0 se recurre a las funciones tradicionales de obtención y establecimiento de atributos, por lo que los juegos que no dispongan de una hoja de Beacon siguen funcionando. En la versión 1.5, también leen y escriben propiedades calculadas de Beacon y los campos «user.* ». Solo para Mod Script Sandbox v1.5. getComputed, setComputed y performAction (véase «Mod Scripts: Documentación de funciones»).

Si el menú desplegable de entornos de prueba de un juego sigue mostrando las etiquetas «Predeterminado» y «Experimental», compruebe el entorno de prueba en ejecución mediante Campaign().sandboxVersion, en lugar de fijarse en la etiqueta. Las propiedades calculadas de Beacon deben tener el valor «1,5».

Actualización de get/set

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 dispone de un conjunto de funciones asíncronas denominadas «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(`El primer éxito es ${firstSuccess}`);
}

Si desea obtener el valor máximo de un atributo (en caso de que exista), puede especificar la propiedad «max», por ejemplo: getSheetItem(characterId, «deathsave_succ1», «max»);.

Observará en el código anterior que la función ` getDeathSaveSuccess ` está marcada como «async». Todas las funciones que utilicen ` getSheetItem ` deben emplear este patrón «async/await» o utilizar promesas. A continuación se muestra la misma función reescrita como una promesa:

const getDeathSaveSuccess = (id) => {
  getSheetItem(characterId, "deathsave_succ1").then((firstSuccess) => {
    log(`El primer éxito es ${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 por separado o utilizar `Promise.all` para resolver todas las promesas a la vez y obtener los valores finales. De lo contrario, el valor que obtendrá será una promesa pendiente, y 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 varias implicaciones en la forma de escribir un script, dependiendo de cómo lo haya estructurado. Por ejemplo, si un script utiliza actualmente `getAttrByName` dentro de una instrucción `replace` o `map`, será necesario dividirlo en un bucle más adecuado para la asincronía, ya que esas funciones no esperarán a que se devuelva un valor antes de continuar.

Volvamos a la frase: «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 depende siempre de ese valor. En la mayoría de los casos será así si utiliza getSheetItem, ya que lo que pretende es realizar alguna acción con el atributo que está obteniendo. En el caso del método inverso, ` setSheetItem`, a menudo no es necesario esperar a que finalice. En ese caso, puede hacer caso omiso de las implicaciones asíncronas y llamarla con total normalidad. El atributo se actualizará en segundo plano mientras su script sigue ejecutándose.

La función `setSheetItem` funciona igual que `getSheetItem`, pero incluye un argumento adicional para el valor que se va a establecer:

setSheetItem(characterId, «hp», 10);
setSheetItem(characterId, «hp», 20, «max»);

Actualización del análisis sintáctico de los rollos

Otro aspecto que muchos scripts de 5.ª edición deben actualizar es el análisis de las tiradas. Los mensajes enviados al chat tienen un formato diferente y deben analizarse de otra manera para obtener resultados o detalles sobre el contenido. El equipo de desarrollo ha añadido algunos atributos de datos al código HTML que reducen la necesidad de realizar un análisis exhaustivo del mismo. Si necesita datos más complejos, es posible que tenga que extraerlos del mensaje enviado al chat. A continuación se enumeran algunas necesidades habituales.

Para obtener el resultado de una tirada en la plantilla de tirada estándar:

const rollResultMatch = msg.content.match(/data-result="(.+?)"/);

Para comprobar de qué tipo de rollo se trata a partir del título:

const deathSaveMatch = msgContent.match(/header__title">Introduzca aquí el encabezado<\/div>/);

Para consultar la descripción de la tirada y obtener información como el nivel del 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, es posible que las plantillas de rollos sufran cambios y requieran nuevas actualizaciones del script. No podemos garantizar que el análisis de cadenas HTML se mantenga estable para siempre, pero estamos trabajando para lograr unas plantillas más estandarizadas a medida que se va desarrollando la hoja de cálculo. Los ejemplos anteriores utilizan expresiones regulares algo rígidas para mayor simplicidad; le recomendamos que utilice una coincidencia más flexible y caracteres comodín para que su coincidencia resulte más robusta mientras las plantillas aún están en fase de desarrollo.

Problemas habituales

Error: No se ha encontrado ningún atributo ni campo de hoja para el «character_id» (SU ID AQUÍ) denominado (SU ATRIBUTO AQUÍ)

Posible causa: Está utilizando Mod Script Sandbox v1.0 en lugar de la v1.5 y está intentando acceder a una propiedad calculada de Beacon. Compruebe que Campaign().sandboxVersion sea «1.5». Si en el menú desplegable de un entorno de pruebas sigue apareciendo la indicación «Predeterminado» frente a «Experimental», es posible que dicha indicación esté desactualizada; reinicie el sistema y compruebe el valor de `sandboxVersion` (así como el registro de reinicio), en lugar de basarse únicamente en el menú desplegable.

El resultado de getSheetItem registra un objeto vacío en lugar de un valor.

Causa probable: no se ha esperado ni se ha utilizado «.then» en la función «getSheetItem ». Debe esperar a que se devuelva el valor antes de continuar con el código.