API: Guide d'utilisation avancée

L'Éditeur de Scripts

Pour modifier vos scripts de jeu, cliquez sur le lien "API Scripts" dans la page Détails du Jeu pour votre jeu (au même endroit où se trouvent des options telles que "Chat Log" et "Copier/Etendre le jeu"). Vous aurez accès à plusieurs fonctionnalités :

  • Une liste d'onglets en haut. Votre jeu peut avoir plusieurs scripts pour faciliter l'organisation. Notez que tous les scripts s'exécuteront dans le même contexte, ce qui signifie que vous ne devriez pas avoir plusieurs scripts essayant de remplacer les mêmes valeurs en même temps, sinon vous pourriez obtenir des résultats non attendus.
  • Un éditeur de code script. Vous pouvez utiliser cet éditeur ou modifier vos scripts dans un éditeur externe de votre choix, puis les coller ici.
  • Une "Console API" située en bas (voir ci-dessous).

Chaque fois que vous cliquez sur le bouton "Enregistrer les scripts", le bac à sable de votre jeu seraredémarré(en perdant toutes les données en mémoire qui n'ont pas été conservées dans l'objetstateou dans les objets Roll20). Cela s'applique également si vous ajoutez un nouveau script, supprimez un script ou activez/désactivez un script.


La Console API

La Console API est la "fenêtre" vers vos scripts. Étant donné que les scripts API s'exécutent dans un bac à sable, vous n'y avez pas accès directement pendant leur exécution pour visualiser les informations sur les résultats ou les erreurs. La Console API affiche ces informations hors du bac à sable afin que vous puissiez les visualiser pendant que vous modifiez vos scripts. Toutes les commandes log()seront affichées ici, ainsi que toutes les erreurs rencontrées lors de l'exécution de vos scripts. Pour plus d'informations, voirl'article sur le débogage des scripts.


Scripts réactifs: Écoutez les événements, modifiez les objets

Le premier (et le plus simple) type d'utilisation de l'API consiste à réagir aux changements sur la table de jeu, puis à répondre avec des fonctionnalités supplémentaires aux objets modifiés. Ce type de script est composé d'un certain nombre de fonctions qui écoutent les événements qui se produisent pendant le jeu. Ensuite, il modifiera les objets qui sont passés pendant ces événements, ce qui modifiera ce qui se passe sur la table de jeu.

Un script de base qui déplace une pièce de 5 pieds supplémentaires (en supposant les paramètres de page par défaut) serait le suivant :


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

Comme vous pouvez le voir, nous avons créé une simple fonction on qui sera exécutée à chaque fois que l'événement change:graphic est entendu. La fonction reçoit l'objet graphique, obj. Pour effectuer une modification, il suffit de modifier obj en utilisant la fonction set - toutes les propriétés que nous modifions seront détectées et modifiées sur le plateau de jeu.

Vous devez utiliser set et get pour définir et obtenir les valeurs actuelles des objets, sinon vos modifications ne seront pas enregistrées. (Voir ci-dessous la liste des types d'objets et de leurs propriétés, ainsi que la liste de tous les événements et des arguments passés à chaque événement.)

Remarque sur les fonctions utilitaires

Bien sûr, l'exemple précédent n'est pas incroyablement utile car il ajoute toujours 70 pixels à la position du jeton. Mais que se passe-t-il si l'utilisateur a modifié son échelle de sorte que 5 pieds correspondent à 140 pixels ? L'API Roll20 fournit plusieurs fonctions utilitaires pratiques pour vous aider dans ce (et d'autres) scénarios courants. Modifions notre exemple précédent pour utiliser la fonctiondistanceToPixelsfunction, qui nous dira combien de pixels représentent "cinq pieds" (ou pouces, ou mètres, ou tout autre type de distance défini) sur le plateau de la table.

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

Maintenant, si la page actuelle est configurée pour utiliser la taille de grille par défaut,distanceToPixels(5) ;renverra toujours 70 pixels, mais si la page est configurée pour avoir une échelle deux fois plus grande que la taille normale, elle renverra 140.

Il est toujours bon d'utiliser des fonctions utilitaires chaque fois qu'elles sont disponibles pour éviter que votre script ne se casse si les paramètres d'une page ou d'un jeton changent.


Scripts proactifs : faire des choses sans intervention de l'utilisateur

En plus de réagir aux événements de l'utilisateur, vous pouvez également effectuer des actions automatiquement avec l'API qui ne sont pas liées à un événement spécifique des joueurs. Par exemple, faisons en sorte qu'un jeton patrouille d'avant en arrière sur la carte.

Remarque: Bien que ce type de script ne dépende pas de l'interaction de l'utilisateur, les scripts API pour votre jeu ne s'exécuteront que lorsque au moins une personne sera connectée à votre jeu.

on("ready", function() {
   //Attendre que l'événement prêt se déclenche pour savoir que le jeu est complètement chargé.
   //Obtenir une référence de notre jeton de patrouille.
   var patroltoken = findObjs({_type: "graphic", name: "Guard A"})[0]; //Nous savons qu'il y a un jeton dans le Jeu appelé "Guard A".
   var direction = -1*distanceToPixels(5); //Marcher à gauche de 70 pixels.
   var etapesfaites = 0; //Combien d'étapes avons-nous faites dans la direction actuelle?
   setInterval(function() {
     if(stepstaken > 3) {
       //Changer de direction!
       direction = direction * -1; //va "retourner" la direction dans laquelle nous marchons
       stepstaken = 0; //réinitialiser les pas à 0.
     }
     patroltoken.set("left", patroltoken.get("left") + direction); //marcher!
     stepstaken++;
   }, 5000); //prendre une action toutes les 5 secondes
});

Un traité sur les fonctions asynchrones

Une fonction asynchrone est une fonction qui renvoie immédiatement le fil de contrôle à la portée d'appel et effectue une tâche en arrière-plan. Voici un exemple très simple et facile à comprendre que vous pouvez coller dans l'onglet API scripts:

on('load',function(){
  log('Parent Scope - Before call to asynchronous function.');

  setTimeout(function(){
    log('Asynchronous Function Scope - Doing the Asynchronous function work.');
  },10 /* 10 milliseconds */);

  log('Parent Scope - after call to asynchronous function.');
});

Dans le journal API, vous verrez quelque chose comme ceci :

"Parent Scope - Before call to asynchronous function."
"Parent Scope - après appel à la fonction asynchrone."
"Asynchronous Function Scope - Faire le travail de la fonction asynchrone."

En regardant ce code, vous pensez : "Bien sûr, cela se produira plus tard, vous lui avez dit de s'exécuter dans 10 millisecondes, évidemment ?". Voici un exemple moins évident qui aura les mêmes messages journaux :

on('load',function(){
  log('Parent Scope - Before call to asynchronous function.');

  sendChat('Async Function','Évaluez ceci : [[1d6]]',function(msg){
    log('Asynchronous Function Scope - Faire le travail de la fonction asynchrone.');
  });

  log('Parent Scope - après appel à la fonction asynchrone.');

Les fonctions asynchrones sont nécessaires pour éviter que l'API ne se bloque tout le temps. Si chaque lancer de dé était traité de manière synchronisée, l'API serait très lente et non réactive. Presque toutes les fonctions que vous voyez qui prennent un rappel sont asynchrones. (Exception pour certaines des fonctions _.map, _.reduce, etc, ce sont des exemples de programmation fonctionnelle contrairement à la programmation procédurale à laquelle la plupart des gens sont habitués.)

Cet article vous a-t-il été utile ?
Utilisateurs qui ont trouvé cela utile : 30 sur 52