Enchanted Realms API for Roll20
All input lines or macros must begin with “!enchantR” to notify the API, followed by the command and parameters. The API is written so that multiple commands (and required parameters for each) can be entered at the same time. Below are a series of available commands. At the very bottom is a glossary of terms.
Characters and Tokens | ||||
Command: | --avatar | !enchantR --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: | --clearTokenMarkers | !enchantR --clearTokenMarkers @{selected|token_id} | ||
Parameter 1: | tokenID | |||
This locates the token by the “token id” and removes all status markers, custom and legacy | ||||
Command: | --changeStatus | !enchantR --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. This is for legacy (original) status markers only. | ||||
Command: | --changeTokenMarkers | !enchantR --changeTokenMarkers @{selected|token_id} charmed true | ||
Parameter 1: | tokenID | |||
Parameter 2: | Custom Marker name | |||
Parameter 3: | Boolean to turn on or off | |||
This locates the token by the “token id” passed by parameter one and applies the marker from second parameter. This is for custom markers only. | ||||
Command: | --character | !enchantR --character @{selected|token_id} | ||
Parameter 1: | tokenID | |||
This allows details of the character of the token object to be displayed. The tokenID parameter is the “token id” of the object to be inspected. | ||||
Command: | --deathSave | !enchantR --deathSave @{target|token_id} | ||
Parameter 1: | tokenID | |||
When the targeted token is below 0 body points, this macro rolls a death save for stability or continued decline | ||||
Command: | --listTokenMarkers | !enchantR --listTokenMarkers @{selected|token_id} | ||
Parameter 1: | tokenID | |||
Displays all the token markers for the object, custom and legacy | ||||
Command: | --perception | !enchantR --perception @{selected|token_id} 11 | ||
Parameter 1: | tokenID (multiple selected tokens permitted) | |||
Parameter 2: | DC | |||
Makes perception checks for all selected tokens | ||||
Command: | --preservationsave | !enchantR --preservationSave @{target|token_id} body<8+d4 SONIC-BLAST deaf | ||
Parameter 1: | tokenID | |||
Parameter 2: | Dice Formula | |||
Parameter 3: | Name of Effect | |||
Parameter 4: | Custom Marker name | |||
Parameter 5: | Optional Number Marker | |||
This performs a preservation save for the target token, then applies the token marker if failed. | ||||
Command: | --setBar | !enchantR --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 | !enchantR --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. | ||||
Command: | --setAttribute | !enchantR --setAttribute @{selected|token_id} {ac_other,2} | ||
Parameter 1: | tokenID | |||
Parameter 2: | Attribute { name, value } | |||
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. | ||||
Command: | --setinvocationlist | !enchantR --setinvocationlist @{target|token_id} calamity | ||
Parameter 1: | tokenID | |||
Parameter 2: | Province [Calamity|Community|Deception|Earth-Fire|Knowledge|Life|Nature|Sea-Sky|War] | |||
Reads character Priestly Points then sets all available invocations based on province. | ||||
Command: | --tokenModifier | !enchantR --tokenModifier @{selected|token_id} attackBonus 2 | ||
Parameter 1: | tokenID | |||
Parameter 2: | Custom Marker name | |||
Parameter 3: | Number to add as a modifier | |||
This is similar to --changeTokenMarkers except it applies a number. This is for custom markers only. | ||||
Combat | ||||
Command: | --normalAttack | !enchantR --normalAttack @{selected|token_id} @{target|token_id} 1 normal | ||
Parameter 1: | tokenID (attacker) | |||
Parameter 2: | tokenID (victim) | |||
Parameter 3: | Number weapon attack from character sheet | |||
Parameter 4: | Optional Advantage flag with default being normal. Values: [normal|adv|dis] (This may be overridden by the conditions of token Markers) | |||
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 defenses 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: | --alternAttack | !enchantR --alternAttack @{selected|token_id} @{target|token_id} normal melee 2 d20 blunt silver anyRaw>=18%20Heavy | ||
Parameter 1: | tokenID (attacker) | |||
Parameter 2: | tokenID (victim) | |||
Parameter 3: | Advantage flag | |||
Parameter 4: | Range or Melee | |||
Parameter 5: | Number of Dice to Roll | |||
Parameter 6: | Dice Formula | |||
Parameter 7: | Damage Type | |||
Parameter 8: | Weapon Type | |||
Parameter 9: | Optional Special Condition | |||
The takes the input to evaluate the information from the input and uses it against the appropriate defenses 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: | --boost | !enchantR --boost @{selected|token_id} d1+1 body | ||
Parameter 1: | tokenID | |||
Parameter 2: | Dice Formula | |||
Parameter 3: | Quality To Boost | |||
This adds the dice formula back to the stat of the token lined by the first parameter’s “token id” | ||||
Command: | --grab | !enchantR --grab @{selected|token_id} @{target | token_id} +3 normal normal | ||
Parameter 1: | tokenID (attacker) | |||
Parameter 2: | tokenID (victim) | |||
Parameter 3: | Environmental modifier | |||
Parameter 4: | Optional Advantage flag for attacker | |||
Parameter 5: | Optional Advantage flag for victim | |||
Resolves a grappling competition. | ||||
Command: | --heal | !enchantR --heal @{selected|token_id} 2d4 body | ||
Parameter 1: | tokenID | |||
Parameter 2: | Dice Formula | |||
Parameter 3: | Quality To Heal | |||
This add temporary points from the dice formula to the stat of the token lined by the first parameter’s “token id” and can exceed the maximum value | ||||
Command: | --inflictsave | !enchantR --inflictsave @{selected|token_id} @{target|token_id} bodyDC8+SM Damage%201:Body%20Necrotic | ||
Parameter 1: | tokenID (attacker) | |||
Parameter 2: | tokenID (victim) | |||
Parameter 3: | Condition Formula (quality DC value[BM,MM,SM attacker's modifiers]) | |||
Parameter 4: | Special Formula (requires %20 for spaces) | |||
The attacker forces the victim to roll a perservation save of a particular quality against a static or formulaic DC. | ||||
Command: | --multiHalfSaves | !enchantR --multiHalfSaves @{selected|token_id} Lightning-Spell Lightning 3 bodyDC8+d4 Damage%201:Body%20Lightning | ||
Parameter 1: | tokenID (attacker) | |||
Parameter 2: | Soundtrack | |||
Parameter 3: | Button Name | |||
Parameter 4: | Number of Targets | |||
Parameter 5: | Condition Formula | |||
Parameter 6: | Special Formula (requires %20 for spaces) | |||
This creates a button to allow n-number of targets to be tested by a boolean condition. Clicking the outputed button applies the potential effect with half-damage for success. | ||||
Command: | --multiTargets | !enchantR --multiTargets @{selected|token_id} Lightning-Spell Lightning 3 bodyDC8+d4 Modifier%20attackPenalty%201 | ||
Parameter 1: | tokenID (attacker) | |||
Parameter 2: | Soundtrack | |||
Parameter 3: | Button Name | |||
Parameter 4: | Number of Targets | |||
Parameter 5: | Condition Formula | |||
Parameter 6: | Special Formula (requires %20 for spaces) | |||
This creates a button to allow n-number of targets to be tested by a boolean condition. Clicking the outputed button applies the potential effect (all or nothing). | ||||
Command: | --targetHalfSaves | |||
Parameter(s): | generated, not manually defined | |||
Generated Button Command from multiHalfSaves command. | ||||
Command: | --targetMany | |||
Parameter(s): | generated, not manually defined | |||
Generated Button Command from multiTargets command. | ||||
Game Date and Time | ||||
Command: | --adjustGameTime | !enchantR --adjustGameTime +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. | ||||
Command: | --defineGameTime | !enchantR --defineGameTime 223 4 25 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 April 25 for the year 223. | ||||
Command: | --showGameTime | !enchantR --showGameTime | ||
This outputs the values of the game world date and current hour as stored in the Campaign object. | ||||
Initiative | ||||
Command: | --groupInit | !enchantR --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 d10. | ||||
Command: | --newinit | !enchantR --newinit | ||
Initiates a new round for tokens still in the Turn Order. This is very handy to set as a macro button. | ||||
Command: | --tokenInit | !enchantR --tokenInit @{target | token_id} | ||
Parameter 1: | tokenID | |||
This allows a token not in the combat to enter, using modified values based ont he current initiative value. It also permits a re-roll of an existing token if there was a mistake. | ||||
Other | ||||
Command: | --applyspecial | !enchanted --applyspecial @{selected|token_id} @{target|token_id} Damage%201:body%20Lightning | ||
Parameter 1: | tokenID (attacker) | |||
Parameter 2: | tokenID (victim) | |||
Parameter 3: | Special Formula (requires %20 for spaces) | |||
Applies the ‘Special Formula” from the selected token to the target token that wasn't applied through automation; this coulb be either an attack or a benvolent effect. | ||||
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: | --playSxList | !enchanted --playSxList CombatMx | ||
Parameter 1: | PLaylist Name | |||
Starts playlist | ||||
Command: | --playTrack | !enchanted --playTrack Blessing04 | ||
Parameter 1: | Name of Track | |||
Plays sound for a track of the passed name | ||||
Command: | --setTrackVolume | !enchanted --setTrackVolume 50 Blessing04 | ||
Parameter 1: | Volume Level (1 - 100) | |||
Parameter 2: | Name of Track | |||
Sets the volume for a specific track | ||||
Command: | --stopSound | !enchanted --stopSound | ||
Stops all sound/music | ||||
Debug | ||||
Command: | --button | !enchanted --button | ||
Creates a predefined command button in the chat log | ||||
Command: | --calcdice | !enchantR --calcdice d10 | ||
Parameter 1: | Dice Formula | |||
Performs a die formula roll and outputs the details. | ||||
Command: | --disectDice | !enchanted --disectDice d6+8MM | ||
Parameter 1: | Value | |||
Outputs how the system will decipher the value into a dice formula [BM,MM,SM will be zero for debug] Dice Formulas for the API are not the same as Roll20. |
||||
Command: | --testcondition | !enchantR --testcondition @{target|token_id} BodyDC10 | ||
Parameter 1: | tokenID | |||
Parameter 2: | Condition Formula | |||
Tests a condition formula against a token. A true value indicates the desired effect will occur; a false indicates the token “saved” | ||||
Again, the API is written so that multiple commands can be entered at the same time.
Therefore, the following is a valid API call:
!enchantR --heal @{selected|token_id} 2d4 body --playTrack Blessing04
--emphasis @{selected|token_name} has been healed.
Condition Formula: This is a boolean condition of left operator right.
Left can be a number, dice formula or a quality of the targeted token (plus modifiers)
Operator can be <, <=, =, =>, > or DC
Right can be a number or dice formula (or a quality modifiers if there is an attacker)
Dice Formula: The specific dice and modifiers to be rolled.
Special Condition: The Trigger, Condition and Special Formula:
Sometimes the Trigger and the Condition are the same, where the Trigger acts as the left portion of the condition.
More information at Weapon Specials
Special Formula: Effects applied after a successful condition.