Scripts de mod : Événements

Il existe plusieurs types d'événements auxquels vous pouvez réagir à l'aide de la syntaxe `on(event, callback)`. Il existe cinq types d'événements : « ready », « change », « add », « destroy » et « Chat ». À l'exception de « ready », le nom comprend un type d'objet (ou un message pour le Chat), et « change » peut inclure une propriété. Chaque événement est déclenché une fois par objet qui subit une modification. Si plusieurs propriétés de l'objet changent simultanément, un seul événement « global » (par exemple « change:graphic ») est déclenché, auquel s'ajoutent les événements spécifiques à chaque propriété que vous avez liés.

Paramètres de rappel

Lorsque vous écoutez un événement, vous créez une fonction appelée « callback » qui s'exécute chaque fois que cet événement se produit. La fonction de rappel reçoit des paramètres qui vous indiquent ce qui a changé, afin que vous puissiez décider de la marche à suivre.

obj

L'objet qui a été modifié. Toute modification apportée à cet objet sera également enregistrée dans le jeu. Ainsi, si vous souhaitez déplacer un objet graphique vers la gauche, vous devrez modifier la propriété « left » de « obj » à l'aide de la commande « set ».

• La méthode obj.get("property") renvoie la valeur actuelle de la propriété.
• obj.set("propriété", "nouvelle_valeur") attribue une nouvelle valeur à la propriété. Si vous modifiez plusieurs propriétés à la fois, vous pouvez passer un objet : obj.set({left: 10, top: 20}).

précédent

Il s'agit d'un objet contenant les propriétés de l'objet « obj » telles qu'elles étaient avant que des modifications ne soient apportées à la suite de cet événement. Utile pour déterminer « dans quelle mesure » un bien immobilier a évolué.

REMARQUE : « prev » n' est pas un objet Roll20. Accédez aux propriétés à l'aide de la notation entre crochets ou avec le point : prev["bar1_value"] ou prev._id. Vous ne pouvez pas appeler les méthodes get ou set sur ce champ, et vous ne pouvez pas omettre le trait de soulignement pour les clés en lecture seule (prev.id n'est pas prev._id).

En ce qui concerne les personnages et les documents à distribuer, les champs « bio », « notes » et « gmnotes » de « prev » sont des identifiants internes, et non du texte. Le caractère _defaulttoken est également un blob. 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.

Commande d'événements

Les événements sont déclenchés de manière synchrone (chaque fonction ne démarre qu'une fois que la précédente s'est terminée), dans l'ordre allant de la première propriété liée à la dernière, ainsi que de la propriété spécifique à l'objet général. Étant donné ce qui suit :

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

Si la propriété « left » de l'objet venait à changer, l'ordre serait alors : fonction3, puis fonction1, puis fonction2.

Si votre campagne comporte plusieurs scripts, ceux-ci sont chargés dans l'ordre dans lequel ils apparaissent sur la page de paramètres « Mod Scripts », de gauche à droite.

Remarque : la méthode `set()` d'un script ne déclenche pas d'événement de modification pour cette propriété. Si un joueur déplace un jeton, vous obtenez « change:graphic ». Si un script modifie ensuite la position à gauche à l'aide de la fonction set(), cette modification ne déclenche pas l'événement « change:graphic ». La création d'un graphique à partir d'un script déclenche l'événement change:graphic. La fonction sendChat() déclenche l'envoi d'un message de Chat, y compris les messages commençant par !. Les propriétés « status_* » virtuelles ne déclenchent pas leurs propres événements ; surveillez l'événement « change:graphic:statusmarkers ».

prêt

Cet événement se déclenche une fois à chaque démarrage du Bac à sable, une fois les données de la campagne chargées. Ne recherchez les objets qui existent déjà qu'une fois que vous êtes prêt. Si vous vous abonnez aux événements « add » (tels que « add:graphic ») avant le déclenchement de l'événement « ready », vous recevrez également les événements « add » concernant les objets qui figuraient déjà dans la campagne. Les scripts sont chargés dans l'ordre défini dans les paramètres « Mod Scripts », de gauche à droite ; les gestionnaires « ready » s'exécutent dans l'ordre dans lequel ils ont été associés.

Paramètres de rappel : aucun

on("ready", function() {
  var tokenThatAlreadyExisted = getObj("graphic", "-ABc123");
});

Événements de chat

Chat : message

Se déclenche chaque fois qu'un nouveau message de Chat est reçu, y compris les messages envoyés via la fonction sendChat(). La fonction de rappel reçoit un objet « msg ». Les types de messages comprennent : général, rollresult, gmrollresult, secretrollresult (/sr), supersecretrollresult (/ssr), emote, chuchotement, desc, direct et api. Messages commençant par ! ont le type === « api » et n'apparaissent pas dans le Chat.

Paramètres de rappel : msg

Consultez la section « Mod Scripts : Chat » pour obtenir la liste complète des propriétés « msg » et découvrir la gestion des résultats de dés.

Événements de campagne

L'objet « campagne » prend en charge les propriétés « change:campaign » et « change:campaign:PROPERTY » pour toute propriété de campagne. Voici ceux que la plupart des scripts surveillent :

Modification : campagne : identifiant de la page du joueur

Déclenché chaque fois que la page sur laquelle se trouvent actuellement les joueurs change.

Modification : campagne : ordre des tours

Déclenché chaque fois que l'ordre des tours pour la campagne change.

Modification : campagne : page d'initiative

Déclenché chaque fois que l'ordre des tours est masqué ou affiché pour une page. Il est possible que cela ne corresponde pas à l'identifiant de la page actuellement active. Si cette option est définie sur « false » (y compris si un script de modification la définit sur « false »), cela mettra fin à l'Ordre des tours pour tous les MJ et joueurs. En le configurant avec un identifiant de page valide, il sera accessible à tous les GM/joueurs.

Événements liés aux objets

Chaque type d'objet prend en charge :

• ajouter : TYPE
• modification : TYPE
• modification : TYPE : PROPRIÉTÉ
• destroy:TYPE

Vous pouvez également créer un lien vers un identifiant d'objet spécifique : change:TYPE:ID, change:TYPE:ID:PROPERTY et destroy:TYPE:ID.

Consultez la section « Scripts de mod : Objets » pour connaître les propriétés de chaque type.

Modification : graphique

Se déclenche chaque fois qu'un objet graphique (pratiquement n'importe quel objet présent sur la table, y compris les Jetons, les cartes de jeu et les cartes) change.

