Skip to content

Computations

Jump to bottom Edit New page
96LawDawg edited this page Sep 2, 2024 · 24 revisions

Computations overview

These functions perform various computations with the given operands. The operation is one of the functions listed below. There up to three operands, each of which may in general be a number, a string, or an array. Any missing required operand defaults to 1. There are three possible ways to write the operations, depending on the computation being performed.

  1. Operations accepting a single parameter should be written:

operation operand1

  1. Operations accepting two or three parameters may be written in either of these formats:

operand1 operation operand2 [operand3]

operation operand1 operand2 [operand3].

  1. Most mathematical functions and the logical comparison functions can have unlimited operations and be nested using parenthesis:

operand1 operation operand2 operation operand3 operation operand4

Mathematical Functions and Constants

Click to see tutorial

Basic math

These operations work with numbers only, except for addition. Otherwise, if the operands contain a string, the result is 0:

  • + (Addition): Returns operand1 + operand2. If the operands are strings, they will be concatenated
  • - (Subtraction): Returns operand1 - operand2.
  • * (Multiplication): Returns operand1 * operand2.
  • ** (Exponentiation): Returns operand1^operand2.
  • / (Division): Returns operand1/operand2.
  • % (Remainder): Returns the integer remainder of dividing operand1 by operand2

Each of these operations except for %can be combined using any number of operations and can be nested using parenthesis. For example, "var total = ((${a} + ${b} + ${c}) * (${d} * ${e})) / (9 + 1) ** 5" is a valid syntax.

Advanced mathematical functions These operations work with numbers only.
  • abs: Returns absolute value of operand1
  • acos: Returns arccosine (in degrees) of operand1
  • asin: Returns arcsine (in degrees) of operand1
  • atan: Returns arctangent (in degrees) of operand1
  • atan2: Returns arctangent (in degrees) between the positive x-axis and the point (x,y) = (operand2, operand1)
  • cbrt: Returns cube root of operand1
  • ceil: Returns the smallest integer greater than or equal to operand1
  • cos: Returns the cosine (in degrees) of operand1
  • exp: Returns E**operand1, where E is Euler's constant (approximately 2.718, the base of the natural logarithm)
  • floor: Returns the largest integer less than or equal to operand1
  • hypot: Returns the square root of the sum of the squares of operand1 and operand2
  • log: Returns the natural logarithm of operand1
  • log10: Returns the base-10 logarithm of operand1
  • log2: Returns the base-2 logarithm of operand1
  • max: Returns the larger of operand1 and operand2
  • min: Returns the smaller of operand1 and operand2
  • pow: Returns base operand1 to the exponent power operand2 (operand1 ** operand2)
  • round: Returns the value of operand1 rounded to the nearest integer
  • sign: Returns the sign of operand1 (possible values are 1, 0, -1)
  • sin: Returns the sine (in degrees) of operand1
  • sqrt: Returns the positive square root of operand1
  • tan: Returns the tangent of operand1
  • trunc: Returns the integer portion of operand1 after removing fractions
Randomization

  • randInt: Returns a random integer in range between (and including) minimum of operand1 and maximum of operand2.

  • randRange: Returns random integer in range between (and including) minimum of operand1 and maximum of operand2, but the maximum endpoint is excluded. Also, optionally, use operand3 to limit the return to a step increment (such as 2, 5, etc.)

  • random: Returns a random number between 0 and 1. This does not use operands.

    For additional information, see

    https://www.w3schools.com/python/ref_random_randint.asp
    https://www.w3schools.com/python/ref_random_randrange.asp

Constants

These operations return a numeric constant and do not use any operands:

  • E: Euler's constant (~2.71828)
  • LN10: Natural logarithm of 10 (~2.30259)
  • LN2: Natural logarithm of 2 (~0.69315)
  • LOG10E: Base-10 logarithm of E (~0.43429)
  • LOG2E: Base-2 logarithm of E (~1.44270)
  • PI: Returns the ratio of a circle's circumference to its diameter (~3.14159)
  • SQRT1_2: Returns the square root of 1/2, or one half the square root of 2 (~0.70711)
  • SQRT2: Returns the square root of 2 (~1.41421)
Formatting operations
For additional information

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math

or

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Expressions_and_Operators

Comparison Operations

Click to see tutorial

Alphanumeric Comparison

These operations work with numbers and strings. In the case of strings, the ordering used is lexical ordering with Unicode values:

  • < (Less than): Returns true if operand1 is less than operand2
  • <= (Less than or equal): Returns true if operand1 is less than or equal to operand2
  • == (Equal): Returns true if operand1 and operand2 are equal
  • === (Identical): Returns true if operand1 and operand2 are identical in value and type
  • != (Not equal): Returns true if operand1 and operand2 are not equal
  • >= (Greater than or equal): Returns true if operand1 is greater than or equal to operand2
  • > (Greater than): Returns true if operand1 is greater than operand2
Logical Comparison

