API: Documentation des fonctions

Variables globales

(Underscore)

Il s'agit de l'objet d'espace de noms pour la bibliothèqueUnderscore.js. Underscore dispose de nombreuses fonctions pour la manipulation des collections.

État

Les propriétés de l'objet d'état persistent entre les sessions de jeu. Le même objet d'état est également partagé entre tous les scripts Mod (API) d'une campagne, il est donc fortement recommandé que lorsque vous écrivez des valeurs dans l'état, vous minimisiez votre empreinte autant que possible afin d'éviter les collisions de noms. Remarque : l'état est sérialisé avec JSON, vous ne pouvez donc pas stocker des fonctions ou des objets avec des références cycliques.

Fonctions globales

Campagne

Paramètres

Aucun paramètre

Retours

L'objet singleton Roll20 de la campagne.

Exemples

var currentPageID = Campaign().get('playerpageid'),
    currentPage = getObj('page', currentPageID) ;

créerObj

Paramètres

TYPE(String) Le type d'objet Roll20 à créer. Seuls 'graphic', 'text', 'path', 'character', 'ability', 'attribute', 'handout', 'rollabletable', 'tableitem' et 'macro' peuvent être créés.ATTRIBUTES(Object) Les valeurs initiales à utiliser pour les propriétés de l'objet Roll20.

Retours

L'objet Roll20 qui a été créé.

Exemples

Lors de la création d'un objet Roll20 ayant un objet parent (tel que la création d'un objet Roll20 attributaire, qui est un enfant d'un objet Roll20 personnage), vous devez fournir l'identifiant du parent dansattributs.

on('add:character', function(obj) {
    createObj('attribute', {
        name : 'Strength',
        current : 0,
        max : 30,
        characterid : obj.id
    }) ;
}) ;

Lors de la création d'un objet path Roll20, vous devez fournir une valeur pour la propriété en lecture seule_path. Il s'agit d'une exception à la règle qui vous empêche de définir la valeur des propriétés en lecture seule lors de la création d'objets Roll20.

createObj('path', {
    left : 7000,
    top : 140,
    width : 140,
    height : 140,
    layer : 'objects',
    path : JSON.stringify([['M', 0, 0], ['L', 70, 0], ['L', 0, 70], ['L', 0, 0]])
}) ;

Lors de la création d'un objet Roll20 handout, vous ne pouvez pas définir le texte ou les gmnotes au moment de la création.

var handout = createObj('handout', {
    name: 'A Letter Addressed to You',
    inplayerjournals: 'all',
    archived: false
}) ;
handout.set({
    notes: 'Notes can only be set after the handout is created',
    gmnotes: 'GM Notes can only be set after the handout is created'
}) ;

filterObjs

Paramètres

CALLBACK(Function) Une fonction prédicat pour tester tous les objets Roll20. La fonction de rappel reçoit un objet Roll20 comme paramètre et doit renvoyer soit true (pour les objets Roll20 qui seront inclus dans la valeur de retour de filterObjs), soit false (pour tous les autres objets Roll20).

Retours

Un tableau d'objets Roll20 qui ont passé le test du prédicat.

Exemples

var tokenName = getMyTokenName(),
    duplicateTokens = filterObjs(function(obj) {
        if (obj.get('type') !== 'graphic' || obj.get('subtype') !== 'token' || obj.get('name') === tokenName) return false ;
        return obj.get('name').indexOf(tokenName) === 0 && /\d+$/.text(obj.get('name')) ;
    }) ;

findObjs

Paramètres

ATTRIBUTES(Objet) Collection de paires clé/valeur à associer aux objets Roll20 de la campagne.OPTIONS(Objet, facultatif) Si options.caseInsensitive est vrai, les comparaisons de chaînes entre les objets Roll20 et les attributs ne tiendront pas compte de la casse.

Retours

Un tableau d'objets Roll20 avec des propriétés correspondantes àattributs.

Exemples

var npcs = findObjs({ type: 'character', controlledby: '' });

getAllObjs

Paramètres

Aucun paramètre

Retours

Un tableau de tous les objets Roll20 de la campagne.

Exemples