Remarque : les objets graphiques créés par des scripts déclencheront cet événement lors de leur création.

Paramètres de la fonction de rappel : obj, prev

on("change:graphic", function(obj, prev) {
  //Effectuez une action avec « obj » ici. « prev » est une liste des valeurs précédentes.
  Veuillez noter que « obj » et « prev » sont des TYPES d'objets différents.
  // Pour utiliser obj, il est nécessaire d'employer obj.get("name") ;
  // Pour utiliser prev, il est possible d'employer prev["name"] ;
});

Modification : graphique : (propriété)

Vous pouvez également vous lier à un événement pour chaque propriété spécifique de l'objet. Ainsi, si vous disposez d'un script que vous souhaitez exécuter uniquement lorsque la rotation change, vous devrez procéder comme suit :

on("change:graphic:rotation", function(obj, prev) {
  // Réinitialisez toujours la rotation à 0, afin que personne ne puisse faire pivoter les objets.
  obj.set("rotation", 0);
});

ajouter : graphique

Déclenché chaque fois qu'un objet graphique est ajouté pour la première fois sur table. Cette méthode sera également appelée pour les objets existants au démarrage de la partie sur table si vous vous enregistrez pour cet événement en dehors de l'événement « ready ».

Paramètres de rappel : obj

var started = false;
on("add:graphic", function(obj) {
  if (!started) return;
  // Uniquement les graphiques ajoutés après la mise en place.
});
on("ready", function() {
  started = true;
});

détruire : graphique

Se déclenchait chaque fois qu'un objet graphique était retiré de la table.

Paramètres de la fonction de rappel : obj

Sous-types graphiques

Les objets graphiques déclenchent également des événements à l'aide de leur _subtype. Les cartes utilisent le sous-type « Jeton ».

La « carte » est à la fois un type d'objet Roll20 et un sous-type graphique ; par conséquent, les gestionnaires d'événements « change:card » et d'événements similaires doivent lever toute ambiguïté concernant le type d'objet (par exemple, obj.get("_type")) afin de s'assurer qu'ils se déclenchent pour le bon type d'objet.

Tous les types d'objets

Chaque type ci-dessous prend en charge les commandes add:TYPE, change:TYPE, change:TYPE:PROPERTY et destroy:TYPE.

Uniquement pour le script Mod Bac à sable v1.5. Les objets `pageFolder` disposent d'événements `add:pageFolder`, `change:pageFolder`, `destroy:pageFolder`, ainsi que d'événements liés aux propriétés, tels que `change:pageFolder:name`. Les pages déclenchent également les événements « change:page:_placement » et « change:page:_path » lorsque la hiérarchie du menu de la page change.

Portail / Les derniers types d'objets du moteur VTV (pathv2, pin, window, door) sont des fonctionnalités du moteur VTV, et non de la version « Bac à sable ». Un jeu en version 1.0 fonctionnant sur le dernier moteur VTV dispose toujours de ces types d'objets et de leurs événements.