Revision as of 17:37, 19 April 2021

APILogic

APILogic introduces logical structures (things like IF, ELSEIF, and ELSE) as well as real-time inline math operations, and variable muling to Roll20 command lines. It can test sets of conditions and, depending on the result, include or exclude parts of the command line that actually reaches the chat processor.

For example, given the statement:

!somescript {& if a = a} true stuff {& else} default stuff {& end}

…results in the following reaching the chat:

!somescript true stuff

• Discussion: APILogic thread^(Forum)
• File Location: APILogic.js (submitted to the one-click, but until then, find it in my personal repo)
  
• Script Dependency: libInline.js (also submitted to the one-click)
  

APILogic exploits a peculiarity of the way many of the scripts reach the chat interface (a peculiarity first discovered by – who else? – The Aaron) to give it the ability to intercept the chat message before it reaches other scripts, no matter if it is installed before or after them in the script library. It also uses a separate bit of script magic to let it retain ownership of the message even when otherwise asynchronous chat calls would be going.

Caveat: The method APILogic utilizes has been tested and shown to work with a large number of scripts. If you find that it doesn’t, you should be reminded that the most foolproof way to ensure proper timing of script execution is to load APILogic in your script library before the other script. But hopefully you’ll find that you don’t need to do that!)

Also, although it requires the API, it is not only for API messages. You can use these logic structures with basic chat messages, too. This document will show you how.

Credits: Created by timmaugh. Many thanks to The Aaron for lending his expertise on questions I had, and to the other members of the House of Mod for sounding out and working through ideas.

Triggering and Usage

You won’t invoke APILogic directly by using a particular handle and a line dedicated for the APILogic to detect. Instead, any API call (beginning with an exclamation point: ‘!’) that also includes any IF, DEFINE, MULE, EVAL, EVAL-, or MATH tag somewhere in the line will trigger APILogic to examine and parse the message before handing it off to other scripts.

As mentioned, you are not limited to using APILogic only for calls that are intended for other scripts. There are mechanisms built into the logic that let you output a simple chat message (no API) once you’ve processed all of the logic structures. That means you can use the logic structures in a simple message that was never intended to be picked up by a script, and also in a message that, depending on the conditions provided, might need to be picked up by another script, or alternatively flattened to a simple message to hit the chat log.

The Basic Structures: IF, ELSEIF, ELSE, and END

An IF begins a logical test, providing conditions that are evaluated. It can be followed by any number of ELSEIF tags, followed by zero or 1 ELSE tag. Finally, an IF block must be terminated with an END tag. Each of these are identified by the {& type ... } formation. For instance:
{& if … }
{& elseif …}
{& else}
{& end}
A properly structured IF block might look like this:

{& if (conditions) } true text {& elseif (conditions) } alt text {& else } default text {& end}

Each IF and ELSEIF tag include conditions to be evaluated (discussed in a moment). If an IF’s conditions evaluate as true, the subsequent text is included in the command line. While nested IF blocks embedded within that included text are detected and evaluated, no further sibling tags to the initial IF tag are evaluated until the associated END tag. On the other hand, if an IF evaluates to false, evaluation moves to the next logical structure (ELSEIF, ELSE, or END). ELSEIFs are evaluated just as IFs are, with processing passing forward if we find a false set of conditions. If we ever reach an ELSE, that text is included.

Nesting IF Blocks

You can nest IF blocks in other portions of the line to prompt a new set of evaluation for the enclosed text. They can occur in another IF, in an ELSEIF, or in an ELSE. If the outer logic structure passes validation so that the contents are evaluated, the nested IF block will be evaluated. Each IF must have an END, therefore the first END to follow the last IF belongs to that IF. Similarly, all ELSEIF and ELSE tags that follow an IF (until an END is detected) belong to that IF.

{& if } ... {& elseif } ... {& if } ... {& elseif } ... {& end } ... {& else } ... {& end}

In the example, an IF-ELSEIF-END block exists in the first ELSEIF of the outer IF block. it will only be evaluated (and can only be included) if the outer IF block fails validation and the ELSEIF passes.

