Revision as of 14:19, 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.

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 attribute b 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