Introduction to Macro Writing/fr: Difference between revisions

From RPTools Wiki
Jump to navigation Jump to search
VisualWikitext
 
(39 intermediate revisions by 3 users not shown)
Line 39: Line 39:
L'endroit le plus naturel où trouver une Macro est un [[Introduction to Tokens|Pion]]. Les Macros de Pion sont liées au Pion sur lequel elles ont été créées le resteront tant que vous les y laisserez.
L'endroit le plus naturel où trouver une Macro est un [[Introduction to Tokens|Pion]]. Les Macros de Pion sont liées au Pion sur lequel elles ont été créées le resteront tant que vous les y laisserez.


Les Macros de Pion (''Token macros '') sont accessibles directement uniquement par les propriétaires du Pion, donc si vous ne possédez pas le Pion, vous ne pourrez pas interagir (ou même voir) les boutons de ces Macros.
Les Macros de Pion (''Token macros '') sont directement accessibles uniquement par les propriétaires du Pion, donc si vous ne possédez pas le Pion, vous ne pourrez pas interagir (ou même voir) les boutons de ces Macros.


===Macros de Campagne===
===Macros de Campagne===


Campaign Macros are macros that aren't linked to a specific token in a campaign, but to the campaign as a whole. These macros work in almost every respect exactly like a token macro, except that:
Les Macros de Campagne ne sont pas liées à un Pion en particulier, mais à la campagne toute entière. Ces Macros fonctionnent pratiquement comme une Macro de Pion, excepté ceci :


# You don't have to select a token to see the macros
# Vous n'avez pas besoin de sélectionner. un Pion pour voir les Macros
# Anyone can access them and run them
# N'importe qui peut y accéder et les exécuter.


Campaign Macros are quite useful for the GM and for the Players to handle common functions - in fact, if you set up a common task as a campaign macro, then you only need to make one copy of it (instead of making copies on every token that needs it).  
Les Macros de campagne sont particulièrement utiles au MJ et aux joueurs pour gérer des fonctions communes - en fait, si vous mettez en place une tache commune en tant que Macro de campagne, vous n'avez besoin que d'avoir une seule copie de celle-ci (au lieu d'une copie pour chaque Pion qui en aurait besoin).


===Macros Globales===
===Macros Globales===


Global Macros aren't linked to a token or a campaign - instead, they are macros that are linked with your copy of MapTool. These macros are ''not'' visible to anyone else who connects to your game.
Les Macros globales se sont liées ni aux Pions, ni à une campagne - en fait, elles sont liées à votre exemplaire de MapTool. Ces Macros ne sont visibles de personne d'autre que vous, que vous soyez joueur ou MJ.  


This is a good place to put macros for tasks you ''don't'' want other people seeing - like information you want to show to players only when ''you'' decide; or tasks you want to perform on your NPCs but you don't want PCs to be able to do.
C'est un bon endroit pour ranger les Macros exécutant des tâches que vous ne voulez pas que les autres voient - comme des informations que vous voudriez montrer uniquement au moment où vous l'avez décidé; ou des tâches que vous voulez faire faire à vos PNJ mais que vous ne voulez pas que les PJ puissent faire.


==The Macro Panels==
==Les fenetres de Macros==


[[Image:Macro-panels.jpg|thumb|The four Macro Panels]] [[Image:Tabbed-panels.jpg|thumb| The four panels stacked together, selectable by the tabs at the bottom (many users stack them like this to save space)]]
[[Image:Macro-panels.jpg|thumb|Les quatre fenêtres de Macros]] [[Image:Tabbed-panels.jpg|thumb| Les quatre fenêtres empilées sur une seule, sélectionnables à travers les onglets situés en bas (de nombreux utilisateurs choisissent cette disposition pour gagner de la place)]]


With all this talk about macros and locations and especially the macro "buttons," you are probably wondering - where are these buttons? You'll find macro buttons on one of the 4 '''macro panels''' that appear in MapTool. If you cannot see any of the macro panels, go to the '''Windows''' menu, and make sure that these four windows are checked:
Avec toutes ces discussions autour des Macros et de leur localisation (plus spécialement des boutons de Macros), vous vous demandez probablement où trouver ces boutons ? Vous les trouverez dans une des quatre fenêtres de Macros qui sont disponibles dans MapTool. Si vous ne trouvez pas ces fenêtres ou qu'une d'entre elles est manquante, vous pouvez les faire apparaître en allant dans le menu '''Windows''' (Fenêtres) et en cochant les fenêtres suivantes en fonction de vos besoins :


* Selection
* Selection (Sélection)
* Impersonated
* Impersonated (Interprétation)
* Campaign
* Campaign (Campagne)
* Global
* Global (Globale)


You should see these windows pop up in MapTool if they were not already there. If you look at the screenshots to the right, you will see that the Global panel is covered with a bunch of buttons. Each of those buttons will execute a macro; the buttons appear when you create a new macro.
Vous devriez voir ces fenêtres apparaître dans MapTool si elle n'étaient pas déjà là. Si vous regardez les copies d'écran sur la droite, vous verrez que la fenêtre Globale est remplie avec un tas de boutons. Chacun d'eux exécute une Macro; les boutons apparaissent lorsque vous créez une nouvelle Macro


===Selection and Impersonated Panels===
===Fenêtre Sélection et Interprétation===


There are two panels that deal directly with token macros: Selection, and Impersonated.
Il y a deux fenêtres qui traitent directement des Macros des Pions : Sélection (''Selection'' et ''Impersonated'')


The '''Selection''' panel will show buttons for all of the macros that are currently residing on the token you have selected (you select tokens by clicking on them with the mouse). Each of these buttons runs a particular group of macro commands.
La fenêtre Sélection montre les boutons de toutes les Macros actuellement associées au Pion que vous avez sélectionné. Chaque bouton lance une série particulière de commandes Macro.


The '''Impersonated''' panel shows buttons for the macros on the token you are ''impersonating''. Impersonating a token is a way to "assume the token's persona" - when you chat, text will appear as if the token was speaking, and so forth. It is possible to impersonate one token, and select another, so make sure you know what panel you're looking at!
La fenêtre Interprétation (''Impersonated'') montre  les macros du Pion que vous avez choisi ''d'interpréter''. Interpréter un Pion est un moyen de faire comme si vous étiez le Pion - lorsque vous discutez, le texte apparaît comme s'il avait été dit par le Pion. Il est possible d'interpréter un Pion tout en en sélectionnant un autre, alors faites attention à la fenêtre que vous êtes en train d'utiliser !


===Campaign Panel===
===La fenêtre Campagne (''Campaign'')===


This panel shows all of the macros currently set up for the Campaign. Remember, these are visible to everybody.
Cette fenêtre affiche toutes les Macros actuellement disponibles pour la campagne. Souvenez-vous qu'elles sont visibles de tout le monde.


===Global Panel===
===La fenêtre Globale===


This panel contains the Global Macros you've set up. Remember, these are ''only visible to you.''
Cette fenêtre contient les Macros globales que vous avez créées. Souvenez-vous qu'elles ne sont visibles ''que de vous''.


==Ecrire des Macros==


[[Image:Camp-panel-nomacros.png|thumb|La fenêtre '''Campagne''' (''Campaign''). Elle ne contient aucune Macro pour l'instant.]]


==Writing Macros==
[[Image:Camp-panel-rcaddnew.png|thumb|Un clic-droit dans cette fenêtre vous permet d'ajouter une nouvelle Macro.]]


[[Image:Camp-panel-nomacros.png|thumb|The '''Campaign Panel'''. You can see there are no macros here yet.]]
La création de Macros se fait en trois étapes (même si chaque étape peut en contenir une multitude!) :


[[Image:Camp-panel-rcaddnew.png|thumb|Right-clicking on the Campaign Panel lets you add a new macro.]]
1. Faites un clic-droit sur la fenêtre où vous voulez voir la Macro apparaître (la fenêtre Pion (''Token''), Campagne (''Campaign'') ou Globale) et choisissez '''Add New Macro''' (''Ajouter une nouvelle Macro''). Un bouton gris avec l'étiquette '''(new)''' apparaîtra.


Macro creation is a three-step procedure (though those three steps can contain multitudes!):
2. Faites un clic-droit sur le bouton et choisissez '''Edit''' (''Editer'')


1. Right-click on the panel where you want the macro to appear (either one of the token panels, the Campaign panel, or the Global panel) and select '''Add New Macro'''. A gray button with the label '''(new)''' will appear.
3. Saisissez du code Macro, attribuez lui un nom et cliquez sur '''OK'''. Bien ! Vous avez créé une Macro


2. Right-click on the button, and select '''Edit'''.
Un instant... que voulez vous dire par "code Macro" ?


3. Enter your macro code, give it a name, and hit '''OK'''. There! You've created a macro!
Comme indiqué précédemment, ces trois étapes peuvent contenir une quantité énorme de détails, étapes, astuces, réussites, échecs, frustrations et parfois hurlements et grincements de dents. Donc, nous allons reculer d'une étape regarder quelque Macros très simples avec une approche très progressive. Si vous voulez voir quelques Macros plus complexes, il en existe des tonnes à lire à travers les tutoriels et les comment-faire sur ce wiki. Pour l'instant, nous nous contenterons d'écrire quelque Macros très simples mais très utiles.


But wait...what do you mean, "macro code?"
===Le Jet d'Initiative===


As I said, those three steps can contain a ''huge'' amount of details, steps, tips, tricks, victories, failures, frustrations, and sometimes, hollering and gnashing of teeth. So, we'll take a step back and look at some very simple macros in a step-by-step fashion. If you want to see what some advanced macros can look like, there are plenty of tutorials and how-tos on this wiki to read through. For now, though, we'll do some simple, but useful, macro writing.
[[Image:Camp-panel-newbutton.png|thumb|Après avoir sélectionné "Add New Macro," un bouton étiqueté '''(new)''' apparaît dans la fenêtre Campagne(''Campaign'').]]


===Roll for Initiative===
[[Image:Camp-panel-rceditbutton.png|thumb|Un clic-droit sur le bouton permet d'ouvrir '''l'éditeur de Macro'''.]]


[[Image:Camp-panel-newbutton.png|thumb|After selecting "Add New Macro," a button labeled '''(new)''' appears on the Campaign Panel.]]
[[Image:Macro-editor-examplestring.png|thumb|Saisissez une étiquette pour la Macro ainsi que la commande Macro.]]


[[Image:Camp-panel-rceditbutton.png|thumb|Right-clicking on the button opens the macro editor.]]
[[Image:Camp-panel-exbutton.png|thumb|La fenêtre Campagne (''Campaign'') avec votre nouvelle Macro dedans.]]


[[Image:Macro-editor-examplestring.png|thumb|Entering a macro label and the macro command]]
Les plus simples des Macros ne sont rien de plus que du texte qui est re-dirigée vers la fenêtre de discussion (''Chat''). En effet, une Macro contenant du texte (en fait toutes les Macros) envoie juste une ligne de commande à la fenêtre de discussion où elle est lue puis interprétée. La plupart des langages de programmation commencent avec le classique programme "Hello World!", donc ce guide ne fera pas cela. A la place, essayons de faire quelque chose de plus "rôlistique" : créons le redoutable message "Effectuez votre jet d'initiative !"


