API: Objet

Note :La propriétéidd'un objet est un identifiant unique à l'échelle mondiale : aucun objet ne doit avoir le même, même s'il s'agit d'un type d'objet différent. En outre, étant donné que l'identifiant d'un objet est fréquemment utilisé et qu'il ne change jamais, il existe un raccourci permettant d'y accéder en utilisantobj.idau lieu deobj.get("_id")si vous le souhaitez (l'un ou l'autre fonctionnera).

Pathv2 (Jumpgate Tabletop)

The shape property has the following values:

• "pol" - Polyline. A straight line is drawn between each consecutive point. If the starting point and ending point are the same, it creates a closed shape.
• "free" - Freehand. A curve is drawn using the points as guides. If the starting point and ending point are the same, it creates a closed shape.
• "eli" - Ellipse. An ellipse is draw using the points to set a bounding box. Only the first two points are used.
• "rec" - Rectangle. A rectangle is draw using the points to set a bounding box. Only the first two points are used.

The points property is a JSON string containing an array of points. Points are represented as a two position array of an x and y location. A triangle from (0,0) to (0,70) to (70,0), and back to (0,0) would be represented as "[[0,0],[0,70],[70,0],[0,0]]".

The x and y properties position the PathV2 object on the page. They specify where the center of the drawing should be. For some shapes (ellipses and rectangles), that is pretty easy to figure out. For more complex shapes (polylines and freehands), you will need to find the minimum and maximum values from the points property and use the point equidistant between them.

Path (Classic Tabletop)

Pour plus d'informations sur le format de_pathdonnées, consultez la section sur les chemins.

Fenêtre

Remarque : Les fenêtres et les portes utilisent un axe inversé par rapport à d'autres types d'objets. Par exemple, une variable top qui serait 100 pour un autre objet est y -100 pour une fenêtre ou une porte.

Example

on('chat:message', function(msg) {
    if (msg.type === 'api' && msg.content === '!cw') {
        const currentPageID = Campaign().get('playerpageid');
        const win = createObj('window', {
            x: 70,
            y: -70,
            pageid: currentPageID,
            path: {
		        handle0: {
        			x: -70,
        			y: 0,
        		},
        		handle1: {
        			x: 35,
        			y: 0,
        		},
        	},
            color: '#000000'
        });
    }

    if (msg.type === 'api' && msg.content === '!mw') {
        const win = getObj('window', '-NG38yUgghBBoV8YR0y1');
        win.set({
           x: 240,
           y: -139
        });
    }

    if (msg.type === 'api' && msg.content === '!dw') {
        const win = getObj('window', '-NG38yUgghBBoV8YR0y1');
        win.remove();
    }
});

Portes

Note: Les fenêtres et les portes utilisent un axe inversé par rapport aux autres types d'objets. Par exemple, une variable supérieure qui serait de 100 pour un autre objet est y -100 pour une fenêtre ou une porte.

Texte

Graphique (Jetons/Carte/Plateau/Etc.)

Icônes de jeton Example

{
          "id":59, // l'id de la base de données pour le
          "name":"Bane", // le nom (non-unique) du marqueur
          "tag":"Bane::59", // comment le jeton est référencé
          // cela inclura l'id pour les marqueurs personnalisés, mais pas
          // pour les marqueurs par défaut.
          "url":"https://s3.amazonaws.com/files.d20.io/images/59/yFnKXmhLTtbMtaq-Did1Yg/icon.png?1575153187"

          // ^l'url de l'image du marqueur de jeton
          }

Notes importantes sur les personnages et les jetons liés

Notez que pour les jetons liés aux personnages, le champcontrolledby sur le jeton est remplacé par le champcontrolledby du personnage.

Pour les barres de jetons (par exemplebar1_valueetbar1_max) dont le jeton est lié à un attribut (par exemplebar1_linkest défini), la définition d'une valeur pour la barre mettra automatiquement à jour les valeurscurrentet/oumaxde l'attribut sous-jacent, de sorte que vous n'aurez pas à définir les deux manuellement.

En outre, lorsque l'attribut (ou la barre de jetons) est modifié(e) dans le jeu, vous entendrez un événementchange:attribute(et une propriété spécifique, par exemplechange:attribute:current), suivi d'un événementchange:graphic(etchange:graphic:bar1_value). Vous pouvez choisir de répondre à l'un ou l'autre événement, mais les valeurs de la barre sous-jacente ne seront pas encore mises à jour lorsque l'événement d'attribut se déclenche, car il se déclenche en premier.

