Comment mettre à jour les scripts de mod (API) pour D&D 2024/Beacon

7 novembre 2025 18:33

Compte tenu des différences entre l'infrastructure de feuilles classique & et l'infrastructure de feuilles Beacon, tous les scripts Mod existants ne sont pas compatibles dès leur installation. Heureusement, nous avons rassemblé la documentation ci-dessous pour vous aider à mettre à niveau vos scripts afin qu'ils puissent fonctionner avec les feuilles Beacon (par exemple, D&D 2024). Nous avons également mis à jour les scripts les plus populaires afin que vous disposiez d'exemples et de scripts prêts à l'emploi pour vos jeux. Scripts qui ont été mis à jour :

GroupeInitiative
TokenMod
GroupCheck
Informations sur l'état

Pour de nombreux scripts, la mise à jour visant à assurer leur compatibilité avec la feuille 2024 se résume à deux modifications : la manière dont vous obtenez et définissez les attributs, et la manière dont vous analysez les modèles de jet/messages de chat. Ce document vous guidera à travers ces deux étapes et vous aidera à résoudre 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 la feuille D&D2024.

Lorsque votre script est mis à jour de cette manière, dans les jeux utilisant des feuilles Beacon tels que D'&D2024, les MJ devront utiliser le serveur API expérimental pour bénéficier de toutes les dernières fonctionnalités. Le serveur expérimental offre les mêmes fonctionnalités que le serveur par défaut. Par conséquent, ce changement ne devrait pas perturber le fonctionnement des autres scripts. Toutefois, il est recommandé de le mentionner dans la description du script afin d'en informer vos utilisateurs. En l'absence de feuille Beacon, le serveur par défaut continuera de fonctionner avec ces fonctions, car il se rabattra sur les fonctions classiques d'obtention et de définition des attributs.

Mise à jour des paramètres/Obtention

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 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(`First success is ${firstSuccess}`)
}

Si vous souhaitez obtenir la valeur maximale d'un attribut (si une valeur maximale existe), vous pouvez transmettre la propriété max, comme getSheetItem(characterId, "deathsave_succ1", « max ») ;.

Vous remarquerez dans le code ci-dessus que getDeathSaveSuccess est marqué comme async. Chaque fonction qui utilise getSheetItem devra soit utiliser ce modèle async/await, soit utiliser des promesses. Voici la même fonction ci-dessus, réécrite sous forme de promesse :

const getDeathSaveSuccess = (id) => {
  getSheetItem(characterId, "deathsave_succ1").then((firstSuccess) => {
    log(`First success is ${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 soit attendre chaque valeur individuellement, soit utiliser Promise.all pour résoudre toutes les promesses à la fois et obtenir la valeur finale. Si vous ne procédez pas ainsi, la valeur que vous obtiendrez ne sera qu'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 de nombreuses répercussions sur la manière dont vous rédigez un script, en fonction de la manière dont vous l'avez structuré. Par exemple, si un script utilise actuellement getAttrByName dans une instruction replace ou carte, il devra être décomposé en une boucle plus adaptée à l'asynchronisme, car ces fonctions n'attendent pas qu'une valeur soit renvoyée 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, si vous utilisez getSheetItem, cette valeur sera prise en compte, car vous souhaiterez effectuer une action avec l'attribut obtenu. Cependant, dans de nombreux cas, pour l'opération inverse, setSheetItem, il n'est pas nécessaire d'attendre qu'elle se termine. Dans ce cas, vous pouvez ignorer les implications liées au caractère asynchrone de ces fonctions et les appeler normalement. L'attributs sera mis à jour en arrière-plan pendant que votre script continue d'exécuter ses opérations.

La fonction setSheetItem fonctionne de la même manière que getSheetItem, mais inclut un argument supplémentaire pour déterminer la valeur à attribuer à l'attribut.

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

Mise à jour de l'analyse des rôles

Un autre élément que de nombreux scripts 5e doivent mettre à jour concerne l'analyse des jets de dés. Les rouleaux envoyés au chat sont formatés de manière complètement différente et devront être analysés différemment pour obtenir des résultats ou obtenir des informations détaillées sur le contenu. L'équipe de développement a ajouté certains attributs de données au code HTML afin de réduire au minimum le besoin d'une analyse approfondie du code HTML. Toutefois, si vous avez besoin de données plus complexes, il se peut que vous deviez encore les extraire du message envoyé au chat. Nous avons répertorié ci-dessous quelques besoins courants afin de vous aider à démarrer.

Pour obtenir le résultat d'un lancer dans notre modèle de jet standard :

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

Pour déterminer le type de rôle en fonction du titre :

const deathSaveMatch = msgContent.match(/header__title">Insérer l'en-tête ici<\/div>/);

Pour vérifier le sous-titre du dé afin de connaître des informations telles que le niveau de sort ou le type de dégâts :

const spellLevelMatch = msgContent.match(/header__subtitle">Level (.+?) /);

Étant donné que la feuille 2024 est encore en cours de développement, il est possible que des modifications soient apportées aux modèles de jet, ce qui nécessiterait de nouvelles mises à jour de vos scripts. Nous ne pouvons garantir que l'analyse syntaxique du code HTML restera stable à jamais, mais nous nous efforçons de créer des modèles plus standardisés à mesure que nous développons la feuille. Les exemples ci-dessus sont quelque peu rigides dans leur expression régulière pour plus de simplicité, mais nous vous recommandons d'utiliser la correspondance approximative et les caractères génériques pour rendre votre correspondance plus robuste tant 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 character_id (VOTRE ID ICI) nommé (VOTRE ATTRIBUT ICI)

Cause probable : vous utilisez probablement l'API par défaut au lieu de l'API expérimentale et vous essayez d'accéder à une propriété calculée Beacon. Lorsque vous cliquez sur « Redémarrer le serveur », veuillez vous assurer que le message de redémarrage de l'API inclut le mot EXPÉRIMENTAL et non PAR DÉFAUT. Si le menu déroulant est réglé sur Expérimental mais que les journaux de redémarrage indiquent PAR DÉFAUT, veuillez revenir à Par défaut, redémarrer, puis revenir à Expérimental et redémarrer à nouveau. Il s'agit d'un problème connu lié au passage entre les modes Par défaut et Expérimental, sur lequel nous enquêtons actuellement.

Le résultat de getSheetItem enregistre un objet vide au lieu d'une valeur.

Cause probable : non-attente ou non-utilisation de .then sur la fonction getSheetItem. Il est nécessaire d'attendre que la valeur soit renvoyée avant de poursuivre l'exécution du code.