Conditions

Each IF and ELSEIF must have at least one condition to evaluate. A condition can be either binary (i.e., a = b), or unary (i.e., c), and each element of a condition (the a, b, or c) can be a sheet item, text, inline roll, or a previously evaluated condition set (more on this in a moment).

Logical Comparisons

The following logical comparisons are allowed for comparing two items (binary operations):

a = b	// equals
a != b	// does not equal
a > b	// is greater than
a >= b	// is greater than or equal
a < b	// is less than
a <= b	// is less than or equal
a ~ b	// includes
a !~ b	// does not include

Sheet Items

The specific ability to retrieve sheet items was removed from APILogic and rolled into the Fetch script (also part of the Meta Toolbox). Use a Fetch construction to retrieve the sheet item data before APILogic evaluates it as part of condition.

Text as Condition

If you need to include space in a bit of text to include as one side of a comparison operation, you should enclose the entire text string in either single quotes, double quotes, or tick marks. With three options available, you should have an option available even if the text you need to include might, itself have an instance of one of those characters. For instance, the following would not evaluate properly, because of the presence of the apostrophe in the word “don’t”:

@(Bob the Slayer.slogan) ~ 'don't go'

Instead, wrap it in another option for denoting the text:

@(Bob the Slayer.slogan) ~ "don't go"

This is good to remember if you intend to use Roll20 parsing to retrieve something. For instance, if you want to use the name of the character associated with the Selected token as a condition, you should wrap that in some form of quotes if there is a chance that name will include a space.

"@{selected|token_name}" ~ Slayer
    // will reach the API after Roll20 parsing as...
"Bob the Slayer" ~ Slayer

Chaining Conditions (AND/OR) and Grouping

Multiple conditions can be used for each IF or ELSEIF tag. Use && to denote and AND case, and use || to denote an OR case.

{& if a = b && c = d }

Conditions are evaluated left to right by default. Use parentheses to enclose groups to force those conditions to evaluate as a group before being compared to sibling conditions:

{& if a = b && ( c = d || e != f) }

Multiple levels of grouping can be used, provided each sibling element (whether group or condition) is connected with && or ||:

{& if ( a = b && ( c = d || e != f ) ) || ( d > b && g ) }

Naming and Reusing Groups

The reasoning behind why you would want to include a part of your command line might be needed at several times in your command line. In that case, you should name your condition group so that you can simply refer to that name later. Name a group by including a bracketed word (no space) after the opening parentheses, before any non-whitespace character:

{& if ([sanitycheck] @|Bob the Slayer|sanity > 10 ) }

The above would store the result of the condition (whether Bob the Slayer’s sanity was over 10) as sanitycheck, available to be used later in the command line, including in future, deferred processing (disucssed later).

{& if ([sanitycheck] @|Bob the Slayer|sanity > 10 ) } conditionally included text {& end} always included text {& if sanitycheck } conditionally included text {& end}

BE AWARE that conditions are ONLY evaluated for IF and ELSEIF tags which reach the parser. If your group is defined in a portion of the command line that is not evaluated because the IF or ELSEIF was never reached, the group will never be evaluated and the test will never be stored.

{& if a = !a } true case text {& if ([sanitycheck] @|Bob the Slayer|sanity > 10 ) } true case for nested if {& end } {& end } always included text {& if sanitycheck} ...{& end}

In that case, the first condition a = !a does not pass validation, so the subsequent text is never evaluated (including the IF tag where the sanitycheck is defined).

If you find yourself in this position, you can either investigate a definition (see Using DEFINE Tag, below), or using a root-level IF tag with a single space of dependent text (that is, providing little alteration to your command line, regardless of if it passes).

!somescript {& if ([sanitycheck] @|Bob the Slayer|sanity > 10 ) } {& end} ...

Because the END tag follows nearly immediately on the IF tag, no important text is included or excluded from the command line, no matter the result of the test. The IF tag is there simply to force the group to be evaluated and the result stored. This would be a better solution than using a definition if the group was particularly complex since the definition is a simple text replacement operation. Using a named group ensures that the group is only being retrieved and evaluated once (read more in Using DEFINE Tag).