These operations work with numbers and strings:

  • && (Logical AND): Returns true if both operand1 and operand2 are true
  • || (Logical OR): Returns true if either operand1 or operand2 is true
  • ! (Logical NOT): Inverts the truthiness of operand1. Returns true if operand1 can not be converted to true

Each of these operations can be combined using any number of operations and can be nested using parenthesis. For example, "var check = ${a} && !${b} || ${c} && ${d}" is a valid syntax.

For additional information

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Expressions_and_Operators

String Operations

Click to see tutorial

Note that the first character in a string has index 0.

Creating strings
  • concat: Combines the text of operand1 and operand2 and returns a new string
  • padEnd: Returns a string consisting of operand1 padded with operand2 spaces at the end
  • padStart: Returns a string consisting of operand1 padded with operand2 spaces at the start
  • repeat: Takes operand1 and repeats it operand2 number of times and returns a new string
  • split: Takes operand2 and uses it to split operand1 into an array of strings split at each point where operand2 occurs
  • slice: Returns a new string consisting of the characters in operand1 starting at the index position of operand2 and through the index position in operand3
  • substr: Returns a new string consisting of the characters in operand1 starting at the index position of operand2 and continuing for the number of characters in operand3
Querying strings and selecting parts of strings

  • charAt: Returns the character in operand1 at index position operand2

  • charCodeAt: Returns a number (UTF-16 code unit value) in operand1 at index position operand2

  • codePointAt: Returns a nonnegative integer that is the code point value of the UTL-16 encoded code point in operand1 at position operand2

  • endsWith: Returns true if operand1 ends with the string in operand2

  • in: Returns true if the string in operand1 is included in the string in operand2

  • includes: Returns true if operand1 contains the string in operand2

  • indexOf: Searches operand1 and returns the first index position of the string in operand2; returns -1 if not found

  • lastIndexOf: Searches operand1 and returns the last index position of the string in operand2; returns -1 if not found

  • length: Returns an integer reflecting the length of the string operand1; empty strings have length 0. Note: if the string contains uncommon UTF-16 characters, the length may not match the actual number of characters in the string as some uncommon ones use up two length units.

  • localeCompare: Compares operand1 with operand2 and returns a negative number if operand2 comes before operand1 alphabetically, returns a positive number if operand2 is before operand1, and 0 if they are the same

  • match: Searches operand1 for the string in operand2 and returns the result as an array consisting of operand2, or null if no match was found (use flags in operand3, such as 'g' for a global search that returns all occurrences)

  • search: Searches operand1 for the first occurrence of the string in operand2 and returns the index position, or -1 if no match was found

  • startsWith: Returns true if operand1 starts with the string in operand2

Modifying strings
  • replace: Searches operand1 for the first occurrence of the string in operand2 and replaces it with the string in operand3
  • replaceAll: Searches operand1 for all occurrences of the string in operand2 and replaces them with the string in operand3
  • shuffle: Shuffles the elements in operand1 (a string or array) and returns the resulting string or array
  • toLocaleLowerCase: Converts operand1 to lower case with respect to current locale settings
  • toLocaleUpperCase: Converts operand1 to uper case with respect to current locale settings
  • toLowerCase: Converts operand1 to lower case
  • toUpperCase: Converts operand1 to upper case
  • trim: Removes whitespace from the beginning and end of operand1
  • trimEnd: Removes whitespace from the end of operand1
  • trimStart: Removes whitespace from the beginning of operand1

Note that all array functions also work on strings.

For additional information

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String

Array Operations

Click to see tutorial

Creating arrays
  • from: Builds an array from the list of strings in operand1
  • reverse: Returns a new array after reversing the order of the elements of the array in operand1 (first becomes last, last becomes first)
  • sort: Returns a new array after sorting the elements of the array in operand1 lexically
  • concatArray: Takes the array (or string) in operand1, appends the array (or string) in operand2 and returns a new array. If both operands are simply strings, then the result is a concatenated string and not an array
  • slice: Returns a new array consisting of the elements of the array in operand1 from index position operand2 to index position operand3
Querying arrays and selecting parts of arrays
  • isArray: Returns true if operand1 is an array; even if the array is empty, this will still return as true
  • length: Returns the number of elements in an array
  • getIndex: Returns the element in the array in operand1 at index position operand2. If the value at the element is null, returns the value 0. If the value at the element does not exists, then it returns nothing.
  • in: Returns true if the string in operand1 is included in the array in operand2
  • includes: Returns true if the array in operand1 contains the string in operand2
  • indexOf: Returns the first index number of the array in operand1 that contains the string in operand2, or -1 if no match
  • join: Returns a string by joining all elements of the array in operand1 with the connector (such as a comma) in operand2
  • lastIndexOf: Returns the last index number of the array in operand1 that contains the string in operand2, or -1 if no match
  • sum: Adds the values of a numerical array
Modifying arrays

  • pop: Removes the last element of the array in operand1 and returns that element

  • shift: Removes the first element of the array in operand1 and returns that element

  • shuffle: Shuffles the elements in operand1 (a string or array) and returns the resulting string or array

Operands Plus Variable

