API : Événements

7 novembre 2025 18:31

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 l'événement se produit. La fonction de rappel reçoit plusieurs paramètres qui sont des objets contenant les informations que vous souhaitez obtenir sur l'événement afin que vous puissiez déterminer la marche à suivre.

Les paramètres de rappel pour chaque événement peuvent varier, mais comprennent :

obj

L'objet qui a été modifié. Toute modification apportée à cet objet sera également enregistrée dans le jeu. Par conséquent, si vous souhaitez déplacer un objet graphique vers la gauche, vous devrez modifier la propriétégauchedel'objetà l'aide dela commande set.

obj.get("propriété")renvoie la valeur actuelle de la propriété.
obj.set("propriété", "nouvelle valeur")définit une nouvelle valeur pour la propriété. Si vous modifiez plusieurs propriétés à la fois, vous pouvez transmettre un objet :obj.set({left: 10, top: 20}) ;

Commande d'événements

Les événements sont déclenchés de manière synchrone (ce qui signifie que chaque fonction ne démarre qu'une fois la précédente terminée) dans l'ordre, de la première liaison à la dernière, et également 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éleftdes objets a changé, l'ordre serait alors function3, puis function1, puis function2.

De plus, si votre campagne comporte plusieurs scripts, ceux-ci sont chargés dans l'ordre dans lequel ils apparaissent sur votre page Scripts de campagne, de gauche à droite.

Remarque : les événements ne sont déclenchés que par les modifications apportées par les joueurs ou le MJ qui dirigent la partie. Les événements ne seront pas déclenchés par les modifications de l'API. Ainsi, si un joueur déplace une pièce sur la table, vous recevrez un événement « change:graphic ». Si vous modifiez les propriétés du même graphique dans un script Mod (API), aucun événement « change:graphic » ne sera déclenché.

Événements de campagne

prêt

Cet événement se déclenche une fois que toutes les données actuelles de la campagne ont été chargées. Par conséquent, si vous souhaitez obtenir la liste de tous les objets d'une campagne ou rechercher un objet spécifique déjà présent dans la campagne, veuillez vous assurer de ne procéder à cette recherche qu'après le déclenchement de l'événement « ready ». De plus, si vous vous liez pourajouterdes événements (tels queadd:graphic) avant le déclenchement de l'événementready, vous recevrez des événements add pour les objets déjà présents dans la campagne.

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

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 Mod (API) la définit sur « false »), l'ordre des tours sera fermé pour tous les MJ/joueurs. En le configurant avec un identifiant de page valide, il sera accessible à tous les GM/joueurs.

Événements liés aux objets

Modification : graphique

Déclenché chaque fois qu'un objet graphique (qui peut être presque n'importe quel type d'objet sur la table, y compris les jetons, les cartes et les cartes à jouer) change.

Remarque : les objets graphiques créés par l'API déclencheront cet événement lors de leur création.

Paramètres de rappel : obj, prev

on("change:graphic", function(obj, prev) {    
  //Effectuer 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. Si vous avez un script que vous souhaitez exécuter uniquement lorsque larotationchange, vous devez procéder comme suit :

on("change:graphic:rotation", function(obj, prev) {    
  //Toujours réinitialiser 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. Sera également appelé pour les objets existants lorsque le sur table démarre si vous vous liez à cet événementen dehorsde l'événementprêt.

Paramètres de rappel : obj

on("add:graphic", function(obj) {
  //Sera appelé pour tous les nouveaux graphiques, y compris ceux qui existaient déjà au début de la session de jeu.
});

var started = false;

on("ready", function() {
  on("add:graphic", function(obj) {
    //Ne sera appelé que pour les nouveaux objets ajoutés, car les objets existants ont déjà été chargés avant le déclenchement de l'événement ready.
  });
  //Vous pouvez également définir une variable et ignorer les événements d'ajout jusqu'à ce qu'elle soit vraie.
  started = true;
});

détruire : graphique

Déclenché chaque fois qu'un objet graphique a été retiré de la sur table.

Paramètres de rappel : obj

Autres types d'objets

Il existe également des événements pour tous les autres types d'objets et sous-types, tels que :

modifier : chemin, ajouter : chemin, supprimer : chemin, modifier : texte, ajouter : texte, supprimer : texte, modifier : jeton, ajouter : jeton, supprimer : jeton, modifier : carte, ajouter : carte, supprimer : carte

Veuillez consulter la référence Objets pour obtenir la liste complète de tous les types et sous-types d'objets.