1. Centre d'aide Roll20
  2. Automatisations
  3. Scripts de modification (API)

Scripts de mod : documentation sur les fonctions

Roll20 propose un certain nombre de fonctions qui ne font pas partie du JavaScript de base ni d'aucune autre bibliothèque.

Les jeux peuvent utiliser Mod Script Bac à sable v1.0 (Campaign().sandboxVersion === "1.0") ou v1.5 ("1.5"). Fonctionnalités réservées à la version 1.5 de Mod Script Bac à sable. ne fonctionnent pas avec la version 1.0.

Variables globales

Variable Description
_ Il s'agit de l'objet d'espace de noms de la bibliothèque Underscore.js.
état Les propriétés de l'objet d'état seront conservées entre les sessions de jeu.

_ (trait de soulignement)

Il s'agit de l'objet d'espace de noms de la bibliothèque 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 d'une campagne ; il est donc vivement recommandé, lorsque vous enregistrez des valeurs dans cet objet d'état, de réduire au maximum votre empreinte afin d'éviter tout conflit 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

Type de retour Fonction Description
Objet Roll20 Campagne Récupère l'objet unique Campaign Roll20.
Objet Roll20 créerObj Permet de créer un nouvel objet Roll20.
Tableau d'objets Roll20 filterObjs Récupère tous les objets Roll20 qui satisfont à un test prédicat.
Tableau d'objets Roll20 findObjs Récupère tous les objets Roll20 dont les propriétés correspondent à un ensemble d'attributs donné.
Tableau d'objets Roll20 obtenirTousLesObjets Récupère tous les objets Roll20 de la campagne.
varie getAttrByName Obtient la valeur actuelle ou maximale d'un attribut d'objet Roll20.
varie getComputed Uniquement pour le script Mod Bac à sable v1.5. Récupère une propriété calculée de type « Beacon ».
varie getSheetDefaultValue Récupère la valeur par défaut d'une feuille de personnage pour un nom d'attribut.
varie getSheetItem Récupère un article de la feuille (attribut ; à partir de la version 1.5, également Beacon / user.*).
Objet Roll20 getObj Récupère un objet Roll20 spécifique.
journal Enregistre un message dans la console de sortie Mod.
sur Enregistre un gestionnaire d'événements.
surSheetWorkerCompleted Enregistre un gestionnaire d'événements à exécuter une seule fois, une fois que la pile complète des scripts de feuille a été traitée.
exécuterAction Uniquement pour le script Mod Bac à sable v1.5. Exécute une action de la feuille « Beacon ».
Booléen joueurEstGM Vérifie si un joueur dispose actuellement des privilèges de MJ.
Lecteur Jukebox Liste de lecture Veuillez commencer à lire une liste de lecture du jukebox.
Numéro  nombre entier aléatoire Génère une valeur entière aléatoire.
envoyer un message Envoie un message instantané.
envoyer un ping Envoie une commande ping similaire à celle obtenue en maintenant le bouton gauche de la souris enfoncé.
setAttrs Définit un ou plusieurs attributs pour un personnage.
setComputed Uniquement pour le script Mod Bac à sable v1.5. Définit une propriété calculée « Beacon » accessible en écriture.
setSheetItem Définit un article de feuille (attribut ; à partir de la version 1.5, également Beacon / user.*).
spawnFx Génère un émetteur de particules.
générer des effets entre des points Génère un émetteur de particules qui se déplace d'un point à un autre.
spawnFxWithDefinition Génère un émetteur de particules qui n'est pas représenté par un objet FX Roll20.
Arrêter la lecture de la liste de lecture du jukebox Interrompt toutes les listes de lecture actuellement en cours de lecture sur le jukebox.
vers le haut Uniquement pour le script Mod Bac à sable v1.5. Place un objet immédiatement au-dessus d'un autre sur le même calque.
Retour Place un élément graphique, un texte, un tracé ou un tracé v2 sous les autres objets de son calque.
vers le bas Uniquement pour le script Mod Bac à sable v1.5. Place un objet immédiatement en dessous d'un autre sur le même calque.
toFront Place un élément graphique, un texte, un tracé ou un tracé v2 au-dessus des autres objets de son calque. Transmettez l'objet, et non un identifiant.
Accessoires pour cartes shuffleDeck, cardInfo, recallCards, dealCardsToTurn, drawCard, pickUpCard, takeCardFromPlayer, playCardToTable, giveCardToPlayer — voir Objets : Jeu de cartes.

Campagne

Paramètres

Aucun paramètre

Retours

L'objet Roll20 de la campagne unique.

Exemples

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

La valeur de Campaign().sandboxVersion est « 1.0 » ou « 1.5 ». Campaign().nodeVersion correspond à la chaîne de caractères indiquant la version de Node.js. Uniquement pour le script Mod Bac à sable v1.5. sheetName, computedSummary et actionSummary. Voir la rubrique « Objets : Campagne ».