These operations work only with a pre-existing variable that contains an array. Unlike most other operations that use operand2 to influence operand1, for these operations, you use the operands to influence the "variable" parameter in COMPUTE. There will be an error if variable does not already contain an array. The functions push, sort, numericSort, reverse, and unshift use only operand1 whereas insert, remove and setIndex use both operand1 and operand2.

  • insert: Inserts operand1 at index operand2 of array in variable
  • push: Adds the string in operand1 as the last element in the array in variable
  • remove: Removes elements starting at index operand1 of array in variable, limited to operand2 elements
  • sort: Sorts the array alphabetically; strings with mixed letters and numbers should use numericStringSort for better sorting
  • numericSort: Sorts the array numerically, treating numbers as numbers
  • numericStringSort: Sorts the array alphabetically, treating numbers as strings
  • reverse: Reverses the order of the elements in the array. To reverse numbers, first perform a numericSort and then a reverse
  • unshift: Adds the string in operand1 as the first element in the array in variable
  • setIndex: Adds the string in operand2 as the nth (operand1) element in the array in variable. If the number in operand1 is larger than the existing length, then null elements will be added between the end of the initial array and the new array created by inserting operand2.

Here is an example of the use of these functions:

  • "var wordArray = insert ${str} 2" inserts the value in str at index 2 of the array in wordArray

  • "var wordArray = push ${str}" appends the value in str as the last element of the array in wordArray

  • "var wordArray = remove 5 2" removes 2 elements starting at index 5 of the array in wordArray

  • "var wordArray = unshift ${str}" prepends the value in str as the first element of the array in wordArray

  • "var wordArray = setIndex ${pos1} ${str}" or "var a.$pos1 = ${str}" inserts the value in str as the pos1th element of the array in wordArray, moving all subsequent elements down

Deep versus shallow copies

VTT uses a deep copy when retrieving and setting properties, but only a shallow copy when sharing between variables. This can have unexpected consequences. For example:

" clickRoutine": [
    "var originalArray = ${PROPERTY someOtherArray}",
    "var newArray = ${originalArray}",
    "var newArray = remove 0 1",
    "var newArray = push 'Q'"
  ],

In the code section above, the var dynamic expression above appear to only act on "newArray." However, because of the shallow copy, "originalArray" is also being modified even though no operations are performed directly on "originalArray." Any array operation that changes the array, including slice, pop, shift, etc., will have this impact. There is a work around using FOREACH to rebuild "newArray" as follows:

"clickRoutine": [
    "var originalArray = ${PROPERTY someOtherArray}",
    "var newArray = []",
    {
      "func": "FOREACH",
      "in": "${originalArray}",
      "loopRoutine": [
        "var newArray = push ${value}"
      ]
    },
    "var newArray = remove 0 1",
    "var newArray = push 'Q'"
  ],
For additional information

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array

Color Operations

Click to see tutorial

The color operations in VTT work with the following common color formats: CSS words (for example, red or black), hex (#ffffff or #fff), rgb, rgba, hsl, and hsla.

Converting color formats
  • colorToRGB: Accepts most color formats in operand1 and returns a value in the format "rgb(0,99,255)"
  • colorToHex: Accepts most color formats in operand1 and returns a hex value in the format "#ffffff". Note: all of the color functions use this to try to convert non-hex color formats to hex. If the format or value is invalid, the output will be black (#000000). You can use this in your routines as an error check; if black is returned, it is likely an error unless black was the operand1 color.
Creating contrasting color

  • colorContrast: Accepts most color formats in operand1 and returns a hex color value in the same hue but different luminance of the provided color to provide contrast. Operand2 (optional) can be a number between -1 and 1 to adjust the intensity of the contrasting change. Defaults to 1. The higher the number, the greater the contrast. With the default, dark colors get lighter return values. Using negative values for operand2 will reverse the direction of the change so that dark colors get darker return values.

  • colorContrastRatio: Accepts most color formats in operand1 and operand2 to return a number between 1 and 21 that is the ratio of the relative luminance of the colors (as defined in WCAG 2.1).

  • colorLuminance: Accepts most color formats in operand1 and returns a value between 0 and 1 reflecting the luminance of the color

  • colorCreateHue: Creates a semi-random color as distinct in hue as possible from active player colors. Operand1 (optional) can be an array of colors in most color formats to use instead of player colors.

JSON Operations

Click to see tutorial

These are operations that can be used to retrieve (including from external URLs) and work with JSON as functions similar to those in the categories above. When fetching from a website, the server must have Cross-Origin Resource Sharing (CORS) enabled. When using another VTT room add "state" before the room name like: https://virtualtabletop.io/state/Tutorials

  • fetch: Downloads the URL specified in operand1 and returns its content as a string.
  • jsonParse: Converts the JSON in operand1 to an object format usable in VTT.
  • jsonStringify: Encodes the data in operand1 into a JSON string.
Add a custom footer

Quick Links

Home

1. Basics

2. Developer Documentation

3. Available Resources

4. Usage Guidelines and Copyrights

5. Other Technical Information

6. Changes

Clone this wiki locally