Pour de nombreux scripts, la mise à jour pour être compatible avec la feuille 2024 se résume à changer deux choses : la façon dont vous obtenez et définissez les attributs et la façon dont vous analysez les modèles de jet/messages de chat. Ce document vous guidera dans les deux cas, ainsi que dans la résolution de certains problèmes courants, afin que vous puissiez mettre à jour n'importe quel script pour qu'il soit compatible à la fois avec la feuille D&D2014 et avec la feuille D&D2024.
Lorsque votre script est mis à jour de cette manière, dans les jeux avec des feuilles Beacon telles que D&D2024, les MJ devront utiliser le serveur API expérimental pour utiliser toutes les dernières fonctionnalités. Le serveur expérimental possède toutes les mêmes fonctionnalités que le serveur par défaut, de sorte que ce changement ne devrait pas perturber d'autres scripts, mais vous voudrez peut-être l'indiquer dans la description du script pour que vos utilisateurs le sachent. S'il n'y a pas de feuille de balise, le serveur Paramètres par défaut fonctionnera toujours avec ces fonctions, car il reviendra aux fonctions classiques d'obtention et de définition d'attributs.
Mise à jour Paramètres/obtention
Le principal changement entre l'accès aux données pour la feuille 2014 et la feuille 2024, du point de vue du code, est la façon dont vous obtenez et définissez les attributs. Il existe désormais un nouvel ensemble de fonctions asynchrones appelées getSheetItem et setSheetItem. Voici un exemple d'utilisation des nouvelles fonctions :
const getDeathSaveSuccess = async (id) => {
const firstSuccess = await getSheetItem(characterId, "deathsave_succ1") ;
log(`Premier succès est ${firstSuccess}`)
}
Si vous souhaitez obtenir la valeur maximale d'un attribut (si un maximum existe), vous pouvez passer la propriété max, comme getSheetItem(characterId, "deathsave_succ1",
" max") ;.
Vous remarquerez que dans le code ci-dessus, getDeathSaveSuccess est marqué comme asynchrone. Chaque fonction qui utilise getSheetItem devra soit utiliser ce modèle async/await, soit utiliser des promesses. Voici la même fonction, réécrite sous forme de promesse :
const getDeathSaveSuccess = (id) => {
getSheetItem(characterId, "deathsave_succ1").then((firstSuccess) => {
log(`Premier succès est ${firstSuccess}`) ;
}) ;
}.
Si vous essayez d'obtenir plusieurs valeurs en même temps ou l'une après l'autre et que le reste de votre code dépend de ces données, vous pouvez soit attendre chaque valeur individuellement, soit utiliser Promise.all pour résoudre toutes les promesses en même temps et obtenir la valeur finale. Si vous ne faites pas cela, la valeur que vous obtiendrez en retour sera simplement une promesse en attente, et non la valeur réelle de l'attribut.
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(`First success is ${results[0]}, second success is ${results[1]}, third success is ${results[2]}`) ;
}
}
Le code asynchrone peut avoir de nombreuses ramifications sur la façon dont vous écrivez un script, en fonction de la façon dont vous l'avez structuré. Par exemple, si un script utilise actuellement getAttrByName à l'intérieur d'un replace ou d'une map, il devra être décomposé en une boucle plus asynchrone, car ces fonctions n'attendront pas le retour d'une valeur avant de continuer.
Revenons au moment où j'ai écrit "Si vous essayez d'obtenir plusieurs valeurs à la fois ou l'une après l'autre et que le reste de votre code dépend de ces données". Le reste de votre code ne dépend pas toujours de cette valeur. La plupart du temps, il s'appuiera sur cette valeur si vous utilisez getSheetItem, parce que vous voudrez faire quelque chose avec l'attribut que vous obtenez. Toutefois, dans le cas de l'opération inverse, setSheetItem, vous n'avez pas besoin d'attendre qu'elle se termine. Dans ce cas, vous pouvez ignorer les ramifications de ces fonctions asynchrones et les appeler normalement. L'attribut sera mis à jour en arrière-plan pendant que votre script se poursuit.
La fonction setSheetItem fonctionne de la même manière que getSheetItem, mais comprend un argument supplémentaire pour déterminer à quoi attribuer l'attribut.
setSheetItem(characterId, "hp", 10) ;
setSheetItem(characterId, "hp", 20, "max") ;
Mise à jour de l'analyse des rouleaux
L'autre chose que beaucoup de scripts 5e font et qui a besoin d'être mis à jour, c'est l'analyse des jets. Les rouleaux envoyés au Chat sont formatés de manière totalement différente et devront être analysés différemment pour obtenir des résultats ou des détails sur le contenu. L'équipe de développement a ajouté des attributs de données au code HTML qui réduiront la nécessité d'une analyse HTML approfondie, mais si vous avez besoin de données plus complexes, vous devrez peut-être encore les analyser à partir du message envoyé au Chat. Pour vous aider à démarrer, nous vous présentons ci-dessous quelques besoins courants.
Pour obtenir le résultat d'un jet dans notre modèle de jet standard :
const rollResultMatch = msg.content.match(/data-result="(.+ ?)"/) ;
Vérifier de quel type de rouleau il s'agit en se basant sur le titre :
const deathSaveMatch = msgContent.match(/header__title">Insert Header Here<\/div>/) ;
Vérifier le sous-titre du jet pour obtenir des informations telles que le niveau du sort ou le type de dégâts :
const spellLevelMatch = msgContent.match(/header__subtitle">Niveau (.+ ?) /) ;
Parce que la feuille 2024 est encore en développement actif, il est possible que des choses changent avec les modèles de jet qui nécessiteront de nouvelles mises à jour de vos scripts. Nous ne pouvons pas promettre que l'analyse des chaînes de caractères du HTML restera stable pour toujours, mais nous travaillons à l'élaboration de modèles plus standardisés au fur et à mesure que nous développons la feuille. Les exemples ci-dessus sont quelque peu rigides dans leur regex pour des raisons de simplicité, mais nous vous recommandons d'utiliser la correspondance floue et les caractères génériques pour rendre votre correspondance plus robuste alors que les modèles de jet sont encore en évolution.
Problèmes courants
"Erreur : Aucun attribut ou champ de feuille n'a été trouvé pour le personnage_id (VOTRE ID ICI) nommé (VOTRE ATTRIBUTE ICI)"
Cause probable : Vous êtes probablement sur l'API par défaut au lieu de l'API expérimentale et vous essayez d'accéder à une propriété calculée de la balise. Lorsque vous cliquez sur "Redémarrer le serveur", assurez-vous que le message de redémarrage de l'API comporte le mot EXPÉRIMENTAL et non DEFAULT. Si la liste déroulante est réglée sur Expérimental mais que les journaux de redémarrage indiquent DEFAULT, revenez à Default, redémarrez, puis revenez à Experimental et redémarrez à nouveau. Il s'agit d'un problème connu lié à la permutation entre Default et Experimental que nous sommes en train d'étudier.
Le résultat de getSheetItem enregistre un objet vide au lieu d'une valeur
Cause probable : ne pas attendre ou utiliser .then sur la fonction getSheetItem. Vous devez attendre que la valeur revienne avant de poursuivre le code.