API: Fonctions Utilité

Des fonctions utilitaires sont fournies pour vous aider à travailler de manière cohérente avec l'espace de jeu Roll20. Vous pouvez appeler une fonction utilitaire de n'importe où dans vos scripts (à l'intérieur de n'importe quelle fonction de rappel, par exemple).


Underscore.js

Vous avez accès à la bibliothèque Underscore.js (via l'objet global_) pour vous faciliter la tâche. Underscore fournit des fonctions d'aide pour des choses comme_.each(pour parcourir un tableau d'objets). Consultez la documentation deUnderscorepour plus d'informations.


Logging

log(message)

Vous pouvez utiliser cette fonction pour consigner les sorties dans la console API de la page Éditeur de scripts. Utile pour déboguer vos scripts et mieux comprendre ce qui se passe à l'intérieur de l'environnement API.

on("change:graphic", function(obj) {    
  log("Événement de modification détecté pour l'ID de l'objet : " + obj.id);
});

Commande d'objet

toFront(obj)ettoBack(obj)

Ces deux fonctions déplacent un objet sur la table de jeu vers l'avant (ou l'arrière) de la couche sur laquelle il se trouve actuellement. Notez que vous devez transmettre un objet réel, tel que celui que vous recevez dans un rappel d'événement ou en appelantgetObjoufindObjs.


Nombres aléatoires

randomInteger(max)

Utilisez cette fonction pour les dés !Cette fonction tient compte deModulo Biasqui garantit que les nombres aléatoires résultants sont également répartis uniformément entre 1 et MAX.

Renvoie un nombre entier aléatoire, dont la valeur la plus faible est 1 et la valeur la plus élevée estmax. Il s'agit de la même fonctionnalité utilisée par Roll20 pour générer ses jets de dés, et ces nombres ont été prouvés statistiquement et rigoureusement comme étant aléatoires.

Math.random()

Vous pouvez appeler Math.random() normalement dans vos scripts API, en vous fiant à ce que les résultats soient aléatoires, car la fonction "par défaut" Math.random() en Javascript a été remplacée par le GPRC qui assure la cryptographie de Roll20. Donc, les scripts existants qui utilisent Math.random() peuvent être utilisés en sachant que les résultats sont vraiment proches de l'aléatoire qu'il est possible d'obtenir sur un ordinateur.

N'utilisez pas Math.random() si une distribution égale des nombres dans une plage est souhaitée. Alors que Math.random() vous donne un bon nombre aléatoire, transformer ce nombre aléatoire en une plage avec une distribution égale (comme un jet de dés) n'est pas aussi simple que la multiplication avec un modulo ou un appel à floor. UtilisezrandomInteger(max)pour ces cas.


Le joueur est MJ

playerIsGM(playerid)

La fonction Player Is GM renvoie une réponse booléenne indiquant si un joueur dans le jeu est un MJ ou non. La fonction renverra toujours la réponse correcte en fonction du moment actuel, donc même si un MJ choisit de se réinscrire en tant que joueur ou qu'un joueur est promu MJ en cours de partie, playerIsGM() répondra en conséquence sans avoir besoin de vider le cache ou de redémarrer le sandbox de l'API.


Caractère

setDefaultTokenForCharacter(personnage, jeton)

Définit le jeton par défaut pour l'objet Personnage fourni avec les détails de l'objet Jeton fourni. Les deux objets doivent déjà exister. Cela écrasera tout jeton par défaut actuellement associé au personnage.


Effets spéciaux (FX)

spawnFx(x, y, type, pageid)

Fait apparaître un bref effet à l'emplacement aux coordonnées x, y de type spécifié. Si vous omettez le pageid ou passez 'undefined', alors la page sur laquelle se trouvent les joueurs ('playerpageid' dans l'objet Campagne) sera utilisée par défaut.

Pour les effets intégrés, le type doit être une chaîne de caractères et être l'un des suivants :beam-colorbomb-colorbreath-colorbubbling-colorburn-colorburst-colorexplode-colorglow-colormissile-colornova-colorsplatter-color

Où "couleur" ci-dessus est l'un des :acide,sang,charme,mort,feu,gel,saint,magie,limon,fumée,eau

