Scripts de Travail de Fiche

Ajout d'un script utilisateur pour une feuille

Pour ajouter un script utilisateur à une feuille de personnage, il suffit d'ajouter le script dans la section "HTML" de la feuille en utilisant le format suivant:

<script type="text/worker">

on("change:strength", function() {

});

// ... etc

</script>

Notez que la balise script doit avoir un type "text/worker" pour être traitée correctement par le système. Lorsque le jeu se charge, toutes les balises script sont supprimées du modèle de la feuille à des fins de sécurité. Cependant, les balises de script avec un type "text/worker" seront utilisées pour lancer un worker en arrière-plan sur l'ordinateur de chaque joueur qui peut répondre aux valeurs changeantes dans leurs feuilles et agir si nécessaire. Tous les scripts sheetworker doivent être contenus dans une seule balise de script.

Plus d'exemples complets des basesdestinés aux non-programmeurs

Avertissement à propos de la portée des variables "global" :la portée d'une variable déclaréeà l'intérieurdes `<script type="text/worker">` maisen dehorsd'une fonction sont actuellement parjoueur, pas par personnage. Le fait de changer sa valeur le changera pour tous les personnages de la session du joueur.

Il est généralement préférable d'éviter les cascades asynchrones autant que possible. En général, il est préférable d'obtenir tous les attributs nécessaires aux calculs dans un seul getAttrs plutôt que de faire getAttrs -> calculs -> setAttrs -> getAttrs -> calculs -> setAttrs…


Feuilles de personnage vs. Champs de calcul automatiques : Que dois-je utiliser ?

Il n'y a pas de règle absolue à ce sujet. Ces deux outils sont capables de réaliser la même chose. Prenons un cas d'utilisation hypothétique d'un attribut "Force", que nous souhaitons utiliser pour maintenir à jour un attribut "Mod Force". Voici les différences entre ces deux outils pour cette utilisation :

  • Les champs de calcul automatique sont tous recalculés à chaque fois qu'une feuille est ouverte pour la première fois. Les champs du Travailleur de feuille, en revanche, ne sont recalculés que lorsque leurs valeurs dépendantes changent. Cela signifie que les feuilles utilisant l'option Travailleur de feuille seront beaucoup, beaucoup plus rapides à ouvrir et à interagir pour les joueurs.
  • De plus, les calculs du Travailleur de feuille s'exécutent en arrière-plan, ce qui signifie qu'il n'y a pas de latence de l'interface utilisateur pendant l'exécution des calculs. Cependant, les champs désactivés s'exécutent sur le processus principal et peuvent donc provoquer des "bloquages" ou des "saccades" s'il y en a un grand nombre calculés en même temps (par exemple, si vous avez une feuille très compliquée utilisant des milliers de champs désactivés).
  • Le champ Mod Force en calcul automatique apparaîtrait désactivé pour le joueur. Un champ Mod Force mis à jour par un Travailleur de feuille, en revanche, serait modifiable après l'exécution du calcul (bien que toute valeur saisie serait écrasée lorsque la valeur de Force change). Ainsi, un Travailleur de feuille prendrait mieux en charge les règles persos car le joueur pourrait simplement modifier la valeur Mod après un changement de Force. D'un autre côté, le champ de calcul automatique n'autoriserait pas un tel changement, donc les règles seraient plus "imposées" rigoureusement.

En général, notre recommandation est que vous utilisiez les champs de calcul automatique avec parcimonie.Donnez-vous un budget de 500 à 1 000 champs de calcul automatique au maximum. Nous recommandons d'utiliser la nouvelle fonctionnalité du Sheet Worker pour la plupart des calculs, en particulier ceux qui n'ont besoin d'être effectués que rarement (par exemple, votre valeur de Force (et donc votre Modificateur de Force) change probablement au maximum une fois par session lorsque le personnage monte de niveau. Il n'est pas nécessaire de réexécuter le même calcul encore et encore chaque fois que la feuille est ouverte.


API du Sheet Worker

Evénements

Objet eventInfo

