L'éditeur de scripts

Pour éditer les scripts de votre campagne, cliquez sur le lien "API Scripts" dans la page de détails de la campagne (le même endroit où se trouvent les options telles que le "Chat log" "Copy/Extend Campaign"). Une page contenant plusieurs fonctions vous sera alors présentée :

• Une liste d'onglets en haut. Votre campagne peut contenir plusieurs scripts pour faciliter l'organisation. Notez que tous les scripts fonctionneront dans le même contexte, ce qui signifie que vous ne devriez pas avoir plusieurs script tentant d'écraser les mêmes valeurs à un même moment sous peine d'avoir des résultats inattendus.
• Un éditeur de scripts. Vous pouvez utiliser cet éditeur ou les modifier dans un éditeur externe puis les copier ici.
• Une console API en bas (voi ci-dessous).

Lorsque vous cliquez sur le bouton "Sauvegarder les scripts", le sandbox de votre campagne sera "redémarré" (supprimant son état précédent) et utilisera les nouvelles modifications que vous venez d'apporter. Cela s'applique également si vous ajouter ou supprimez un nouveau script ou si vous activez ou désactivez un script.

La Console API

La console API vous permet de suivre l'exécution de vos scripts. Jusqu'à ce que les scripts soient exécutés dans le sandbox, vous n'y avez pas accès directement pour voir des informations sur les résultats ou erreurs du script. La console apporte ces informations hors du sandbox de manière à ce que vous puissiez les voir lors de l'édition des scripts. Toutes les commandes log() apparaîtront ici ainsi que les erreurs rencontrées durant l'exécution. Pour plus d'informations, consultez les informations sur le débuggage des scripts.

Des scripts réactifs : écoutez les événements, modifiez des objets

La première (et plus simple) utilisation de l'API est la réaction aux changements de la table de jeu pour y répondre en appliquant des modifications sur certains objets. Ce type de script est composé d'un certain nombre de fonctions qui écoutent les événements produits durant la partie. Puis il modifiera les objets envoyés avec cet événement, ce qui modifiera la table de jeu.

Le script le plus simple qui bougerait simplement un objet de 5 pieds vers la droite (en supposant que les paramètres de la page soient ceux par défaut) pourrait ressembler à ceci :

on("change:graphic", function(obj) {
  obj.set({
    left: obj.get("left") + 70    
  });
});

Comme vous pouvez le voir, nous avons créer une simple fonction qui sera exécutée chaque fois que l'événement change:graphic sera entendu. Cette fonction reçoit l'élément graphique obj. Pour faire une modification, nous changeons simplement obj en utilisant la méthode set -- chaque propriété que nous modifions sera détectée et mise à jour sur la table de jeu.

Note importante : Vous devez utiliser les méthodes set et get pour modifier et récupérer les valeurs actuelles des objets ou vos changements ne seront pas enregistrés. (Voir ci-dessous pour une liste des types d'objets et leurs attributs, ainsi qu'une liste de tous les événements et quels arguments attend chaque événement.)

Note sur les fonctions utilitaires

Bien sûr, l'exemple précédent n'est pas très pratique car il déplace tout le temps le jeton de 70px. Mais que se passerait-il si l'utilisateur changeait l'échelle de sa carte pour que cinq pieds fassent 140 pixels ? L'API Roll20 fournit plusieurs fonctions utilitaires pratiques pour aider à résoudre ce type de scénarios. Modifions notre exemple précédent en utilisant la fonction distanceToPixels() qui nous dira combien de pixels représentent "cinq pieds" (ou pouces, mètres, ou n'importe quel unité de distance qui a été précisée dans les paramètres de la page) sur la table de jeu.

on("change:graphic", function(obj) {
  obj.set({
    left: obj.get("left") + distanceToPixels(5);
  });
}

Désormais, si la page courante est paramétrée avec la taille de grille par défaut, distanceToPixels(5) renverra bien 70 pixels, mais si l'échelle de la grille de la page a été doublée, elle renverra 140 pixels.

Utiliser les fonctions utilitaires est toujours une bonne idée car elles permettent de s'adapter aux modifications apportées aux paramètres de la page ou à une modification sur un jeton.

Scripts proactifs : exécutez des actions sans intervention de l'utilisateur

En plus de réagir aux événements créés par l'utilisateur, vous pouvez également réaliser des actions automatiques qui ne sont pas liées à un événement produit par les joueurs avec l'API. Par exemple, prenons un jeton qui patrouille d'avant en arrière sur une carte.

Note: Même si ce type de script est indépendant des actions utilisateur, les scripts de votre campagne ne seront actifs que lorsqu'au moins une personne sera connectée à votre campagne.

on("ready", function() {
   //Attend que l'événement "ready" soit reçu, nous saurons alors que la campagne est complètement chargée.
   // Récupère la référence de notre jeton patrouilleur.
   var jetonPatrouilleur = findObjs({_type: "graphic", name: "Guard A"})[0]; //Nous savons qu'il existe un jeton dans notre campagne nomme "Garde A".
   var direction = -70; //On le déplace de 70 pixels à gauche
   var nombrePas = 0; //Combien de pas avons-nous fait dans la direction actuelle ?
   setInterval(function() {
     if(nombrePas > 3) {
       //On change de direction !
       direction = direction * -1; //On inverse la direction dans laquelle nous marchons
       nombrePas = 0; //Et on réinitialise le nombre de pas.
     }
     jetonPatrouilleur.set("left", jetonPatrouilleur.get("left") + direction); //Marchons !
     nombrePas++;
   }, 5000); //L'action se déroule toutes les cinq secondes.
});