var everything = getAllObjs();

getAttrByName

Paramètres

CHARACTER_ID(String) L'ID de l'objet Roll20 du personnage qui est le parent de l'objet Roll20 de l'attribut dont vous voulez la valeur.ATTRIBUTE_NAME(String) Le nom de l'objet Roll20 de l'attribut dont vous voulez la valeur.VALUE_TYPE(String, facultatif) Soit "current" ou "max" (par défaut "current" si omis).

Renvoie

La propriétécurrent ou maxappropriée de l'attribut correspondant. Si la propriété souhaitée n'est pas définie, la valeur par défaut spécifiée par la fiche de personnage (s'il existe une valeur par défaut) sera utilisée.

Exemples

var character = getMyCharacter(),
    strength = getAttrByName(character.id, 'strength'),
    strength_max = getAttrByName(character.id, 'strength', 'max');

getObj

Paramètres

TYPE(String) Le type de l'objet Roll20 à obtenir.ID(String) L'identifiant unique de l'objet Roll20 à obtenir.

Renvoie

L'objet Roll20 spécifié.

Exemples

on('chat:message', function(msg) {
    var sendingPlayer = getObj('player', msg.playerid);
});

journal

Paramètres

MESSAGE(variable) Le message à afficher dans la console Mod (API). Le paramètre de message sera transformé en chaîne avec JSON.stringify.

Renvoie

(Vide)

Exemples

on('chat:message', function(msg) {
    journal('Message reçu de :');
    journal(getObj('player', msg.playerid));
});

"Message reçu de :"
{"_d20userid":"123456","_displayname":"John Doe","speakingas":"","_online":true,"color":"#885b68","_macrobar":"-J16Z-dRU5tleKiKOg0X|-K3F_4q_b1p-Vdiwgn1t","showmacrobar":true,"_id":"-J16Z-dRU5tleKiKOc0X","_type":"joueur","_lastpage":""}

sur

Paramètres

ÉVÉNEMENT(String) Il existe cinq types d'événement:prêtchangementajoutdestructiondiscussionA l'exception de prêt, tous les types d'événement doivent également être associés à un type d'objet. Pour discussion, c'est toujours message. Pour tout le reste, c'est la propriété type d'un objet Roll20. En plus du type d'objet, les événements de changement peuvent également spécifier facultativement une propriété de l'objet Roll20 spécifié.Les 2-3 parties de l'événement (type, objet et éventuellement propriété) sont séparées par des deux-points. Ainsi, les chaînes d'événement valides incluent mais ne se limitent pas à "prêt", "discussion:message", "changement:graphique", "changement:campagne:idpagejoueur", "ajout:personnage" et "destruction:fichier".APPELRETOUR(Fonction)La fonction qui sera appelée lorsque l'événement spécifié sera déclenché. Les paramètres passés dépendent du type d'événement: les événements de prêt n'ont pas de paramètres de rappel; les événements de changement ont un paramètre obj, qui est une référence à l'objet Roll20 tel qu'il existe après le changement, et un paramètre prev, qui est un objet JavaScript ordinaire avec des propriétés correspondant à l'objet Roll20 avant l'événement de changement; les événements d'ajout ont un paramètre obj, qui est une référence au nouvel objet Roll20; les événements de destruction ont un paramètre obj, qui est une référence à l'objet Roll20 qui n'existe plus; les événements de discussion ont un paramètre msg, qui contient les détails du message qui a été envoyé dans le chat.

Renvoi

(Vide)

Exemples

Les événements sont déclenchés dans l'ordre où ils ont été enregistrés, du plus spécifique au moins spécifique. Dans cet exemple, une modification de la propriétéleftd'un objet graphique Roll20 entraînera l'appel de la fonctionfunction3, puis de la fonctionfunction1et enfin de la fonctionfunction2.

on ('change:graphic', fonction1);
on ('change:graphic', fonction2);
on ('change:graphic:left', fonction3);

Les événements ajoutenttenteront de se déclencher pour les objets Roll20 déjà présents dans la campagne lorsqu'une nouvelle session démarre. Afin d'éviter ce comportement, vous pouvez attendre pour enregistrer votrepour ajouterévénement jusqu'à ce que lesoit prêt et que lese déclenche.

on('add:graphic', function(obj) {
    // Lorsque la session commence, cette fonction sera appelée pour chaque élément graphique de la campagne
    // Cette fonction sera également appelée chaque fois qu'un nouvel objet graphique Roll20 est créé
});

on('ready', function() {
    on('add:graphic', function(obj) {
        // Cette fonction ne sera *jamais* appelée pour un objet graphique Roll20 déjà existant, seulement pour les nouveaux
    });
});

Le paramètreprépour les événementschangen'est pas un objet Roll20, mais un simple objet JavaScript. En conséquence, vous ne pouvez pas utiliser les fonctionsgetouset, et vous ne pouvez pas omettre les tirets bas au début des propriétés en lecture seule.

on('change:graphic', function(obj, prev) {
    var id1 = obj.id,         // all three are equivalent
        id2 = obj.get('id'),
        id3 = obj.get('_id'),

        id4 = prev.id,        // undefined
        id5 = prev.get('id'), // undefined is not a function
        id6 = prev._id;       // correct

    // both are equivalent
    obj.set('left', 70);
    obj.set({
        left: 70
    });

    prev.set('left', 70); // undefined is not a function
    prev.set({            // undefined is not a function
        left: 70
    });
    prev.left = 70;       // correct, although it won't change anything on the tabletop
});

Pour les champs asynchrones des objets Roll20 (notes,gmnotes, etbio), le paramètreprevne contiendra pas les données dont vous avez besoin. (Il aura plutôt un identifiant numérique utilisé par le système.) Si vous avez besoin d'accéder à la valeur précédente de l'un de ces champs, vous devrez la suivre vous-même:

on('ready', function() {
    if (!state.example) state.example = { bioCache : {} } ;
}) ;

on('change:character:bio', function(obj, prev) {
    obj.get('bio', function(text) {
        state.example.bioCache[obj.id] = text ;

        // do stuff...

        if (shouldRevertBio()) {
            obj.set('bio', state.example.bioCache[obj.id]) ;
        }.
    }) ;
}) ;

onSheetWorkerCompleted

Paramètres

CALLBACK(Function) Fonction qui sera appelée lorsque la "pile" actuelle de scripts de travailleur à la feuille sera terminée.

Retours

(Vide)

Exemples

Cette fonction doit être appelée avant setWithWorker. La fonction de rappelne sera appelée qu'une seule fois.

var myCharacter = ...,
    mySourceAttr = findObjs({ type: 'attribute', characterid: myCharacter.id, name: 'mySourceAttribute' })[0];

onSheetWorkerCompleted(function() {
    var calculatedAttr = findObjs({ type: 'attribute', characterid: myCharacter.id, name: 'myCalculatedAttribute' })[0];
    // do something with calculatedAttr.get('current');
});
mySourceAttr.setWithWorker({ current: 5 });

playerIsGM

Parameters

PLAYER_ID(String) The id of the player Roll20 object to check.

Returns

trueif the player currently has GM permissions, orfalseotherwise.

Examples

Cette fonction est particulièrement utile pour limiter les commandes Mod (API) à une utilisation par le MJ.

on('chat:message', function(msg) {
    if (msg.type  !== 'api') return;

    if (msg.content.indexOf('!playercommand') === 0) {
        // ...
    } else if (msg.content.indexOf('!gmcommand') === 0) {
        if (!playerIsGM(msg.playerid)) return;
        // ...
    }
});

playJukeboxPlaylist

Parameters

PLAYLIST_ID(String) The id of the playlist to start playing.

Returns

(Void)

Examples

var playlists = JSON.parse(Campaign().get('jukeboxfolder')),
    myPlaylist = _.find(playlists, (folder) => _.isObject(folder) && folder.n === myPlaylistName);
playJukeboxPlaylist(myPlaylist.id);

randomInteger

Parameters

MAX(Number) The maximum number to return, inclusive.

Retours

Un nombre entier aléatoire entre 1 (inclus) et max (inclus). Cette fonction a une meilleure distribution que Math.random(), et elle est recommandée à sa place. Cette fonction n'utilise pas la fonctionQuantum Rollutilisée par le moteur de dés, mais elle utilise le même algorithme pseudo-aléatoire que celui utilisé par le moteur de dés si Quantum Roll n'est pas disponible.

Exemples

Parce que cette fonction renvoie un entier de 1 àmax, elle est idéale pour générer rapidement un résultat de lancer de dé si vous n'avez pas besoin de l'intégralité de la puissance du moteur de dés de Roll20.

var d20Result = randomInteger(20); // approximativement équivalent à lancer un dé à 20 faces

sendChat Asynchrone

Paramètres

SPEAKINGAS(String) Le nom à attacher au message en cours d'envoi. Si speakingAs est au format player|player_id ou character|character_id, le message sera envoyé en tant que joueur ou personnage. Sinon, le message utilisera le nom donné comme si un MJ avait utilisé la commande /as.MESSAGE(String) Le message à envoyer dans la discussion.CALLBACK(Function, facultatif) Si callback est spécifié, le résultat du message de discussion lui sera transmis au lieu d'apparaître dans la discussion. Le paramètre de la méthode de rappel est un tableau d'objets de message.OPTIONS(Object, facultatif) Si options.noarchive est true, le message ne sera pas ajouté à l'archive de discussion. Si les options.use3d sont true, les lancers de dés dans le message utiliseront la fonctionnalité de dés 3D. Les options ne s'appliquent pas si un rappel est spécifié.

Retourne

(Vide)

Exemples

sendChat('Example', 'Ceci est un exemple simple.');

Vous pouvez facilement écrire du code pour envoyer un message en tant que même joueur ou personnage qui a déclenché un événement chat:message.

on('chat:message', function(msg) {
    var character = findObjs({ type: 'character', name: msg.who })[0],
        player = getObj('player', msg.playerid),
        message = ' a dit quelque chose';

    if (character) sendChat('character|'+character.id, character.get('name')+message);
    else sendChat('player|'+player.id, player.get('displayname')+message);
});

Le paramètrecallbackest utile si vous avez besoin d'exploiter le moteur de désde Roll20. La valeurspeakingAsn'est pas particulièrement nécessaire lors de l'utilisation du rappel, puisque le message n'apparaîtra de toute façon pas dans le chat.

sendChat('', '/r 2d20k1+'+strengthMod, function(ops) {
    var msg = ops[0];
    // ...
});

options.noarchiveest principalement conçu pour envoyer aux joueurs des menus créés à partir de boutons de commande d'APIsans encombrer leur historique de discussion.

sendChat('System', '[Effacer les changements](!clear)\n[Ajouter une tuile](!add)\n[Voir un exemple](!view)\n[Enregistrer la disposition](!save)', null, { noarchive: true });

sendPing

Paramètres

LEFT(Number) La coordonnée x où placer le ping.TOP(Number) La coordonnée y où placer le ping.PAGE_ID(String) L'identifiant de la page Roll20 pour placer le ping.PLAYER_ID(String, optionnel) Le ping utilisera la couleur du joueur spécifié. Si player_id est omis, le ping sera jaune.MOVEALL(Boolean, optionnel) Si moveAll est true, toutes les vues des joueurs sur la page appropriée auront leur point de vue centré sur le ping.

Note: Actuellement, seuls les MJ auront leur point de vue centré si moveAll est true. Ce comportement est documenté ici

Retours

(Vide)

Exemples

on('chat:message', function(msg) {
    var obj ;
    if (msg.type === 'api' && msg.content.indexOf('!ping') === 0) {
        if (!msg.selected) return ;
        obj = getObj(msg.selected[0]._type, msg.selected[0]._id) ;
        sendPing(obj.get('left'), obj.get('top'), obj.get('pageid'), msg.playerid, true) ; // centre tout le monde sur le token sélectionné
    }
}) ;

spawnFx

Paramètres

LEFT(Number) La coordonnée x pour placer l'émetteur de particules.TOP(Number) La coordonnée y pour placer l'émetteur de particules.TYPE(String) Le type d'émetteur de particules à placer. Pour les effets intégrés, il s'agit de "type-couleur", où le type est l'un des suivants : bombe, bulle, brûlure, éclatement, explosion, lueur, missile ou nova, et la couleur l'une des suivantes : acide, sang, charme, mort, feu, givre, saint, magie, bave, fumée ou eau. Pour les effets personnalisés, ceci devrait être l'identifiant de l'objet FX Roll20. Remarque : les types de faisceau, souffle et éclaboussure ne peuvent pas être utilisés avec spawnFx. Voir spawnFxBetweenPoints à la place. PAGE_ID (chaîne, facultatif) L'identifiant de l'objet Roll20 de la page sur laquelle placer l'émetteur de particules. Si omis, Campaign().get('playerpageid') sera utilisé à la place.

Retourne

(Vide)

Exemples

spawnFx(1400, 1400, 'bubbling-acid');

spawnFxBetweenPoints

Paramètres

START(Objet) Le point de départ de l'émetteur de particules. Le point devrait être au format { x: nombre, y: nomb}) END(Objet) Le point final de l'émetteur de particules. Le point devrait être au format { x: nombre, y: nombre } TYPE(Chaîne) Le type d'émetteur de particules à placer. Pour les effets intégrés, cela devrait être "type-color", où le type est l'un des suivants : faisceau, bombe, souffle, bouillonnement, brûlure, explosion, lueur, projectile, nova ou éclaboussure, et la couleur est l'une des suivantes : acide, sang, charme, mort, feu, gel, saint, magie, limon, fumée ou eau. Pour les effets personnalisés, cela devrait être l'identifiant de l'objet FX de Roll20.PAGE_ID(String, optionnel) L'identifiant de la page Roll20 sur laquelle placer l'émetteur de particules. Si omis, Campaign().get('playerpageid') sera utilisé à la place.

Renvoie

(Void)

Exemples

spawnFxBetweenPoints({ x: 1400, y: 1400 }, { x: 2100, y: 2100 }, 'beam-acid');

spawnFxWithDefinition

Paramètres

GAUCHE(Number) La coordonnée x pour placer l'émetteur de particules.HAUT(Number) La coordonnée y pour placer l'émetteur de particules.DÉFINITION(Objet) Les caractéristiques de l'émetteur de particules à placer. Consultez Custom FX pour une liste des propriétés possibles et les propriétés des types et couleurs d'émetteurs de particules par défaut. Voir FX Library pour des effets personnalisés créés par les utilisateurs de Roll20.PAGE_ID(String, optional) L'identifiant de la page de l'objet Roll20 sur laquelle l'émetteur de particules doit être placé. En cas d'omission, Campaign().get('playerpageid') sera utilisé à la place.

Retours

(Vide)

Exemples

// ces deux éléments sont équivalents
spawnFx(1400, 1400, 'bubbling-acid') ;
spawnFxWithDefinition(1400, 1400, {
    maxParticles : 200,
    size : 15,
    sizeRandom : 3,
    lifeSpan : 20,
    lifeSpanRandom : 5,
    speed : 7,
    speedRandom : 2,
    gravity : { x: 0.01, y: 0.65 },
    angle : 270,
    angleRandom : 35,
    emissionRate : 1,
    startColour : [0, 35, 10, 1],
    startColourRandom : [0, 10, 10, 0.25],
    endColour : [0, 75, 30, 0],
    endColourRandom :   [0, 20, 20, 0]
}) ;

stopJukeboxPlaylist

Parameters

No parameters

Returns

(Void)

Examples

stopJukeboxPlaylist();

toBack

Parameters

OBJ(Roll20 object) The Roll20 object to send to the back of its layer.

Returns

(Void)

Examples

on('chat:message', function(msg) {
    if (msg.type === 'api' && msg.content === '!toback' && msg.selected) {
        _.each(msg.selected, (s) => {
            toBack(getObj(s._type, s._id));
        });
    }
});

toFront

Parameters

OBJ(Roll20 object) The Roll20 object to bring to the front of its layer.

Returns

(Void)

Examples

on('ready', function() {
    on('add:graphic', function(obj) {
        toFront(obj);
    });
});