[[Image:Camp-panel-exbutton.png|thumb|The '''Campaign Panel''' with your newly created macro on it]]
1. Sélectionnez la fenêtre Campagne.


The simplest macros are no more than text, which is output to the chat window. In effect, a macro containing text (in fact, all macros) just send a string of commands to the chat window where it is read and interpreted. Most programming languages start off with the classic "Hello World!" program, so this guide is ''not'' going to do that. Instead, let's do something a bit more RPG: create the dreaded "Roll for Initiative!" message!
2. Faites un clic-droit dessus et choisissez '''Add New Macro'''.


1. Select the Campaign Panel.
3. Faites un clic-droit sur la nouvelle Macro et cliquez sur '''Edit'''.


2. Right-click on it, and select '''Add New Macro'''.
4. Dans le champ '''Label''' (''Etiquette''), saisissez "Jet d'initiative"


3. Right-click on the new macro button, and click '''Edit'''.
5. Laissez les champs '''Group''' et '''Sort Prefix''' vide.


4. In the '''Label''' field, enter "Roll for Initiative!"
6. Dans le champ '''Command''', tapez 


5. Leave the '''Group''' and '''Sort Prefix''' fields blank.
<blockquote style="background-color:lightgray; border=1px solid gray; width:50%;"><tt>Effectuez votre jet d'initiative !</tt></blockquote>


6. In the '''Command''' field, type
7. Cliquez sur '''OK'''.


<blockquote style="background-color:lightgray; border=1px solid gray; width:50%;"><tt>Roll for Initiative!</tt></blockquote>
8. Vous voyez maintenant que votre bouton a changé - il est maintenant écrit dessus : '''Jet d'initiative''', et lorsque vous cliquez dessus, ô merveilles, le texte "Effectuez votre jet d'initiative !" apparaît dans la fenêtre de discussion.


7. Click '''OK'''.  
Ceci représente la base de l'écriture de Macros : vous saisissez du texte dans la Macro, puis, lorsque vous appuyez sur le bouton, ce texte est lu par l'analyseur syntaxique et envoyé à la fenêtre de discussion.


8. When you're done, you'll see that the button has changed - it now says '''Roll for Initiative!''' on it, and when you click it, lo and behold, the text "Roll for Initiative!" appears in the chat window.
===Toujours plus intéressant===


That is macro writing at its most basic: you enter some text in the macro, and that text is read by the parser and sent to the chat window when you press the button.  
Le "Jet d'initiative", tout effrayant qu'il soit lorsqu'il est demandé par votre MJ, n'est par ce qu'on peut trouver de plus intéressant en terme de Macro. Vous vous êtes probablement demandé "pourquoi ne pas le taper tout simplement dans la fenêtre de discussion ?" Et la réponse est "vous auriez sûrement mieux fait !" Alors essayons de faire quelque chose de plus intéressant, que nous voudrions garder au premier plan en utilisant MapTool (après tout, nous ne sommes pas là pour écrire des programmes - nous sommes ici pour jouer) : nous allons ajouter quelques ''commandes Macro'', en complément du simple texte. Les commandes Macro sont des instruction spéciales qui, lorsqu'elles sont lues par l'analyseur syntaxique, lui demandent de faire des choses en plus que simplement afficher du texte dans la fenêtre de discussion, comme lancer des dés ou calculer des valeurs.


===Something More Interesting===
Les commandes Macro doivent ''toujours'' être encadrées par des crochets ([''commande Macro'']) ou des accolades ({''commande Macro''}). Les encadrer de cette manière indique à l'analyseur syntaxique qu'une commande est en train d'arriver - autrement, il traitera la commande comme du simple texte et l'affichera dans la fenêtre de discussion.


"Roll for Initiative," though scary when your GM utters it, is not all that ''interesting'' a macro. You probably thought, "why wouldn't I just type that in chat?" And in fact, the answer is, "you probably would." So let's do something more interesting, and more in keeping with why we're using MapTool in the first place (after all, we're not here to write programs - we're here to play games): we're going to add some ''macro commands'' to the macro, in addition to just plain text. Macro commands are special instructions that, when read by the parser, tell it to do something more than just print text in the chat window, like roll some dice or calculate a value.
====Quelques jets de dés====


Macro commands must ''always'' be enclosed in square brackets (e.g, [''macro command'']) or curly braces (e.g., {''macro command''}). Enclosing them in this fashion is what clues the parser in that a command is coming - otherwise, it will treat the command just like any other text, and print it in chat.
[[Image:Macro-editor-rolldice.png|thumb|Une Macro contenant du texte et un jet de dés basique de 1D20+7]]


====Roll Some Dice====
Ceci est une Macro simple qui va automatiquement lancer un dé 20 et ajouter le nombre 7 à ce jet, avant d'afficher l'ensemble dans la fenêtre de discussion.