Notes importantes sur les marqueurs de statut

À partir du 6 août 2013, la manière dont les marqueurs de statut sur les jetons sont gérés a changé. La propriété "statusmarkers" de l'objet Graphique est désormais une liste de tous les couleurs/icônes de marqueurs de statut qui doivent être actifs sur le jeton, séparée par des virgules. Le format est le suivant :

//Séparé par des virgules (utilisez join pour créer ou split pour transformer en tableau). 
//Si une icône/couleur de statut est suivie d'un symbole "@", le nombre après 
//"@" sera affiché comme badge sur l'icône
statusmarkers = "rouge,bleu,crâne,mort,marron@2,vert@6"

Bien que vous puissiez accéder directement à la propriétéstatusmarkers, nous fournissons un ensemble de propriétés "virtuelles" sur l'objet que vous pouvez définir/obtenir pour travailler avec les marqueurs d'état, afin de maintenir la compatibilité ascendante avec les scripts existants et de fournir un moyen facile de travailler avec les marqueurs d'état sans avoir besoin d'écrire du code pour gérer la division et l'analyse de la chaîne de caractères vous-même. Chaque marqueur d'état a une propriété "status_<markername>" . Par exemple :

obj.get("status_red"); // Renvoie false si le marqueur n'est pas actif, true sinon, et une chaîne (i.e. "2" ou "5") si un badge est actuellement défini sur le marqueur
obj.get('status_bluemarker'); // Est encore pris en charge pour la compatibilité ascendante, et est équivalent à faire obj.get("status_blue");
obj.set("status_red", false); // retirerait le marqueur
obj.set("status_skull", "2"); // définitrait un badge "2" sur l'icône tête de mort et l'ajouterait au jeton s'il n'est pas déjà actif.

Notez que ces propriétés virtuelles n'ont pas d'événements, vous devez donc utiliserchange:graphic:statusmarkerspour écouter les changements des marqueurs d'état d'un jeton, et par exemplechange:graphic:status_redn'est PAS un événement valide et ne se déclenchera jamais.

Voici la liste complète des marqueurs d'état disponibles (dans le même ordre qu'ils apparaissent dans le plateau de marqueurs) :

"rouge", "bleu", "vert", "brun", "violet", "rose", "jaune", "mort", "crâne", "endormi", "demi-cœur", "demi-folie", "interdiction", "escargot", "hélice foudroyante", "clé à molette", "cœur enchaîné", "boulon chimique", "zone de mort", "buvez-moi", "fissure du bord", "masque de ninja", "chronomètre", "filet de pêche", "surmultipliée", "forte", "poing", "cadenas", "trois feuilles", "aile duveteuse", "pilonné", "piétiné", "fléché", "aura", "mal de dos", "drapeau noir", "oeil saignant", "bouclier à boulons", "coeur brisé", "toile d'araignée", "bouclier brisé", "drapeau volant", "radioactif", "trophée", "crâne brisé", "orbe gelé", "bombe roulante", "tour blanche", "saisir", "crier", "grenade", "fusil de sentinelle", "tout pour un", "tenue d'ange", "cible de tir à l'arc"

Page

Campagne

 Ordre de tour

L'ordre de tour est une chaîne JSON représentant la liste de l'ordre de tour actuel. Il s'agit d'un tableau d'objets. Actuellement, l'ordre de tour ne peut contenir que des objets d'une seule page à la fois - l'ID de page actuelle pour l'ordre de tour est l'attribut "initiativepage". Assurez-vous de les maintenir tous les deux synchronisés, sinon vous pourriez obtenir des résultats étranges.

Pour travailler avec l'ordre de tour, vous voudrez utiliserJSON.parse()pour obtenir un objet représentant l'état actuel de l'ordre de tour (REMARQUE: Vérifiez d'abord qu'il ne s'agit pas d'une chaîne vide""... s'il l'est, initialisez-le vous-même avec un tableau vide). Voici un exemple d'objet d'ordre de tour:

[
    {
     "id":"36CA8D77-CF43-48D1-8682-FA2F5DFD495F", //L'ID de l'objet graphique. Si cela est défini, la liste de l'ordre de tour récupérera automatiquement le nom et l'icône de la liste en fonction de l'objet graphique sur la table.
     "pr":"0", //La valeur actuelle de l'élément dans la liste. Peut être un nombre ou du texte.
     "custom":"" //Titre personnalisé pour l'élément. Sera ignoré si l'ID est défini sur une valeur autre que "-1".
    },
    {
     "id":"-1", //Pour les éléments personnalisés, l'ID DOIT être défini sur "-1" (notez que c'est une CHAÎNE, pas un NOMBRE.
     "pr":"12",
     "custom":"Test Custom" //Le nom à afficher pour les éléments personnalisés.
    }
]

Pour modifier l'ordre de passage, modifiez l'objet "ordre de passage" actuel, puis utilisezJSON.stringify()pour modifier l'attribut de la campagne. Notez que l'ordre des tours dans la liste est le même que l'ordre du tableau. Par exemple,push()ajoute un élément à la fin de la liste,unshift()l'ajoute au début, etc.

var turnorder;
if(Campaign().get("turnorder") == "") turnorder = []; //NOTE: We check to make sure that the turnorder isn't just an empty string first. If it is treat it like an empty array.
else turnorder = JSON.parse(Campaign().get("turnorder"));

//Add a new custom entry to the end of the turn order.
turnorder.push({
    id: "-1",
    pr: "15",
    custom: "Turn Counter"
});
Campaign().set("turnorder", JSON.stringify(turnorder));

Player

Macro

Table lancable

Élément de Table 

Caractère

Attribut

 Important : Voir la note ci-dessous sur l'utilisation des feuilles de caractères pour savoir comment les valeurs par défaut des feuilles de caractères affectent l'utilisation des attributs.

Capacité

Document à distribuer

Remarque :L'API n'a pas accès à la hiérarchie des dossiers. Les documents créés par l'API seront placés au niveau de la racine.

Pont

Notez qu'il existe des méthodes API d'assistance pour "tirer", "distribuer" ou "mélanger" les cartes du jeu. VoirAPI Update forum post from March 2018.

Carte

Man

Notez que chaque joueur ne devrait avoir QU'UNE seule main.

Piste de jukebox

Custom FX

restrictions des propriétés imgsrc et avatar

Bien que vous puissiez désormais modifier les propriétésimgsrcetavatar, nous avons mis en place les restrictions suivantes pour ces propriétés afin d'assurer la sécurité de tous les utilisateurs de Roll20 :

• Vous devez utiliser un fichier image téléchargé dans votre bibliothèque Roll20 - pas un site externe (comme Imgur) et pas le Marché Roll20. Il commencera par 'https://s3.amazonaws.com/files.d20.io/images/' pour les images téléchargées vers le serveur principal, ou 'https://s3.amazonaws.com/files.staging.d20.io/images/' pour les images téléchargées vers le serveur de développement. Vous pouvez consulter l'URL source d'une image en utilisant les outils de développement de votre navigateur.

• Vous devez inclure la chaîne de requête dans l'URL - par exemple, 'https://s3.amazonaws.com/files.staging.d20.io/images/123456/med.png?12345678', pas seulement 'https://s3.amazonaws.com/files.staging.d20.io/images/123456/med.png'

• Pour les objets graphiques (jetons), vous devez utiliser la taille "thumb" de l'image. Il devrait ressembler à 'https://s3.amazonaws.com/files.staging.d20.io/images/123456/thumb.png?12345678'.

Dans le futur, nous pourrions ajouter un outil pour que les images puissent être téléchargées spécifiquement pour être utilisées avec les scripts Mod (API), mais pour l'instant, utilisez simplement les images téléchargées dans votre propre bibliothèque. Notez que si vous supprimez une image de votre bibliothèque, elle sera supprimée de tous les jeux utilisant cette image, y compris les jeux utilisant vos scripts Mod (API).

Utilisation des champs Notes, GMNotes et Bio de manière asynchrone

Pour accéder aux champs "notes", "gmnotes" ou "bio" des personnages et des documents, vous devez passer une fonction de rappel en tant que deuxième argument de la fonction get(). Voici un exemple:

var character = getObj("character", "-JMGkBaMgMWiQdNDwjjS");
character.get("bio", function(bio) {
    log(bio); //do something with the character bio here.
});

