Scripts de mod : débogage

Chaque fois que vous écrivez des programmes (des plus simples aux plus complexes), vous rencontrerez inévitablement des bogues qui entraînent un dysfonctionnement du programme. Compte tenu de la nature même du Bac à sable, il peut être un peu difficile de savoir exactement ce qui se passe. Voici donc quelques conseils qui vous aideront à diagnostiquer les problèmes rencontrés avec vos scripts.

Le débogage « à l’ancienne »

Comme vous n'avez pas d'accès direct à l'environnement dans lequel les scripts sont exécutés, vous pouvez vous appuyer sur un grand nombre d'appels à la fonction `log() ` pour savoir ce qui se passe dans votre programme. Par exemple, si vous ne comprenez pas bien pourquoi un jeton ne se déplace pas correctement et que vous souhaitez mieux cerner les valeurs qui sont manipulées, vous pourriez procéder ainsi :

on("change:graphic:left", function(obj) {
  //Quelle est la valeur « left » de l'objet qui est transmise ici ?
  log(obj.get("left"));
  obj.set("left", obj.get("left") + 70);
  //Quelle est la valeur actuelle ?
  log(obj.get("left"));
  //Vous pouvez également déboguer des objets entiers pour afficher la liste de leurs attributs actuels
  log(obj);
});

Vous trouverez les résultats de vos commandes log() dans la console de sortie des mods, accessible depuis la page « Paramètres des scripts de mods » de votre campagne.

Uniquement pour le script Mod Bac à sable v1.5. Dans la mesure du possible, les messages d'erreur incluent un objet de contexte afin que vous puissiez identifier l'objet Roll20 concerné (type et identifiant) :

ERREUR : la fonction toBelow() doit être appelée avec un objet graphique, un objet texte ou un objet chemin de Roll20. Appel effectué avec le personnage Roll20 [-NM0tVij02hIfnoTdihc].

Verrous de sécurité

Le Bac à sable corrigera automatiquement les petites erreurs présentes dans votre script en le redémarrant si nécessaire. Toutefois, s’il détecte une erreur grave dont il ne peut pas se remettre, plutôt que de simplement relancer votre script à l’infini pour qu’il continue à générer des erreurs, il appliquera un « verrouillage d’erreur » à votre campagne, ce qui empêchera vos scripts de mod de s’exécuter tant que l’erreur n’aura pas été résolue. Si vos scripts ont été verrouillés en raison d'une erreur, un message similaire à celui-ci s'affichera sur la page « Paramètres des scripts de mod » :

Ne vous inquiétez pas ! Il vous suffit d'apporter des modifications à vos scripts pour tenter de résoudre le problème, puis de cliquer sur le bouton « Enregistrer le script ». Lorsque vous aurez effectué cette opération, le verrou d'erreur sera désactivé et le Bac à sable tentera à nouveau d'exécuter vos scripts. Si une autre erreur survient, le verrouillage d'erreur sera réappliqué. Vous pouvez répéter cette procédure autant de fois que nécessaire pour corriger l'erreur ; vous ne serez jamais empêché de supprimer vos verrous d'erreur au motif que vous avez échoué trop de fois.

Pile d'appels spécifique au script

Les piles d'appels affichent les noms des scripts et les numéros de ligne.

Parmi les erreurs, on trouve une pile d'appels réécrite qui mentionne le nom du script et la ligne, et non le fichier de Bac à sable concaténé. Les scripts manuels sont identifiés par la mention « SCRIPT », suivie du nom que vous avez attribué à l'onglet, du numéro de l'onglet, de la ligne où l'erreur s'est produite et du décalage de colonne :

Exemple : SCRIPT : Script « Bad Actor » [Onglet 85]:3

Les scripts de bibliothèque « au clic » sont identiques, mais leur libellé est « 1-CLICK » :

L'intégralité de la pile d'appels sera traduite ; ainsi, si vous disposez de plusieurs scripts appelant d'autres scripts, vous pourrez identifier où tout cela se produit.

Détection d'une boucle infinie potentielle - Informations complémentaires

Si le Bac à sable cesse d'envoyer des signaux de présence, il s'arrête et peut entrer dans une boucle infinie. Vous verrez l'événement ainsi que l'endroit où la fonction de rappel qui était en cours d'exécution a été enregistrée. Cela facilite grandement la localisation de l'origine d'un problème et devrait permettre de trouver des solutions beaucoup plus rapidement.

• Événement : change:graphic
• Rappel : à la ligne 37 du script « Bad Actor »

Erreurs courantes

Voici quelques erreurs fréquentes :

myvar n'est pas défini

on("ready", function() {
  var myVar;
  log(myvar);
});

Bien que le message d'erreur indique « non défini », ce qui s'est en réalité produit, c'est que la variable n'a pas été déclarée. L'une des causes les plus courantes est une erreur de frappe dans le nom d'une de vos variables, telle qu'une majuscule manquante.

Impossible de lire la propriété « myProperty » ou impossible d'appeler la méthode « myMethod »

on("ready", function() {
  var myVar;
  log(myVar.myProperty);
  log(myVar.myMethod());
});

myVar n'est pas défini ; le script ne sait donc pas comment gérer votre tentative d'accès à une propriété de myVar. Cela est probablement dû à l'une des raisons suivantes :

• Vous avez essayé de rechercher un objet à l'aide de getObj ou de findObjs, mais le résultat était indéfini. Veuillez effectuer une vérification d'erreur pour vous assurer que votre variable est bien définie avant d'accéder à ses propriétés.
• Votre variable est définie de manière conditionnelle (à l'aide d'une série d'instructions « if » ou d'une structure similaire), et aucune de vos conditions n'ayant été remplie, votre variable est restée déclarée, mais n'a jamais été définie. Veuillez vous assurer que vous avez défini des conditions pour toutes les possibilités, ou créez une option par défaut, ou effectuez une vérification d'erreur pour vous assurer que votre variable est définie avant d'accéder à ses propriétés.

Les objets Roll20 doivent également disposer de méthodes « get » et « set ». obj.left ne correspond pas à la position sur la table ; veuillez utiliser obj.get("left").

Jeton inattendu

Il vous manque un personnage ou vous avez un personnage en trop. Cela peut résulter de l'oubli d'une virgule entre une liste de propriétés dans un objet ou des éléments dans un tableau, ou du fait d'avoir une parenthèse fermante en trop ou en moins à la fin d'un appel de méthode imbriqué complexe.

_displayname renvoie « undefined », tandis que get("_displayname") renvoie un nom

La plupart des propriétés des objets Roll20 doivent être consultées ou modifiées à l'aide des méthodes get() et set(). Lorsque vous utilisez la méthode get(), vous pouvez omettre le trait de soulignement initial pour les propriétés en lecture seule : obj.get("displayname") revient au même que obj.get("_displayname"). obj._displayname ne l'est pas.

Si vous rencontrez toujours des problèmes, n'hésitez pas à publier un message sur notre forum consacré aux scripts de mod. Veuillez indiquer le message d'erreur affiché dans la console ainsi qu'une brève description du résultat attendu.