[[Image:Macro-editor-rolldice.png|thumb|A macro with text and a basic dice roll of 1d20+7]]
1. Créez une nouvelle Macro (à l'endroit que vous voulez - sur un Pion, dans la fenêtre Campagne ou globale), et ouvrez l'éditeur de Macro (souvenez vous que pour faire cela, vous devez faire un clic-droit surle bouton '''(new)'''.


This is a simple macro that's going to automatically roll some dice, and add a number to that roll, before displaying the whole thing in the chat window.  
2. Dans le champ '''Label''' donnez le nom "jet d'attaque" ou "jet de dés".


1. Create a new macro (this can be created anywhere you like - on a token, in the campaign panel, or in the global panel), and open the edit dialog (remember, you do that by right-clicking on the button labeled '''(new)''').
3. Dans le champ '''Command''', entrez:


2. In the '''Label''' field, call the macro something like "Attack Roll" or "Dice Roll"
<blockquote style="background-color:lightgray; border=1px solid gray; width:50%;"><tt>Mon jet d'attaque est : [1d20+7]!</tt></blockquote>


3. In the '''Command''' area, enter:
4. Cliquez sur '''OK'''. Vous devriez voir un bouton avec le nom que vous avez choisi précédemment. Quand vous cliquez dessus, vous voyez apparaître quelque chose comme ceci dans la fenêtre de discussion :


<blockquote style="background-color:lightgray; border=1px solid gray; width:50%;"><tt>My attack roll is [1d20+7]!</tt></blockquote>
<blockquote style="border:1px solid gray; width:50%;">Chris: Mon jet d'attaque est : <font style="background-color:lightgray;">8</font>!</blockquote>


4. Click '''OK'''. You should see a button labeled with whatever you chose in Step 2, above. When you click it, you'll see something like the following appear in chat:
Ce qui s'est passé est que MapTool a lu le contenu de la Macro et quand il est arrive à la partie '''[1d20+7]''', il a su qu'il devait :


<blockquote style="border:1px solid gray; width:50%;">Chris: My attack roll is <font style="background-color:lightgray;">8</font>!</blockquote>
# Lancer 1 dé à 20 faces (ou plus exactement choisir un nombre aléatoire entre 1 et 20),
# Ajouter 7 à ce résultat,
# Afficher le résultat dans la fenêtre de Discussion correctement placé après le texte.


What has happened is that MapTool read through the contents of the macro, and when it got to the section '''[1d20+7]''', it knew to:
Vous avez remarqué que le nombre 8 a un fond gris. Si vous laissez la souris au-dessus un moment, une info-bulle apparaîtra expliquant comment ce chiffre a été obtenu. Dans notre cas, j'ai obtenu 1 sur le dé 20 (un échec critique !). Si vous ne pouvez pas voir l'info-bulle, vérifiez vos réglages de [[MapTool Preferences#Chat|discussion]] et  choisissez '''Use ToolTips for Inline Rolls''' (''utiliser les info-bulles pour les jets en interne'').


# Roll a 20-sided die (or, in reality, choose a random number between 1 and 20), and
De plus, vous ne verrez probablement pas le mot "Chris", à moins que vous ne vous appeliez également Chris. Cette partie de la fenêtre de discussion est juste pour indiquer qui "a dit" ce morceau de texte en particulier. Si c'était un Pion, vous auriez eu le nom du Pion avec son image au lieu de l'ennuyeux "Chris".
# Add 7 to that result, and
# Display the results in the chat window, inserted into the text in the right place


You'll see that the number 8 has a gray background. If you hover over that number, a "tooltip" will pop up showing how that number was reached. In this case, I managed to roll a 1 on the 1d20 (bummer! a critical fumble!)  If you don't see this tooltip, check your [[MapTool Preferences#Chat]] settings, specifically '''Use ToolTips for Inline Rolls'''.
====Autre chose que des nombres ?====


Also, you probably won't see the name "Chris", unless your name happens to be Chris. That part of the chat output is just indicates who "said" that particular bit of text; if it was a token, it would have the token's picture and name instead of boring old "Chris."
Les commandes Macro peuvent fonctionner avec des nombres et avec du texte -- vous pouvez manipuler les ''lignes'' (des collections de caractères alphanumériques) de la même façon grâce au langage de Macros de MapTool. Disons que pour l'occasion, vous voulez effectuer un jet de dé, mais vous voulez aussi que le nom de votre cible soit affiché dans la fenêtre de discussion.


====More than Just Numbers====
[[Image:Macro-editor-basiccommands.png|thumb|Une Macro avec une commande de dé et une variable appelée ''target'' (cible)]]


Macro commands can work with numbers and with text -- you can manipulate ''strings'' (that is, collections of alphanumeric characters) as well using the MapTool macro language. Say, for instance, you wanted to roll your attack, but wanted to enter the name of your target so that it showed up in chat.
[[Image:Prompt-undeclared-variable.png|thumb|Une boite de dialogue pour une "variable indéfinie"]]


[[Image:Macro-editor-basiccommands.png|thumb|A macro with a basic dice command and a variable called ''target'']]
Vous pouvez ainsi modifier votre Macro ''Jet de dés'' de la manière suivante :


[[Image:Prompt-undeclared-variable.png|thumb|A prompt for an "undeclared variable"]]
<blockquote style="background-color:lightgray; width:50%;"><tt>J'ai obtenu [1d20+7] à mon jet d'attaque contre [cible] !</tt></blockquote>


What you can do is edit your Attack Roll macro to look like this:
Lorsque vous lancez cette Macro, une boite de dialogue apparaît vous demandant : "Value For cible." Que s'est-il passé ?


<blockquote style="background-color:lightgray; width:50%;"><tt>My attack roll against [target] is [1d20+7]!</tt></blockquote>
Et bien, quand MapTool a analysé la Macro, il a vu une commande macro disant simplement '''[cible]'''. MapTool part du principe que tout mot entre crochet et qui n'est pas reconnu par l'analyseur syntaxique comme partie d'une commande macro, représente une variable (en d'autres termes, sa valeur peut changer).


When you run this macro, though, suddenly a window pops up in your face demanding a "Value For target." What happened?
MapTool a aussi remarqué que nulle part dans la Macro, il n'était précisé à quoi était égale la variable ''cible''. Les langages de programmation appelle ce genre de situation des ''variables non déclarées'' (vous n'avez jamais précisé à quoi elle était égale). Puisque MapTool n'a aucun moyen de savoir ce que ''cible'' pourrait être, il vous le demande ! Si vous tapez un nom, un nombre ou tout ce qui vous passe par la tête dans cette boite de dialogue, MapTool prendra cette information et l'attribuera à la variable ''cible'', avant de poursuivre le déroulement de la Macro.


Well, when MapTool looked at that macro, it saw a macro command that just says '''[target]'''. MapTool assumes that any word ''inside'' a macro command that is ''not'' enclosed in quotes is actually the name of a ''variable'' (in other words, a value that might change).  
Continuez et saisissez "cet orque désobligeant" (vous pouvez retirer les guillemets) dans cette boite de dialogue, et cliquez sur '''OK'''. vous devriez obtenir dans la fenetre de discussion quelque chose comme :


MapTool also noted that nowhere in that macro do we say ''what'' the variable ''target'' happens to equal. Programming languages call this sort of situation an ''undeclared variable'' (in other words, you never declared what it equaled). Since MapTool has no way of knowing what ''target'' should be, it asks! If you type a name, number, or pretty much anything in that popup window, MapTool will take that information, assign it to the variable ''target'', and finish the macro.
<blockquote style="border:1px solid gray;" width:50%;>Chris: J'ai obtenu  <font style="background-color:lightgray;">23</font> à mon jet d'attaque contre <font style="background-color:lightgray;">cet orque désobligeant</font> !</blockquote>


Go ahead and type "Nasty Orcses" (you can leave off the quotes) in the box, and hit '''OK'''. You should see in the chat window something like:
Encore une fois, l'analyseur syntaxique parcourt le texte et les commandes macro que vous avez placés dans la Macro, et à la place indiquée par les commandes macro (entre crochet), MapTool substitue le résultat approprié.


<blockquote style="border:1px solid gray;" width:50%;>Chris: My attack roll against <font style="background-color:lightgray;">Nasty Orcses</font> is <font style="background-color:lightgray;">23</font>!</blockquote>
==Utiliser des Variables dans une Macro==


Once again, the parser read through the text and macro commands you put inside the macro, and in the places where a macro command was indicated (by the square brackets, remember), MapTool substituted the appropriate information.
Nous avons vu une paire d'exemples avec quelques utilisations de variables (comme {{code|cible}} dans l'exemple précédent) dans une Macro, mais nous n'avons pas encore été très loin dans cette matière. Pourtant, les variables et leurs utilisations représentent vraiment le cœur de l'écriture de macro. Il est donc impossible de passer outre ce sujet.


==Using Variables in a Macro==
===Qu'est-ce qu'une Variable?===


We've seen in a couple of the examples some use of variables (like {{code|target}} in the example above) in a macro, but we haven't gone into the process too deeply yet. However, variables, and their use, is really the core of macro writing, so it would be remiss of me to leave it go.
Si vous avez déjà fait de la programmation, vous devez déjà savoir tout cela, mais si vous venez juste de vous lancer dedans, une définition simple de ''variable'' en terme de langage de Macro est :


===What's a Variable?===
:'''Une variable est une valeur qui peut changer et qui est basée sur une propriété d'un Pion, sur un calcul ou une autre commande Macro'''.


If you're familiar with programming at all, you will know this already, but if you're just stepping into this stuff cold, the simple definition of a ''variable'' in terms of the macro language is:
Puisque la valeur d'une variable n'est pas fixe, nous devons lui donner un nom (on dit qu'on ''déclare'' la variable pour que le système sache qu'elle existe) de manière à pouvoir l'utiliser. Ensuite, quel que soit le moment où nous aurons besoin de la valeur de la variable ''à ce moment'', nous n'aurons qu'à placer son nom dans une commande Macro (entre crochet), et MapTool remplacera la valeur adéquate à ce moment là.


:'''A variable is a value that might change (i.e., vary) based on a token property, a calculation, or another macro command'''
Pensez de cette manière : si le résultat d'un jet de dés peut être n'importe quoi entre 1 et 20, vous pouvez par exemple dire qu'un résultat particulier a été un 19, un 2, un 7 ou n'importe quoi. Donc, à la place vous pourriez dire "quel que soit le résultat du jet de dés, affiche ce résultat-ci !"


Since the value of a variable might change, we have to give it a name (which is called ''declaring'' the variable - you declare that "this variable exists!") in order to talk about it. Then, whenever we need to use whatever value the variable has ''at that time'', we just put its name in the macro command, and MapTool will substitute the appropriate value at that time.  
:'''Remarque''': cela ne signifie pas que MapTool va substituer la valeur ''correcte'' en fonction de ''vos'' besoins; cela signifie qu'il va remplacer la valeur correspondant à la variable par une autre quand vous le lui demanderez. Donc si votre Macro contient une erreur, le résultat risque d'être faux - mais MapTool n'a aucun moyen de savoir si un résultat est faux, il ne fait qu'exécuter ce que vous lui demander.


Think of it this way: if the value of a dice roll could be anything between 1 and 20, for example, you can't just enter 19 wherever you need to use that dice roll - it could be 19, or 2, or 7, or whatever. So instead, you'd want to say "whatever this dice roll is, put that number here."
===Affectation de Variables===


:'''Note''': that doesn't mean that MapTool will substitute the ''correct'' value for ''your'' needs; it means it will substitute the value corresponding to that variable at that time. So if your program has a mistake in it, the value might end up being wrong - but MapTool doesn't understand "wrong," it just understand "this is what it says right now."
Lorsque vous voulez donner à une variable une valeur donnée, cela est appelé "affecter" une valeur à la variable. "L'opérateur d'affectation" dans MapTool est le signe égal ( = ). Cela semble facile, mais cela signifie juste que vous utilisez le signe égal pour dire à MapTool qu'une certaine variable a une valeur particulière. Un exemple d'affectation de variables est :
 
===Variable Assignments===
 
When you want to give a variable a value, this is called "assigning" a value to the variable. The "asignment operator" in MapTool is the equals sign ( = ). That sounds fancy, but it just means that you use an equals sign to tell MapTool that a particular variable has a particular value. An example of a variable assignment is


<blockquote>
<blockquote>
<source lang="mtmacro">
<syntaxhighlight lang="mtmacro">
[h:myHP = 30]
[h:mesPV = 30]
</source>
</syntaxhighlight>
</blockquote>
</blockquote>


As you have probably figured out, what that line does is first ''declare'' a variable called {{code|myHP}} exists, and then ''assign'' it the value {{code|30}}. That is variable assignment at its root - ''some variable'' equals ''some value''.  
Comme vous l'avez déjà deviné, ce que fait cette ligne est :
# déclarer l'existence d'une variable appelée {{code|mesPV}},
# assigner la valeur {{code|30}} dans cette variable.
Il s'agit ici d'une affectation de variable à la racine - ''une variable'' égale ''une valeur''.


You'll remember from the example where you were prompted for the name of a target that you can use a variable name without assigning a value to it. If you do that, you have declared that the variable exists, but no value is assigned, so MapTool asks you (or whoever runs that macro) for a value. The lesson learned is that a variable needs to have a value assigned to it for the macro to finish, but you don't always have to enter it ahead of time - sometimes you want to get ''input'' from the user.  
Vous vous souvenez de l'exemple où vous était demandé de saisir le nom de la cible que vous utilisiez comme variable sans lui avoir affecté de valeur. Vous aviez déclaré l'existence de la variable, mais sans lui assigner de valeur, en conséquence, MapTool vous demandait cette valeur. Ce qu'il faut retenir ici, c'est qu'une Macro utilisant des variables a besoin de connaître les valeurs de celles-ci pour pouvoir se terminer. Il n'est cependant pas toujours nécessaire de les affecter auparavant, quelquefois il est indispensable de demander à l'utilisateur quel paramètre utiliser.


===When to Make an Assignment===
===Comment déclarer une affectation===


MapTool processes each macro command in a macro in order, starting at the top. Therefore, unless you want MapTool to pop up a window asking for input from the user, you have to assign a value to a variable ''before'' you use it! For example, in the macro command:
MapTool traite chaque commande Macro à l'intérieur d'une Macro dans l'ordre, en commençant par le haut. En conséquence, à moins que vous ne vouliez que MapTool vous demande la valeur de toutes les variables que vous projetez d'utiliser, vous devrez affecter des valeurs à ces variables avant ''d'utiliser'' la Macro ! Par exemple dans la commande Macro suivante :


{{code|The hit does [damage] [damageType] damage, leaving you with [remainingHP] hit points!}}
{{code|Ce coup inflige [Dommages] points de dégâts de [TypedeDommages], vous laissant avec [PVrestants] points de vie!}}


Unless you want MapTool to prompt the user for the variables {{code|damage}}, {{code|damageType}}, and {{code|remainingHP}}, you'll want to make sure to give them a value ''before'' you get to that line. Maybe something like:
A moins que vous ne vouliez que MapTool n'ouvre des boites de dialogue pour vous demander la valeur de  {{code|Dommages}}, {{code|TypedeDommages}}, et {{code|PVrestants}}, vous devrez vous assurer de leur avoir donné une valeur ''avant'' que MapTool n'exécute cette ligne. Peut-être avec quelque chose comme ceci :


<blockquote style="background-color:lightgray;">
<blockquote style="background-color:lightgray;">
<source lang="mtmacro">
<syntaxhighlight lang="mtmacro">
[h:damage = 1d6+4]
[h:Dommages = 1d6+4]
[h:damageType = "fire"]
[h:TypedeDommagese = "feu"]
[h:remainingHP = 30 - damage]
[h:PVrestants = 30 - Dommages]
The hit does [damage] [damageType] damage, leaving you with [remainingHP] hit points!
Ce coup inflige [Dommages] points de dégâts de [TypedeDommages], vous laissant avec [PVrestants] points de vie!
</source>
</syntaxhighlight>
</blockquote>
</blockquote>


As you can see, we've made three variable assignments ''before'' the variables are used in the line about the hit. We've assigned the value of a dice roll of 1d6+4 to the variable {{code|damage}}, the value {{code|"fire"}} to the variable {{code|damageType}}, and the value of the operation {{code|30 - damage}} to the variable {{code|remainingHP}}.  
Comme vous pouvez le voir, nous avons fait trois affectations de variables avant qu'elles ne soient utilisées dans la ligne gérant le coup reçu. Nous avons affecté la valeur d'un jet de dés à six face plus quatre à la variable {{code|Dommages}}, la valeur {{code|"feu"}} à la variable {{code|TypedeDommages}}, et le résultat de l'opération {{code|30 - Dommages}} à la variable {{code|PVrestants}}.


If you look carefully, you'll see that we've even used one variable in assigning a value to another variable: the value of the variable {{code|damage}} is used when we assign a value to {{code|remainingHP}} - so variables can be used to set and manipulate other variables.  
si vous regardez attentivement, vous verrez que nous avons même utilisé une variable pour affecter une valeur dans une autre variable : la valeur de la variable {{code|Dommages}} est utilisée quand nous affectons une valeur à la variable {{code|PVrestants}} - donc, des variables peuvent être utilisées pour définir ou manipuler d'autres variables.


===Variable Rules===
===Règles concernant les Variables===


There are two rules to remember when making up variables:
Il y a deux règles à se souvenir quand on crée une variable :


# No spaces: variable names can't have spaces in them, so you can't use the variable {{code|Hit Points}} - it has to be {{code|HitPoints}}.  
# aucun espace : les noms de variables ne peuvent contenir d'espace, ainsi vous ne pouvez utiliser la variable : {{code|Points de Vie}}, mais plutôt choisir celle-ci : {{code|PointsdeVie}}.
# Special Variables: there are several "special variables" that MapTool has reserved - which means you can't use them for other purposes than what MapTool already reserves them for. You can usually tell a special variable because it has a period it's name, like {{code|[[roll.count]]}} or {{code|[[macro.args]]}}. We'll get into those in another guide, but for now, just know that you can't create a variable with the same name as any of the variables on the [[:Category:Special Variable|Special Variables]] page.
# Variables spéciales : il existe plusieurs "variables spéciales" que MapTool se réserve - ce qui signifie que vous ne pouvez pas les utiliser pour autre chose que ce qui a déjà été prévu par MapTool. En général, vous pouvez les reconnaître facilement car elles ont un point dans leur nom, comme {{code|[[roll.count]]}} ou {{code|[[macro.args]]}}. Ces variables spéciales seront traitées dans un autre guide, mais pour l'instant vous devez juste savoir que vous ne pouvez pas créer de variable avec un nom se trouvant dans la [[:Category:Special Variable|liste suivante]].


==Stepping Up Our Game==
==Mettre à niveau notre jeu==


The examples above show very basic macro use: printing text to the chat window at the click of a button; making a simple dice roll inside a macro; and even getting some simple input from the user in order to complete a macro.
Les exemples précédents montre des utilisations basiques des Macros : afficher du texte dans la fenêtre de discussion lorsqu'on clique sur un bouton, effectuer un jet de dés simple à l'intérieur d'une Macro et même récupérer des infos de la part de l'utilisateur pour terminer une Macro.


Now, let's step it up: we'll play with some formatting options, change token properties, and look at some basic looping (doing the same thing over and over again) and branching (doing different things based on some condition or situation).  
Allons maintenant un peu plus loin : nous allons jouer avec les options de mise en page, modifier les valeurs des propriétés des Pions et jeter un œil à quelques boucles très simple (lorsque vous faites et refaites quelque chose) et au embranchement (faire des choses différentes en fonction des conditions ou de la situation).


===Formatting Options===
===Options de mise en page===


Macro output (like any chat output) can be formatted using basic HTML tags, as well as some options built into MapTool. We'll first look at the HTML briefly, and then at a couple [[:Category:Display Roll Option|Display Roll Options]].
Le résultat d'une Macro (tout comme n'importe quelle ligne dans la fenêtre de discussion) peut être formaté en utilisant les balises [http://www.codeshttp.com/baliseh.htm HTML] de base, de même que quelques options propres à MapTool. Nous examinerons brièvement la partie HTML, pour observer quelques [[:Category:Display Roll Option|options d'affichage de jet de dés]].


====Expanded Rolls====
====Jets de dés explicites====


In MapTool 1.3.b54, the default way to output the result of a dice roll or calculation is just to print out the total or final value. So if you rolled 1d20+7, what will appear in chat is just the final result, with the tooltip (remember when you hovered your mouse over the number) showing the mathematical breakdown.  
Dans MapTool 1.3.b54, la manière habituelle d'afficher un résultat d'un jet de dés ou d'un calcul consiste à n'afficher que le total ou le résultat final. Ainsi si vous lancez 1D20+7, seul le résultat final apparaître dans la fenêtre de discussion, avec une info-bulle (si vous passez la souris sur le résultat) affichant le détail du calcul.


If you wish, you can instruct MapTool to print out the full math breakdown for a roll too, by using a Roll Formatting Option - specifically, the '''Expanded Roll'''.
Si vous le souhaitez, vous pouvez demander à MapTool de décomposer le résultat du calcul également, en utilisant une option de formatage des jets de dés - appelée '''Jets de dés explicites'''.


Think of a formatting option as a switch telling MapTool how to treat the results of a roll. To get the expanded form, edit your attack roll macro to show:
Pensez à ces options de formatage comme à un interrupteur qui dirait à MapTool comment s'occuper du résultat d'un jet de dés. Pour obtenir la forme explicite, éditez votre Macro sur le jet d'attaque comme ceci :


<blockquote style="background-color:lightgray; border=1px solid gray; width:50%;"><tt>My attack roll against [target] is [e:1d20+7]!</tt></blockquote>
<blockquote style="background-color:lightgray; border=1px solid gray; width:50%;"><tt>J'ai obtenu [e:1d20+7] à mon jet d'attaque contre [cible] !</tt></blockquote>


Then, when you run it, you'll get something like this in the chat:
Lorsque vous lancerez la Macro plus tard, vous obtiendrez dans la fenêtre de discussion :


<blockquote style="border:1px solid gray;width:50%;">My attack roll against <font style="background-color:lightgray; ">Nasty Orcses</font> is <font style="background-color:lightgray; color:blue;">« 1d20+7 = 1 + 7 = 8 »</font></blockquote>
<blockquote style="border:1px solid gray;width:50%;">J'ai obtenu <font style="background-color:lightgray; ">« 1d20+7 = 1 + 7 = 8 »</font> à mon jet d'attaque contre <font style="background-color:lightgray; color:blue;">cet orque désobligeant</font> !</blockquote>


Now you can see the full breakdown of your roll.  
Vous pouvez ainsi voir le détail du résultat de votre jet de dés.


====Result-Only Rolls====
====Affichage exclusif du résultat====


But what if you ''don't'' want anyone to be able to see the breakdown? So far, both options still let everyone see the actual roll. For this, you use the '''Result Roll''' option. Edit your macro to look like this:
A l'inverse, que se passe-t-il si vous ne voulez pas que qui que ce soit puisse voir le détail d'un résultat (par exemple, si vous ne voulez pas que vos joueurs puissent en déduire la puissance ou les faiblesses de leur adversaire). Pour cela choisissez l'option '''d'affichage exclusif du résultat'''. Éditez votre macro de la manière suivante :


<blockquote style="background-color:lightgray; border=1px solid gray; width:50%;"><tt>My attack roll against [target] is [r:1d20+7]!</tt></blockquote>
<blockquote style="background-color:lightgray; border=1px solid gray; width:50%;"><tt>J'ai obtenu [r:1d20+7] à mon jet d'attaque contre [cible] !</tt></blockquote>


And your output will look like this:
Et le résultat apparaîtra comme ceci :


<blockquote style="border:1px solid gray; width:50%;">My attack roll against <font style="background-color:lightgray">Nasty Orcses</font> is 11!</blockquote>
<blockquote style="border:1px solid gray; width:50%;">J'ai obtenu 11 à mon jet d'attaque contre <font style="background-color:lightgray">cet orque désobligeant</font> !</blockquote>


Note that there's no gray background behind the number 11, and you can't get a tooltip if you hover over it. The Results Roll option strips out the special formatting, giving you just the plain text. If you wanted to get rid of the highlight behind the words "Nasty Orcses," you can just change the macro to:
Remarquez qu'il n'y a plus de fond gris derrière le nombre 11, et qu'aucune info-bulle n'apparaît lorsque vous passez la souris sur ce dernier. L'affichage exclusif ne fournit que du texte standard. Si vous voulez également vous débarrasser sur sur-lignage entourant les mots "cet orques désobligeant", vous n'avez qu'à éditer la Macro comme suit :


<blockquote style="background-color:lightgray; border=1px solid gray; width:50%;"><tt>My attack roll against [r:target] is [r:1d20+7]!</tt></blockquote>
<blockquote style="background-color:lightgray; border=1px solid gray; width:50%;"><tt>J'ai obtenu [r:1d20+7] à mon jet d'attaque contre [r:cible] !</tt></blockquote>


And the name of the target will be shown without any special highlighting.  
Et le nom de la cible s'affichera sans sur-lignage particulier.


====Hidden Rolls====
====Résultats cachés====


Sometimes, you don't want to see any output from the macro - maybe you just want it to show some text, and do the math in the background, without revealing everything. In those cases, you would replace the "r:" or "e:" in the above examples with an "h:", like in the example below:
Quelquefois, vous ne voulez pas du tout afficher le résultat d'une Macro - peut-être avez vous juste besoin d'afficher du texte et de faire les calcul en tâche de fond, sans rien révéler. Dans ce cas, vous devriez remplacer les "r:" ou les "e:" dans les exemples précédents par des "h:", comme dans l'exemple suivant :


<blockquote style="background-color:lightgray; border=1px solid gray; width:50%;"><tt>
<blockquote style="background-color:lightgray; border=1px solid gray; width:50%;"><tt>
[h:myHP = 30]<br/>
[h:PVmax = 30]<br/>
[h:Bloodied = myHP / 2]<br/>
[h:EnPeril =PVmax / 2]<br/>
My bloodied value is [Bloodied].</tt></blockquote>
Je suis en péril si j'ai moins de [EnPeril] points de vie.</tt></blockquote>


The example above is a very simple illustration of how the '''hidden roll''' is useful. In that macro, we're doing three things:
L'exemple ci-dessus est caractéristique de l'utilité du '''résultat caché'''. Dans cette Macro, nous faisons trois choses :


# Setting the value of the variable ''myHP'' to 30, but telling MapTool to hide this calculation
# régler la variable ''PVmax'' à 30, mais demander à MapTool de ne pas afficher le résultat,
# Setting the value of the variable ''Bloodied'' to the value of ''myHP'' divided by 2, but telling MapTool to hide this calculation too
# attribuer à la valeur de la variable ''EnPeril'' la moitié de la valeur ''PVmax'', mais demander là aussi à MapTool de ne pas afficher le résultat,
# Displaying some text, and inserting the value of ''Bloodied'' in at the end of the text output.
# afficher du texte en insérant la valeur ''EnPeril'' à l'endroit approprié.


If you run this macro, the output will look like:
Si vous lancez cette Macro, vous obtiendrez :
<blockquote style="border:1px solid gray; width:50%;">
<blockquote style="border:1px solid gray; width:50%;">
My bloodied value is <font style="background-color:lightgray;">15</font>
Je suis en péril si j'ai moins de <font style="background-color:lightgray;">15</font> points de vie.
</blockquote>
</blockquote>


However, if you ''don't'' use the '''hidden roll''' option, the output would look like:
En revanche, si vous ''n'utilisez pas'' la fonction '''résultat caché''', la sortie ressemblera à :


<blockquote style="border:1px solid gray; width:50%;">
<blockquote style="border:1px solid gray; width:50%;">
<font style="background-color:lightgray;">30</font> <font style="background-color:lightgray">15</font> My bloodied value is <font style="background-color:lightgray;">15</font>
<font style="background-color:lightgray;">30</font> <font style="background-color:lightgray">15</font>Je suis en péril si j'ai moins de <font style="background-color:lightgray;">15</font> points de vie.
</blockquote>
</blockquote>


The extra numbers come from the two calculations ''before'' the line of text. You don't need to see those, so, conveniently, you can hide them!
Les nombres en plus proviennent des deux déclarations de variables ''avant'' la ligne de texte. Vous n'avez aucun intérêt à montrer ces choses, alors il est bien pratique de pouvoir les cacher.


====HTML Formatting====
====Formatage HTML====


MapTool macros support formatting using some basic HTML tags. Let's say you wanted to put the name of your target as one line, the attack roll you're making as another, and as a third line, you wanted to add a dice roll for damage. You might edit your Attack Roll macro to look like this:
Les Macros dans MapTool supportent les balises HTML de base. Disons que vous voulez afficher le nom de votre cible sur une ligne, le résultat du jet d'attaque sur la suivante et enfin le résultat du jet de dommages éventuels sur la troisième. Vous pourriez éditer votre Macro de cette manière :


<blockquote style="background-color:lightgray; border=1px solid gray; width:50%;"><tt>
<blockquote style="background-color:lightgray; border=1px solid gray; width:50%;"><tt>
<nowiki>I make an attack roll!<br></nowiki><br>
<nowiki>J'ai fait un jet d'attaque !<br></nowiki><br>
<nowiki><b>Target</b>: [r:target]<br></nowiki><br>
<nowiki><b>Cible    </b>: [r:cible]<br></nowiki><br>
<nowiki><b>Attack</b>: [1d20+7]<br></nowiki><br>
<nowiki><b>Attaque  </b>: [1d20+7]<br></nowiki><br>
<nowiki><b>Damage</b>: [1d8+5]</nowiki>
<nowiki><b>Dommages </b>: [1d8+5]</nowiki>
</tt></blockquote>
</tt></blockquote>


When you run that macro, your output in chat will look like:
En lançant la Macro, vous obtiendrez :


<blockquote style="border:1px solid gray; width:50%;">
<blockquote style="border:1px solid gray; width:50%;">
I make an attack roll!<br/>
J'ai fait un jet d'attaque !<br/>
'''Target''': Nasty Orcses<br/>
'''Cible    ''': cet orque désobligeant<br/>
'''Attack''': <font style="background-color:lightgray;">15</font><br/>
'''Attaque  ''': <font style="background-color:lightgray;">15</font><br/>
'''Damage''': <font style="background-color:lightgray;">7</font><br/>
'''Dommages ''': <font style="background-color:lightgray;">7</font><br/>
</blockquote>
</blockquote>


That's just simple formatting - you could put the output in a table, change the font and background colors, change its size...many options are available!
Il s'agit simplement d'une mise en page - vous pourriez envoyer le résultat dans une table, changer les fontes, les couleurs de fond, les tailles de polices... de nombreuses options sont possibles.


'''NOTE''': If you're handy with HTML, be aware that MapTool supports HTML 3.2 - so things like the <nowiki><br></nowiki> tag should ''not'' be closed - it's <nowiki><br></nowiki>, not <nowiki><br/></nowiki>. Additionally, MapTool supports a subset of CSS 1 in the form of in-line styles, and also style sheets in certain instances. More information on the supported CSS tags can be found at [[Supported CSS Styles]].
'''REMARQUE''': si vous êtes déjà familier avec le HTML, notez bien que MapTool supporte le format HTML 3.2 - ainsi des balises telles que <nowiki><br></nowiki> ne doivent pas être ''fermées'' - utilisez <nowiki><br></nowiki> au lieu de <nowiki><br/></nowiki>. De plus, MapTool supporte partielement les feuilles de style en cascade au standard CSS 1. Pour plus d'informations sur les balises CSS supportées consultez cette [[Supported CSS Styles|partie]].


===Using Token Properties===
===Utiliser les Propriétés des Pions===


So far, we've manipulated some variables that are entered ahead of time, or that MapTool will ask for when you run a macro. We've got a formatted attack macro that lists a target, an attack, and a damage roll. However, we're still either ''hardcoding'' the values into the macro, or having the user put them in themselves every time they're needed. Since RPG characters are not all the same, we'll have to figure out a way to automate some of the numbers, so we can:
Ainsi, nous savons manipuler quelques variables définies préalablement, ou que MapTool demande à chaque fois que nous lancons une Macro. Nous savons en outre mettre en forme une attaque en listant la cible, le jet d'attaque et les eventuels dommages. Pourtant, nous devons encore coder en dur les valeurs dans les Macro ou laisser l'utilisateur les insérer lui-meme chaque fois que c'est nécessaire. Puisque les personnages de JDR ne sont pas tous les memes, nous devons imaginer un moyen d'automatiser certains de ces nombres, ainsi, nous pouvons :


# Make one macro that many people or characters can use
# créer une Macro que differentes personnes ou personnages peuvent utiliser
# Minimize how much typing we have to do!
# Réduire au strict minimum les différentes saisies au clavier !


As discussed in the [[Introduction to Tokens]], every token carries around with it a personal "character sheet" of sorts, in the form of the token's ''properties''. These properties can be ''referenced'' by a macro - so you can, for instance, write a macro that says "Roll 1d20, and add my character's Dexterity to the roll." I'm sure you see how this might be useful.
Comme indiqué dans la section [[Introduction to Tokens/fr]], tous les Pions emportent avec eux leur propre "feuille de personnage" à l'intérieur de l'onglet ''properties''. Ces propriétés peuvent etre ''référencées'' par une macro - vous pouvez ainsi par exemple écrire une macro disant "lance 1D20, et ajoute la dextérité de mon personnage au résultat." Je suis sur que vous voyez à quel point cela peut etre utile.


====Setting Some Sample Properties====
====Mise en place de quelques exemples de Propriétés====


Of course, for token properties to work, we've got to set them up. It's a good thing you read the [[Introduction to Properties]] and created a campaign file for the MapTool RPG [[Sample Ruleset]]!
Of course, for token properties to work, we've got to set them up. It's a good thing you read the [[Introduction to Properties]] and created a campaign file for the MapTool RPG [[Sample Ruleset]]!
Line 464: Line 465:


<blockquote>
<blockquote>
<source lang="mtmacro">
<syntaxhighlight lang="mtmacro">
Attack: [1d20]
Attack: [1d20]
</source>
</syntaxhighlight>
</blockquote>
</blockquote>


Line 479: Line 480:
'''Correct String'''
'''Correct String'''
<blockquote>
<blockquote>
<source lang="mtmacro">
<syntaxhighlight lang="mtmacro">
[string = "This is a string"]
[string = "This is a string"]
</source>
</syntaxhighlight>
</blockquote>
</blockquote>


'''Incorrect String'''
'''Incorrect String'''
<blockquote>
<blockquote>
<source lang="mtmacro">
<syntaxhighlight lang="mtmacro">
[string = This is a string]
[string = This is a string]
</source>
</syntaxhighlight>
</blockquote>
</blockquote>


Line 498: Line 499:


<blockquote>
<blockquote>
<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
[h:existingString = "The skill name you entered is "]
[h:existingString = "The skill name you entered is "]
[h:concatString = existingString+skill+"."]
[h:concatString = existingString+skill+"."]
[r:concatString]
[r:concatString]
</source>
</syntaxhighlight>
</blockquote>
</blockquote>


Latest revision as of 20:50, 15 March 2023

Languages:  English  • Deutsch  • français  • italiano  • 日本語  • 한국어

BEGINNER
THIS IS A BEGINNER ARTICLE

Qu'est-ce qu'une Macro?

Une Macro est une méthode simple d'automatiser des actions dans MapTool. La plupart du temps, les macros sont des scripts lus par un analyseur syntaxique, qui les interprète et garantit que les différentes parties sont traitées de la bonne manière ( par exemple, en garantissant qu'une commande pour ajouter deux nombres entre eux et bien traitée comme une commande de Macro et pas comme du simple texte dans une fenêtre de discussion).

Les Macros ont commencé tout doucement dans MapTool, mais maintenant, le langage de script est devenu un ensemble très complet de commandes et de fonctions qui peuvent pratiquement exécuter toutes les opérations que vous pouvez imaginer !

Ce que vous devriez déjà connaître

Les Macros représentent le point à partir duquel nous commençons à approfondir les caractéristiques et les fonctionnalités les plus puissantes - et les plus compliquées - de MapTool. Même si ce guide se veut le plus accessible possible, il y a quelques points que vous êtes supposés avoir déjà acquis :

  1. Nous supposons que vous avez lu "Introduction à la création de carte (fr)", et que vous êtes maintenant familiarisé avec l'interface de MapTool, que vous savez comment créer une nouvelle carte, sauvegarder des fichiers et placer des Pions sur la carte.
  2. Vous devez également avoir lu "Introduction à la gestion des Pions (fr)", et avoir les connaissances de base pour manipuler les Pions, examiner leurs propriétés et tout ce qui s'y rapporte.
  3. Enfin, puisque les Macros sont intimement liées aux propriétés des Pions, vous devez avoir lu les étapes qui y sont consacrées dans "Introduction aux Propriétés (fr)"et vous devez avoir créé un nouveau fichier de campagne basé sur un exemple de règles de jeu créé pour permettre aux nouveaux joueurs de se familiariser avec MapTool. Si vous n'avez pas lu ce guide, faites-le - cela rendra la plupart des exemples suivants beaucoup plus compréhensible !

Conventions utilisées pour ce Guide

Le maximum sera fait pour conserver le langage et la terminologie les plus cohérents possible. Dans ce guide :

  • Macro renvoie à une collection de commandes qui sont groupées ensemble pour exécuter automatiquement une tache.
  • Commande Macro renvoie à toute commande individuelle particulière ou à toute fonction utilisée à l'intérieur d'une Macro.
  • Le langage de Macro représente l'ensemble des commandes, fonctions et opérations que vous pouvez utiliser quand vous écrivez une Macro. Vous pouvez consulter la liste des fonctions disponibles ici.

De plus, Bien qu'il soit possible pour une Macro d'interagir avec une autre (on dit dans ce cas qu'elle "appelle" une autre Macro), dans ce guide, nous aborderons uniquement les Macros accessibles depuis l'onglet Macro et qui peuvent affecter uniquement les Pions auxquels elles sont associées.

Dans quels cas les utiliser ?

Il n'y a aucune obligation d'utiliser des Macros pour pouvoir utiliser MapTool. En effet, la fonction principale de MapTool est de partager une carte avec des amis et de pouvoir jouer à des jeux ( lisez Introduction à la création de carte (fr) et Introduction à l'hébergement de partie (fr) pour apprendre comment créer et partager des cartes avec votre groupe de joueurs), et MapTool fournit tout ce dont vous avez besoin pour cela : des cartes, des pions et un système de discussion (chat) pour vous permettre de dialoguer ou effectuer des jet de dés.

Toutefois, les possibilités sont beaucoup plus importantes, pour peu que vous souhaitiez en apprendre un petit plus sur les capacités des Macros. Par exemple, si vous voulez avoir un bouton qui en cliquant dessus vous permettra de lancer 1D20 et d'ajouter le modificateur automatiquement, c'est possible en créant une Macro pour cela. Si vous voulez modifier les points de vie après une blessure, vous pouvez écrire une Macro pour le faire. Ce guide va vous montrer comment.

Où trouver ces "Macros?"

Les Macros sont intégrées à différentes parties de l'interface de MapTool et aux objets à l'intérieur. Il ressort qu'une Macro peut "résider" à trois endroits :

Macros de Pion

L'endroit le plus naturel où trouver une Macro est un Pion. Les Macros de Pion sont liées au Pion sur lequel elles ont été créées le resteront tant que vous les y laisserez.

Les Macros de Pion (Token macros ) sont directement accessibles uniquement par les propriétaires du Pion, donc si vous ne possédez pas le Pion, vous ne pourrez pas interagir (ou même voir) les boutons de ces Macros.

Macros de Campagne

Les Macros de Campagne ne sont pas liées à un Pion en particulier, mais à la campagne toute entière. Ces Macros fonctionnent pratiquement comme une Macro de Pion, excepté ceci :

  1. Vous n'avez pas besoin de sélectionner. un Pion pour voir les Macros
  2. N'importe qui peut y accéder et les exécuter.

Les Macros de campagne sont particulièrement utiles au MJ et aux joueurs pour gérer des fonctions communes - en fait, si vous mettez en place une tache commune en tant que Macro de campagne, vous n'avez besoin que d'avoir une seule copie de celle-ci (au lieu d'une copie pour chaque Pion qui en aurait besoin).

Macros Globales

Les Macros globales se sont liées ni aux Pions, ni à une campagne - en fait, elles sont liées à votre exemplaire de MapTool. Ces Macros ne sont visibles de personne d'autre que vous, que vous soyez joueur ou MJ.

C'est un bon endroit pour ranger les Macros exécutant des tâches que vous ne voulez pas que les autres voient - comme des informations que vous voudriez montrer uniquement au moment où vous l'avez décidé; ou des tâches que vous voulez faire faire à vos PNJ mais que vous ne voulez pas que les PJ puissent faire.

Les fenetres de Macros

Les quatre fenêtres de Macros
Les quatre fenêtres empilées sur une seule, sélectionnables à travers les onglets situés en bas (de nombreux utilisateurs choisissent cette disposition pour gagner de la place)

Avec toutes ces discussions autour des Macros et de leur localisation (plus spécialement des boutons de Macros), vous vous demandez probablement où trouver ces boutons ? Vous les trouverez dans une des quatre fenêtres de Macros qui sont disponibles dans MapTool. Si vous ne trouvez pas ces fenêtres ou qu'une d'entre elles est manquante, vous pouvez les faire apparaître en allant dans le menu Windows (Fenêtres) et en cochant les fenêtres suivantes en fonction de vos besoins :

  • Selection (Sélection)
  • Impersonated (Interprétation)
  • Campaign (Campagne)
  • Global (Globale)

Vous devriez voir ces fenêtres apparaître dans MapTool si elle n'étaient pas déjà là. Si vous regardez les copies d'écran sur la droite, vous verrez que la fenêtre Globale est remplie avec un tas de boutons. Chacun d'eux exécute une Macro; les boutons apparaissent lorsque vous créez une nouvelle Macro

Fenêtre Sélection et Interprétation

Il y a deux fenêtres qui traitent directement des Macros des Pions : Sélection (Selection et Impersonated)

La fenêtre Sélection montre les boutons de toutes les Macros actuellement associées au Pion que vous avez sélectionné. Chaque bouton lance une série particulière de commandes Macro.

La fenêtre Interprétation (Impersonated) montre les macros du Pion que vous avez choisi d'interpréter. Interpréter un Pion est un moyen de faire comme si vous étiez le Pion - lorsque vous discutez, le texte apparaît comme s'il avait été dit par le Pion. Il est possible d'interpréter un Pion tout en en sélectionnant un autre, alors faites attention à la fenêtre que vous êtes en train d'utiliser !

La fenêtre Campagne (Campaign)

Cette fenêtre affiche toutes les Macros actuellement disponibles pour la campagne. Souvenez-vous qu'elles sont visibles de tout le monde.

La fenêtre Globale

Cette fenêtre contient les Macros globales que vous avez créées. Souvenez-vous qu'elles ne sont visibles que de vous.

Ecrire des Macros

La fenêtre Campagne (Campaign). Elle ne contient aucune Macro pour l'instant.
Un clic-droit dans cette fenêtre vous permet d'ajouter une nouvelle Macro.

La création de Macros se fait en trois étapes (même si chaque étape peut en contenir une multitude!) :

1. Faites un clic-droit sur la fenêtre où vous voulez voir la Macro apparaître (la fenêtre Pion (Token), Campagne (Campaign) ou Globale) et choisissez Add New Macro (Ajouter une nouvelle Macro). Un bouton gris avec l'étiquette (new) apparaîtra.

2. Faites un clic-droit sur le bouton et choisissez Edit (Editer)

3. Saisissez du code Macro, attribuez lui un nom et cliquez sur OK. Bien ! Vous avez créé une Macro

Un instant... que voulez vous dire par "code Macro" ?

Comme indiqué précédemment, ces trois étapes peuvent contenir une quantité énorme de détails, étapes, astuces, réussites, échecs, frustrations et parfois hurlements et grincements de dents. Donc, nous allons reculer d'une étape regarder quelque Macros très simples avec une approche très progressive. Si vous voulez voir quelques Macros plus complexes, il en existe des tonnes à lire à travers les tutoriels et les comment-faire sur ce wiki. Pour l'instant, nous nous contenterons d'écrire quelque Macros très simples mais très utiles.

Le Jet d'Initiative

Après avoir sélectionné "Add New Macro," un bouton étiqueté (new) apparaît dans la fenêtre Campagne(Campaign).
Un clic-droit sur le bouton permet d'ouvrir l'éditeur de Macro.
Saisissez une étiquette pour la Macro ainsi que la commande Macro.
La fenêtre Campagne (Campaign) avec votre nouvelle Macro dedans.

Les plus simples des Macros ne sont rien de plus que du texte qui est re-dirigée vers la fenêtre de discussion (Chat). En effet, une Macro contenant du texte (en fait toutes les Macros) envoie juste une ligne de commande à la fenêtre de discussion où elle est lue puis interprétée. La plupart des langages de programmation commencent avec le classique programme "Hello World!", donc ce guide ne fera pas cela. A la place, essayons de faire quelque chose de plus "rôlistique" : créons le redoutable message "Effectuez votre jet d'initiative !"

1. Sélectionnez la fenêtre Campagne.

2. Faites un clic-droit dessus et choisissez Add New Macro.

3. Faites un clic-droit sur la nouvelle Macro et cliquez sur Edit.

4. Dans le champ Label (Etiquette), saisissez "Jet d'initiative"

5. Laissez les champs Group et Sort Prefix vide.

6. Dans le champ Command, tapez

Effectuez votre jet d'initiative !

7. Cliquez sur OK.

8. Vous voyez maintenant que votre bouton a changé - il est maintenant écrit dessus : Jet d'initiative, et lorsque vous cliquez dessus, ô merveilles, le texte "Effectuez votre jet d'initiative !" apparaît dans la fenêtre de discussion.

Ceci représente la base de l'écriture de Macros : vous saisissez du texte dans la Macro, puis, lorsque vous appuyez sur le bouton, ce texte est lu par l'analyseur syntaxique et envoyé à la fenêtre de discussion.

Toujours plus intéressant

Le "Jet d'initiative", tout effrayant qu'il soit lorsqu'il est demandé par votre MJ, n'est par ce qu'on peut trouver de plus intéressant en terme de Macro. Vous vous êtes probablement demandé "pourquoi ne pas le taper tout simplement dans la fenêtre de discussion ?" Et la réponse est "vous auriez sûrement mieux fait !" Alors essayons de faire quelque chose de plus intéressant, que nous voudrions garder au premier plan en utilisant MapTool (après tout, nous ne sommes pas là pour écrire des programmes - nous sommes ici pour jouer) : nous allons ajouter quelques commandes Macro, en complément du simple texte. Les commandes Macro sont des instruction spéciales qui, lorsqu'elles sont lues par l'analyseur syntaxique, lui demandent de faire des choses en plus que simplement afficher du texte dans la fenêtre de discussion, comme lancer des dés ou calculer des valeurs.

Les commandes Macro doivent toujours être encadrées par des crochets ([commande Macro]) ou des accolades ({commande Macro}). Les encadrer de cette manière indique à l'analyseur syntaxique qu'une commande est en train d'arriver - autrement, il traitera la commande comme du simple texte et l'affichera dans la fenêtre de discussion.

Quelques jets de dés

Une Macro contenant du texte et un jet de dés basique de 1D20+7

Ceci est une Macro simple qui va automatiquement lancer un dé 20 et ajouter le nombre 7 à ce jet, avant d'afficher l'ensemble dans la fenêtre de discussion.

1. Créez une nouvelle Macro (à l'endroit que vous voulez - sur un Pion, dans la fenêtre Campagne ou globale), et ouvrez l'éditeur de Macro (souvenez vous que pour faire cela, vous devez faire un clic-droit surle bouton (new).

2. Dans le champ Label donnez le nom "jet d'attaque" ou "jet de dés".

3. Dans le champ Command, entrez:

Mon jet d'attaque est : [1d20+7]!

4. Cliquez sur OK. Vous devriez voir un bouton avec le nom que vous avez choisi précédemment. Quand vous cliquez dessus, vous voyez apparaître quelque chose comme ceci dans la fenêtre de discussion :

Chris: Mon jet d'attaque est : 8!

Ce qui s'est passé est que MapTool a lu le contenu de la Macro et quand il est arrive à la partie [1d20+7], il a su qu'il devait :

  1. Lancer 1 dé à 20 faces (ou plus exactement choisir un nombre aléatoire entre 1 et 20),
  2. Ajouter 7 à ce résultat,
  3. Afficher le résultat dans la fenêtre de Discussion correctement placé après le texte.

Vous avez remarqué que le nombre 8 a un fond gris. Si vous laissez la souris au-dessus un moment, une info-bulle apparaîtra expliquant comment ce chiffre a été obtenu. Dans notre cas, j'ai obtenu 1 sur le dé 20 (un échec critique !). Si vous ne pouvez pas voir l'info-bulle, vérifiez vos réglages de discussion et choisissez Use ToolTips for Inline Rolls (utiliser les info-bulles pour les jets en interne).

De plus, vous ne verrez probablement pas le mot "Chris", à moins que vous ne vous appeliez également Chris. Cette partie de la fenêtre de discussion est juste pour indiquer qui "a dit" ce morceau de texte en particulier. Si c'était un Pion, vous auriez eu le nom du Pion avec son image au lieu de l'ennuyeux "Chris".

Autre chose que des nombres ?

Les commandes Macro peuvent fonctionner avec des nombres et avec du texte -- vous pouvez manipuler les lignes (des collections de caractères alphanumériques) de la même façon grâce au langage de Macros de MapTool. Disons que pour l'occasion, vous voulez effectuer un jet de dé, mais vous voulez aussi que le nom de votre cible soit affiché dans la fenêtre de discussion.

Une Macro avec une commande de dé et une variable appelée target (cible)
Une boite de dialogue pour une "variable indéfinie"

Vous pouvez ainsi modifier votre Macro Jet de dés de la manière suivante :

J'ai obtenu [1d20+7] à mon jet d'attaque contre [cible] !

Lorsque vous lancez cette Macro, une boite de dialogue apparaît vous demandant : "Value For cible." Que s'est-il passé ?

Et bien, quand MapTool a analysé la Macro, il a vu une commande macro disant simplement [cible]. MapTool part du principe que tout mot entre crochet et qui n'est pas reconnu par l'analyseur syntaxique comme partie d'une commande macro, représente une variable (en d'autres termes, sa valeur peut changer).

MapTool a aussi remarqué que nulle part dans la Macro, il n'était précisé à quoi était égale la variable cible. Les langages de programmation appelle ce genre de situation des variables non déclarées (vous n'avez jamais précisé à quoi elle était égale). Puisque MapTool n'a aucun moyen de savoir ce que cible pourrait être, il vous le demande ! Si vous tapez un nom, un nombre ou tout ce qui vous passe par la tête dans cette boite de dialogue, MapTool prendra cette information et l'attribuera à la variable cible, avant de poursuivre le déroulement de la Macro.

Continuez et saisissez "cet orque désobligeant" (vous pouvez retirer les guillemets) dans cette boite de dialogue, et cliquez sur OK. vous devriez obtenir dans la fenetre de discussion quelque chose comme :

Chris: J'ai obtenu 23 à mon jet d'attaque contre cet orque désobligeant !

Encore une fois, l'analyseur syntaxique parcourt le texte et les commandes macro que vous avez placés dans la Macro, et à la place indiquée par les commandes macro (entre crochet), MapTool substitue le résultat approprié.

Utiliser des Variables dans une Macro

Nous avons vu une paire d'exemples avec quelques utilisations de variables (comme cible dans l'exemple précédent) dans une Macro, mais nous n'avons pas encore été très loin dans cette matière. Pourtant, les variables et leurs utilisations représentent vraiment le cœur de l'écriture de macro. Il est donc impossible de passer outre ce sujet.

Qu'est-ce qu'une Variable?

Si vous avez déjà fait de la programmation, vous devez déjà savoir tout cela, mais si vous venez juste de vous lancer dedans, une définition simple de variable en terme de langage de Macro est :

Une variable est une valeur qui peut changer et qui est basée sur une propriété d'un Pion, sur un calcul ou une autre commande Macro.

Puisque la valeur d'une variable n'est pas fixe, nous devons lui donner un nom (on dit qu'on déclare la variable pour que le système sache qu'elle existe) de manière à pouvoir l'utiliser. Ensuite, quel que soit le moment où nous aurons besoin de la valeur de la variable à ce moment, nous n'aurons qu'à placer son nom dans une commande Macro (entre crochet), et MapTool remplacera la valeur adéquate à ce moment là.

Pensez de cette manière : si le résultat d'un jet de dés peut être n'importe quoi entre 1 et 20, vous pouvez par exemple dire qu'un résultat particulier a été un 19, un 2, un 7 ou n'importe quoi. Donc, à la place vous pourriez dire "quel que soit le résultat du jet de dés, affiche ce résultat-ci !"

Remarque: cela ne signifie pas que MapTool va substituer la valeur correcte en fonction de vos besoins; cela signifie qu'il va remplacer la valeur correspondant à la variable par une autre quand vous le lui demanderez. Donc si votre Macro contient une erreur, le résultat risque d'être faux - mais MapTool n'a aucun moyen de savoir si un résultat est faux, il ne fait qu'exécuter ce que vous lui demander.

Affectation de Variables

Lorsque vous voulez donner à une variable une valeur donnée, cela est appelé "affecter" une valeur à la variable. "L'opérateur d'affectation" dans MapTool est le signe égal ( = ). Cela semble facile, mais cela signifie juste que vous utilisez le signe égal pour dire à MapTool qu'une certaine variable a une valeur particulière. Un exemple d'affectation de variables est : 

[h:mesPV = 30]

Comme vous l'avez déjà deviné, ce que fait cette ligne est :

  1. déclarer l'existence d'une variable appelée mesPV,
  2. assigner la valeur 30 dans cette variable.

Il s'agit ici d'une affectation de variable à la racine - une variable égale une valeur.

Vous vous souvenez de l'exemple où vous était demandé de saisir le nom de la cible que vous utilisiez comme variable sans lui avoir affecté de valeur. Vous aviez déclaré l'existence de la variable, mais sans lui assigner de valeur, en conséquence, MapTool vous demandait cette valeur. Ce qu'il faut retenir ici, c'est qu'une Macro utilisant des variables a besoin de connaître les valeurs de celles-ci pour pouvoir se terminer. Il n'est cependant pas toujours nécessaire de les affecter auparavant, quelquefois il est indispensable de demander à l'utilisateur quel paramètre utiliser.

Comment déclarer une affectation

MapTool traite chaque commande Macro à l'intérieur d'une Macro dans l'ordre, en commençant par le haut. En conséquence, à moins que vous ne vouliez que MapTool vous demande la valeur de toutes les variables que vous projetez d'utiliser, vous devrez affecter des valeurs à ces variables avant d'utiliser la Macro ! Par exemple dans la commande Macro suivante :

Ce coup inflige [Dommages] points de dégâts de [TypedeDommages], vous laissant avec [PVrestants] points de vie!

A moins que vous ne vouliez que MapTool n'ouvre des boites de dialogue pour vous demander la valeur de Dommages, TypedeDommages, et PVrestants, vous devrez vous assurer de leur avoir donné une valeur avant que MapTool n'exécute cette ligne. Peut-être avec quelque chose comme ceci : 

[h:Dommages = 1d6+4]
[h:TypedeDommagese = "feu"]
[h:PVrestants = 30 - Dommages]
Ce coup inflige [Dommages] points de dégâts de [TypedeDommages], vous laissant avec [PVrestants] points de vie!

Comme vous pouvez le voir, nous avons fait trois affectations de variables avant qu'elles ne soient utilisées dans la ligne gérant le coup reçu. Nous avons affecté la valeur d'un jet de dés à six face plus quatre à la variable Dommages, la valeur "feu" à la variable TypedeDommages, et le résultat de l'opération 30 - Dommages à la variable PVrestants.

si vous regardez attentivement, vous verrez que nous avons même utilisé une variable pour affecter une valeur dans une autre variable : la valeur de la variable Dommages est utilisée quand nous affectons une valeur à la variable PVrestants - donc, des variables peuvent être utilisées pour définir ou manipuler d'autres variables.

Règles concernant les Variables

Il y a deux règles à se souvenir quand on crée une variable :

  1. aucun espace : les noms de variables ne peuvent contenir d'espace, ainsi vous ne pouvez utiliser la variable : Points de Vie, mais plutôt choisir celle-ci : PointsdeVie.
  2. Variables spéciales : il existe plusieurs "variables spéciales" que MapTool se réserve - ce qui signifie que vous ne pouvez pas les utiliser pour autre chose que ce qui a déjà été prévu par MapTool. En général, vous pouvez les reconnaître facilement car elles ont un point dans leur nom, comme roll.count ou macro.args. Ces variables spéciales seront traitées dans un autre guide, mais pour l'instant vous devez juste savoir que vous ne pouvez pas créer de variable avec un nom se trouvant dans la liste suivante.

Mettre à niveau notre jeu

Les exemples précédents montre des utilisations basiques des Macros : afficher du texte dans la fenêtre de discussion lorsqu'on clique sur un bouton, effectuer un jet de dés simple à l'intérieur d'une Macro et même récupérer des infos de la part de l'utilisateur pour terminer une Macro.

Allons maintenant un peu plus loin : nous allons jouer avec les options de mise en page, modifier les valeurs des propriétés des Pions et jeter un œil à quelques boucles très simple (lorsque vous faites et refaites quelque chose) et au embranchement (faire des choses différentes en fonction des conditions ou de la situation).

Options de mise en page

Le résultat d'une Macro (tout comme n'importe quelle ligne dans la fenêtre de discussion) peut être formaté en utilisant les balises HTML de base, de même que quelques options propres à MapTool. Nous examinerons brièvement la partie HTML, pour observer quelques options d'affichage de jet de dés.

Jets de dés explicites

Dans MapTool 1.3.b54, la manière habituelle d'afficher un résultat d'un jet de dés ou d'un calcul consiste à n'afficher que le total ou le résultat final. Ainsi si vous lancez 1D20+7, seul le résultat final apparaître dans la fenêtre de discussion, avec une info-bulle (si vous passez la souris sur le résultat) affichant le détail du calcul.

Si vous le souhaitez, vous pouvez demander à MapTool de décomposer le résultat du calcul également, en utilisant une option de formatage des jets de dés - appelée Jets de dés explicites.

Pensez à ces options de formatage comme à un interrupteur qui dirait à MapTool comment s'occuper du résultat d'un jet de dés. Pour obtenir la forme explicite, éditez votre Macro sur le jet d'attaque comme ceci :

J'ai obtenu [e:1d20+7] à mon jet d'attaque contre [cible] !

Lorsque vous lancerez la Macro plus tard, vous obtiendrez dans la fenêtre de discussion :

J'ai obtenu « 1d20+7 = 1 + 7 = 8 » à mon jet d'attaque contre cet orque désobligeant !

Vous pouvez ainsi voir le détail du résultat de votre jet de dés.

Affichage exclusif du résultat

A l'inverse, que se passe-t-il si vous ne voulez pas que qui que ce soit puisse voir le détail d'un résultat (par exemple, si vous ne voulez pas que vos joueurs puissent en déduire la puissance ou les faiblesses de leur adversaire). Pour cela choisissez l'option d'affichage exclusif du résultat. Éditez votre macro de la manière suivante :

J'ai obtenu [r:1d20+7] à mon jet d'attaque contre [cible] !

Et le résultat apparaîtra comme ceci :

J'ai obtenu 11 à mon jet d'attaque contre cet orque désobligeant !

Remarquez qu'il n'y a plus de fond gris derrière le nombre 11, et qu'aucune info-bulle n'apparaît lorsque vous passez la souris sur ce dernier. L'affichage exclusif ne fournit que du texte standard. Si vous voulez également vous débarrasser sur sur-lignage entourant les mots "cet orques désobligeant", vous n'avez qu'à éditer la Macro comme suit :

J'ai obtenu [r:1d20+7] à mon jet d'attaque contre [r:cible] !

Et le nom de la cible s'affichera sans sur-lignage particulier.

Résultats cachés

Quelquefois, vous ne voulez pas du tout afficher le résultat d'une Macro - peut-être avez vous juste besoin d'afficher du texte et de faire les calcul en tâche de fond, sans rien révéler. Dans ce cas, vous devriez remplacer les "r:" ou les "e:" dans les exemples précédents par des "h:", comme dans l'exemple suivant :

[h:PVmax = 30]
[h:EnPeril =PVmax / 2]

Je suis en péril si j'ai moins de [EnPeril] points de vie.

L'exemple ci-dessus est caractéristique de l'utilité du résultat caché. Dans cette Macro, nous faisons trois choses :

  1. régler la variable PVmax à 30, mais demander à MapTool de ne pas afficher le résultat,
  2. attribuer à la valeur de la variable EnPeril la moitié de la valeur PVmax, mais demander là aussi à MapTool de ne pas afficher le résultat,
  3. afficher du texte en insérant la valeur EnPeril à l'endroit approprié.

Si vous lancez cette Macro, vous obtiendrez :

Je suis en péril si j'ai moins de 15 points de vie.

En revanche, si vous n'utilisez pas la fonction résultat caché, la sortie ressemblera à :

30 15Je suis en péril si j'ai moins de 15 points de vie.

Les nombres en plus proviennent des deux déclarations de variables avant la ligne de texte. Vous n'avez aucun intérêt à montrer ces choses, alors il est bien pratique de pouvoir les cacher.

Formatage HTML

Les Macros dans MapTool supportent les balises HTML de base. Disons que vous voulez afficher le nom de votre cible sur une ligne, le résultat du jet d'attaque sur la suivante et enfin le résultat du jet de dommages éventuels sur la troisième. Vous pourriez éditer votre Macro de cette manière :

J'ai fait un jet d'attaque !<br>
<b>Cible </b>: [r:cible]<br>
<b>Attaque </b>: [1d20+7]<br>
<b>Dommages </b>: [1d8+5]

En lançant la Macro, vous obtiendrez :

J'ai fait un jet d'attaque !
Cible : cet orque désobligeant
Attaque : 15
Dommages : 7

Il s'agit simplement d'une mise en page - vous pourriez envoyer le résultat dans une table, changer les fontes, les couleurs de fond, les tailles de polices... de nombreuses options sont possibles.

REMARQUE: si vous êtes déjà familier avec le HTML, notez bien que MapTool supporte le format HTML 3.2 - ainsi des balises telles que <br> ne doivent pas être fermées - utilisez <br> au lieu de <br/>. De plus, MapTool supporte partielement les feuilles de style en cascade au standard CSS 1. Pour plus d'informations sur les balises CSS supportées consultez cette partie.

Utiliser les Propriétés des Pions

Ainsi, nous savons manipuler quelques variables définies préalablement, ou que MapTool demande à chaque fois que nous lancons une Macro. Nous savons en outre mettre en forme une attaque en listant la cible, le jet d'attaque et les eventuels dommages. Pourtant, nous devons encore coder en dur les valeurs dans les Macro ou laisser l'utilisateur les insérer lui-meme chaque fois que c'est nécessaire. Puisque les personnages de JDR ne sont pas tous les memes, nous devons imaginer un moyen d'automatiser certains de ces nombres, ainsi, nous pouvons :

  1. créer une Macro que differentes personnes ou personnages peuvent utiliser
  2. Réduire au strict minimum les différentes saisies au clavier !

Comme indiqué dans la section Introduction to Tokens/fr, tous les Pions emportent avec eux leur propre "feuille de personnage" à l'intérieur de l'onglet properties. Ces propriétés peuvent etre référencées par une macro - vous pouvez ainsi par exemple écrire une macro disant "lance 1D20, et ajoute la dextérité de mon personnage au résultat." Je suis sur que vous voyez à quel point cela peut etre utile.

Mise en place de quelques exemples de Propriétés

Of course, for token properties to work, we've got to set them up. It's a good thing you read the Introduction to Properties and created a campaign file for the MapTool RPG Sample Ruleset!

The first step is to open up the MTRPG.cmpgn file (or whatever name you saved it as), and drag a token onto the map (if you don't already have one on there). If you've got no idea what that means, check out the Introduction to Mapping to learn about making maps and putting tokens on them. Now, follow these steps:

1. Double click on a token to open the Edit Token dialog.

2. Go to the tab marked Properties.

3. You'll see a spreadsheet-style list of all the properties in the token that you can edit directly (tokens have other properties that can be edited only with macros, but for now, let's not worry about them!). You should see (if you're using the MTRPG.cmpgn file we set up in Introduction to Properties):

*Strength:1
*Dexterity:1
*Intelligence:1
*Endurance:1
*HitPoints(HP):{Endurance * 6}
*Armor(AR)
*Movement(MV):{Dexterity}

4. Click in the cell next to Strength. A cursor will appear, showing that you can type in that cell. Enter a number in that cell as the token's Strength value. I'm going to use 6.

5. Repeat step 4 for Dexterity, Intelligence, and Endurance, choosing whatever number you like (I'm going to use 3, 2, and 6, respectively). Remember that HitPoints and Movement will be automatically calculated!

6. Click OK. You have just manually updated the token's properties. If you double-click on the token, and look at those properties again, you'll see that the numbers you entered are remembered.

You'll also see that now, when you hover your mouse over the token, a little popup appears in the lower right corner of the map, showing the values for the properties you've entered. This popup is called the Statsheet, and is a quick way to look at the token's properties - it's basically a convenient quick-reference "character sheet."

Referencing a Token Property in a Macro

Now that we've configured some token properties, let's use them in a macro. For our first macro, we're going to roll 1d20, and instead of adding 7, we're going to add the token's Strength.

1. Open up your Attack Roll macro.

2. In the lower left corner, make sure the box Apply to Selected Tokens is checked (otherwise, the macro won't know which token's Strength to use!)

3. Edit your macro to look like this:

I make an attack roll!<br>
<b>Target</b>: [r:target]<br>
<b>Attack</b>: [1d20+Strength]<br>
<b>Damage</b>: [1d8+5]

You'll note I replaced the 7 with the word "Strength." Since Strength is not in quotes, MapTool will know that you mean it to be a variable, and it will look on the current token (that is, the token that is selected) for a property called Strength. If it doesn't find it (or if the property has never been set), it will prompt you for it (just like you were prompted for the value of target). If it does find it, MapTool will put the value of Strength into the macro when it runs.

4. Select your token, and run the macro by clicking the button. The output will look something like:

I make an attack roll!
Target: Nasty Orcses
Attack: 27
Damage: 6

The important thing to note is that if you hover over the attack roll result, the tooltip will now say something like « 1d20 + Strength = 17 + 10 » indicating that the value being plugged in to the dice roll is the property Strength.

Changing a Property with a Macro

Token properties can also be changed using a macro. Suppose we want to reduce the token's hit points after an enemy hit the character. You can manually edit the token and change the value in the HP property, or, you can create a macro that subtracts the amount of damage from the value of HP. Here's how:

1. Create a new macro on the Campaign panel.

2. In the Label field, enter "Damage".

3. In the Command field, enter:

Aarrgh! I'm hit! I have [HitPoints = HitPoints - damage] hit points left.

4. Check the box Apply to Selected Tokens (in the lower left corner).

5. Click OK. When you run the macro, you will be prompted for a value to put in the variable damage. I put in the number 7. The output will look something like this:

Aarrgh! I'm hit! I have 23 hit points left

And, if you double click on the token, you will see that the property HP is now 23. What this macro did was:

  1. Prompt the user for a value for damage (in this example, I entered 7)
  2. Retrieve the value of HitPoints from the token (in this example, the value is 30, because it is equal to Endurance * 6)
  3. Subtract the value of damage from the value of HitPoints (30 - 7, resulting in 23)
  4. Set the value of HitPoints (originally 30) to the newly calculated total (23)
  5. Output the text and the new value of HitPoints to chat

String Concatenation

An essential ability to master when writing macros is the ability to assemble strings - that is, collections of alphanumeric characters that are then manipulated or sent to chat. Frequently, you'll want to construct a string from some text that is always the same ("hardcoded" text) and text that can change (text that is the value of a variable, in other words). The construction of a string is often called "concatenation," but it just means "building a long string out of multiple short pieces."

There are two ways to do this in a macro - outside of a macro command, and inside of a macro command.

Outside of a Command

The basic way a macro works is this:

  1. The parser reads through the whole macro, and separates the macro commands from the plain text
  2. The parser diverts those macro commands to the appropriate places to be processed (so, numbers are added up, dice are rolled, etc.)
  3. The processed commands are sent back to the parser, which substitutes the results of those commands in the place where each command was.
  4. The whole mess - plain text, and the results of the commands (now sitting in place of the actual commands) is sent to the chat window.

So, when you want to display the result of a command along with some text (for instance, you want to print the word "Attack:" and then next to it print the result of a 1d20 roll) in a macro, the easiest way is to just insert a command in the right place in your text, like so: 

Attack: [1d20]

The parser will read that whole thing, send off the command [1d20] to be processed, and when it gets that result back, plug it in in place of the command, and send it off to chat. The result will be something like "Attack: 17."

That's the most straightforward way to send text to chat - just put the variables you want displayed in the right place in the text, and they will be shown in the chat window.

Inside of a Macro Command

Sometimes, though, you need to use strings inside of the square brackets. In that case, putting them together is a little different. First of all, within square brackets, you need to use single or double quotes to surround something you want to be treated as a string. Otherwise, MapTool will think you want each word to be a variable! For example:

Correct String 

[string = "This is a string"]

Incorrect String 

[string = This is a string]

Remember - outside of square brackets, no need for quotes. Inside? QUOTES.

So what if we need to build up a string dynamically? That is, what if we need to make a string that is partly "hardcoded," and partly based on user input? You can't guess what the user is going to say, so you can't write that part ahead of time. What you can do is concatenate the user input into your hardcoded string. The way to do that is to use the plus sign (+), which - when it's used with strings - will piece them together into a long string.

Here's an example: suppose we want the user to enter the name of a skill, and we then want to put that skill name into an existing, hardcoded string, which will be stored in another variable. You would do that like this: 

[h:existingString = "The skill name you entered is "]
[h:concatString = existingString+skill+"."]
[r:concatString]

What happens here is this:

  • Line 1 sets the "hardcoded" portion of the output
  • Line 2 sets the concatenated string - concatString to equal the value of existingString plus the value of skill (which MapTool will prompt for). However, in this case, since MapTool knows that existingString is a string, it will not try to add them mathematically, but just append the value of skill after the value of existingString. To be grammatically correct, we concatenate another little string on the end, this time, the period. Remember - strings inside square brackets need to be in quotes (but variable names, of course, do not!)
  • Line 3 displays the final value of concatString, after skill has been appended to it. The output will look something like:

The skill name you entered is Archery.

That's a very simple example, but it illustrates the essence of constructing strings - you "add" them together with a plus sign.

Where do We Go From Here?

This guide barely brushes the surface of the full potential of the macro language in MapTool. However, using just the basic techniques shown here, you can create a lot of very handy, convenient macros to make playing your game easier and more fun. In future guides, I'll cover more advanced macro commands and techniques.

Languages:  English  • Deutsch  • français  • italiano  • 日本語  • 한국어

{{#customtitle:Introduction à l'écriture de Macro|Introduction à l'écriture de Macro}}

Retrieved from "https://rptools.hyperbooks.com/index.php?title=Introduction_to_Macro_Writing/fr&oldid=16509"