API : Documentation des fonctions

Variables globales

_ (Tiret bas)

Il s'agit de l'objet d'espace de noms pour l' Underscore.js . Underscore propose de nombreuses fonctions pour la manipulation de collections.

état

Les propriétés de l'objet d'état seront conservées 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é, lorsque vous écrivez des valeurs dans l'état, de minimiser autant que possible votre empreinte afin d'éviter les conflits de noms. Remarque : l'état est sérialisé avec JSON, vous ne pouvez donc pas stocker de fonctions ou d'objets avec des références cycliques.

Fonctions globales

Campagne

Paramètres

Aucun paramètre

Retours

L'objet Roll20 de la campagne unique.

Exemples

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

créerObj

Paramètres

TYPE(Chaîne) Le type d'objet Roll20 à créer. Seuls « graphic », « text », « path », « personnage », « ability », « attribute », « document », « rollabletable », « tableitem » et « macro » peuvent être créés. ATTRIBUTES(Object) 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 qui possède un objet parent (par exemple, lors de la création d'un objet Roll20 attribut, qui est un enfant d'un objet Roll20 personnage), il est nécessaire de fournir l'identifiant du parent dansles attributs.

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

Lors de la création d'un objet Roll20 de type chemin, il est nécessaire de fournir une valeur pour la propriété en lecture seule_path. Il s'agit d'une exception à la règle qui 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,
    theight: 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 Document, il n'est pas possible de définir le texte ou les notes du maître du jeu 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(Fonction) Une fonction prédicative permettant de tester tous les objets Roll20. La fonction de rappel reçoit un objet Roll20 en tant que paramètre et doit renvoyer soit true (pour les objets Roll20 qui seront inclus dans la valeur de retour filterObjs), soit false (pour tous les autres objets Roll20).

Retours

Un tableau d'objets Roll20 qui ont réussi le test de 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) Ensemble de paires clé:valeur à associer aux objets Roll20 dans 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

Tableau d'objets Roll20 dont les propriétés correspondentaux attributs.

Exemples

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

obtenirTousLesObjets

Paramètres

Aucun paramètre

Retours

Tableau de tous les objets Roll20 de la campagne.

Exemples

var tout = getAllObjs();

getAttrByName

Paramètres

CHARACTER_ID(Chaîne) Identifiant de l'objet Roll20 du personnage qui est le parent de l'objet Roll20 de l'attribut dont vous souhaitez obtenir la valeur.ATTRIBUTE_NAME(Chaîne) Le nom de l'objet Roll20 attribut dont vous souhaitez obtenir la valeur. VALUE_TYPE(Chaîne, facultatif) Soit « current » (actuel), soit « max » (maximum) (la valeur par défaut est « current » si elle est omise).

Retours

