bar.name: Difference between revisions

From RPTools Wiki
Jump to navigation Jump to search
No edit summary
 
(20 intermediate revisions by 5 users not shown)
Line 1: Line 1:
The ''bar.[bar_name]'' variable permits the getting and setting of the [[Token:bar|token bar]] value (and the corresponding image displayed on the token) programmatically. Token bars are one, two, or multi-image graphical elements displayed on a token that are used (typically) to visually indicate the status of consumable or expendable items or character traits (such as Hit Points, Ammunition, Health, or the like).  
[[Image:Bar-example.jpg|frame|right|A Two Tone "HP" bar on a token]]
The <code>bar.''name''</code> variable permits the getting and setting of the [[Bars|token bar]] value (and the corresponding image displayed on the token) programmatically. Token bars are one, two, or multi-image graphical elements displayed on a token that are used (typically) to visually indicate the status of consumable or expendable items or character traits (such as Hit Points, Ammunition, Health, or the like).  


Bars, like [[Token:state|token states]], are configured via the Campaign Properties dialog and are specific to the campaign in which they exist. In the screenshot shown below, the green-on-black line across the top of the token is a token bar.
Bars, like [[Token:state|token states]], are configured via the Campaign Properties dialog and are specific to the campaign in which they exist. In the screenshot shown below, the green-on-black line across the top of the token is a token bar.


[[Image:Bar-example.jpg]]
==Usage==
 
<syntaxhighlight lang="mtmacro" line>
[bar.<i>name</i> = value]
</syntaxhighlight>


==Usage==
Sets the value of the token bar named ''name'' to the desired value. The bar's ''name'' is set when the bar is created, and may be any name, provided it contains no spaces or special characters except the underscore. ''Value'' must be a number between 0 and 1. When providing a decimal value, include the leading 0 (e.g. enter <code>0.5</code> rather than <code>.5</code>) or your macro will produce an error.


<source lang="mtmacro" line>
Assigning a value to a bar.<i>name</i> will make the bar visible. Checking or using the value of bar.<i>name</i> when the bar is not already visible returns {{code|null}}.
[bar.[bar_name] = value]
</source>


Sets the value of the token bar named ''bar_name'' to the desired value. ''bar_name'' is set when the bar is created, and may be any name, provided it contains no spaces or special characters except the underscore. ''Value'' must be a number between 0 and 1.
While this special variable can be convenient, Using [[:Category:Bar_Function|Token Bar Functions]] instead of token.<i>name</i> can give you more flexibility in your macros.


==Examples==
==Examples==


<source lang="mtmacro" line>
<syntaxhighlight lang="mtmacro" line>
[h: HP = HP - DamageTaken]
[h: HP = HP - DamageTaken]
[h: bar.Health = HP / MaxHP]
[h: bar.Health = HP / MaxHP]
</source>
</syntaxhighlight>


Sets the value of ''bar.Health'' to the result of ''HP / MaxHP''.
Sets the value of ''bar.Health'' to the result of ''HP / MaxHP''.
Line 28: Line 31:
==Related Pages==
==Related Pages==


* [[HP and Health Bars]]
* [[Macros:Variables:list_of_special_variables|List of Special Variables]]
* [[Macros:Variables:list_of_special_variables|List of Special Variables]]
* [[Macros:Functions:list_of_functions_by_area#Token_Bars|Token Bar Functions]]
* [[:Category:Bar_Function|Token Bar Functions]]
 
[[Category:Special Variable]]
{{DISPLAYTITLE:bar.<i>name</i> (Special Variable)}}
[[Category:Macro Function]]

Latest revision as of 19:59, 4 July 2023

A Two Tone "HP" bar on a token

The bar.name variable permits the getting and setting of the token bar value (and the corresponding image displayed on the token) programmatically. Token bars are one, two, or multi-image graphical elements displayed on a token that are used (typically) to visually indicate the status of consumable or expendable items or character traits (such as Hit Points, Ammunition, Health, or the like).

Bars, like token states, are configured via the Campaign Properties dialog and are specific to the campaign in which they exist. In the screenshot shown below, the green-on-black line across the top of the token is a token bar.

Usage

[bar.<i>name</i> = value]

Sets the value of the token bar named name to the desired value. The bar's name is set when the bar is created, and may be any name, provided it contains no spaces or special characters except the underscore. Value must be a number between 0 and 1. When providing a decimal value, include the leading 0 (e.g. enter 0.5 rather than .5) or your macro will produce an error.

Assigning a value to a bar.name will make the bar visible. Checking or using the value of bar.name when the bar is not already visible returns null.

While this special variable can be convenient, Using Token Bar Functions instead of token.name can give you more flexibility in your macros.

Examples

[h: HP = HP - DamageTaken]
[h: bar.Health = HP / MaxHP]

Sets the value of bar.Health to the result of HP / MaxHP.

Notes

Two functions, setBar() and getBar() also exist to get and set the value of the token bar.

Related Pages