Enchanted Realms API for Roll20
All input lines or macros must begin with “!enchanted” to notify the API, followed by the command and parameters. Below are a series of available commands..
Characters and Tokens | |||
| Command: | --avatar | !enchanted --avatar @{selected|token_id} | |
| Parameter 1: | tokenID | ||
| This allows details of the object to be displayed. The tokenID parameter is the “token id” of the object to be inspected. | |||
| Command: | --changeStatus | !enchanted --changeStatus @{selected|token_id} {status_yellow,true} | |
| Parameter 1: | tokenID | ||
| Parameter 2: | Status_marker code | ||
| This locates the token by the “token id” passed by parameter one and applies the status change defined in the second parameter. | |||
| Command: | --setBar | !enchanted --setBar @{selected|token_id} body -3 | |
| Parameter 1: | tokenID | ||
| Parameter 2: | Stat [body|mind|spirit] | ||
| Parameter 3: | Adjustment | ||
| Parameter 4: | Optional Boolean to set limit not to exceed maximum | ||
| This alters the value linked to the body, mind or spirit bar by the adjustment amount. If the fourth parameter is true, then positive numbers will not allow the current value to exceed the maximum. | |||
| Command: | --selectSide | !enchanted --selectSide @{selected|token_id} 0 | |
| Parameter 1: | tokenID | ||
| Parameter 2: | index | ||
| This changes the side of a multi-image token, as selected by its “token id” in the first parameter. It will be set to the index of the images based on the value of the second parameter. The index is zero-based. | |||
Combat | |||
| Command: | --standardAttack | !enchanted --standardAttack @{selected|token_id} @{target|token_id} | |
| Parameter 1: | tokenID (attacker) | ||
| Parameter 2: | tokenID (victim) | ||
| The reads the information from the attacking token to determine the type of attack set on the combat tab and uses those values, weapons, styles and number of attacks against the appropriate defense of the victim’s character sheet. Both tokens must be related to a character sheet, even if the token is a mook. It then evaluates the rolls and applies the proper damage and special status changes as needed. | |||
| Command: | --alternateAttack | !enchanted --alternateAttack @{selected|token_id} @{target|token_id} 30 2 slash d6+1 attacks | |
| Parameter 1: | tokenID (attacker) | ||
| Parameter 2: | tokenID (victim) | ||
| Parameter 3: | Attack Bonus | ||
| Parameter 4: | Number of d100s | ||
| Parameter 5: | Damage Type | ||
| Parameter 6: | Damage Dice Formula | ||
| Parameter 7: | Verb-Object Description of attack, such as “swings sword” | ||
| The takes the input to evaluate the information from the input and uses it against the appropriate defense of the victim’s character sheet. Both tokens must be related to a character sheet, even if the token is a mook. It then evaluates the rolls and applies the proper damage and special status changes as needed. It is best to use this with a queryable macro to ensure the splitting of parameters is set correctly. | |||
| Command: | --heal | !enchanted --heal @{selected|token_id} 2d4|body | |
| Parameter 1: | tokenID | ||
| Parameter 2: | Dice Formula | ||
| This adds the dice formula back to the stat (defined in the dice formula) of the token lined by the first parameter’s “token id” | |||
Game Date and Time | |||
| Command: | --showGameTime | !enchanted --showGameTime | |
| This outputs the values of the game world date and current hour as stored in the Campaign object. | |||
| Command: | --defineGameTime | !enchanted --defineGameTime 707 2 21 15 | |
| Parameter 1: | Year | ||
| Parameter 2: | Month | ||
| Parameter 3: | Day | ||
| Parameter 4: | Hour | ||
| This is a four-parameter method for setting the exact game time. The example sets the current Game Time to 3PM on February 21st for the year 707. | |||
| Command: | --setGameTime | !enchanted --setGameTime +h 2 | |
| Parameter 1: | datePart operation [+][h|d|m|y][=] | ||
| Parameter 2: | Value | ||
| This increases or sets a datePart (hour, day, month or year) the value of the second parameter. The example increases the game time by two hours. Another example would be “d= 3” to set the day precisely to the 3rd day of the month. | |||
Initiative | |||
| Command: | --groupInit | !enchanted --groupInit | |
| This finds all the currently selected tokens and adds them to the Turn Order. It reads the token represents to find the character sheet and uses the adjustments set on the sheet for any variances from the standard 2d10. | |||
| Command: | --resetInit | !enchanted --resetInit | |
| Uses the values currently in the Turn Order and defines initiative for the next round. Any values greater than 20 or custom-defined are adjusted to be used as preserved in the new combat round, but all others are rerolled with the same rules as the original groupInit command. | |||
| Command: | --nextInit | !enchanted --nextInit | |
| This increments the second counter of the combat round. When reaching past 20, it automatically calls the resetInit command. This is very hand to set as a macro button. | |||
Other | |||
| Command: | --moonBlink | !enchanted --moonBlink @{selected|token_id} | |
| Parameter 1: | tokenID | ||
| This moves the token associated with the “token id” of the parameter in a random direction by 20 feet. | |||
| Command: | --odds | !enchanted --odds d100 26 heal @{target|token_id} 2d4|body | |
| Parameter 1: | Dice Formula | ||
| Parameter 2: | Required Threshold | ||
| Parameter 3: | New Command Sequence | ||
| This sets a random chance of a second command. When starting the new command sequence do NOT use the --command indicator. In the example given there is a 75% chance of a 2d4 healing effect to occur. | |||
| Command: | --sorceryTest | !enchanted --sorceryTest @{target|token_id} 20 | |
| Parameter 1: | tokenID | ||
| Parameter 2: | Spell Difficulty | ||
| This checks whether or not an axiom can be cast. Use the raw difficulty score, as the function will examine the character for stat modifiers. | |||
Dice Formulas
There two basic parts to a “dice formula:” the dice to be rolled and optional special-effect commands.
At the simplest, a “dice formula” is the [n]umber of [s]-sided dice to roll. This is represented by the following: [n]d[s]. Therefore “2d10” is two 10-sided dice added together. Optionally, the [n] value can be omitted, which would assume only one die is rolled. Thus, “d6” is one roll of a six-sided die.
An additional option is for bonuses or penalties, represented by appending a plus or minus sign and a number without any additional spaces. Therefore, “2d10+5” means two rolls of 10-sided dice added together then having 5 more points added to that sum, making the possible range from 7 to 25.
Lastly in the first part, body is assumed to be damaged in an attack; however, sometimes mind or spirit will be afflicted. In such cases, also without spaces, add a pipe-character and the stat to inflict. Thus, “d6+2|mind” indicates the result of a 6-sided die roll plus 2 will inflict that amount of damage against the mind value. It is also possible to do no damage at all by using “d1|none” as the formula. This would indicate a successful hit (possibly touch) that does not damage the victim in any way from the initial attack.
This is where the second and optional portion of the formula comes into play, the special-effect command. Often this is for administering poison or to see if the victim has become restrained in some way. There are several ways to test a condition to see if the special-effect is valid. This is performed by three parameters separated by spaces; when there is an opportunity for ambiguity, such as with the alternateAttack command, use “%20” in place of a space.
The first part can be one of the five following options:
| onHit | This sets the special-effect true if any of the attacks scored a hit against the opponent’s defense. | |||||||||
| ifHitPlus:[a]>[b] | If any attack scores a hit, then roll a new check where [a] is a new dice formula to be equal or greater than [b]. The value of [b] is usually a number, but it can be “def” to indicate the defense of the opponent. If that condition is true, then the special-effect happens. |
Substitution for [b]:
|
||||||||
| newRoll:[a]>[b] | This forces a new roll whether there was a hit or not. It creates a separate special roll with [a] being the formula and [b] being the target difficulty. It is also possible to set [b] as “def” to indicate the opponent’s defense score. If that condition is true, then the special-effect occurs. | |||||||||
| anyRaw>[b] | This tests all the raw values of the original dice thrown without modifiers considered. If any raw values is equal or greater to target of [b] (which can be set to “def”), then the special-effect is valid. | |||||||||
| anyScore>[b] | This is similar to the raw value but this considers the total score. Perhaps if any attack has a total value equal or better than 120, then something happens, then this would be the way to check. In this case [b] can also be defined as “def” but that would be moot as the onHit option could have just been used for that condition. |
If the first part condition becomes true, then the second part is what happens. This can be one of two things: either damage or a “status_marker” change. Status_marker codes are exactly as those in the Roll20 documentation. An example would be {status_yellow,true} which would turn on the yellow circle for the victim token on. If damage is needed, then use a simple dice formula, such as “d6+1|mind” to indicate the damage to be inflicted. Lastly, the third part is the description. This would be like “gripped” or “slowed” or “poisoned,” etc.
Often the dice formula is used on the “damage” part of the character sheet for standard attacks or as the sixth parameter of alternate attacks (often stored as a character ability macro). Thus, if a character is wielding a dagger, then the “damage” field would read “d4+1” on the character sheet. However, below are a few examples of other situations.
| Double-Punch | d4+1%20ifHitPlus:d100+23>def%20d4+1%20Double-Punch |
| Martial-Arts Grapple | d1|none%20onHit%20{status_grab,true}%20Held |
| Poison | d4+1%20ifHitPlus:d100>bdiff%20{status_green,true}%20Poison |
| Weapon of Doubt | d6+1%20onHit%20d1|spirit%20Doubt |