Negation

Negation can be applied to any element of a condition or to any group by use of the ! character. This can be handy to test for the non-existence of a sheet item:

!@|Bob the Slayer|weaponsmith

…or to reverse the evaluation of a group:

!( @|Bob the Slayer|weaponsmith > 4 && @|Bob the Slayer|impromptu_poetry > 2 )

…or to get the opposite result from a named group:

{& if !sanitycheck }

Note that if you use negation at the same time you are naming a group, the group will evaluate and the result will be stored as with the name. Negation will then return the opposite of the stored value:

! ( [sanitycheck] a = a )

…will store true as the value of the sanitycheck group, but return false because of the negation. Referring to the sanitycheck group later will retrieve the initial true value.

Using DEFINE Tag

A DEFINE tag is a way to provide definitions for terms that you will then use in text replacements throughout your command line. A DEFINE tag can come anywhere in your command line, and is parsed out before any processing of logical constructs occurs. A DEFINE tag is structured like this:

{& define ([term1] definition1) ([term2] definition2) ... }

The term refers to what you will use, elsewhere in the command line, to represent the definition. Since the definition is terminated by a parentheses, you do NOT need to enclose it in some form of quotation marks UNLESS you need to include leading or trailing spaces.

Since DEFINE replacements are simple text replacement operations, these can be a way to save typing (providing a short term to represent a long definition that will need to be utilized a number of times in a command line). It also provides a way of minimizing work should a definition need to change – giving you only one place to change it instead of many. This means you could define a ([speaker] Bob the Slayer) term, and use speaker anywhere you would refer to the character; then, if you passed that macro language to a fellow player, they would only have to replace the name with their character in one place.

Difference Between Definition and Named Group

As mentioned in the section on using named groups, although the syntax for defining a term is very similar to naming a group, the two structures are different. If you placed the entirety of a group as a definition, you would be replicating that text anywhere you referenced the associated term, but each time that text was encountered, the group would be evaluated anew. Declaring the name for the group in an IF tag, where that name represents a set of conditions, ensures that those conditions are only evaluated once.

Advanced Usage and Tricks

Defining Inline Rolls

Knowing which inline roll marker (i.e., $0) refers to which inline roll can sometimes be confusing, especially for rolls containing rolls in a message that has other rolls containing rolls, or for branches of the logic that don’t exists anymore, or where you deferred an inline roll with escape characters in part of the command line that was never processed.

A rough description is that Roll20 processes (and numbers) the rolls from innermost-leftmost to outermost-rightmost. Like I said, that can be confusing, especially when you add in APILogic letting you nest roll markers. In that case, the second pass of roll indices will start where the first pass left off, from innermost-leftmost to outermost-rightmost.

You can shortcut having to parse all of that by using an inline roll in a DEFINE tag definition, at the proper level of escape for when the roll should process. That way, when the roll in this definition resolves:

{& define ([chaosdice] [[2d10!]] ) }

…the chaosdice term will be filled with the appropriate roll marker definition. In effect, APILogic sees:

{& define ([chaosdice] $[[0]] ) }

…and uses that definition anywhere it sees the chaosdice term else where in the command line.

Table Result Recursion

The normal process of replacing a roll with its value (for instance with the .value command or by nesting it in a deferred inline roll) will return the table entry for a rollable table. Obviously, you may need to verify through straight input into the chat that the roll you enter will return a table entry instead of a number. For instance, [[ 1t[Armor] ]] will return the item from the table, while [[ 2t[Armor] ]] will return the result of only the first roll against the table, and [[ 1t[Armor] + 2 ]] will return 2.

This, paired with the fact that APILogic searches for newly-formed inline roll formations during each pass of the parsing, means you can leverage this behavior to handle recursive rolls based on table entries. If the Armor table has entries of:

[[1d10]]
[[1d10+3]]
[[2d10r<2-3]]
[[2d10r<2]]

…and the following text is encountered in your command line:

[[ 1t[Armor] ]].value

