Difference between revisions of "Building Character Sheets/Auto-Calc"
From Roll20 Wiki
Andreas J. (Talk | contribs) (create page, moved content here from BCS and CSS wizardry-pages) |
Andreas J. (Talk | contribs) (copy info form css wizardry page) |
||
Line 4: | Line 4: | ||
=Auto-Calc= | =Auto-Calc= | ||
− | For example, <code><input type="number" name="attr_StrMod" value="(@{Strength}/2)" disabled="true" /></ | + | For example, this would create a <code>StrMod</code>-attribute, which shows half the Strength value. |
+ | <pre data-language="html"> | ||
+ | <input type="number" name="attr_StrMod" value="(@{Strength}/2)" disabled="true" /> | ||
+ | </pre> | ||
+ | |||
+ | These auto-calculating attributes can be used in Sheet Rolls, [[Macros]], and Abilities as normal. | ||
+ | * '''[[CSS_Wizardry#Autocalc_Fields|Autocalc Fields]]''' on the [[CSS Wizardry]] page. | ||
* Auto-calc attributes can only include attributes from the current Character. | * Auto-calc attributes can only include attributes from the current Character. | ||
* Auto-calc attributes can't include macros, abilities, or rolls...just basic math such as <code>(@{Intelligence}/2+@{Level})</code>. | * Auto-calc attributes can't include macros, abilities, or rolls...just basic math such as <code>(@{Intelligence}/2+@{Level})</code>. | ||
* Auto-calc attributes have access to the floor, round, and ceil functions, such as <code>(floor(@{Intelligence}/2))</code>. | * Auto-calc attributes have access to the floor, round, and ceil functions, such as <code>(floor(@{Intelligence}/2))</code>. | ||
+ | * Errors in the formula (for example, <code>@{a} + @{b} + @{c}</code>, when attribute <code>b</code> has no value) will result in no output. | ||
* If your auto-calculated field depends of another auto-calculated field(s), '''you have to add parenthesis around intermediate formula(s)'''. Otherwise miscalculations could appear. | * If your auto-calculated field depends of another auto-calculated field(s), '''you have to add parenthesis around intermediate formula(s)'''. Otherwise miscalculations could appear. | ||
+ | |||
+ | |||
+ | When using sheetworkers, the value of the autocalc field you get from the <code>getAttrs</code> function will be its formula, and you cannot set its value to something else. See [https://github.com/Lithl/lithl-snippets/tree/master/sheetworker-autocalc sheetworker-autocalc] for a utility to resolve autocalc fields to their calculated value in a sheet worker script. {{note|sheetworker-autocalc has not been tested with repeating fields.}} | ||
You can include an auto-calc formula in the default value for the field, and specify either <code>disabled="true"</code> or <code>readonly</code> attribute on the field. If you do so, the sheet will display the result of the formula instead of the formula itself. | You can include an auto-calc formula in the default value for the field, and specify either <code>disabled="true"</code> or <code>readonly</code> attribute on the field. If you do so, the sheet will display the result of the formula instead of the formula itself. | ||
− | + | ==Example== | |
<pre data-language="html"> | <pre data-language="html"> | ||
<!--normal attributes--> | <!--normal attributes--> | ||
Line 22: | Line 32: | ||
Total:<input type="number" name="attr_StrModLeveled" value="(@{StrMod})+(@{Level})" disabled="true" /> | Total:<input type="number" name="attr_StrModLeveled" value="(@{StrMod})+(@{Level})" disabled="true" /> | ||
</pre> | </pre> | ||
+ | |||
+ | The <code>StrModLeveled</code>-attribute essentially sums up half of the character's Strength, plus the character's Level. <code>StrModLeveled</code> calls for <code>StrMod</code>, another auto-calc attribute, rather than <code>Strength</code> directly, which results in a more simple calculation that is easier to read. | ||
== Problems with using Auto-Calc== | == Problems with using Auto-Calc== | ||
Line 27: | Line 39: | ||
* '''Auto-calculated attributes doesn't show up in a [[Token]]'s [[Token_Features#Radial_Menu_Bubbles_.281.29|bubble]] or bar'''. This can be fixed by replacing an auto-calc attribute with one that is updated with a sheetworker. | * '''Auto-calculated attributes doesn't show up in a [[Token]]'s [[Token_Features#Radial_Menu_Bubbles_.281.29|bubble]] or bar'''. This can be fixed by replacing an auto-calc attribute with one that is updated with a sheetworker. | ||
− | * '''Auto-calc attributes can't be edited | + | * '''Auto-calc attributes can't be edited by sheetworkers'''. This causes problems with sheets that contains both auto-calc & sheetworker-backed attributes. The reason is the use of <code>disbled="true"</code> in auto-calc attributes. |
+ | * '''When using sheetworkers, the value of the autocalc field you get is the formula itself, not the auto-calculated value.''' | ||
* '''Auto-calculating values will increase the load of a sheet''' when its opened, and as a result should be used sparingly or not at all. Back when there existed larger sheets with tons of auto-calc sections, those sheets where considerably slower to use. | * '''Auto-calculating values will increase the load of a sheet''' when its opened, and as a result should be used sparingly or not at all. Back when there existed larger sheets with tons of auto-calc sections, those sheets where considerably slower to use. | ||
* '''Calculations do not show up in the [[#Preview_Panel|Preview]]''', they only show on a character sheet in-game. | * '''Calculations do not show up in the [[#Preview_Panel|Preview]]''', they only show on a character sheet in-game. | ||
Line 280: | Line 293: | ||
** [[Building Character Sheets]] | ** [[Building Character Sheets]] | ||
** [[Sheetworkers]] - the better, but more complex, alternative to using Auto-Calc values | ** [[Sheetworkers]] - the better, but more complex, alternative to using Auto-Calc values | ||
− | ** [[Tokens]] - auto-calc attributes conflict with showing up on token bubbles & stat-bars | + | ** [[Tokens]] - auto-calc attributes conflict with showing up on token bubbles & stat-bars |
+ | ** [[CSS_Wizardry#Autocalc_Fields]] | ||
<br> | <br> | ||
[[Category:Character Sheet Creation]] | [[Category:Character Sheet Creation]] |
Revision as of 13:28, 11 January 2021
Auto-Calculated Formula (Auto-Calc for short), is an older method for doing math on Roll20 Character Sheets, from before Sheetworkers where created.
It's a more simple method, but have several drawbacks, so most sheet authors recommend against using auto-calc in anything but the most simple sheets.
Contents |
Auto-Calc
For example, this would create a StrMod
-attribute, which shows half the Strength value.
<input type="number" name="attr_StrMod" value="(@{Strength}/2)" disabled="true" />
These auto-calculating attributes can be used in Sheet Rolls, Macros, and Abilities as normal.
- Autocalc Fields on the CSS Wizardry page.
- Auto-calc attributes can only include attributes from the current Character.
- Auto-calc attributes can't include macros, abilities, or rolls...just basic math such as
(@{Intelligence}/2+@{Level})
. - Auto-calc attributes have access to the floor, round, and ceil functions, such as
(floor(@{Intelligence}/2))
. - Errors in the formula (for example,
@{a} + @{b} + @{c}
, when attributeb
has no value) will result in no output. - If your auto-calculated field depends of another auto-calculated field(s), you have to add parenthesis around intermediate formula(s). Otherwise miscalculations could appear.
When using sheetworkers, the value of the autocalc field you get from the getAttrs
function will be its formula, and you cannot set its value to something else. See sheetworker-autocalc for a utility to resolve autocalc fields to their calculated value in a sheet worker script. Note: sheetworker-autocalc has not been tested with repeating fields.
You can include an auto-calc formula in the default value for the field, and specify either disabled="true"
or readonly
attribute on the field. If you do so, the sheet will display the result of the formula instead of the formula itself.
Example
<!--normal attributes--> STR:<input type="number" name="attr_Strength" value="0" /> Level:<input type="number" name="attr_Level" value="0" /> <!--auto-calculated attributes--> STR Mod:<input type="number" name="attr_StrMod" value="(@{Strength}/2)" disabled="true" /> Total:<input type="number" name="attr_StrModLeveled" value="(@{StrMod})+(@{Level})" disabled="true" />
The StrModLeveled
-attribute essentially sums up half of the character's Strength, plus the character's Level. StrModLeveled
calls for StrMod
, another auto-calc attribute, rather than Strength
directly, which results in a more simple calculation that is easier to read.
Problems with using Auto-Calc
There are a number of drawbacks in using Auto-Calc values, and most Sheet Authors recommend using sheet worker scripts instead. The following is an incomplete list of problems that using Auto-Calc causes.
- Auto-calculated attributes doesn't show up in a Token's bubble or bar. This can be fixed by replacing an auto-calc attribute with one that is updated with a sheetworker.
- Auto-calc attributes can't be edited by sheetworkers. This causes problems with sheets that contains both auto-calc & sheetworker-backed attributes. The reason is the use of
disbled="true"
in auto-calc attributes. - When using sheetworkers, the value of the autocalc field you get is the formula itself, not the auto-calculated value.
- Auto-calculating values will increase the load of a sheet when its opened, and as a result should be used sparingly or not at all. Back when there existed larger sheets with tons of auto-calc sections, those sheets where considerably slower to use.
- Calculations do not show up in the Preview, they only show on a character sheet in-game.
Replicating the JavaScript Math Library
Note: With the advent of Sheet Worker Scripts, the value of these tricks mainly used by auto-calc formulas is diminished, as you can use the Math library directly with a sheet worker. However, they are kept here for legacy purposes, and because they still work. It is possible to replicate most of the functionality of JavaScript's Math library with autocalc fields.Functions with an asterisk (*) produce approximate results; you can increase their accuracy by adding iterations to the computation.
Some functions below may reference other functions below.
Constants
The following are constants in JavaScript, so there's no reason to not have them as constants if you happen to need them.
E
E is Euler's constant, the base for the natural logarithm. The exact value is Sum[1 / n!, {n, 0, Infinity}]
. Math.log(Math.E)
is 1.
<input type="hidden" name="attr_cE" value="2.718281828459045">
LN2
LN2 is the value of Math.log(2)
.
<input type="hidden" name="attr_cLN2" value="0.6931471805599453">
LN10
LN10 is the value of Math.log(10)
.
<input type="hidden" name="attr_cLN10" value="2.302585092994046">
LOG2E
LOG2E is the base-2 logarithm of E. In other words, the value of Math.log2(Math.E)
, or 1 / Math.log(2)
.
<input type="hidden" name="attr_cLOG2E" value="1.4426950408889634">
LOG10E
LOG10E is the base-10 logarithm of E. In other words, the value of Math.log10(Math.E)
, or 1 / Math.log(10)
.
<input type="hidden" name="attr_cLOG10E" value="0.4342944819032518">
PI
PI is the radio between the circumference and diameter of a circle.
<input type="hidden" name="attr_cPI" value="3.141592653589793">
SQRT1_2
SQRT1_2 is the square root of 1/2 (0.5).
<input type="hidden" name="attr_cSQRT1_2" value="0.7071067811865476">
SQRT2
SQRT2 is the square root of 2.
<input type="hidden" name="attr_cSQRT2" value="1.4142135623730951">
Trivially Represented
The following functions you can use in autocalc fields easily, either because they're simple or because they're directly available.
abs(x)
If x < 0
, the result is -1 * x
. Otherwise, the result is x
.
<input type="hidden" name="attr_abs" value="abs(@{x})" disabled>
cbrt(x)
Cube root: cbrt(x)^3 = x
.
<input type="hidden" name="attr_cbrt" value="(@{x}**(1/3))" disabled>
ceil(x)
Rounds towards positive infinity.
<input type="hidden" name="attr_ceil" value="ceil(@{x})" disabled>
exp(x)
E^x.
<input type="hidden" name="attr_exp" value="(@{cE}**@{x})" disabled>
floor(x)
Rounds towards negative infinity.
<input type="hidden" name="attr_floor" value="floor(@{x})" disabled>
hypot(x, y, z, ...)
Hypotenuse: sqrt(x^2 + y^2 + z^2 + ...)
.
<!-- include as many values as you need --> <input type="hidden" name="attr_hypot" value="((@{x}**2 + @{y}**2 + @{z}**2)**0.5)" disabled>
max(x, y, z, ...)
If x > y
, the result is x
, while if x < y
, the result is y
.
<input type="hidden" name="attr_max_xy" value="(((@{x} + @{y}) + abs(@{x} - @{y})) / 2)" disabled> <input type="hidden" name="attr_max_xyz" value="(((@{max_xy} + @{z}) + abs(@{max_xy} - @{z})) / 2)" disabled> <input type="hidden" name="attr_max_xyzw" value="(((@{max_xyz} + @{w}) + abs(@{max_xyz} - @{w})) / 2)" disabled>
min(x, y, z, ...)
If x > y
, the result is y
, while if x < y
, the result is x
.
<input type="hidden" name="attr_min_xy" value="(((@{x} + @{y}) - abs(@{x} - @{y})) / 2)" disabled> <input type="hidden" name="attr_min_xyz" value="(((@{min_xy} + @{z}) - abs(@{min_xy} - @{z})) / 2)" disabled> <input type="hidden" name="attr_min_xyzw" value="(((@{min_xyz} + @{w}) - abs(@{min_xyz} - @{w})) / 2)" disabled>
pow(x, y)
x^y
, this is x
multiplied by itself y
times; fractional values for y
are permissible.
<input type="number" name="attr_pow" value="(@{x}**@{y})" disabled>
round(x)
Round towards the nearest integer. If the fractional part is 0.5, it will round towards positive infinity.
<input type="hidden" name="attr_round" value="round(@{x})" disabled>
sign(x)
If x < 0
, the result is -1, while if x > 0
, the result is 1 and if x = 0
, the result is 0. Unfortunately, because of the nature of the calculation, we cannot correctly calculate the final possibility. This works for all values of x
other than 0, however.
<input type="hidden" name="attr_sign" value="(@{x} / abs(@{x}))" disabled>
sqrt(x)
Square root: sqrt(x)^2 = x
.
<input type="hidden" name="attr_sqrt" value="(@{x}**0.5)" disabled>
trunc(x)
Round towards 0.
<input type="hidden" name="attr_trunc" value="(@{sign} * floor(abs(@{x})))" disabled>
Trigonometric Functions
Trigonometric functions deal with angles and the relations between the sides of a triangle.
*acos(x)
Inverse function of cos
; acos(cos(x)) = x
, and if abs(x) <= 1
, cos(acos(x)) = x
.
<input type="hidden" name="attr_acos" value="(@{cPI} / 2 - @{asin})" disabled>
*acosh(x)
Hyperbolic arccosine.
Note: See log(x) for the definition of @{log_2x}
<input type="hidden" name="attr_acosh" value="(@{log_2x} - (1 / (4 * @{x}**2) + 3 / (32 * @{x}**4) + 15 / (288 * @{x}**6) + 105 / (384 * @{x}**8)))" disabled>
*asin(x)
Inverse function of sin
; asin(sin(x))
= x, and if abs(x) <= 1
, sin(asin(x)) = x
.
<input type="hidden" name="attr_asin" value="(@{x} + @{x}**3 / 6 + (3 * @{x}**5) / 40 + (15 * @{x}**7) / 336)" disabled>
*asinh(x)
Hyperbolic arcsine.
<input type="hidden" name="attr_asinh" value="(@{x} - @{x}**3 / 6 + 3 * @{x}**5 / 40 - 15 * @{x}**7 / 336)" disabled>
*atan(x)
Inverse function of tan
; atan(tan(x)) = x = tan(atan(x))
.
<input type="hidden" name="attr_atan" value="(@{x} - @{x}**3 / 3 + @{x}**5 / 5 - @{x}**7 / 7)" disabled>
*atanh(x)
Hyperbolic arctangent.
<input type="hidden" name="attr_atan" value="(@{x} + @{x}**3 / 3 + @{x}**5 / 5 + @{x}**7 / 7)" disabled>
*atan2(y, x)
The same as atan(y / x)
, although the actual Math library function gracefully handles x = 0
.
<input type="hidden" name="attr_atan2" value="((@{y} / @{x}) - (@{y} / @{x})**3 / 3 + (@{y} / @{x})**5 / 5 - (@{y} / @{x})**7 / 7)" disabled>
*cos(x)
The ratio of the adjacent side of a triganle from the given angle (on a right triangle) to the hypotenuse.
<input type="hidden" name="attr_cos" value="(1 - @{x}**2 / 2 + @{x}**4 / 24 - @{x}**6 / 720 + @{x}**8 / 40320)" disabled>
*cosh(x)
Hyperbolic cosine.
<input type="hidden" name="attr_cosh" value="(1 + @{x}**2 / 2 + @{x}**4 / 24 + @{x}**6 / 720 + @{x}**8 / 40320)" disabled>
*sin(x)
The ratio of the opposite side of a triangle from the given angle (on a right triangle) to the hypotenuse.
<input type="hidden" name="attr_sin" value="(@{x} - @{x}**3 / 6 + @{x}**5 / 120 - @{x}**7 / 5040)" disabled>
*sinh(x)
Hyperbolic sine.
<input type="hidden" name="attr_sinh" value="(@{x} + @{x}**3 / 6 + @{x}**5 / 120 + @{x}**7 / 5040)" disabled>
*tan(x)
The ratio of the opposite side of a triangle from the given angle (on a right triangle) to the adjacent side.
<input type="hidden" name="attr_tan" value="(@{sin} / @{cos})" disabled>
*tanh(x)
Hyperbolic tangent.
<input type="hidden" name="attr_tanh" value="(@{sinh} / @{cosh})" disabled>
Other Transcendental Functions
Transcendental functions cannot be expressed with a finite number of algebraic operations. The trigonometric functions are transcendental as well.
*log(x)
Natural logarithm (log base E) of x.
<input type="hidden" name="attr_log" value="(@{x} - @{x}**2 / 2 + @{x}**3 / 3 - @{x}**4 / 4 + @{x}**5 / 5 - @{x}**6 / 6 + @{x}**7 / 7)" disabled> <!-- used for acosh, above --> <input type="hidden" name="attr_log_2x" value="(@{cLN2} + @{log})" disabled>
*log1p(x)
log(1 + x)
<input type="hidden" name="attr_log1p" value="((1 + @{x}) - (1 + @{x})**2 / 2 + (1 + @{x})**3 / 3 - (1 + @{x})**4 / 4 + (1 + @{x})**5 / 5 - (1 + @{x})**6 / 6 + (1 + @{x})**7 / 7)" disabled>
*log10(x)
Log base 10 of x.
<input type="hidden" name="attr_log10" value="(@{log} / @{cLN10})" disabled>
*log2(x)
Log base 2 of x.
<input type="hidden" name="attr_log2" value="(@{log} / @{cLN2})" disabled>
Other Functions
The following functions don't really have a mathematical categorization.
*clz32(x)
The number of leading zero bits in a 32-bit number. For example, the number 64 is represented in binary as 00000000000000000000000001000000
, so clz32(64) = 25
.
<input type="hidden" name="attr_clz32" value="(32 - ceil(@{log1p} / @{cLN2}))" disabled>
Impossible to Implement
Some functions cannot be implemented with autocalc fields.
fround(x)
Rounds a number to the nearest 32-bit representable floating point number.
imul(x, y)
Perform 32-bit multiplication. This is functionally equivalent to trunc(x * y)
, except when large numbers get involved.
random()
Generate a random number in the range [0, 1). While this can't be done with autocalc fields, you can roll dice!
Related pages
- Character Sheets
- Building Character Sheets
- Sheetworkers - the better, but more complex, alternative to using Auto-Calc values
- Tokens - auto-calc attributes conflict with showing up on token bubbles & stat-bars
- CSS_Wizardry#Autocalc_Fields