Vous pouvez définir la valeur de ces champs normalement. Notez qu'il existe actuellement (au 09/05/2016) un bug avec ces champs asynchrones, où les définir en passant des valeurs à createObj échoue silencieusement, laissant l'objet dans un état étrange. Vous ne devriez définir ces valeurs qu'en utilisant .set jusqu'à ce que ce problème soit résolu. Détails sur leForum. Il y a aussi un bug (à partir du 05/11/2016) où essayer de définir à la fois les propriétés notes et gmnotes dans le même appel set() entraîne la définition erronée de la deuxième propriété dans l'appel. Détails sur leForum.

Travailler avec des fiches de personnage

La fonctionnalité des fiches de personnage affecte l'utilisation du type d'objet Attributs, car les fiches ont la possibilité de spécifier une valeur par défaut pour chaque attribut sur la fiche. Cependant, si l'attribut est défini sur la valeur par défaut, il n'existe pas encore d'objet Attribut réel créé dans le jeu pour ce personnage. Nous fournissons une fonction de commodité qui masque cette complexité pour vous. Vous devriez utiliser cette fonction pour obtenir la valeur d'un attribut à l'avenir, surtout si vous savez qu'un jeu utilise une fiche de personnage.

getAttrByName(character_id, attribute_name, value_type)

Il suffit de spécifier l'ID du caractère, le nom(et non l'ID) de l'attribut (par exemple "HP" ou "Str"), puis de préciser si vous souhaitez "current" ou "max" pour value_type. Voici un exemple :

var character = getObj("character", "-JMGkBaMgMWiQdNDwjjS");
getAttrByName(character.id, "str"); // la valeur actuelle de For, par exemple "12"
getAttrByName(character.id, "str", "max"); // la valeur max de For, par exemple "[[floor(@{STR}/2-5)]]"

Notez que les champs ayant des valeurs calculées automatiquement renverront la formule au lieu du résultat de la valeur. Vous pouvez ensuite transmettre cette formule à sendChat() pour utiliser le moteur de dés afin de calculer automatiquement le résultat pour vous.

Consultez également la documentation de la feuille de personnagepour plus d'informations sur la façon dont les feuilles de personnage interagissent avec l'API.

getAttrByNamen'obtiendra quela valeur de l'attribut, et non l'objet attribut lui-même. Si vous souhaitez vous référer à d'autres propriétés de l'attribut que "actuelle" ou "max", ou si vous souhaitez modifier des propriétés de l'attribut, vous devez utiliser l'une des autres fonctions ci-dessus, comme findObjs.

Dans le cas où l'attribut demandé n'existe pas,getAttrByName()renverraundefined.

Création d'objets

createObj(type, attributs)

Note : Vous pouvez actuellement créer des objets 'graphiques', 'texte', 'chemin', 'personnage', 'faculté', 'attribut', 'aide', 'tablederoll', 'élémentdetable' et 'macro'.