Then whatever result is obtained from rolling against that table will insert another inline roll into the command line, which will be detected and rolled by the Roll20 quantum roller.

Be aware that the resulting roll will, itself be wrapped in an inline roll marker ($0), so if you need to obtain the value from it (and it is not nested in another deferred inline roll) you will need another .value. Obviously, if that value is another table entry, and the table entry points to another inline roll, the process will continue.

Conditional non-API Calls (Basic Chat Messages)

If you want to just want to leverage logical structures for your simple chat message, so you don’t want to end up with an API call at all, put a SIMPLE tag outside of any logical structure (in text that will always be included in the final, reconstructed command line). In that case, simply begin your message (or your first IF or DEFINE tag) after the !.

!{& if @|Bob the Slayer|slogan}@\{Bob the Slayer|slogan}{& end} For tomorrow we dine in hell.{& simple}

If Bob the Slayer has a slogan, this will include that and tack on the extra. Otherwise, it would just output the last portion as a simple chat message.

Obfuscating the API Handle

Since we are interrupting other scripts answering the API message and reconstructing the command line that they see, we can preempt the API handle that would trigger another script to pick up the message. We did this, above, when we had a SIMPLE tag embedded in an IF construct. If we are going to drop the resulting message to a simple chat statement, we probably wouldn’t want the API handle to some other script to be included, so we make its inclusion dependent on the result of some conditions.

!{& if @|Bob the Slayer|smooth_jazz}somescript arg1 arg2{&else} Sorry, speaker doesn't have the smooth_jazz attribute{&simple}{&end}

If smooth_jazz exists for Bob the Slayer, the above example will run the somescript script. If it does not exist, the api handle for that script is dropped, but the {& simple} tag is included, ensuring that a readable message is sent to the chat window.

Mules as Static Access Tables

Rollable tables on Roll20 do a lot to provide random results from weighted entries, which can be good for things like random encounters or the like, but which aren’t as helpful for times when you know the value from which you need to derive the result. For instance, if a given level of a character’s Stamina has a direct correlation to a mod applied to their activities, you don’t need a randomized result… you need the result directly tied to what the character’s Stamina is when you consult the table. Similarly, some systems have charts built for how rolls map an attack roll to damage. A Mule can fill this gap.

Construct your Mule as the entries of the table, with the various states of the referenced input as the variable names. For an Encumbrance Mod table that would return a modifier to rolls based on the weight of the items the character was carrying, that might look like:

0=0
1=0
2=-1
3=-1
4=-1
5=-2
...etc...

If the Mule were named “EncumbranceTable”, you can reference that using the character’s CarryWeight attribute like so:

... {& mule EncumbranceTable} ... get.@{selected|CarryWeight} ...

Using a Mule this way, you can also leverage a MATH tag, if the input number needs to be altered at all:

get\.{& math @{selected|CarryWeight} + 2*(20-@{selected|Stamina}) }

The above adds twice the value that the character’s Stamina is below 20 to the CarryWeight before determining which row to retrieve. Also note that since MATH tags are evaluated after get statements, the get had to be deferred for one cycle of the loop.

Change Log

Version 1.0.0 - Initial Release
Version 1.0.1 (link) - minor bug fix related to inline table resolution
Version 1.1.0 (link) - changed special tests for sheet items to be int and max instead of i and m; changed DEFINE tags to evaluate sheet items; added the ability to return the name of a sheet item
Version 1.1.1 (link) - Minor bug fix, added rowname and row returns for repeating items
Version 1.1.2 (link) - Bug fix in the logic engine where numeric conditions were not always properly detected
Version 1.1.3 (link) - Bug fix where inline rolls in a condition were not accessed correctly
Version 1.2.0 (link) - added EVAL tag; added rule registration for scriptlet plugins; added row and rowname as retrievable things for repeating sheet items; added MATH tag for inline math calculations; added MULE tag (and get/set language) to handle variable storage

APPENDICES

APPENDIX I - Writing a 3rd-Party Script Plugin

