En raison des différences entre l'infrastructure des feuilles « classiques » et celle des feuilles « Beacon », tous les scripts Mod existants ne fonctionnent pas d'emblée avec les feuilles « Beacon ». Les remarques ci-dessous vous aideront à mettre à jour vos scripts afin qu'ils fonctionnent avec les feuilles Beacon (par exemple,&D 2024). Nous avons également mis à jour plusieurs scripts essentiels ; vous y trouverez ainsi des exemples et des scripts prêts à l'emploi pour vos jeux. Scripts qui ont été mis à jour :
- Initiative de groupe
- TokenMod
- Vérification de groupe
- Informations sur le statut
Pour de nombreux scripts, leur mise en conformité avec la feuille 2024 se résume à deux modifications : la manière dont vous récupérez et définissez les attributs, et la manière dont vous analysez les modèles de jet de dés et les messages de chat. Ce document présente ces deux versions et aborde également les problèmes courants, afin que vous puissiez mettre à jour un script pour qu'il fonctionne aussi bien avec la feuille D&D 2014 qu'avec la feuille D&D 2024.
Les propriétés calculées de Beacon et les attributs personnalisés « user.* » nécessitent Mod Script Bac à sable v1.5 (Campaign().sandboxVersion === "1.5"). La version 1.5 est actuellement le Bac à sable par défaut. Les méthodes `getSheetItem ` et `setSheetItem` sont disponibles à la fois dans la version 1.0 et dans la version 1.5. Dans la version 1.0, le système revient aux fonctions get/set d'attributs classiques, ce qui permet aux jeux ne disposant pas de feuille Beacon de continuer à fonctionner. Dans la version 1.5, ils lisent et écrivent également les propriétés calculées de Beacon et les champs user.*. Uniquement pour le script Mod Bac à sable v1.5. getComputed, setComputed et performAction (voir « Scripts de mod : documentation sur les fonctions »).
Si le menu déroulant « Bac à sable » d'un jeu propose toujours les libellés « Par défaut » et « Expérimental », vérifiez le Bac à sable en cours d'exécution à l'aide de la fonction Campaign().sandboxVersion plutôt que de vous fier au libellé. Les propriétés calculées de Beacon doivent prendre la valeur « 1,5 ».
Mise à jour des méthodes get/set
La principale modification entre l'accès aux données de la feuille 2014 et celui de la feuille 2024, en termes de code, concerne la manière dont vous obtenez et définissez les attributs. Il existe désormais un 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 : ${firstSuccess}`);
}Si vous souhaitez obtenir la valeur maximale d'un attribut (si une telle valeur existe), vous pouvez passer la propriété « max », par exemple : getSheetItem(characterId, "deathsave_succ1", "max");.
Vous remarquerez dans le code ci-dessus que la fonction ` getDeathSaveSuccess ` est marquée comme asynchrone. Toutes les fonctions qui utilisent ` getSheetItem ` doivent recourir à ce modèle « async/await » ou utiliser des « promises ». Voici cette même fonction réécrite sous forme de « promise » :
const getDeathSaveSuccess = (id) => {
getSheetItem(characterId, "deathsave_succ1").then((firstSuccess) => {
log(`Premier succès : ${firstSuccess}`);
});
}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, vous pouvez attendre chaque valeur individuellement ou utiliser `Promise.all` pour résoudre toutes les promesses en une seule fois et obtenir les valeurs finales. Si vous ne le faites pas, la valeur que vous obtiendrez sera 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(`Le premier succès est ${results[0]}, le deuxième succès est ${results[1]}, le troisième succès est ${results[2]}`);
});
}Le code asynchrone peut avoir plusieurs implications sur la manière dont vous écrivez un script, selon la façon dont vous l'avez structuré. Par exemple, si un script utilise actuellement la fonction `getAttrByName` à l'intérieur d'une instruction `replace` ou `map`, il devra être refactorisé en une boucle mieux adaptée au traitement asynchrone, car ces fonctions ne attendent pas qu'une valeur soit renvoyée avant de poursuivre leur exécution.
Revenons à la phrase suivante : « Si vous essayez d'obtenir plusieurs valeurs à la fois ou les unes après les autres, 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, ce sera le cas si vous utilisez la méthode `getSheetItem`, car vous souhaitez effectuer une opération sur l'attribut que vous récupérez. En revanche, pour la fonction « setSheetItem », il n'est souvent pas nécessaire d'attendre qu'elle se termine. Dans ce cas, vous pouvez ne pas tenir compte des implications liées à l'asynchronie et l'appeler simplement de manière classique. Les attributs seront mis à jour en arrière-plan pendant que votre script continue de s'exécuter.
La fonction `setSheetItem` fonctionne de la même manière que `getSheetItem`, mais comporte un argument supplémentaire permettant de définir la valeur à attribuer :
setSheetItem(characterId, « hp », 10) ;
setSheetItem(characterId, « hp », 20, « max ») ;Mise à jour de l'analyse des rôles
Un autre aspect de nombreux scripts 5e qui nécessite une mise à jour concerne l'analyse des jets de dés. Les messages envoyés dans le Chat sont formatés différemment et doivent être analysés différemment pour obtenir des résultats ou des détails sur leur contenu. L'équipe de développement a ajouté certains attributs de données au code HTML, ce qui réduit la nécessité d'un analyseur syntaxique HTML approfondi. Si vous avez besoin de données plus complexes, vous devrez peut-être tout de même les extraire du message envoyé sur le Chat. Vous trouverez ci-dessous quelques besoins courants.
Pour obtenir le résultat d'un jet de dé dans le Modèle de jet standard :
const rollResultMatch = msg.content.match(/data-result="(.+?)"/);Pour déterminer de quel type de rouleau il s'agit d'après le titre :
const deathSaveMatch = msgContent.match(/header__title">Entrez l'en-tête ici<\/div>/);Pour consulter la description du jet et obtenir des informations telles que le niveau du sort ou le type de dégâts :
const spellLevelMatch = msgContent.match(/header__subtitle">Level (.+?) /);La feuille de calcul 2024 étant encore en cours d'élaboration, les modèles de jet sont susceptibles d'évoluer et de nécessiter de nouvelles mises à jour du script. Nous ne pouvons pas garantir que l'analyse des chaînes de caractères dans le code HTML restera stable indéfiniment, mais nous nous efforçons de mettre en place des modèles plus standardisés à mesure que la feuille évolue. Pour des raisons de simplicité, les expressions régulières utilisées dans les exemples ci-dessus sont un peu rigides ; nous vous recommandons d'opter pour des correspondances plus souples et d'utiliser des caractères génériques afin de rendre vos correspondances plus robustes tant que les modèles sont encore en cours d'évolution.
Problèmes courants
Erreur : aucun attribut ni champ de feuille n'a été trouvé pour le character_id (VOTRE ID ICI) nommé (VOTRE ATTRIBUT ICI)
Cause probable : vous utilisez la version 1.0 du Bac à sable de Mod Script au lieu de la version 1.5 et vous essayez d'accéder à une propriété calculée de Beacon. Vérifiez que Campaign().sandboxVersion vaut « 1.5 ». Si le menu déroulant du Bac à sable porte toujours la mention « Par défaut » ou « Expérimental », il se peut que cette mention ne soit plus à jour ; redémarrez et vérifiez la valeur de `sandboxVersion` (ainsi que le journal de redémarrage) plutôt que de vous fier uniquement au menu déroulant.
Le résultat de getSheetItem enregistre un objet vide au lieu d'une valeur.
Cause probable : vous n'avez pas attendu l'exécution de la fonction ` getSheetItem ` ou vous n'avez pas utilisé `.then` avec celle-ci. Il est nécessaire d'attendre que la valeur soit renvoyée avant de poursuivre l'exécution du code.