Pour les effets personnalisés, le type doit être l'ID de l'objet custfx pour 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 passez deux points, au format {x: 100, y: 100}. Par exemple: spawnFxBetweenPoints({x: 100, y: 100}, {x: 400, y: 400}, "beam-acid") L'effet ''voyagera'' entre les deux points pour les effets qui le permettent (les mêmes qui permettent une agence côté client).

Les types d'effet suivants doivent toujours utiliser spawnFxBetweenPoints au lieu de spawnFx :beam-color,breath-color,splatter-color

spawnFxWithDefinition(x, y, definitionJSON, pageid)

Fait apparaître un effet personnalisé ad hoc en utilisant le JSON pour la définition de l'effet à l'emplacement x,y. Si vous omettez le pageid ou passez 'undefined', alors la page sur laquelle se trouvent les joueurs ('playerpageid' dans l'objet Campaign) sera utilisée par défaut.

definitionJSON est un objet javascript suivant la spécification JSON pourFX personnalisé.


Playlist du jukebox

playJukeboxPlaylist(playlistid)

La fonction play prend en argument l'ID de dossier (obtenu à partir de la propriété "_jukeboxfolder" dans l'objet Campaign) de la playlist, et commencera à jouer cette playlist pour tous les joueurs de la partie.

stopJukeboxPlaylist()

La fonction stop ne nécessite aucun argument et arrêtera toute playlist en cours de lecture.


Divers

sendPing(left, top, pageid, (optional) playerid, (optional) moveAll, (optional) visibleTo)

Envoie un "ping" sur la table de jeu (comme si un joueur maintenait enfoncé le bouton de la souris). Vous devez spécifier les coordonnées haut/gauche et l'ID de la page à laquelle le ping est destiné. Vous pouvez facultativement spécifier l'ID d'un joueur qui a effectué le ping : si vous ne le faites pas, "api" sera supposé et le ping sera jaune.

Vous pouvez passer "true" pour l'option moveAll si vous souhaitez déplacer également les vues des joueurs à cet emplacement.

Vous pouvez définir les ID des joueurs dans visibleTo pour les joueurs qui peuvent voir ou être déplacés par le ping. Cela est présenté sous la forme d'un seul ID de joueur, d'un tableau ou d'une chaîne de caractères délimitée par des virgules.

on("chat:message", function(msg) {
  // Entrer "!pingtest" dans le chat pour exécuter le test
  if(msg.type == "api" && msg.content.indexOf("!pingtest") !== -1) {
 
    // pour obtenir un joueur spécifique, utiliser findObjs({_type: "player"})[i].id à la place de null pour le 3ème paramètre
    players = findObjs({_type: "player"});
    player1 = players[1].id;
    player2 = players[2].id;
 
    // Créer un tableau de tous les IDs des joueurs
    var allPlayerIDs = players.map(function(player) {
      return player['id'];
    });
 
    // Ping tout le monde sur cette page au même emplacement.
    sendPing(300, 300, Campaign().get('playerpageid'), null, true);
    setTimeout(function() {
        // Ping everyone on this page to the same location
        sendPing(1500, 500, Campaign().get('playerpageid'), msg.playerid, true, "");
    }, 1000);
    setTimeout(function() {
        // Ping only the specified player to this location
        sendPing(1200, 500, Campaign().get('playerpageid'), null, true, player1);
    }, 2000);
    setTimeout(function() {
        // Ping an array of player IDs (player 1 and 2) to this location
        sendPing(900, 100, Campaign().get('playerpageid'), player2, true, [player1, player2]);
    }, 3000);
    setTimeout(function() {
        // Ping a comma-separated list supplied as a string to this location
        sendPing(300, 300, Campaign().get('playerpageid'), player1, true, allPlayerIDs.join());
    }, 4000);
 
  }
})
 

A Note on Distances and Grids in Roll20

In Roll20, a "unit" is always 70 pixels on the screen. The "unit" is the building block that distance and the grid are built on top of. By default:

  • 1 unité = 5 pieds
  • 1 unité = 1 carré de la grille
  • Donc, 5 pieds = 1 unité = 1 carré

Cependant, le MJ peut modifier à la fois la taille de la grille et l'échelle de la distance. 1 unité est toujours de 70 pixels, mais le MJ peut modifier les paramètres de telle sorte que 1 unité équivaut désormais à 10 pieds (ce qui signifie que 70 pixels = 10 pieds) ou que chaque espace de la grille vaut 2 unités (ce qui signifie que chaque espace de la grille fait désormais 140 pixels).

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