The EVAL tag allows for anyone with a little coding experience to provide an infinite number of extensible features. The EVAL tag will run the script as designated, looking first in its bank of registered plugins. If the script isn’t found there, APILogic will send the script call to the chat to have the script fire that way.

Remember, only plugins registered to APILogic are handled in sequence, with their result substituted into the command line. If nothing is returned, an empty string will be substituted in place of the EVAL block. Only after the plugin code finishes does APILogic take over again. Calls to outside scripts, on the other hand, are not guaranteed to finish before APILogic moves on.

So, how do you write a scriptlet and register it to APILogic?

Accept a Message

A plug-in for APILogic should accept a message object, just as any function that answers a chat event (i.e., handleInput). In fact, your script can also answer a chat event if you like (more on that under Who Called?). The message object will be identical to a message that would be received from a user – it will have properties of who, playerid, content, etc. If there were any inline rolls, it will have an inlinerolls array. This will be a copy of the message data that is in APILogic, with the content replaced to be the reconstructed command line that the user would have sent had they invoked your script directly from chat.

In other words, the withinrange script might require a command line like the following, if it were to be invoked from the chat interface:

!withinrange 3 -M1234567890abcdef ,

When a user places that in an EVAL tag block, they would write:

{& eval}withinrange(3 -M1234567890abcdef ,){& /eval}

If APILogic detects withinrange as a registered plugin in that game, it will hand off a message with the former command line.

Accepting a message might look like this:

const withinrange = (m) => {
	log(m.who); // logs who sent the message
};

Parse the content String

As you would with any script, parse the command line to extract the data you require to perform your calculations. If you intend to allow the scriptlet to be called from the command line, make sure that you verify ownership of the message, as well. This might look like:

const withinrange = (m) => {
    // verify ownership
    if (m.type !== 'api' || !/^!withinrange\s/.test(m.content)) return;
	// parse arguments
	let [range, sourcetoken, delim] = m.content.split(' ').slice(1);
	log(range);
	log(sourcetoken);
	log(delim);
};

Perform Calculations and Return

Code as you normally would to calculate and arrive at the data you are looking for. When you are done, if you want something to be substituted into the original command line (where APILogic called your plugin), return a string, number, bigint, or boolean. Anything else (included no return or an undefined return) will be replaced with an empty string.

Who Called?

A message that comes from APILogic to a plugin scriptlet will have one property that a chat-interface-generated or API-generated call will not have: apil. If you want your script to answer both a straight invocation as well as an APILogic invocation, you can differentiate your return based on if you detect this property.

For instance, if a user invokes withinrange from the chat interface, maybe we want to display a small panel of information regarding the tokens that are in the specified range – including their image, name, etc. However, if the call comes from APILogic, you only want to return the token IDs in a delimited string. In that case, once you have arrived at the data, you could test for existence of the apil property, and return accordingly:

let tokens = getTheTokens();
if (m.apil) return tokens.join(delim);
// if the code continues, you're dealing with a direct invocation
// so proceed to build the panel output...

Register to APILogic

The step that turns your script into an APILogic plugin is when your script implements the APILogic.RegisterRule() function in an on('ready'...) block. Here is an example:

on('ready', () => {
    try {
        APILogic.RegisterRule(withinrange);
    } catch (error) {
        log(error);
    }
});

The RegisterRule() function can take any number of functions as parameters, so tack on as many plugins as you’ve written:

APILogic.RegisterRule(withinrange, getclosest, getpageforchar);

APPENDIX II - Included Script Plugins

The following Script Plugins are included as a part of the APILogic script. If you find a script plugin that you use to be quite helpful, it can be rolled into the included library of plugins for a future release of APILogic.

getDiceByVal

Retrieves a subset of dice from an inline roll based on testing them against a series of pipe-separated value ranges. Outputs either a count of the number of dice (the default), or a total of the dice, or a delimited list of the dice values (delimiter default is a comma).

===== EXAMPLE SYNTAX =====
getDiceByVal( $[[0]] <=2|6-7|>10 total)

The above would retrieve dice from the first inline roll ($0) that were either less-than-or-equal-to 2, between 6 and 7 (inclusive), or greater than 10. It would output the total of those dice.