La propriétéactuelleoumaximalede l'attribut approprié. Si la propriété souhaitée n'est pas définie, la valeur par défaut spécifiée dans la feuille de personnage (s'il y en a une) sera utilisée à la place.

Exemples

var personnage = getMyPersonnage(),
    strength = getAttrByName(personnage.id, 'strength'),
    strength_max = getAttrByName(personnage.id, 'strength', 'max');

getObj

Paramètres

TYPE(Chaîne) Le type d'objet Roll20 à récupérer. ID(Chaîne) L'identifiant unique de l'objet Roll20 à récupérer.

Retours

L'objet Roll20 spécifié.

Exemples

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

journal

Paramètres

MESSAGE(variable) Le message à envoyer à la console Mod (API). Le paramètre message sera converti en chaîne de caractères à l'aide de JSON.stringify.

Retours

(Nul)

Exemples

on('chat:message', function(msg) {
    log('Message reçu de :');
    log(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":"player","_lastpage":""}

sur

Paramètres

EVENT(Chaîne) Il existe cinq types d'événements : ready, change, add, destroy et chat. À l'exception de ready, tous les types d'événements doivent également être associés à un type d'objet. Pour le chat, il s'agit toujours d'un message. Pour tout le reste, il s'agit de la propriété de type d'un objet Roll20. En plus du type d'objet, les événements de modification peuvent également spécifier une propriété de l'objet Roll20 à surveiller. 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énements valides comprennent, sans s'y limiter, « ready », « chat:message », « change:graphic », « change:campaign:playerpageid », « add:personnage » et « destroy:document ». CALLBACK(Fonction) La fonction qui sera appelée lorsque l'événement spécifié se produira. Les paramètres transmis dépendent du type d'événement : les événements « ready » n'ont pas de paramètres de rappel. Les événements « change » 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 classique avec des propriétés correspondant à l'objet Roll20 avant l'événement de changement.Les événements « add » ont un paramètre « obj », qui est une référence au nouvel objet Roll20. Les événements « destroy » ont un paramètre « obj », qui est une référence à l'objet Roll20 qui n'existe plus. Les événements « chat » ont un paramètre « msg », qui contient les détails du message qui a été envoyé au chat.

Retours

(Nul)

Exemples

Les événements sont déclenchés dans l'ordre dans lequel ils ont été enregistrés, du plus spécifique au moins spécifique. Dans cet exemple, une modification de la propriétégauched'un objet graphique Roll20 entraînera l'appel dela fonction3, suivie dela fonction1, puis dela fonction2.

on('change:graphic', function1);
on('change:graphic', function2);
on('change:graphic:left', function3);

Les événements « add »tenteront de se déclencher pour les objets Roll20 déjà présents dans la campagne lorsqu'une nouvelle session commence. Afin d'éviter ce comportement, il est conseillé d'attendre que l'événement «ready» se déclenche avant d'enregistrer votre événement «add».

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

on('ready', function() {
    on('add:graphic', function(obj) {
        // Cette fonction sera appelée *uniquement* lorsqu'un nouvel objet graphique Roll20 est créé, et non pour ceux qui existent déjà
    });
});

Le paramètreprepour les événementsde modificationn'est pas un objet Roll20, mais un simple objet JavaScript classique. Par conséquent, il n'est pas possible d'utiliser les fonctionsgetouset, et il est nécessaire de conserver les traits de soulignement au début des propriétés en lecture seule.

on('change:graphic', function(obj, prev) {
    var id1 = obj.id, // les trois sont équivalents
        id2 = obj.get('id'),
        id3 = obj.get('_id'),

        id4 = prev.id, // indéfini
        id5 = prev.get('id'), // undefined n'est pas une fonction
        id6 = prev._id;       // correct

    // les deux sont équivalents
    obj.set('left', 70);
    obj.set({
        left: 70
    });

    prev.set('left', 70); // undefined n'est pas une fonction
    prev.set({ // undefined n'est pas une fonction
        left: 70
    });
    prev.left = 70; // correct, bien que cela ne change rien sur la table
});

Pour les champs asynchrones des objets Roll20 de type personnage et document (notes,gmnotes etbio), le paramètreprevne contiendra pas les données requises. (Il comportera à la place 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 en assurer le suivi vous-même :

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

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

        // effectuer des actions...

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

surSheetWorkerCompleted

Paramètres

CALLBACK(Fonction) La fonction qui sera appelée lorsque la « pile » actuelle des scripts de feuille sera terminée.

Retours

(Nul)

Exemples

Cette fonction doit être appelée avant setWithWorker. La fonctionde 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];
    // effectuer une action avec calculatedAttr.get('current');
});
mySourceAttr.setWithWorker({ current: 5 });

joueurEstGM

Paramètres

PLAYER_ID(Chaîne) Identifiant de l'objet Roll20 du joueur à vérifier.

Retours

vraisi le joueur dispose actuellement des autorisations MJ,fauxdans le cas contraire.

Exemples

Cette fonction est particulièrement utile pour limiter les commandes Mod (API) à l'usage des 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;
        // ...
    
);

Lecteur Jukebox Liste de lecture

Paramètres

PLAYLIST_ID(Chaîne) Identifiant de la liste de lecture à démarrer.

Retours

(Nul)

Exemples

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

nombre entier aléatoire

Paramètres

MAX(Nombre) Le nombre maximal à renvoyer, inclus.

Retours

Un nombre entier aléatoire compris entre 1 (inclus) etmax(inclus). Cette fonction offre une meilleure distribution queMath.random() et est donc recommandée à sa place. Cette fonction n'utilise pas le Jet quantique utilisée par le moteur de dés, mais elle utilise le même algorithme pseudo-aléatoire que celui auquel le moteur de dés aura recours si le Jet quantique n'est pas disponible.

Exemples

Étant donné que cette fonction renvoie un nombre entier compris entre 1 etmax, elle est idéale pour générer rapidement le résultat d'un lancer de dés si vous n'avez pas besoin de toute la puissance du moteur de dés de Roll20. ..

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

sendChat Asynchrone

Paramètres

SPEAKINGAS(Chaîne) Le nom à associer au message envoyé. Si speakingAs est au format joueur|joueur_id ou personnage|personnage_id, le message sera envoyé en tant que ce joueur ou ce personnage. Dans le cas contraire, le message utilisera le nom donné comme si un MJ avait utilisé la commande /as. MESSAGE(Chaîne) Le message à envoyer au chat. CALLBACK(Fonction, facultatif) Si callback est spécifié, le résultat du message de chat lui sera transmis au lieu d'apparaître dans le chat. Le paramètre de la méthode de rappel est un tableau d'objets message. OPTIONS (Objet, facultatif) Si options.noarchive est vrai, le message ne sera pas ajouté aux archives des chats. Si options.use3d est défini sur « true », les lancers de dés dans le message utiliseront la fonctionnalité de dés en 3D. Les options ne sont pas applicables si le rappel est spécifié.

Retours

(Nul)

Exemples

sendChat('Exemple', '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énementchat:message.

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

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

Le paramètrecallbackest utile si vous avez besoin d'utiliser le moteur de dés de Roll20. moteur de dés. Il n'est pas nécessaire d'utiliser la valeurspeakingAslors de l'utilisation durappel, car le message n'apparaîtra pas dans le chat de toute façon.

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 API sans encombrer leur historique de discussion.

sendChat('Système', '[Effacer les modifications](!clear)\n[Ajouter une vignette](!add)\n[Afficher un exemple](!view)\n[Enregistrer la disposition](!save)', null, { noarchive: true });

envoyer un ping

Paramètres

LEFT(Nombre) La coordonnée x à laquelle placer le ping. TOP(Nombre) La coordonnée y à laquelle placer le ping. PAGE_ID(Chaîne) L'identifiant de l'objet Roll20 de la page sur lequel placer le ping. PLAYER_ID(Chaîne, facultatif) Le ping utilisera la couleur du joueur spécifié. Si player_id est omis, le ping sera jaune. MOVEALL(Booléen, facultatif) Si moveAll est vrai, tous les joueurs de la page appropriée verront leur vue centrée sur le ping.

Remarque :pour le moment, seuls les GM verront leur affichage centré simoveAllest défini surtrue. Ce comportement est documenté ici.

Retours

(Nul)

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); // centrer tout le monde sur le jeton sélectionné
    }
});