De nombreux événements sont accompagnés d'un objeteventInfoqui fournit des détails supplémentaires sur les circonstances de l'événement.

Propriété Description
sourceAttribute L'attribut d'origine qui a déclenché l'événement. Il s'agit du nom complet (y compris RowID s'il se trouve dans une section répétitive) de l'attribut qui a initialement déclenché cet événement.

Remarque: La chaîne entière aura été traduite en minuscules et pourrait donc ne pas être adaptée pour être directement utilisée dans getAttrs().

sourceType L'agent qui a déclenché l'événement, soit lejoueur oule travailleur de feuille
previousValue La valeur d'origine de l'attribut lors d'un événement on:change , avant que l'attribut ne soit modifié.
newValue La valeur à laquelle l'attribut a été modifié lors d'un événement on:change .
removedInfo Un objet contenant les valeurs de tous les attributs supprimés lors d'un événement remove:repeating_groupname .

 

change:<attribute_name>

Vous permet d'écouter les modifications des attributs spécifiques, ou dans le cas d'une section répétée, toutes les modifications dans la section entière. C'est très simple :

on("change:strength change:StrengthMod change:StrengthOtherThing", function(eventInfo) {
   //Faites quelque chose ici
   // eventInfo.previousValue est la valeur originale de l'attribut qui a déclenché cet événement, avant d'être modifié.
   // eventInfo.newValue est la valeur actuelle de l'attribut qui a déclenché cet événement, après avoir été modifié.
}) ;

on("change:repeating_spells:spellname", function(eventInfo) {
   /Faire quelque chose ici
   // eventInfo.sourceAttribute est le nom complet (y compris l'ID répétitif) de l'attribut 
   // qui a déclenché cet événement à l'origine, 
   // cependant la chaîne entière aura été traduite en minuscules et pourrait donc ne pas être 
   // appropriée pour être introduite directement
   // dans getAttrs() ou d'autres utilisations sans être dévandalisée d'abord.
}) ;

on("change:repeating_spells", function(eventInfo) {
   //Serait déclenché lorsqu'un attribut de la section repeating_spells est modifié
   // eventInfo.sourceAttribute est le nom complet (en minuscules) (y compris l'ID de répétition) 
   // de l'attribut qui a déclenché cet événement à l'origine. 
}) ;

Note: Tous les noms d'attributs sont en minuscules dans les événements. Même si vous vous référez normalement à un attribut comme "Force", utilisez "change:strength" dans l'écouteur d'événements.

Note: Cela prend en charge le suffixe "_max" de sorte que "change:strength" ou "change:strength_max" déclenchera un événement, cependant ces deux variations semblent interchangeables, dans la mesure où l'éther ou les deux se déclencheront lorsque "force" ou "force_max" change.

Pour les attributs dans les champs répétitifs, tous les éléments suivants sont déclenchés lorsque l'attribut "repeating_spells_SpellName" est mis à jour: "change:repeating_spells:spellname", "change:repeating_spells", "change:spellname", "change:spellname_max". Cela vous donne une flexibilité maximale dans le choix du "niveau" d'événement de modification auquel vous souhaitez lier votre fonction.

Les travailleurs d'armure peuvent également écouter un événement de modification d'un attribut spécial modifié chaque fois qu'une section répétitive est réordonnée.

sur("change:_reporder:<sectionname>", function(eventInfo) {
   // Où <sectionname> ci-dessus doit être un nom de section répétitive, tel que compétences ou sorts
});

 

retirer : répétition_<groupname>

Il s'agit d'un événement qui se déclenchera chaque fois qu'une ligne est supprimée d'une section de champ répétitif. Vous pouvez également écouter la suppression d'une ligne spécifique si vous connaissez son identifiant, par exemple sur("remove:repeating_inventory:-ABC123")

sur("remove:repeating_inventory", fonction(eventInfo) {
     // Déclenché à chaque fois qu'une ligne est supprimée de repeating_inventory
     // eventInfo.sourceAttribute est le nom complet (y compris l'identifiant) du premier attribut qui a déclenché l'événement (vous pouvez l'utiliser pour déterminer l'identifiant de la ligne qui a été supprimée)
});

La fonction removed:repeating_<groupname> de l'événementinfo inclut une propriété spéciale removedInfo qui affiche tous les attributs de la section répétée maintenant supprimée.

sur("remove:repeating_inventory", fonction(eventinfo) {
   console.log(eventinfo.removedInfo);
});

 

feuille:ouverte

Cet événement se déclenche chaque fois qu'une feuille est ouverte par un joueur lors d'une session de jeu. Il devrait être utile pour effectuer des vérifications pour les mises à niveau de feuille nécessaires.

sur('feuille:ouverte',fonction(){

// Faire quelque chose la première fois que la feuille est ouverte par un joueur lors d'une session

});

 

cliqué :<button_name>

Cet événement se déclenchera lorsqu'un bouton d'action est cliqué. Le nom du bouton devra commencer par "act_". Par exemple :

<button type="action" name="act_activate">Activer!</button>

sur("clické : activer", fonction() {
  console.journal("Bouton d'activation cliqué");
});

 

Fonctions

getAttrs (tableauNomAttribut, rappel)Asynchrone

La fonction getAttrs vous permet d'obtenir les valeurs d'un ensemble d'attributs de la feuille. Le suffixe "_max" est pris en charge, doncgetAttrs (["Force", "Force_max"], func)obtiendra à la fois les valeurs actuelles et maximales de "Force". Notez que la fonction est asynchrone, ce qui signifie qu'il n'y a aucune garantie que l'ordre dans lequel plusieurs appels getAttrs sont effectués est l'ordre dans lequel les résultats seront renvoyés. Au lieu de cela, vous passez une fonction de rappel qui sera exécutée lorsque les valeurs auront été calculées. La fonction de rappel reçoit un objet Javascript simple avec une liste de paires clé-valeur, une pour chaque attribut que vous avez demandé.

Voici un exemple:

sur("change:strength", fonction() {
   getAttrs(["Force", "Niveau"], fonction(valeurs) {
      //Faire quelque chose avec valeurs.Force et/ou valeurs[ "Niveau" ]
   });
});

Les valeurs dans les sections répétées nécessitent un traitement particulier. Si l'événement dans lequel vous vous trouvez est déjà à l'intérieur d'une section répétée, vous pouvez simplement demander la variable en utilisant son nom précédé du nom du groupe répété et vous recevrez la valeur dans la même section répétée où l'événement a été déclenché. Par exemple, si nous avons une section repeating_spells qui contient à la fois SpellName, SpellLevel et SpellDamage, alors :

sur("change:repeating_spells:spelllevel", function() {
   getAttrs([
      "repeating_spells_SpellDamage",
      "repeating_spells_SpellName"
    ], function(values) {
      //values.repeating_spells_SpellDamage et values.repeating_spells_SpellName 
// seront tous les deux de la même ligne de section répétée que SpellLevel qui a changé.
   });
});

D'autre part, si vous n'êtes pas actuellement dans une section répétée, vous pouvez spécifiquement demander la valeur d'un champ dans une ligne de section répétée en spécifiant manuellement son ID :

getAttrs(["repeating_spells_-ABC123_SpellDamage"]...

Vous pouvez également demander l'attribut "_reporder_repeating_<sectionname>" avec getAttrs() pour obtenir une liste de tous les IDs dans la section qui ont été commandés. Cependant, notez que cela peut ne pas inclure la liste complète de tous les identifiants dans une section. Tous les identifiants qui ne sont pas dans la liste et qui sont dans la section sont supposés venir après les identifiants ordonnés dans l'ordre lexicographique.

 

setAttrs(valeurs,options,callback) Asynchrone

valeurs-- Il s'agit d'un objet dont les propriétés sont les noms des attributs (sans le préfixe attr_) et dont les valeurs sont ce que vous souhaitez définir pour cet attribut.

options-- (Facultatif) Il s'agit d'un objet qui spécifie le comportement optionnel de la fonction. Actuellement, la seule option est "silent", ce qui empêche la propagation des événements de modification à partir de la définition des attributs fournis.

callback-- (Facultatif) Il s'agit d'une fonction de rappel qui sera exécutée lorsque les attributs définis auront été mis à jour.

La fonction setAttrs vous permet de définir les attributs de la feuille de personnage. Utilisez le suffixe "_max" pour définir la valeur maximale d'un attribut. Par exemple "Strength_max".

sur("change:strength", function() {
   getAttrs(["Strength", "Level"], function(values) {
      setAttrs({
          StrengthMod: Math.floor(values.Strength / 2)
      });
   });
});

Note: If you are trying to update a disabled input field with this method you may run into trouble. One option is to use this `setAttrs` method to set a hidden input, then set the disabled input to the hidden element. In this example we have an attr named will, and we want to calculate judgement based off 1/2 of the will stat, but not to allow it to exceed 90. Voir ci-dessous.

<label>Jugement</label>
<input type="hidden" name="attr_foo_judgment" value="0" />
<input type="number" name="attr_judgment" value="@{foo_judgment}" disabled="true" title="1/2 of will rounded down, 90 max" />
on("change:will", function() {
  getAttrs(["will"], function(values) {
    setAttrs({ foo_judgment : Math.min(90, (values.will/2)) }) ;
  }) ;
}) ;

Notez que bien que setAttrs soit une fonction asynchrone, il n'y a aucune garantie quant à l'ordre dans lequel les attributs réels seront définis en cas d'appels multiples de setAttrs().

Pour les sections répétitives, vous avez la possibilité d'utiliser le nom simple de la variable si l'événement original se trouve dans une section répétitive, ou vous pouvez spécifier le nom complet de la variable de la section répétitive, y compris l'ID, dans n'importe quel événement.

on("change:repeating_spells:spelllevel", function() {
   getAttrs(["repeating_spells_SpellLevel", "repeating_spells_SpellName"], function(values) {
      setAttrs({
         repeating_spells_SpellDamage : Math.floor(values.repeating_spells_SpellLevel / 2) + 10
      }) ;
   }) ;
}) ;

 

getSectionIDs(nom_de_la_section,callback) Asynchrone

Cette fonction vous permet d'obtenir une liste des identifiants qui existent actuellement pour une section répétitive donnée. Cette fonction est utile pour calculer des éléments tels que les stocks, pour lesquels le nombre de lignes peut être variable.

on("change:repeating_inventory", function() {
   getSectionIDs("inventory", function(idarray) {
      for(var i=0; i < idarray.length; i++) {
         //Faire quelque chose avec les ID
      }.
   }) ;
}) ;

Notez que vous pouvez utiliser GetAttrs() (décrit ci-dessus) pour demander l'attribut "_reporder_repeating_<sectionname>" afin d'obtenir une liste de tous les ID de la section qui ont été ordonnés. Notez toutefois qu'il se peut que la liste complète de tous les ID d'une section ne soit pas incluse. Tous les identifiants qui ne figurent pas dans la liste mais qui se trouvent dans la section sont supposés venir après les identifiants ordonnés dans l'ordre lexographique.
En d'autres termes, getSectionIDs() récupère tous les identifiants, mais pas dans l'ordre dans lequel ils sont affichés à l'utilisateur. getAttrs( "_reporder_repeating_<sectionname>", ... ) renverra une liste de tous les ID qui ont été déplacés hors de leur ordre lexographique normal. Vous pouvez utiliser la fonction suivante en remplacement de getSectionIDs pour obtenir les ID dans l'ordre où ils sont affichés.

var getSectionIDsOrdered = function (sectionName, callback) {
  'use strict';
  getAttrs([`_reporder_${sectionName}`], function (v) {
    getSectionIDs(sectionName, function (idArray) {
      let reporderArray = v[`_reporder_${sectionName}`] ? v[`_reporder_${sectionName}`].toLowerCase().split(',') : [],
        ids = [...new Set(reporderArray.filter(x => idArray.includes(x)).concat(idArray))] ;
      callback(ids) ;
    } ;
  }) ;
} ;}

 

generateRowID()

Une fonction synchrone qui renvoie immédiatement un nouvel identifiant aléatoire que vous pouvez utiliser pour créer une nouvelle ligne de section répétitive. Si vous utilisez setAttrs() et que vous transmettez l'ID d'une ligne de section répétitive qui n'existe pas, une ligne sera créée avec cet ID.

Voici un exemple que vous pouvez utiliser pour créer une nouvelle ligne dans une section répétitive :

var newrowid = generateRowID() ;
var newrowattrs = {} ;
newrowattrs["repeating_inventory_" + newrowid + "_weight"] = "testnewrow";
setAttrs(newrowattrs) ;

 

removeRepeatingRow( RowID )

Une fonction synchrone qui supprime immédiatement tous les attributs associés à un RowID donné et supprime ensuite la ligne de la feuille de caractères. Le RowID doit être du format "repeating_<sectionname>_<rowid>". Par exemple, "repeating_skills_-KbjuRmBRiJNeAJBJeh2".

Voici un exemple d'effacement d'une liste récapitulative en cas de modification de la liste d'origine :

on("change:repeating_inventory", function() {
   getSectionIDs("repeating_inventorysummary", function(idarray) {
      for(var i=0; i < idarray.length; i++) {
        removeRepeatingRow("repeating_inventorysummary_" + idarray[i]) ;
      }.
   }) ;
}) ;

 

getTranslationByKey([key])

Une fonction synchrone qui renvoie immédiatement la chaîne de traduction liée à la clé donnée. Si aucune clé n'existe, false sera renvoyé et un message sera envoyé à la console avec la liste de la clé spécifique qui n'a pas été trouvée dans le JSON de traduction.

Voici un exemple que vous pouvez utiliser pour récupérer une chaîne de traduction à partir du JSON de traduction : Avec le JSON de traduction suivant

{
    "str": "Strength",
    "dex": "Dexterity"
}
var strTranslation = getTranslationByKey('str') ; // "Force"
var dexTranslation = getTranslationByKey('dex') ; // "Dextérité"
var intTranslation = getTranslationByKey('int') ; // false

 

getTranslationLanguage()

Fonction synchrone qui renvoie immédiatement le code linguistique à 2 caractères de la langue sélectionnée par l'utilisateur.

Voici un exemple que vous pouvez utiliser pour récupérer la langue de traduction :

var translationLang = getTranslationLanguage() ; // "en" , pour un compte utilisant l'anglais

 

setDefaultToken(valeurs)

Une fonction qui permet à l'auteur de la feuille de déterminer quels attributs sont définis sur les personnages retirés du recueil. Lors de la définition du jeton par défaut après un dépôt de compendium, cette fonction peut définir n'importe quel attribut sur le jeton par défaut pour lier les attributs importants spécifiques à cette feuille de personnage, tels que attr_hit_points.

La liste des attributs du jeton qui peuvent être définis par setDefaultToken est la suivante :

["bar1_value","bar1_max","bar2_value","bar2_max","bar3_value","bar3_max","aura1_square","aura1_radius","aura1_color","aura2_square","aura2_radius", "aura2_color",
"tint_color", "showname", "showplayers_name", "playersedit_name", "showplayers_bar1", "playersedit_bar1","showplayers_bar2", "playersedit_bar2", "showplayers_bar3",
"playersedit_bar3", "showplayers_aura1", "playersedit_aura1", "showplayers_aura2","playersedit_aura2", "light_radius", "light_dimradius", "light_angle", "light_otherplayers",
"light_hassight", "light_losangle", "light_multiplier"]

Pour plus d'informations sur ces attributs et leur fonction, veuillez consulter la pageAPI Objects.

Voici un exemple:

on("sheet :compendium-drop", function() {
    var default_attr = {} ;
    default_attr["width"] = 70;
    default_attr["height"] = 70;
    default_attr["bar1_value"] = 10;
    default_attr["bar1_max"] = 15;
    setDefaultToken(default_attr) ;
}) ;
Cet article vous a-t-il été utile ?
Utilisateurs qui ont trouvé cela utile : 17 sur 32