Des outils sont mis à votre disposition pour vous aider à utiliser l'espace de jeu Roll20 de manière cohérente. Vous pouvez appeler une fonction d'outil depuis n'importe quel endroit de vos scripts (au sein d'un rappel d'événement, par exemple). La documentation complète sur les fonctions est disponible sur Mod Scripts : Documentation des fonctions.
Underscore.js
Vous disposez de la bibliothèque Underscore.js (via l'objet global _ ) pour vous faciliter la tâche. Underscore propose des fonctions d'aide telles que _.each (pour parcourir un tableau d'objets). Pour plus d'informations, veuillez consulter la documentation d'Underscore.
Exploitation forestière
journal (message)
Vous pouvez utiliser cette fonction pour afficher les résultats dans la console de sortie Mod, sur la page Éditeur de script. Utile pour déboguer vos scripts et mieux comprendre ce qui se passe au sein du « Bac à sable de scripts modifiés ».
on("change:graphic", function(obj) {
log("Changement détecté pour l'objet ID : " + obj.id);
});Uniquement pour le script Mod Bac à sable v1.5. Dans la mesure du possible, les messages d'erreur comportent un objet de contexte indiquant le nom de l'objet Roll20 concerné, par exemple :
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].
Commande d'objets
toFront(obj) et toBack(obj)
Ces deux fonctions permettent de déplacer un objet situé sur la table vers l'avant (ou vers l'arrière) du calque sur lequel il se trouve actuellement. Veuillez noter que vous devez passer un objet réel, tel que celui que vous recevez dans un rappel d'événement ou en appelant les méthodes `getObj ` ou `findObjs`.
toAbove(obj, target) et toBelow(obj, target)
Uniquement pour le script Mod Bac à sable v1.5. Placez l'objet immédiatement au-dessus ou en dessous de la cible dans l'ordre de superposition. La cible peut être un objet graphique, un objet texte, un objet « path » ou « pathv2 », ou encore l'identifiant d'un tel objet. Les méthodes toFront et toBack prennent l'objet lui-même. Ces mêmes types disposent également de méthodes d'instance toFront(), toBack(), toAbove(target) et toBelow(target).
Nombres aléatoires
entier aléatoire(max)
Renvoie un nombre entier aléatoire compris entre 1 et max, en utilisant le même générateur que les dés de Roll20. Utilisez ceci pour les dés. Math.floor(Math.random() * max) + 1 est uniformément réparti pour les tailles de dés que l'on lance couramment ; le biais modulo est un problème distinct (entier % n).
Math.random()
Vous pouvez appeler Math.random() comme d'habitude dans vos scripts de mod, en étant assuré que les résultats seront aléatoires, car la fonction Math.random() « par défaut » de JavaScript a été remplacée par le générateur de nombres aléatoires pseudo-aléatoires (PRNG) cryptographiquement sécurisé qui alimente Roll20. Ainsi, les scripts existants qui utilisent Math.random() peuvent être utilisés en sachant que les résultats sont réellement aussi proches du hasard que cela est possible sur un ordinateur.
Pour un lancer de dés, privilégiez la fonction ` randomInteger(max)`. Il s'agit du même générateur que celui utilisé par le moteur de dés.
Le joueur est MJ
joueurEstGM(identifiantJoueur)
Indique si ce joueur est actuellement MJ. Cela permet de passer des promotions à la fonction « Rejoindre en tant que joueur » sans avoir à redémarrer. La valeur de playerIsGM("API") est fausse : le Chat envoyé par le script utilise l'identifiant de joueur « API », qui ne correspond à aucun joueur dans le jeu.
Personnage
setDefaultTokenForCharacter(personnage, jeton)
Définit le jeton par défaut pour l'objet personnage fourni en fonction des détails de l'objet jeton fourni. Les deux objets doivent déjà exister. Cela remplacera tout jeton par défaut actuellement associé au personnage.
Effets (FX)
spawnFx(x, y, type, pageid)
Génère un effet de courte durée à l'emplacement ( x,y ) de type. Si vous omettez le « pageid » ou si vous transmettez la valeur « undefined », la page sur laquelle se trouvent actuellement les joueurs (playerpageid dans l'objet « Campaign ») sera utilisée par défaut.
Pour les effets intégrés, le type doit être une chaîne de caractères et correspondre à l'une des valeurs suivantes : beam-color, bomb-color, breath-color, bubbling-color, burn-color, burst-color, explode-color, glow-color, missile-color, nova-color, splatter-color
Où le terme « couleur » dans ce qui précède désigne l'un des éléments suivants : acide, sang, charme, mort, feu, givre, sacré, magie, boue, fumée, eau
Pour les effets personnalisés, « type » doit correspondre à l'identifiant de l'objet custfx associé à l'effet personnalisé.
spawnFxBetweenPoints(point1, point2, type, pageid)
Fonctionne de la même manière que `spawnFx`, mais au lieu d'un seul point, vous transmettez deux points, au format {x : 100, y : 100}. Par exemple : spawnFxBetweenPoints({x : 100, y : 100}, {x : 400, y : 400}, « beam-acid »). Les effets de faisceau, de souffle et d'éclaboussures se propagent entre ces deux points. Les coordonnées correspondent aux pixels de la page ; l'espacementà gauche et en haut est le même que pour les images. Les coordonnéesx/y des fenêtres et des portes utilisent les axes inversés et ne correspondent pas à ces coordonnées.
Les types d'effets suivants doivent toujours utiliser `spawnFxBetweenPoints` au lieu de `spawnFx`: `beam-color`, `breath-color`, ` splatter-color`
Uniquement pour le script Mod Bac à sable v1.5. Les effets de type « poutre » sont directement orientés vers le point 2 (une erreur de calcul d'angle a été corrigée).
spawnFxWithDefinition(x, y, definition, pageid)
Crée un effet personnalisé ad hoc aux coordonnées x, y. La définition est un objet JavaScript, et non une chaîne JSON. La structure est identique à celle d'une définition Custom FX. Si vous omettez le paramètre « pageid » ou si vous lui attribuez la valeur « undefined », c'est la page actuelle du joueur (Campaign().get("playerpageid")) qui est utilisée.
Playlist du Jukebox
jouerJukeboxPlaylist(playlistid)
Récupère l'identifiant du dossier (disponible via la propriété _jukeboxfolder de l'objet Campaign) de la Playlist, puis lance la lecture de cette Playlist pour tous les joueurs.
arrêterJukeboxListeDeLecture()
Cette commande ne nécessite aucun argument et mettra fin à la lecture de toute Playlist en cours.
Autres
sendPing(left, top, pageid, playerid, moveAll, visibleTo)
Envoie un signal à la table (comme lorsque vous maintenez le bouton de la souris enfoncé). « gauche » et « haut » correspondent aux pixels de la page. Le champ « pageid » est obligatoire. Le paramètre « playerid » est facultatif et correspond au quatrième argument : il s'agit du joueur auquel le ping est attribué. Si vous ne le spécifiez pas ou si vous transmettez une valeur fausse, le ping est attribué à « api » (jaune).
Passez la valeur « true » à la fonction « moveAll » pour faire défiler les joueurs jusqu'à ce point. visibleTo permet de limiter les personnes pouvant voir le ping : un identifiant de joueur, un tableau d'identifiants ou une chaîne de caractères séparée par des virgules. Omettez-le ou indiquez « », pour envoyer un message à tout le monde.
Les délais définis avec `setTimeout` dans l'exemple ci-dessous sont réinitialisés en cas de redémarrage du Bac à sable.
on("chat:message", function(msg) {
if (msg.type !== "api" || msg.content.indexOf("!pingtest") !== 0) return;
var players = findObjs({_type: "player"});
if (players.length < 1) return;
var player1 = players[0].id;
var player2 = players.length > 1 ? players[1].id : player1 ;
var allPlayerIDs = players.map(function(player) { return player.id ; });
var pageid = Campaign().get("playerpageid") ;
// pageid est le 3e argument ; playerid est le 4e. L'attribut « null » attribue le ping à « api ».
sendPing(300, 300, pageid, null, true);
setTimeout(function() {
// « » pour « visibleTo » permet également d'envoyer un ping à tout le monde
sendPing(1500, 500, pageid, msg.playerid, true, "");
}, 1000);
setTimeout(function() {
sendPing(1200, 500, pageid, null, true, player1);
}, 2000);
setTimeout(function() {
sendPing(900, 100, pageid, player2, true, [player1, player2]);
}, 3000);
setTimeout(function() {
sendPing(300, 300, pageid, player1, true, allPlayerIDs.join());
}, 4000);
});Remarque sur les distances et les grilles dans Roll20
Sur une grille carrée, une unité correspond à 70 pixels. La valeur « snapping_increment » de la page correspond au nombre d'unités que représente chaque case de la grille, « scale_number » correspond à la distance d'une unité, et « scale_units » correspond au nom de l'unité (souvent « ft »). Les valeurs par défaut sont les suivantes : 1 unité = 5 pieds = 1 carré = 70 pixels. Un MJ peut définir 1 unité comme équivalant à 10 pieds, ou chaque case comme équivalant à 2 unités (140 pixels).
Les grilles hexagonales n'utilisent pas ce carré de 70 pixels. Les positions des fenêtres et des portes utilisent un axe Y inversé ; ce n'est pas le cas pour les éléments graphiques situés à gauche ouen haut.