créerObj

Paramètres

TYPE (chaîne de caractères) Le type d'objet Roll20 à créer. Vous pouvez créer des éléments de type « graphic », « text », « path », « pathv2 », « personnage », « caractéristique », « document », « rollabletable », « tableitem », « Macro », « card », « deck », « custfx », « window », « door » et « pin ». Uniquement pour le script Mod Bac à sable v1.5. « pageFolder ».

ATTRIBUTS (Objet) Les valeurs initiales à utiliser pour les propriétés de l'objet Roll20.

Retours

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

Exemples

Lorsque vous créez un objet Roll20 qui possède un objet parent (par exemple, lorsque vous créez un objet Roll20 de type « attribut », qui est un enfant d'un objet Roll20 de type « personnage »), vous devez indiquer l'identifiant du parent dans les attributs.


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

Lors de la création d'un chemin, indiquez le chemin (enregistré sous le nom _path) et l'identifiant de page. Le chemin d'accès sans trait de soulignement correspond au nom attribué lors de la création. Il devient ensuite en lecture seule.

createObj('path', {
  pageid : Campaign().get('playerpageid'),
  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 document dans Roll20, vous ne pouvez pas définir le texte ni les notes du MJ au moment de la création.

var document = createObj('document', {
  name: 'Une lettre qui vous est adressée',
  inplayerjournals: 'all',
  archived: false
});
document.set('notes', 'Les notes ne peuvent être définies qu’après la création du document.');
document.set('gmnotes', 'Définissez les gmnotes dans un appel distinct de celui des notes.');

filterObjs

Paramètres

CALLBACK (Fonction) Une fonction de prédicat permettant de vérifier tous les objets Roll20. La fonction de rappel reçoit un objet Roll20 en 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 réussi le test de prédicat.

findObjs

Paramètres

ATTRIBUTS (Objet) Ensemble de paires clé-valeur permettant d'établir une correspondance avec les objets Roll20 de la campagne.

OPTIONS (objet, facultatif)

  • caseInsensitive — si cette option est définie sur « true », les comparaisons de chaînes de caractères ne tiennent pas compte de la casse.
  • startsWith — si la valeur est « true », les chaînes de caractères doivent correspondre au niveau du préfixe.
  • tagMatch — lors de la recherche de tags: « all » (par défaut ; l'objet possède toutes les balises répertoriées), « any » (au moins une), « only » (exactement l'ensemble répertorié).

Retours

Un tableau d'objets Roll20 dont les propriétés correspondent aux attributs. Les clés peuvent ne pas comporter le trait de soulignement initial : « type » et « _type » correspondent tous les deux.

Exemples

var npcs = findObjs({ type : 'personnage', controlledby : '' });
var knights = findObjs({ type : 'personnage', name : 'Sir' }, { startsWith : true });

obtenirTousLesObjets

Paramètres

Aucun paramètre

Retours

Tableau de tous les objets Roll20 de la campagne.

getAttrByName

Paramètres

CHARACTER_ID (chaîne de caractères) L'identifiant du personnage. ATTRIBUTE_NAME (Chaîne de caractères) Le nom de l'attribut. VALUE_TYPE (chaîne de caractères, facultatif) « current » ou « max » (valeur par défaut : « current »).

Retours

La propriété « current » ou « max ». Si cette option n'est pas définie, la feuille de personnage par défaut est utilisée (le cas échéant).

getComputed

Uniquement pour le script Mod Bac à sable v1.5. (Dans la version 1.0, ce nom correspond à un stub sans opération.)

Paramètres

Un objet : { characterId, property, args?, playerId? }.

Lorsque vous utilisez une feuille de personnage Beacon, cette méthode récupère la valeur d'une propriété calculée. Répertoriez les noms à l'aide de Campaign().computedSummary. Le paramètre « playerId » est facultatif ; certaines fonctionnalités de Beacon (comme les requêtes « roll », par exemple) l'exigent.

getSheetDefaultValue

Paramètres

ATTRIBUTE_NAME (chaîne de caractères), VALUE_TYPE (chaîne de caractères, facultatif) : « current » ou « max ».

Retours

La valeur par défaut de la feuille pour ce champ, et non la valeur réelle du caractère.

getSheetItem

Paramètres

getSheetItem(characterId, property, valtype?, options?) — asynchrone (Promise).

Dans la version 1.0, cela encapsule la fonction getAttrByName. Uniquement pour le script Mod Bac à sable v1.5. Dans les feuilles Beacon, il lit également les propriétés calculées et les attributs personnalisés nommés user.*.

getObj

Paramètres

TYPE (chaîne de caractères), ID (chaîne de caractères)

Retours

L'objet Roll20 spécifié.

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

journal

Paramètres

MESSAGE (variable) Affiché dans la console de sortie du Mod. Converti à l'aide de JSON.stringify.

Uniquement pour le script Mod Bac à sable v1.5. Les messages d'erreur comportent souvent un objet de contexte, tel que [personnage Roll20 -id].

sur

Paramètres

ÉVÉNEMENT (chaîne de caractères) Il existe cinq types d'événements : ready, change, add, destroy, Chat. À l'exception de « ready », associez l'événement à un type d'objet. Pour le Chat, ce type est toujours « message ». Les événements de modification peuvent également désigner une propriété, un identifiant d'objet, ou les deux : change:graphic:left, change:graphic:ID, change:graphic:ID:left. Les graphiques déclenchent également des événements de sous-type, tels que « change:token » et « change:dicetoken ». Consultez la rubrique « Événements ».

Les événements « ready » de la fonction CALLBACK ne comportent aucun paramètre de rappel. Les événements de modification disposent d'un paramètre « obj » (l'objet Roll20 après la modification) et d'un paramètre « prev » (un objet JavaScript simple contenant les propriétés avant la modification). Les événements « add » comportent un paramètre « obj » (le nouvel objet). Les événements « destroy » disposent d'un paramètre « obj » (l'objet qui n'existe plus). Les événements de Chat comportent un paramètre « msg » (détails du message).

Retours

(Nul)

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, toute modification de la propriété « left » d'un objet graphique Roll20 entraînera l'appel de la fonction 3, puis de la fonction 1 et enfin de la fonction 2.

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

Les événements « add events » tenteront de se déclencher pour les objets Roll20 déjà présents dans la campagne au moment où une nouvelle session commence. Pour éviter ce comportement, vous pouvez attendre que l'événement « ready » se déclenche avant d'enregistrer votre événement « add ».

on('add:graphic', function(obj) {
  // Au début de la session, cette fonction sera appelée pour chaque élément graphique de la campagne
});
on('ready', function() {
  on('add:graphic', function(obj) {
    // Cette fonction ne sera appelée *que* lorsqu'un nouvel objet graphique Roll20 sera créé
  });
});

Le paramètre « prev » des événements de modification n'est pas un objet Roll20. Vous ne pouvez pas utiliser les opérateurs « get » ou « set », et vous ne pouvez pas omettre les traits de soulignement en début de nom pour les propriétés en lecture seule. Utilisez « prev._id » et non « prev.id ».

Pour les champs « blob » des personnages et des documents (biographie, notes, notes du MJ) ainsi que pour le champ _defaulttoken des personnages, « prev » ne correspond pas au texte. La chaîne « gmnotes » est une chaîne de caractères ordinaire. Enregistrez vous-même en cache les valeurs précédentes des blobs si vous en avez besoin.

surSheetWorkerCompleted

Paramètres

CALLBACK (Fonction) Appelée lorsque la pile actuelle des scripts de feuille est terminée. Cette méthode est destinée à être appelée avant la méthode ` setWithWorker`. Ne s'exécute qu'une seule fois. La fonction de rappel peut recevoir { workersExecuted : booléen }.

exécuterAction

Uniquement pour le script Mod Bac à sable v1.5. (Dans la version 1.0, ce nom correspond à un stub sans opération.)

Paramètres

{ characterId, action, args?, playerId? }

Exécute une action de la feuille « Beacon ». Répertoriez les noms à l'aide de Campaign().actionSummary. Le paramètre « playerId » est facultatif ; certaines fonctionnalités de Beacon l'exigent. Si le nom ne correspond pas à une action « Beacon », la version 1.5 peut se rabattre sur une caractéristique du personnage portant ce nom via « sendChat ».

joueurEstGM

Paramètres

PLAYER_ID (chaîne de caractères)

Retours

vrai si le joueur dispose actuellement des droits de MJ.

Particulièrement utile pour réserver les commandes Mod Script à l'usage des MJ. Conservez « msg.type !== 'api' » tel quel — il s'agit du type de message de commande.

Lecteur Jukebox Liste de lecture

Paramètres

PLAYLIST_ID (chaîne de caractères) L'identifiant de la Playlist dont la lecture doit être lancée.

nombre entier aléatoire

Paramètres

MAX (Nombre) Maximum inclus.

Retours

Un nombre entier aléatoire compris entre 1 et max. Préférez cette méthode à Math.random() pour obtenir des plages de valeurs simulant le lancer de dés.

sendChat asynchrone

Paramètres

SPEAKINGAS (chaîne de caractères) Un nom, ou joueur|id_joueur / personnage|id_personnage. MESSAGE (chaîne de caractères). CALLBACK (fonction, facultatif) — les résultats sont transmis à la fonction de rappel au lieu d'apparaître dans le Chat. OPTIONS (Objet, facultatif) noarchive, use3d.

Consultez la section « Scripts de mod : Chat » pour les boutons de commande ([label](!command)).

envoyer un ping

Paramètres

GAUCHE, HAUT, PAGE_ID, PLAYER_ID (facultatif), MOVEALL (facultatif), VISIBLETO (facultatif). Si « player_id » n'est pas renseigné, le ping est affiché en jaune. Si moveAll est défini sur « true », les vues se centrent sur le ping. « visibleTo » peut être un identifiant de joueur, un tableau d'identifiants ou une chaîne de caractères séparée par des virgules.

setAttrs

Paramètres

CHARACTER_ID (chaîne de caractères), ATTRIBUTE_OBJ (objet de type nom → valeur). Les noms se terminant par _max définissent la valeur maximale. Les noms $n sont autorisés. options.silent utilise la méthode set au lieu de setWithWorker.

setComputed

Uniquement pour le script « Mod Script Bac à sable » v1.5.

{ characterId, property, args?, playerId? } — définit une propriété calculée Beacon accessible en écriture. Voir Campaign().computedSummary.

setSheetItem

setSheetItem(characterId, property, value, valtype?, options?) — asynchrone. Dans la version 1.0, les attributs sont définis. Uniquement pour le script Mod Bac à sable v1.5. Ainsi que les propriétés calculées de Beacon et les attributs personnalisés « user.* ». Les options disponibles sont : createAttr, withWorker et allowThrow.

spawnFx

Paramètres

GAUCHE (Nombre) La coordonnée x à laquelle placer l'émetteur de particules. TOP (Nombre) La coordonnée y. TYPE (chaîne de caractères) Pour les effets intégrés, « type-couleur », où « type » correspond à l'un des termes suivants : bombe, bulles, brûlure, éclatement, explosion, lueur, missile ou nova, et « couleur » correspond à l'un des termes suivants : acide, sang, charme, mort, feu, givre, sacré, magie, boue, fumée ou eau. Pour les effets personnalisés, l'identifiant d'un objet custfx. Remarque : les paramètres « beam », « breath » et « splatter » ne peuvent pas être utilisés avec la fonction `spawnFx` — voir `spawnFxBetweenPoints`. PAGE_ID (chaîne de caractères, facultatif) prend par défaut la valeur Campaign().get('playerpageid').

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

générer des effets entre des points

Paramètres

START (Objet) { x, y }. END (Objet) { x, y }. TYPE (chaîne de caractères) en tant que « spawnFx », ainsi que « beam », « breath » et « splatter ». PAGE_ID (chaîne de caractères, facultatif).

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

Uniquement pour le script Mod Bac à sable v1.5. Les effets de type « poutre » sont désormais orientés directement vers le point d'arrivée (une erreur de calcul d'angle a été corrigée).

spawnFxWithDefinition

Paramètres

GAUCHE, HAUT, DÉFINITION (objet décrivant l'émetteur), PAGE_ID (facultatif). Pour connaître les noms des propriétés, consultez l'article « Effets personnalisés sur les objets ».

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]
});

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