Vous pouvez créer un nouvel objet dans le jeu en utilisant la fonctioncreateObj. Vous devez indiquer le type de l'objet (l'une des propriétés valides_typede la liste des objets ci-dessus), ainsi qu'un objetattributscontenant une liste de propriétés pour l'objet. Notez que si l'objet a un objet parent (par exemple, les attributs et les facultés appartiennent aux personnages, les graphiques, les textes et les chemins appartiennent aux pages, etc.), vous devez spécifier dans la liste des propriétés l'ID du parent (par exemple, vous devez inclure la propriétécharacteridlors de la création d'un attribut). Notez également que même lors de la création de nouveaux objets, vous ne pouvez pas définir des propriétés en lecture seule, elles seront automatiquement définies sur leur valeur par défaut. La seule exception à cette règle est lors de la création d'un chemin, vous devez inclure la propriété 'path', mais elle ne peut pas être modifiée une fois que le chemin est créé initialement.

createObj retournera le nouvel objet, de sorte que vous pouvez continuer à travailler avec lui.

//Crée un nouvel attribut "Strength" sur tous les personnages ajoutés au jeu.
on("add:character", function(obj) {
    createObj("attribute", {
        name: "Strength",
        current: 0,
        max: 30,
        characterid: obj.id
    });
});

Supprimer des objets

object.remove()

Remarque : actuellement, vous pouvez supprimer des objets 'graphic', 'text', 'path', 'character', 'ability', 'attribute', 'handout', 'rollabletable', 'tableitem' et 'macro'.

Vous pouvez supprimer les objets de jeu existants en utilisant la fonction remove().remove(). La fonction .remove() fonctionne sur tous les objets que vous pouvez créer avec la fonction createObj. Vous appelez la fonction directement sur l'objet. Par exemple,mycharacter.remove();.

Objets Globaux

Il existe plusieurs objets disponibles globalement n'importe où dans votre script.

Campagne() (fonction)

Une fonction qui renvoie l'objetCampaign. Étant donné qu'il n'y a qu'une seule campagne, cette variable globale pointe toujours vers la seule campagne du jeu. Utile pour des choses comme vérifier si un objet est sur la page active en utilisantCampaign().get("playerpageid").

État

La variablestateest un objet global accessible à tous les scripts du jeu. Vous pouvez accéder à l'objetstatedepuis n'importe quelle fonction ou callback à tout moment en utilisant la variable globale nomméestate. En outre, l'objetstateest conservé entre les exécutions deSandbox, de sorte que vous pouvez l'utiliser pour stocker des informations dont vous souhaitez disposer lors des prochaines exécutions de votre script.

Note :Vous devez utiliser l'objet state pour stocker les informations dont l'API a seulement besoin, car elles ne sont pas envoyées aux ordinateurs des joueurs et ne rendent pas votre fichier de jeu plus volumineux. Stockez les valeurs nécessaires en jeu dans les propriétés des objets Roll20.

Types stockables

L'objetstaten'est capable de conserver que des types de données simples, comme le prévoit la normeJSON.

Attention :Si les fonctions semblent fonctionner lorsqu'elles sont stockées initialement dans l'état, elles disparaissent la première fois que l'étatest restauré à partir de la persistance, par exemple lors d'un redémarrage du bac à sable.

• Note :Cela inclut les objets Roll20 que vous obtenez à partir d'événements ou des fonctionsfindObjs(),getObj(),filterObjs(),createObj(), etc.

Rappels Importants

L'objetstateest partagé par tous les scripts d'un bac à sable. Pour éviter de casser d'autres scripts, il est important de suivre quelques directives simples :

• Ne jamaisassigner directement à l'objet racinestate.

state = { break: 'all the things' }; // NE JAMAIS FAIRE CELA !!!

• Évitezd'utiliser des variables locales nomméesstatedans vos scripts. Bien que cela fonctionne, cela sera déroutant pour les utilisateurs ultérieurs de vos scripts et pourrait causer des problèmes si le code est modifié sans précaution.

function turn(){
    var state = Campaign().get('turnorder');  // Mauvaise pratique, à éviter !
    // ...
}

• Toujoursplacer vos propriétés sous au moins une propriété d'espace de noms. Assurez-vous d'utiliser une propriété d'espace de noms suffisamment descriptive. Évitez les noms comme script ou settings. Il est préférable d'utiliser le nom de votre module ou votre propre nom ou pseudonyme.

if( ! state.MyModuleNamespace ) {
    state.MyModuleNamespace = { module: 'mon module', ok: 'c'est bien !', count: 0 };
}
state.MyModuleNamespace.count++;

Exemple d'utilisation

Il s'agit d'un exemple pratique qui utilise l'objetstatede manière appropriée.

on('ready',function() {
    "use strict" ;

    // Vérifier si la propriété namespaced existe, la créer si ce n'est pas le cas
    if( ! state.MyModuleNS ) {
        state.MyModuleNS = {
            version : 1.0,
            config : {
                color1: '#ff0000',
                color2: '#0000ff'
            },
            count : 0
        } ;
    }

    // Utilisation des propriétés de l'état pour configurer un message pour le chat. 
    sendChat(
        'Test Module',
        '<span style="color: '+state.MyModuleNS.config.color1+';">'+
            'State test'+
        '</span> '+
        '<span style="color: '+state.MyModuleNS.config.color2+';">'+
            'Script v'+state.MyModuleNS.version+' démarré '+(++state.MyModuleNS.count)+' fois!'+
        '</span>'
    ) ;
}) ;

Recherche/filtrage d'objets

L'API fournit plusieurs fonctions d'aide qui peuvent être utilisées pour trouver des objets.

getObj(type, id)
Cette fonction obtient un seul objet si le _type de l'objet et l'_id sont passés. Il est préférable d'utiliser cette fonction plutôt que les autres fonctions de recherche chaque fois que possible, car c'est la seule qui ne doit pas parcourir l'ensemble de la collection d'objets.

on("change:graphic:represents", function(obj) {
    Si(obj.get("represents") != "") {
       var personnage = getObj("character", obj.get("represents"));
    }
});

findObjs(attrs)

Transmettez cette fonction une liste d'attributs, et elle renverra tous les objets correspondants sous forme de tableau. Notez que cela s'applique à tous les objets de tous les types sur toutes les pages - donc vous voudrez probablement inclure au moins un filtre pour _type et _pageid si vous travaillez avec des objets de jeu de rôle.

var personnagesPageCourante = findObjs({                              
  _pageid: Campaign().get("playerpageid"),                              
  _type: "graphic",                          
});
_.each(personnagesPageCourante, function(obj) {    
  //Faites quelque chose avec obj, qui est sur la page actuelle et qui est un graphique.
});

Vous pouvez également passer un deuxième argument facultatif qui contient un objet avec une liste d'options, y compris :

• caseInsensitive(true/false) : Si vrai, les propriétés des chaînes de caractères seront comparées sans tenir compte de la casse de la chaîne.

var targetTokens = findObjs({
    name : "target"
}, {caseInsensitive: true}) ;
/Retourne tous les tokens dont le nom est "target", "Target", "TARGET", etc.

filterObjs(callback)

Exécute la fonction de rappel fournie sur chaque objet et, si la fonction de rappel renvoie un résultat positif, l'objet est inclus dans le tableau de résultats. Actuellement, il est déconseillé d'utiliser filterObjs() dans la plupart des cas - étant donné que findObjs() dispose d'un index intégré pour améliorer la vitesse d'exécution, il est presque toujours préférable d'utiliser findObjs() pour obtenir d'abord les objets du type souhaité, puis de les filtrer à l'aide de la méthode native .filter() pour les tableaux.

var results = filterObjs(function(obj) {    
  if(obj.get("left") < 200 && obj.get("top") < 200) return true ;    
  else return false ;
}) ;
//Results is an array of all objects that are in the top-left corner of the tabletop.

getAllObjs()

Renvoie un tableau de tous les objets du jeu (tous types confondus). Cela équivaut à appeler filterObjs et à renvoyertruepour chaque objet.

getAttrByName(character_id, attribute_name, value_type)

Obtient la valeur d'un attribut, en utilisant la valeur par défaut de la feuille de caractères si l'attribut n'est pas présent. value_typeest un paramètre facultatif, que vous pouvez utiliser pour spécifier "current" ou "max".

getAttrByNamen'obtiendra quela valeur de l'attribut, et non l'objet attribut lui-même. Si vous souhaitez référencer des propriétés de l'attribut autres que "current" ou "max", ou si vous souhaitez modifier des propriétés de l'attribut, vous devez utiliser l'une des autres fonctions ci-dessus, telles quefindObjs.

Pour les sections répétitives, vous pouvez utiliser le formatrepeating_section_$n_attribute, oùnest le numéro de ligne répétitive (en commençant par zéro). Par exemple,repeating_spells_$2_nameretournera la valeur denamede la troisième ligne derepeating_spells.

Vous pouvez obtenir le même comportement quegetAttrByNameavec ce qui suit :

// current and max are completely dependent on the attribute and game system
// in question; there is no function available for determining them automatically
function myGetAttrByName(character_id,
                         attribute_name,
                         attribute_default_current,
                         attribute_default_max,
                         value_type) {
    attribute_default_current = attribute_default_current || '';
    attribute_default_max = attribute_default_max || '';
    value_type = value_type || 'current';

    var attribute = findObjs({
        type: 'attribute',
        characterid: character_id,
        name: attribute_name
    }, {caseInsensitive: true})[0];
    if (!attribute) {
        attribute = createObj('attribute', {
            characterid: character_id,
            name: attribute_name,
            current: attribute_default_current,
            max: attribute_default_max
        });
    }

    if (value_type == 'max') {
        return attribute.get('max');
    } else {
        return attribute.get('current');
    }
}