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.)

A Note on Utility Functions

Of course, the previous example isn't incredibly helpful because it always adds 70 pixels to the location of the token. But what if the user has changed their scale so that 5ft is 140 pixels? The Roll20 API provides several handy utility functions to help with this (and other) common scenarios. Let's modify our previous example to use the distanceToPixelsfunction, which will tell us how many pixels "five feet" (or inches, or meters, or whatever other distance type has been set) on the tabletop is.

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

Now if the current page is setup to use the default grid sizing, distanceToPixels(5); will still return 70 pixels, but if the page is setup to have a scale twice the size of normal, it would return 140.

It's always a good idea to use utility functions whenever they're available to help keep your script from breaking if the settings of a page or a token change.

Proactive Scripts: Do Things Without User Intervention

In addition to reacting to user events, you can also do things with the API automatically that aren't tied to a specific event from the players. For example, let's have a token that patrols back and forth on the map.

Note: Although this type of script is not dependent on user interaction, the API scripts for your campaign will still only run when at least one person is connected to your campaign.

on("ready", function() {
   //Wait until the ready event fires so we know the campaign is completely loaded.
   //Get a reference to our patrolling token.
   var patroltoken = findObjs({_type: "graphic", name: "Guard A"})[0]; //We know there is a token in the Campaign called "Guard A".
   var direction = -70; //Walk left 70 pixels.
   var stepstaken = 0; //How many steps have we walked in the current direction?
   setInterval(function() {
     if(stepstaken > 3) {
       //Switch directions!
       direction = direction * -1; //will "flip" the direction we're walking
       stepstaken = 0; //reset steps back to 0.
     }
     patroltoken.set("left", patroltoken.get("left") + direction); //walk!
     stepstaken++;
   }, 5000); //take an action every 5 seconds
});