If you choose a list output, the default delimiter is a comma. You can alter this by using a pipe character followed by the delimiter you wish to include. If your delimiter includes a space, you must enclose it in either single-quotation marks, double-quotation marks, or tick characters.

getDiceByVal( $[[1]] 1|3|5|7|9 list)

The above would output a comma-separated list of odd value die results from the second inline roll ($1). The following table shows how the delimiter changes based on altering the ‘list’ argument:

ARG			|	EXAMPLE OUTPUT
------------|---------------------
list		|	3,7,5,9
list|", "	|	3, 7, 5, 9
list|+		|	3+7+5+9
list|` + `	|	3 + 7 + 5 + 9
list|		|	3759

getDiceByPos

Retrieves a subset of dice from an inline roll based on testing them against a series of pipe-separated position ranges. Outputs either the total of the number of dice (the default), or a count of the dice (seems pointless, but it’s available), or a delimited list of the dice values (delimiter default is a comma). Dice position is 0-based, so the first die is in position 0, the second in position 1, etc.

===== EXAMPLE SYNTAX =====
getDiceByPos( $[[0]] <=2|6)

The above would retrieve dice from the first inline roll ($0) that were in positions 0, 1, 2, or 6. It would output the total of those dice.

The same guidelines apply for the list delimiter as for the getDiceByVal plugin, above.

APPENDIX III - Included Math Functions

The following functions are available as part of the Math processor. Feel free to suggest others if you think one would be helpful.

• abs(x) Returns the absolute value of x
• acos(x) Returns the arc-cosine of x
• asin(x) Returns the arc-sine of x
• asinh(x) Returns the hyperbolic arc-sine of x
• atan(x) Returns the arc-tangent of x
• atanh(x) Returns the hyperbolic arc-tangent of x
• atantwo(x, y) Returns the arc-tangent of the quotient of the arguments (x, y)
• cbrt(x) Returns the cube root of x
• ceiling(x) Returns the smallest integer larger than x
  • -2.1 => -2
  • 2.1 => 3
• cos(x) Returns the cosine of x
• cosh(x) Returns the hyperbolic cosine of x
• exp(x) Returns Euler’s constant (e), the base of the natural log, raised to x
• expmone(x) Returns 1 subtracted from the value of Euler’s constant (e) raised to x
• floor(x) Returns the largest integer less than x
  • -2.1 => -3
  • 2.1 => 2
• hypot(x[, y [, …]]) Returns the square root of the sum of the squares of its arguments
• log(x) Returns the natural logarithm of x
• logonep(x) Returns the natural logarithm of 1 + x
• logten(x) Returns the base-10 logarithm of x
• logtwo(x) Returns the base-2 logarithm of x
• min([x[, y[, …]]]) Returns the smallest value of 0 or more numbers
• max([x[, y[, …]]]) Returns the largest value of 0 or more numbers
• pow(x, y) Returns the value of x raised to the y power
• rand() Returns a pseudo-random number between 0 and 1
• randa(x[, y[, …]]) Returns a random element from a list of 1 or more numbers
• randb(x, y) Returns a pseudo-random number between x (inclusive) and y (inclusive)
• randib(x, y) Returns a pseudo-random integer between x and y, where the lesser value is inclusive and the larger value is exclusive
• round(x, y) Returns x rounded to y decimal places
• sin(x) Returns the sine of x
• sinh(x) Returns the hyperbolic sine of x
• sqrt(x) Returns the square root of x
• tan(x) Returns the tangent of x
• tanh(x) Returns the hyperbolic tangent of x
• trunc(x) Returns the integer portion of x
  • -2.1 => -2
  • 2.1 => 2

Related Pages

• API:Script Index Other avaiable APIs
  • libInline^(Forum) - provides an easy interface for inlinerolls
  • InsertArg^(Forum) -- script preamp, siege engine, menu maker, command line constructor
  • SelectManager^(Forum) -- Utility to Preserve the Selected Tokens For API-Generated Calls
• Complete Guide to Rolls & Macros
  • Inline Rolls
  • Order of Operations