spawnFx

Paramètres

GAUCHE(Nombre) : Coordonnée x pour positionner l'émetteur de particules. HAUT(Nombre) : Coordonnée y pour positionner l'émetteur de particules. TYPE(Chaîne) : Type d'émetteur de particules à positionner. Pour les effets intégrés, il devrait s'agir de « type-couleur », où le type est l'un des suivants : bombe, bulles, brûlure, explosion, lueur, missile ou nova, et la couleur est l'une des suivantes : acide, sang, charme, mort, feu, givre, sacré, magie, boue, fumée ou eau. ou water. Pour les effets personnalisés, il s'agit de l'identifiant de l'objet FX Roll20. Remarque : les types beam, breath et splatter ne peuvent pas être utilisés avec spawnFx. Veuillez consulter spawnFxBetweenPoints à la place. PAGE_ID(chaîne, facultatif) Identifiant de l'objet Roll20 de la page sur lequel placer l'émetteur de particules. Si cette information est omise, Campaign().get('playerpageid') sera utilisé à la place.

Retours

(Nul)

Exemples

spawnFx(1400, 1400, « acidité bouillonnante ») ;

générer des effets entre des points

Paramètres

START(Objet) Le point de départ de l'émetteur de particules. Le point doit être au format { x : nombre, y : nombre }.END(Objet) Le point final pour l'émetteur de particules. Le point doit être au format { x : nombre, y : nombre }.TYPE(String) Le type d'émetteur de particules à placer. Pour les effets intégrés, il devrait s'agir de « type-couleur », où le type est l'un des suivants : rayon, bombe, souffle, bulles, brûlure, explosion, lueur, missile, nova, ou éclaboussure et « color » est l'un des suivants : acide, sang, charme, mort, feu, givre, sacré, magie, boue, fumée ou eau. Pour les effets personnalisés, il s'agit de l'identifiant de l'objet FX Roll20. PAGE_ID(chaîne, facultatif) Identifiant de l'objet Roll20 de la page sur lequel placer l'émetteur de particules. Si cette information est omise, Campaign().get('playerpageid') sera utilisé à la place.

Retours

(Nul)

Exemples

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

spawnFxWithDefinition

Paramètres

GAUCHE(Nombre) : Coordonnée x pour positionner l'émetteur de particules. HAUT(Nombre) : Coordonnée y pour positionner l'émetteur de particules. DÉFINITION(Objet) : Caractéristiques de l'émetteur de particules à positionner. Veuillez consulter la section Effets personnalisés pour obtenir la liste des propriétés disponibles ainsi que les propriétés des types et couleurs d'émetteurs de particules par défaut. Veuillez consulter la bibliothèque FX pour découvrir certains effets personnalisés créés par les utilisateurs de Roll20. PAGE_ID(chaîne, facultatif) Identifiant de l'objet Roll20 de la page sur lequel placer l'émetteur de particules. Si cette information est omise, Campaign().get('playerpageid') sera utilisé à la place.

Retours

(Nul)

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,
    angle aléatoire : 35,
    taux d'émission : 1,
    couleur de départ :       [0, 35, 10, 1],
    couleur de départ aléatoire : [0, 10, 10, 0,25],
    endColour:         [0, 75, 30, 0],
    endColourRandom:   [0, 20, 20, 0]
});

Arrêter la lecture de la liste de lecture du jukebox

Paramètres

Aucun paramètre

Retours

(Nul)

Exemples

arrêterJukeboxPlaylist() ;

Retour

Paramètres

OBJ(objet Roll20) L'objet Roll20 à placer à l'arrière de son calque.

Retours

(Nul)

Exemples

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

Paramètres

OBJ(objet Roll20) L'objet Roll20 à placer au premier plan de son calque.

Retours

(Nul)

Exemples

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