Arrête toutes les playlists de la Jukebox en cours de lecture.

arrêterJukeboxPlaylist() ;

Accessoires pour cartes

Disponible sur les deux versions du Bac à sable. Vous trouverez tous les détails dans la section « Mod Scripts : Objets (Pont) ».

  • shuffleDeck(deckid, pile de défausse, nouvelOrdre)
  • cardInfo(paramètres)
  • recallCards(deckid, type)
  • dealCardsToTurn(deckid)
  • drawCard(deckid, cardid)
  • pickUpCard(cardid, fromDiscard)
  • takeCardFromPlayer(playerid, options)
  • playCardToTable(cardid, settings)
  • giveCardToPlayer(cardid, playerid)

setDefaultTokenForCharacter

CARACTÈRE (objet « caractère »), JETON (objet graphique). Les deux doivent déjà exister. Écrit le blob _defaulttoken du personnage à partir du jeton. C'est ainsi que l'on définit ce champ ; la fonction set() ne le fait pas.

vers le haut

Uniquement pour le script « Mod Script Bac à sable » v1.5.

Paramètres

OBJ (graphique, texte, tracé ou pathv2), TARGET (objet ou identifiant).

Place l'objet « obj » immédiatement au-dessus de la cible, sur le même calque.

Retour / Suivant

OBJ doit être un graphique, du texte, un tracé ou un tracé v2. Transmettez l'objet, et non un identifiant. Dans la version 1.5, celles-ci sont nettement plus rapides, et ces types disposent également de méthodes d'instance toFront() / toBack().

vers le bas

Uniquement pour le script « Mod Script Bac à sable » v1.5.

Place l'objet « obj » immédiatement en dessous de la cible (objet ou identifiant) sur le même calque.

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