Le rédacteur en chef
Pour modifier les scripts de votre jeu, veuillez cliquer sur le lien « Scripts Mod (API) » dans la Page détails de la partie correspondant à votre jeu (au même endroit où se trouvent les options telles que « Journal du chat » et « Copier/Prolonger le jeu »). Plusieurs fonctionnalités vous seront présentées :
- Une liste d'onglets en haut de la page. Votre jeu peut comporter plusieurs scripts afin de faciliter l'organisation. Veuillez noter que tous les scripts continueront à s'exécuter dans le même contexte, ce qui signifie qu'il est déconseillé d'avoir plusieurs scripts essayant de remplacer les mêmes valeurs en même temps, car cela pourrait entraîner des résultats imprévus.
- Un éditeur de code de script. Vous pouvez utiliser cet éditeur ou modifier vos scripts dans un éditeur externe de votre choix, puis les insérer ici.
- Une « console Mod (API) » située en bas de l'écran (voir ci-dessous).
Chaque fois que vous cliquez sur le bouton « Enregistrer les scripts », le bac à sable de votre jeu seraredémarré(ce qui entraînera la perte de toutes les données en mémoire qui n'ont pas été conservées dans l'objetd'étatou 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 Mod (API)
La console Mod (API) constitue la « fenêtre » sur vos scripts. Étant donné que les scripts Mod (API) s'exécutent dans un bac à sable, il n'est pas possible d'y accéder directement pendant leur exécution afin de consulter les informations relatives aux résultats ou aux erreurs du script. La console Mod (API) affiche ces informations en dehors du bac à sable afin que vous puissiez les consulter pendant que vous modifiez vos scripts. Toutes les commandes log()s'afficheront ici, ainsi que les éventuelles erreurs rencontrées lors de l'exécution de vos scripts. Pour plus d'informations, veuillez consulter l'article sur le débogage des scripts.
Scripts réactifs : écouter les événements, modifier les objets
Le premier type (et le plus simple) d'utilisation du Mod (API) consiste à réagir aux changements survenant sur la table, puis à répondre par des fonctionnalités supplémentaires aux objets modifiés. Ce type de script est constitué d'un ensemble de fonctions qui détectent les événements survenant pendant le jeu. Ensuite, il modifiera les objets qui sont transmis lors de ces événements, ce qui changera ce qui se passe sur table.
Un script de base qui déplace un élément de 1,5 mètre supplémentaire (en supposant des 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 constater, nous avons créé une fonction simple qui sera exécutée chaque fois que l'événement change:graphic sera détecté. La fonction reçoit l'objet graphique obj. Pour effectuer une modification, il suffit de modifier obj à l'aide de la fonction set. Toutes les propriétés modifiées seront détectées et modifiées sur table.
les méthodes setetgetpour définir et obtenir les valeurs actuelles des objets, sinon vos modifications ne seront pas enregistrées. (Veuillez consulter ci-dessous la liste des types d'objets et de leurs propriétés, ainsi que la liste de tous les événements et les arguments transmis à chaque événement.)Remarque sur les fonctions d'outil
Bien entendu, l'exemple précédent n'est pas particulièrement utile, car il ajoute systématiquement 70 pixels à l'emplacement du jeton. Cependant, 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 outils pratiques pour vous aider dans ce type de situation (et d'autres) courantes. Modifions notre exemple précédent afin d'utiliser lafonction distanceToPixels, qui nous indiquera combien de pixels représentent « cinq pieds » (ou pouces, mètres, ou toute autre unité de distance définie) sur la surface de la table.
on("change:graphic", function(obj) {
obj.set({
left: obj.get("left") + distanceToPixels(5);
});
});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 normale, elle renverra 140.
Il est toujours recommandé d'utiliser les fonctions outils lorsqu'elles sont disponibles afin d'éviter que votre script ne cesse de fonctionner si les paramètres d'une page ou d'un jeton changent.
Scripts proactifs : exécuter des tâches sans intervention de l'utilisateur
En plus de réagir aux événements des utilisateurs, vous pouvez également effectuer automatiquement des actions avec l'API qui ne sont pas liées à un événement spécifique des joueurs. Par exemple, considérons un jeton qui effectue des allers-retours sur la carte.
Remarque: bien que ce type de script ne dépende pas de l'interaction de l'utilisateur, les scripts Mod (API) de votre jeu ne s'exécuteront que lorsqu'au moins une personne sera connectée à votre jeu.
on("ready", function() {
//Attendez que l'événement « ready » se déclenche afin de confirmer que le jeu est entièrement chargé.
//Obtenir une référence à notre jeton de patrouille.
var patroltoken = findObjs({_type: "graphic", name: "Guard A"})[0]; //Nous savons qu'il existe un jeton dans le jeu appelé « Guard A ».
var direction = -1*distanceToPixels(5); //Se déplacer vers la gauche de 70 pixels.
var stepstaken = 0 ; //Combien de pas avons-nous effectués dans la direction actuelle ?
setInterval(function() {
if(pas effectués > 3) {
//Changer de direction !
direction = direction * -1 ; //inversera la direction dans laquelle nous marchons
stepstaken = 0 ; //réinitialise les pas à 0.
patroltoken.set("left", patroltoken.get("left") + direction); //marcher !
stepstaken++;
}, 5000); //effectuer une action toutes les 5 secondes
});Traité sur les fonctions asynchrones
Une fonction asynchrone est une fonction qui renvoie immédiatement le fil de contrôle à la portée appelante et exécute certaines tâches en arrière-plan. Voici un exemple très simple et facile à comprendre que vous pouvez insérer dans l'onglet des scripts Mod (API) :
on('load',function(){
log('Portée parentale - Avant l'appel à la fonction asynchrone.');
setTimeout(function(){
log('Portée de la fonction asynchrone - Exécution de la fonction asynchrone.');
},10 /* 10 millisecondes */);
log('Portée parentale - après l'appel à la fonction asynchrone.');
});Dans le journal Mod (API), vous observerez quelque chose de similaire à ceci :
Portée parentale - Avant l'appel à une fonction asynchrone. « Portée parentale - après appel à une fonction asynchrone. » Portée de la fonction asynchrone - Exécution de la fonction asynchrone.
En observant ce code, vous vous dites : « Bien entendu que cela se produira plus tard, vous avez spécifié qu'il devait s'exécuter en 10 millisecondes, n'est-ce pas ? ». Voici un exemple moins évident qui produira les mêmes messages de journal :
on('load',function(){
log('Portée parent - Avant l'appel à la fonction asynchrone.');
sendChat('Fonction asynchrone','Évaluez ceci : [[1d6]]',function(msg){
log('Portée de la fonction asynchrone - Exécution de la fonction asynchrone.');
});
log('Portée parent - après l'appel à la fonction asynchrone.');Les fonctions asynchrones sont indispensables pour éviter que l'API ne se bloque fréquemment. Si chaque lancer de dés était traité de manière synchrone, l'API serait extrêmement lente et peu réactive. Presque toutes les fonctions qui utilisent un rappel sont asynchrones. (À l'exception de certaines fonctions telles que _.map, _.reduce, etc., il s'agit d'exemples de programmation fonctionnelle, par opposition à la programmation procédurale à laquelle la plupart des gens sont habitués.)