Enchanted Realms 2.7

Downloads

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.

API Usage
The Roll20 API used for enchanted realms is somewhat like a 4th-generation scripting language to be used inside chat calls or macros. It is written to interact with the Roll20 chat interface, which means that certain Roll20 objects and syntax can be used with the API. The API key word !enchantR is required at the beginning but only once, even if issuing multiple commands. After the key word or to start another command it is denoted by two dashes and the command word, e.g., --groupInit. Following the command, its parameters are typed using a [space] between each one; thus, if a parameter needs to use a [space] as perhaps part of its text, then the HTML-encoded value of %20 is used instead. This can be easily seen using the --textSubstitute command. There are a few exceptions to this rule, but it is safest to assume the encoded value will be needed. A few other characters may need to be encoded as well. Candidates are #123; for { (left bracket), #125; for } (right bracket), #44; for , (comma), #37; for % (percent sign), #64; for @ (at sign), among others. Single-command API call: !enchantR --getdefender @{selected\|token_id} edged Multiple-command API call: !enchantR --heal @{selected\|token_id} 2d4 body --playTrack Blessing04 --emphasis @{selected\|token_name} has been healed. Roll20 inline roll syntax with API call: !enchantR --heal @{selected\|token_id} [[5d4kl3]] body (the inline syntax means roll five d4s and keep the lower 3 rolls)

Characters and Tokens
Command:		--auraToggle	!enchantR --auraToggle @{target\|token_id} 1 10 #EFEFEF true false
	Parameter 1:	tokenID
	Parameter 2:	ID of aura (either 1 or 2)
	Parameter 3:	distance in map-feet
	Parameter 4:	RGBColor (hex value)
	Parameter 5:	Boolean is visible to others
	Parameter 6:	[Optional] Boolean Square Shape (the default is false, which indicates using a circle)
	This locates the token by the “token id” and sets the aura values. Use 0 for feet to turn off. Reasons for this might be due to a spell effect or because of caster has the evocation of fire skill.

Command:		--addAxiom	!enchantR --addAxiom @{selected\|token_id} Burning%20Hands 1 [Base64-fx] [Base64-macro]
	Parameter 1:	tokenID
	Parameter 2:	axiom_Name
	Parameter 3:	cost
	Parameter 4:	base64-text
	Parameter 5:	base64-text
	This adds an axiom to the character sheet from the axiom spell list tool. It is not recommended to attempt this without using the tool.

Command:		--addInvocation	!enchantR --addInvocation @{selected\|token_id} Detect%20Magic 2 [Base64-fx] [Base64-macro]
	Parameter 1:	tokenID
	Parameter 2:	incantation_Name
	Parameter 3:	cost
	Parameter 4:	base64-text
	Parameter 5:	base64-text
	This adds an incantation to the character sheet from the incantation spell list tool. It is not recommended to attempt this without using the tool.

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
	DEPRECATED: use --changeTokenMarkers or --tokenModifier instead. 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:		--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:		--deflectRebuff	!enchantR --deflectRebuff @{selected\|token_id} @{target\|token_id} d6 Deflection
	Parameter 1:	tokenID (deflecter)
	Parameter 2:	tokenID (original attacker)
	Parameter 3:	diceFormula
	Parameter 4:	method [Deflection\|Rebuff]
	Used when character has deflect missiles or rebuff skill. The dice formula is available as an option in case enhanced skills have been obtained by the character.

Command:		--dodge	!enchantR --dodge @{selected\|token_id} @{target\|token_id} d6
	Parameter 1:	tokenID (deflecter)
	Parameter 2:	tokenID (original attacker)
	Parameter 3:	diceFormula
	Used when character has the dodge skill. The dice formula is available as an option in case enhanced skills have been obtained by the character.

Command:		--emphasis	!enchantR --emphasis This is a description that is displayed to everyone.
	Parameter 1:	text
	This displays all the text after the command (until the next command) as output to be shown in the chat. It will be spoken in the voice of the GM.

Command:		--emphasisWhisper	!enchantR --emphasisWhisper @{selected\|token_name} This is a description that is displayed to only to the designated target.
	Parameter 1:	targetname
	This displays all the text after the command (until the next command) as output to be shown in the chat; however, it will only be “whispered” to the target name. It will be spoken in the voice of the GM. Tip: if the GM adds his or her player name to the “Can Be Edited & Controlled By” select box of the token, then the GM will also see the output of these whispered texts.

Command:		--featSave	!enchantR --featSave @{target\|token_id} {"type":"save","quality":"resilience","DC":"d4+8"}
	Parameter 1:	tokenID
	Parameter 2:	conditionObject
	Parameter 3:	[Optional] additionalModifier (must be number)
	Parameter 4:	[Optional] advantage [normal\|adv\|dis]
	Parameter 5:	[Optional] Title
	Parameter 6:	[Optional] Custom Marker name
	Parameter 6:	[Optional] Marker Numeric Value (must be number 1-9)
	This locates the token by the “token id” and performs a feat save for the target token based on the “quality” and “DC” properties of the conditionObject. If the additionalModifer parameter is used, then this adds a value to the feat roll for whatever additional condition might be determined by the GM. Further, the advantage parameter can be used to define whether the feat roll is the better or worse of two rolls. Should the Title parameter be passed, then in the output of the roll results this value will displayed rather than the default; however, if multiple words are used, then %20 should be substituted for spaces to ensure parsing of the Title correctly. If a Custom Marker name is passed in, then if the feat fails, this custom marker will be placed on the token that failed the feat. And finally, the Marker Numeric Value would set a number from 1 to 9 as an overlay display of the token-marker displayed. To better understand how to build a conditionObject, read here.

Command:		--getattack	!enchantR --getattack @{target\|token_id}
	Parameter 1:	tokenID
	INFORMATIONAL & DEBUG ONLY This locates the token by the “token id” and displays the current weaponSet attack details in the chat.

Command:		--getdefender	!enchantR --getdefender @{target\|token_id} blunt
	Parameter 1:	tokenID
	Parameter 2:	incoming attack type
	INFORMATIONAL & DEBUG ONLY This locates the token by the “token id” and displays the current defense settings details in the chat. The incoming attack type allows for calculations of resistances.

Command:		--lightToggle	!enchantR --lightToggle @{target\|token_id} 20 5 #EFEFEF true
	Parameter 1:	tokenID
	Parameter 2:	bright light shed in map-feet
	Parameter 3:	dim light extended beyond bright in map-feet
	Parameter 4:	RGBColor (hex value) of the light shed
	Parameter 5:	Boolean to turn light on or off
	This locates the token by the “token id” and sets light-shedding values.

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 false
	Parameter 1:	tokenID (multiple selected tokens permitted)
	Parameter 2:	DC (Number or diceFormula)
	Parameter 2:	Boolean Show Players
	This locates all the currently selected tokens, then for each one a Perception feat is rolled against the DC parameter. The final option determines if only the GM or everyone sees the result table.

Command:		--setBar	!enchantR --setBar @{selected\|token_id} body -3
	Parameter 1:	tokenID
	Parameter 2:	barName [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. It is important to note that formating of the Adjustment parameter controls how the math is applied; if there is a sign (plus or minus) as part of the number value, then this will add or subtract from the current value, but if the Adjustment number has no sign, then this will be the new value set directly. Lastly, the fourth parameter controls whether the new resulting value can exceed the defined maximum. If it is true, then positive numbers will not allow exceed the maximum; while false will permit the barrier to be broken. One scenario might be the difference between healing and gaining from a favor incantation.

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. This helpful for creating a custom macro for a shapeshifter.

Command:		--setAttribute	!enchantR --setAttribute @{selected\|token_id} body 5
	Parameter 1:	tokenID
	Parameter 2:	AttributeName
	Parameter 3:	Value
	This locates the token by the “token id” passed by parameter one and makes a directed change to current value of the named attribute to the value passed as the third parameter. This can be dangerous, as an attribute is essentially any value on the character sheet, determined by the rules of Roll20’s convention for input "name" property.

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 overlayed atop of the token-marker to represent some result of an effect, such as the number of rounds for duration or the modifier of an effect, such as when used with ACBonus marker.

Combat
Command:		--normalAttack	!enchantR --normalAttack @{selected\|token_id} @{target\|token_id} 1 normal
	Parameter 1:	tokenID (attacker)
	Parameter 2:	tokenID (victim)
	This locates the tokens, the selected as the attacker and the target as the defender of the attack. It then reads the current Weapon Set defined on each character to determine the details of the attack and armor/defenses. Then based on those values, the appropriate attack rolls are made and compared to the defending AC values to determine the quality of hit (or perhaps a total miss), considers the type of weapon used, resistances, etc to come up with the final result of success, failure and any damage that might be inflicted against the defender.

Command:		--alternAttack	!enchantR --alternAttack @{selected\|token_id} @{target\|token_id} melee 2 yes edged silver 1 strength 0 onHit;;{"command":"sickness"}
	Parameter 1:	tokenID (attacker)
	Parameter 2:	tokenID (victim)
	Parameter 3:	actionStyle (melee or range)
	Parameter 4:	number of Dice Rolled (must be a number)
	Parameter 5:	has hand-domination (must be yes or no)
	Parameter 6:	Damage Type [alchemical\|blunt\|cold\|edged\|fire\|lightning\|necrotic\|piercing\|poison\|smite]
	Parameter 7:	Weapon Type [normal\|silver\|magic]
	Parameter 8:	Weapon Weight (0, 1 or 2)
	Parameter 9:	subAttribute Modifier (STRENGTH, AGILITY, FAITH, etc)
	Parameter 10:	additional ToHit (must be a number)
	Parameter 11:	[Optional] Special Occurrence Object
	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. The subQuality Modifier parameter will almost always be either STRENGTH or AGILITY based on the weapon used; however, LOGIC and PERCEPTION are also acceptable values due to a few magical effects that use those to modify an attack. For more details on the optional weaponSpecial parameter, read here.

Command:		--extraAttack	!enchantR --extraAttack @{selected\|token_id} @{target\|token_id} melee 2 no edged silver 1 strength 0
	Parameter 1:	tokenID (attacker)
	Parameter 2:	tokenID (victim)
	Parameter 3:	actionStyle (melee or range)
	Parameter 4:	number of Dice Rolled (must be a number)
	Parameter 5:	has hand-domination (must be yes or no)
	Parameter 6:	Damage Type [alchemical\|blunt\|cold\|edged\|fire\|lightning\|necrotic\|piercing\|poison\|smite]
	Parameter 7:	Weapon Type [normal\|silver\|magic]
	Parameter 8:	Weapon Weight (0, 1 or 2)
	Parameter 9:	subAttribute Modifier (STRENGTH, AGILITY, LOGIC, etc)
	Parameter 10:	additional ToHit (must be a number)
	Parameter 11:	[Optional] Special Occurrence Object
	This command is identical to --alternAttack with important distinction. This command will append its dice information that is stored in the token's graphicInfo object rather than overwrite the value. This is critical for multiple-attacks. When creating a macro for a multiple attack, the second attack in the attack sequence must be the --extraAttack to ensure a --dodge command used against the last attack from the token has all the dice stored properly for that calculation.

Command:		--touchAttack	!enchantR --touchAttack @{selected\|token_id} @{target\|token_id} attack 0
	Parameter 1:	tokenID (attacker)
	Parameter 2:	tokenID (victim)
	Parameter 3:	technique [attack\|grapple]
	Parameter 4:	additional ToHit (must be a number)
	Parameter 5:	[Optional] weaponSpecial
	This locates the tokens, the selected as the attacker and the target as the defender of the attack. Then based on whether using a melee attack or a grappling technique from parameter three, the API calculates whether or not the touch attack is successful or not. If it is successful, then the weaponSpecial would occur, depending on the Trigger component of the weaponSpecial as well as the other parts, which may call for a save or test for raw dice score values to apply the special result.

Command:		--boost	!enchantR --boost @{selected\|token_id} d3 body
	Parameter 1:	tokenID
	Parameter 2:	Adjustment (number or diceFormula)
	Parameter 3:	barName [body\|mind\|spirit]
	This adds a value back to the bar of the token linked by the first parameter’s “token id”

Command:		--changeWeaponSet	!enchantR --changeWeaponSet @{selected\|token_id} 2
	Parameter 1:	tokenID (initiator)
	Parameter 2:	weaponSet [1,2,3]
	Sets the predefined weapon set on the character sheet

Command:		--competitionSave	!enchantR --competitionSave @{selected\|token_id} agility 0 @{target\|token_id} strength 0
	Parameter 1:	tokenID (initiator)
	Parameter 2:	SubAttribute used (initiator)
	Parameter 3:	bonus value (initiator)
	Parameter 4:	tokenID (victim)
	Parameter 5:	SubAttribute used (victim)
	Parameter 6:	bonus value (victim)
	Parameter 7:	[Optional] selectedAdvFlag [normal\|adv\|dis]
	Parameter 8:	[Optional] targetAdvFlag [normal\|adv\|dis]
	Parameter 9:	[Optional] Special Occurrence Object
	Competion Saves are used to resolve several conditions, usually which involve two separate characters wanting to perform the same action or an action that is in direct opposition of each other. This might be a character trying to running through someone’s occupied space. Perhaps two combatants are fighting over the state of a door, one trying to open it while the other attempts hold it closed. Possibly two fighters see a free knife laying on the ground and both insist upon obtaining said knife. All of these are examples that would be resolved by a competition. More information about competitions can be found, in the Competitions subsection of Combat Mechanics.

Command:		--deflectRebuff	!enchantR --deflectRebuff @{selected\|token_id} @{target\|token_id} d6 Deflection
	Parameter 1:	tokenID (defending token)
	Parameter 2:	tokenID (token that attacked)
	Parameter 3:	diceFormula value for the roll
	Parameter 3:	descriptionWord [Deflection\|Rebuff]
	This performs either a deflect missiles or a rebuff maneuver against the last attack. The diceFormula is a parameter in case skills change the standard d6 roll.

Command:		--dodge	!enchantR --dodge @{selected\|token_id} @{target\|token_id} d6
	Parameter 1:	tokenID (dodging token)
	Parameter 2:	tokenID (token that attack is being dodged)
	Parameter 3:	diceFormula value for the dodge roll
	This performs a dodge maneuver against the last attack. The diceFormula is a parameter in case skills change the standard d6 roll.

Command:		--grab	!enchantR --grab @{selected\|token_id} @{target\|token_id} 0 +3
	Parameter 1:	tokenID (attacker)
	Parameter 2:	tokenID (victim)
	Parameter 3:	victim Modifier (must be a number)
	Parameter 4:	attacker Modifier (must be a number)
	Parameter 5:	[Optional] defenderFlag [normal\|advantage\|disadvantage]
	Parameter 6:	[Optional] attackerFlag [normal\|advantage\|disadvantage]
	Resolves a grappling competition. In addition to the d12 competition rolls used, the API will examine physical size differences, movement speeds, and any other token-marker advantage or disadvantage conditions.

Command:		--heal	!enchantR --heal @{selected\|token_id} 2d4 body 6
	Parameter 1:	tokenID
	Parameter 2:	Adjustment (number or diceFormula)
	Parameter 3:	barName [body\|mind\|spirit]
	Parameter 4:	[Optional] maxPossible (must be a number)
	This add temporary points from the adjustment to the bar [body\|mind\|spirit] which belongs to the token based on the “token id” from the first parameter. The optional maxPossible paramater can cap the maximum points able to be healed. However, in all cases of this command, the max value of the bar cannot be exceeded through healing. If that is desired, consider the --boost command.

Command:		--inflictsave	!enchantR --inflictsave @{selected\|token_id} @{target\|token_id} {"type":"save","quality":"body","DC":"d4+8"} {"command":"sickness"}
	Parameter 1:	tokenID (attacker)
	Parameter 2:	tokenID (victim)
	Parameter 3:	conditionObject
	Parameter 4:	Special Occurrence Object (requires %20 for spaces)
	The attacker forces the victim to roll a perservation save as defined in the conditionObject. If the victim fails the save, then the formula of the Special Occurrence Object gets applied against them.

Command:		--multiHalfSaves	!enchantR --multiHalfSaves @{selected\|token_id} Lightning-Spell none Lightning%20Strike ?{Targets\|3} {"type":"save","quality":"agility","DC":"15"} {"command":"damage","quality":"body","value":"d4","damageType":"lightning","specialWord":"Lightning%20Shower"}
	Parameter 1:	tokenID (attacker)
	Parameter 2:	Soundtrack
	Parameter 2:	fxFormula (“none” can be used instead of a jSON object)
	Parameter 3:	buttonName
	Parameter 4:	number of Targets (must be a number)
	Parameter 5:	conditionObject
	Parameter 6:	Special Occurrence Object (requires %20 for spaces)
	This creates a button to allow n-number of targets to be tested by the defined condition. Clicking the outputed button applies the potential effect with half-damage for success against the condition. Logically, this means that for this type of command, the formula of the Special Occurrence Object should always use “damage” as its command property.

Command:		--multiTargets	!enchantR --multiTargets @{selected\|token_id} Lightning-Spell {"name":"magic-beam","points":"2","targetNumber":"1"} Voltaic%20Ray ?{Targets\|3} {"type":"save","quality":"agility","DC":"13"} {"command":"damageCascade","quality":"body","value":["2d4","d4","d2"],"damageType":"lightning","specialWord":"Forked%20Lightning"}
	Parameter 1:	tokenID (attacker)
	Parameter 2:	Soundtrack
	Parameter 2:	fxFormula (“none” can be used instead of a jSON object)
	Parameter 3:	buttonName
	Parameter 4:	number of Targets (must be a number)
	Parameter 5:	conditionObject
	Parameter 6:	Special Occurrence Object (requires %20 for spaces)
	This creates a button to allow n-number of targets to be tested by a condition which is defined in the conditionObject parameter. Clicking the outputed button applies the potential effect (all or nothing) from the Special Occurrence Object object parameter. Because the result of this command is designed for each target either to be successful or to fail, the effect could be damage, poison, sickness, applying a token-marker or nearly anything that can be defined by the Special Occurrence Object object parameter.

Command:		--push	!enchantR --push @{selected\|token_id} @{target\|token_id} shove 0 2
	Parameter 1:	tokenID (attacker)
	Parameter 2:	tokenID (victim)
	Parameter 3:	push Type [shove\|trip]
	Parameter 4:	victim Modifier (must be a number)
	Parameter 5:	attacker Modifier (must be a number)
	Resolves a pushing competition, which might be a shove or trip, depending on the desired result. Further the API will examine physical size differences, prone state, and conditions.

Command:		--restore	!enchantR --restore @{selected\|token_id}
	Parameter 1:	tokenID
	This is specifically for the powerful restore incantation.

Command:		--rollGuardDice	!enchantR --rollGuardDice @{selected\|token_id} melee
	Parameter 1:	tokenID
	Parameter 2:	type (melee or range)
	This is specifically for the powerful restore incantation.

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.

Command:		--weaponSetAttack	!enchantR --weaponSetAttack @{selected\|token_id} @{target\|token_id} 2
	Parameter 1:	tokenID
	Parameter 2:	tokenID
	Parameter 3:	weaponSet (must be a number)
	This selects the pre-defined weapon set, then performs a normal attack with that set.

Game Date and Time
Command:		--adjustGameTime	!enchantR --adjustGameTime {"datePart":"h","operator":"+","value":2}
	Parameter 1:	dateAdjust object {"datePart":"[y\|m\|d\|h]","operator":"[+\|=]","value":1}
	This increases or sets one component of the Campaign Calender (hour, day, month or year) by the “value” property of the object. The example shown above increases the game time by two hours. Another example could use the “operator” as “=” to set the day or month to a precise value.

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 roll.

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 (and probably limit it to the GM).

Command:		--tokenInit	!enchantR --tokenInit @{target\|token_id}
	Parameter 1:	tokenID
	This allows a token not currently 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	!enchantR --applySpecial @{target\|token_id} {"command":"ghoultouch","movement":"25"}
	Parameter 1:	tokenID (target)
	Parameter 2:	specialFormula Object (requires %20 for spaces)
	Applies the ‘specialFormula” result to the target token that wasn't applied through automation; this could be either an attack or a benvolent effect.

Command:		--conditionalDice	!enchantR --conditionalDice 20 2 ?{Bonus\|0} 10 20 1
	Parameter 1:	Sides on Dice
	Parameter 2:	Number of Rolls
	Parameter 3:	Bonus Per Die
	Parameter 4:	Target Number
	Parameter 5:	[Optional] Raw Success
	Parameter 6:	[Optional] Raw Failure
	This rolls a die or set of dice, then stores the number of successes (measured by the target number or higher) in the \|stored\| value to be accessed later. Raw success/failure is when the raw score equals the defined value, such as “natural 20.” The LayOnHands macro uses this to determine how many save rolls the recipient makes to determine the number of d3 rolls to heal the target.

Command:		--ifThis	!enchantR --ifThis d2=1 then command:calcDice d10 else command:button
	!enchantR --ifThis d2=1 then command:calcDice d10 else command:button
	Yellow is the API chat trigger. Green is the API command. Blue is the evaluation. Magenta is executed if the evalution is TRUE. Red is executed if the evalution is FALSE. The else statement is not required and if omitted no command will be executed on a FALSE evaluation. The evaluation must result in a boolean. This text could be a literal boolean or a boolean equation. Equations can use dieFormulas, inline rolls, or the \|stored\| keyword. Further, to ensure proper parsing the typical -- delimiter is not used in the ifThis command. Instead the phrase “command:” is used. Note: be certain to include the colon and use no space in that delimiter phrase. Also, be careful not to use the keywords “then” and “else” as part of a commands parameters or the results may be unexpected.

Command:		--moonBlink	!enchantR --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. In the game, there are creatures that have “blink” abilities based on triggers of being hit or after an attack. Moon spiers are one example. This command allows private macros to be added on to those mooks.

Command:		--playSxList	!enchantR --playSxList CombatMusicList
	Parameter 1:	Playlist Name
	Starts a playlist

Command:		--playTrack	!enchantR --playTrack Blessing04
	Parameter 1:	Name of Track
	Plays sound for a track of the passed name

Command:		--prolongation	!enchantR --prolongation ?{Duration\|1} @{selected\|spirit_faith}
	Parameter 1:	duration
	Parameter 1:	faithScore
	This calculates the new duration from the parameters when having the prolongation skill, then stores that value to the campaign object so that a macro can pick its value up in a second command.

Command:		--setTrackVolume	!enchantR --setTrackVolume 50 Blessing04
	Parameter 1:	Volume Level (1 - 100)
	Parameter 2:	Name of Track
	Sets the default volume for a specific track

Command:		--stopSound	!enchantR --stopSound
	Stops all sound/music

Command:		--storeDice	!enchantR --storeDice 3d4
	Parameter 1:	diceFormula (number or diceFormula)
	There are times that a number or a result of a dice roll needs to be stored to be recalled or displayed later by another API command. This is helpful when a value cannot be determined by a single API comand. It can be recalled by using \|stored\| in API text and is currently supported by any diceFormula parameter and the commands: emphasis, emphasisWhisper and setBar. The LayOnHands macro shows an example of this.

Debugging
Command:		--analyzeSpOO	!enchantR --analyzeSpOO @{selected\|token_id} @{target\|token_id} onHit;;{"command":"poison"}
	Parameter 1:	tokenId
	Parameter 2:	tokenId
	Parameter 3:	Special Occurrence Object
	INFORMATIONAL & DEBUG ONLY This will apply consequence if the spOO is succesful from parsing, using the selected and target for a hypothetical single natural20 die roll, then display the result in the chat output.

Command:		--button	!enchantR --button
	INFORMATIONAL & DEBUG ONLY Creates a predefined command button as output in the chat log. This can be used to test for player's ability to create on output button from their own context.

Command:		--calcDice	!enchantR --calcDice d10+?{UserBonus\|2}
	Parameter 1:	diceFormula
	INFORMATIONAL & DEBUG ONLY Performs a die formula roll, to test how the parameter is formatted, then outputs the details, which include many depths of the roll.

Command:		--getMarkerCondition	!enchantR --getMarkerCondition @{target\|token_id} attack melee blunt
	Parameter 1:	tokenID
	Parameter 2:	actionMethod (attack or defend)
	Parameter 2:	actionStyle (melee or range)
	Parameter 2:	incoming attack type
	INFORMATIONAL & DEBUG ONLY This locates the token by the “token id” and analyzes the currenly set token-markers for modifiers to be used as part of either the token’s attack or the token’s defense, based on the effects currently set. Essentially, a token may be attacking with melee, attacking with range, defending against melee, or defending against range. Based on that, the application of the various token-markers currently set can create the conditions which would be modified.

Command:		--listSoundFX	!enchantR --listsoundfx
	INFORMATIONAL & DEBUG ONLY This displays all the tracks in the playlist called “SoundFX” as output shown in the chat.

Command:		--parseWeaponSpecial	!enchantR --parseWeaponSpecial anyRaw>=18;;{"command":"heavy"}
	Parameter 1:	Special Occurrence Object
	INFORMATIONAL & DEBUG ONLY This does not apply anything but only parses and tests the text of the Special Occurrence, display the result of its interpretation of the text in the chat output.

Command:		--showStored	!enchantR --showStored
	INFORMATIONAL & DEBUG ONLY This does not reads and reports the value from commands that store a value, such as --prolongation or --storedice

Command:		--testCondition	!enchantR --testCondition @{selected\|token_id} @{target\|token_id} {"type":"bool","comparison":"3d4<=6"}
	Parameter 1:	tokenID (selected)
	Parameter 2:	tokenID (target)
	Parameter 3:	conditionObject
	INFORMATIONAL & DEBUG ONLY This requires a selected token and then will ask for a target token. It will test the conditionObject and outputs the details of the evaluation. This can be used to test boolean logic, a save condition or even a competition. If using a save, it will be tested against the target.

Command:		--textSubstitute	!enchantR --textSubstitute %2D%2Demphasis%20This%20is%20an%20Example;%20right%3F
	Parameter 1:	UnspacedTextWith%URLEncoding
	INFORMATIONAL & DEBUG ONLY This does not apply anything but only reveals how encoded text will be interpreted and appear

Expert Usage
Command:		--createEffect	!enchantR --createEffect @{target\|token_id} thicket
	Parameter 1:	tokenID
	Parameter 2:	effectName (one of the defined effects)
	Creates a graphic token of the matching named effect centered on the identified token. Common effects are: Darkness, FogOfWar, Shower, Silence, Tremor, WallRing and WallStraight
Command:		--output	!enchantR --output @{target\|token_id} {"object":"token"}
	Parameter 1:	ID (static word “all” can be substituted)
	Parameter 2:	filter
	INFORMATIONAL & DEBUG ONLY This is a very powerful export feature which allows details of any object to be displayed in both the chat output and the API debug window. As such, the filter paramter can be very complex. It will not be detailed here but rather assume a simple object-type definition will be used in simple form. This entry is meant to document how to display information associated with a graphical token. Therefore, rather than full documentation of this command, a list of examples for such a limited scope are shown below:
		--output @{target\|token_id} {"object":"character"} : outputs Roll20 character object related to the selected token
		--output @{target\|token_id} {"object":"graphicinfo"} : outputs graphicInfoObject for the selected token
		--output @{target\|token_id} {"object":"player"} : outputs player details connected to the selected token
		--output @{target\|token_id} {"object":"token"} : outputs the Roll20 token object for the selected token

Object Documentation
@{target\|token_id}		Any object starting with an @-sign is a Roll20 object. Roll20 has its own objects and documentation to understand them.

?{Prompt Text\|2}		This is a Roll20 User-Prompt for macros. Any object starting with a ?-mark is a Roll20 object. Roll20 has its own objects and documentation to understand them.

attackerInformation		This is an internal object the API uses whenever examining a Roll20 token. Here is its structure: { "handDom": true, "name": "Flail", "style": "melee", "attackDice": 3, "damageDice": "d20", "damageType": "blunt", "weaponType": "magic", "weaponSize": 2, "weaponModifier": "strength", "weaponToHitBonus": 6, "weaponDmgBonus": 2, "extraModifier": 3, "special": "anyRaw>=20;;{\"command\":\"stunned\",\"save\":\"ResilienceDC8\"}", "sound": "Melee01", "sizeCategory": "Medium", "sizeMod": 0, "singleDieAdvantage": false, "tab": 1 }

attackResult		This is an internal object that is returned after a token item attacks another character, creature or mook. Here is its structure: { "totalHits":1, "damage":3, "diceUsed":{Roll Object} "UIchat":"text/html sent to the chat UI" }

cmdObject		This is an internal object the API uses to store the command sent into the chat. Here is its structure: { "commandText": "!enchantR --stopSound", "order": 1, "processed": false }

cmdOutputObject		This is an internal object the API uses interact with the internal sendChat function to write the response back to the UI. Here is its structure: { "speakAs": "GM", "response": "The command did not produce a response value. Check the debug log for details." }

conditionObject		The conditionObject can either be part of a Special Occurrence Object or act independently as a means to identify a resolvable condition. It will be formatted as a JSON object and have various properties based on its intent. However, it will always have a “type” property to define how the condition works. The viable values for this are [bool\|competition\|dice\|feat\|save]. If it is a bool type, the another property of “comparison” will be included and its value will be boolean text that can be interpreted by the js eval() method, such as "3d4<=6" (because the dice calculation will be internally resolved before the eval method) which would make the object formatted like {"type":"bool","comparison":"3d4<=6"} If the type is competition, then a “quality” property will be needed for the object. The value will be one of the sub-attributes like strength or muse. This is interpretted by the API will applied to mean both opponents involved will resolve a competition on that attribute of their characters. A valid object of this type would look like {"type":"competition","quality":"agility"} For a dice-type condition, a “comparison” property is included where only the operator and value of the evaluation is used. This is rarely written manually, but the API will generate internal objects of this type when associated with triggers in a weaponSpecial. Thus, it looked like {"type":"dice","comparison":">=18"} which might be used with a “anyRaw” trigger. In this case, each result of the dice of a roll is compared to see if its raw score >=18. If so, then the condition would be true. Again, this would be rare to see it manually configured this way because the trigger will often include that part of the dice-comparison in its text and the conditionObject would be omitted in the weaponSpecial. While building a feat or save competitions, then several properties must be included to the object; however, there is also an optional property. Values for “quality” and “DC” will be needed. The text-format of the object would look like {"type":"save","quality":"strength","DC":"13"} For this example, the condition would be a save/feat roll made by the defender or target, using strength against a DC of 13. The “DC” value could also be a dice-formula like d4+10. One final optional property is “DCMod” valued by a sub-attribute. The comparison then looks at the attacker (or selected token) for the modifier of that sub-attribute. It would then add any modifer value to the the DC needed for the save or feat. Thus, {"type":"feat","quality":"strength","DC":"13""DCMod":"faith"} would check the attacker's faith modifer value and increment the DC needed for the save or feat by that amount. Remember, the difference between a feat and save is that feats use the sub-attribute modifier as the bonus to the roll where a save will use the whole sub-attribute value.

conditionTestResponse		This is an internal object the API uses when testing if the condition happened. Here is its structure: { "test": false, "type": "dice", "UIchat": "The feedback to the UI is written here.", "diceResults": [15,4], "errorMessage":"If there is reason why the condition did not process, this is the error information." }

dateAdjust		This is an object to adjust the game calendar. It has three properties: “datePart” “operator” and “value” used to make the changes. The “datePart” can be [y\|m\|d\|h], while the “operator” is"[+\|=]", and “value” is a number. Thus, {"datePart":"d","operator":"=","value":15} means to set the current day of the month to exactly 15.

defenderInformation		This is an internal object the API uses whenever examining a Roll20 token. Here is its structure: { "totalRangePP": 12, "totalMeleePP": 14, "resistance": "Normal", "shield": 0, "weaponToHit": "normal", "reactions": "Potential reactions: Dodge", "parry": 0, "damageReduction": 0, "success": true, "errorMessage": "" }

diceFormula		This is a spaceless text to represent how dice and modifiers are rolled. For example, 2d20+3, which would roll two 20-sided dice, sum their raw scores, then add 3 to the total.

graphicInfoObject		This is an internal object the API uses whenever examining a Roll20 token. Here is its structure: { "id":"-DK343kdCPEsopJALvj", "name":"Bob", "tokenObject":{Roll20object}, "characterObject":{Roll20object}, "hasToken":true, "hasCharacter":true, "lastAttackRoll":{object}, "lastAttackDetail":{object}, "errorMessage":"" }

specialFormula		the specialFormula object is either the third part of the Special Occurrence Object or a stand-alone object that controls the an effect to be applied. For example, the --multiTargets command used this as a stand-alone object. There are many different types of effects that this object can be used to represent. So many that it is recommend to use the tool to discover all the different permutations that this can take. However, all specialFormula objects will begin with a “command” property. The possible values for the command are [backstab\|button\|crit\|custom\|damage\|damageCascade\|ghoulTouch\|grapple\|heavy\|heavyBlow\|itching\|n-markers\|poison\|regen\|sickness\|swallow\|word] and due to this plethera of options, it would be nearly impossible to document each. Again, it is recommend to to use the tool to learn how to format a specialFormula object for a desired effect. Blackbelt Note: If two or more effects need to be delivered in a single formula, then one can use the “various” command. This will be followed by the property “inner” with the value of an array of specialFormula objects. The giant spider monster has this as its specialFormula on its bite attack. {"command":"various","inner":[{"command":"damage","quality":"mind","value":"d4","damageType":"poison"},{"command":"poison"}]}

Special Occurrence Object		The Special Occurrence Object (or spOO) is an object; however, it can have text represent it with short-hand portions. Whenever, the text is passed into the API, it will be transformed into the object. In its text-form, it must be a continuous stream of text with no spaces; therefore, if a space is required to display as part of its rendering values, then the value %20 is used instead. There are three sub-objects to a spOO: a trigger, a condition, and a formula. The text will use semi-colons as a delimiter between these three, but the entire text will never has spaces. Examples of the weaponSpecial would be anyRaw>=18;;{"command":"heavy"} and onHit;ResilienceDC14;{"command":"poison"} The two examples will be turned into the actual spOO, shown below: {"trigger":"anyRaw","condition":{"type":"dice","comparison":">=18"},"formula":{"command":"heavy"}} {"trigger":"onHit:,"condition":{"type":"save","quality":"resilience","DC":"14"},"formula":{"command":"poison"} Especially after a character has gained several skills, there may be the need to have more than one possible result. This is managed with two different options. The first is when the trigger and condition are the same, but multiple commands are needed. An example would be a save against a poison that both inflicts blindness and the poison restriction. This would be codified by using the various command. An example is shown below: onHit;ResilienceDC14;{"command":"various","inner":[{"command":"poison"},{"command":"blind"}]} The other option is by using multiple spOOs in the object itself delimited by the pipe (\|) character. This is typically done when the triggers and conditions are different; however, depending on the triggers (such as raw scores), this might be the same as the method above. That said, it is good practice to think of the different spOOs as whether these are separate events or just one, especially when a save is involved. Separating them with a delimiter will instruct the engine to roll two separate conditions; thus, two saves if the type is save, meaning one could work and the other avoided, even if the save conditions are the same. An example of multiple spOOs might be when a gladius would potentially maim a victim but also has been infused with ice. To demonstrate the syntax, see the example below: anyRaw>=20;;{"command":"maimed","save":"AgiltyDC6","movement":5}\|onHit;;onHit;;{"command":"damage","quality":"body","value":"1","damageType":"cold","specialWord":"ICE%20BONUS"} Sometimes the condition text is needed as a separate object for some API commands. In such cases, the parameter will be designated as conditionObject. As example of this is the --featSave command. Likewise, the formula text may be needed as a separate object for different API commands, where it will be called specialFormula, as can be seen in the --inflictSave command. More information about this can be found with the conditionObject. Finally, to understand the Special Occurrence Object, it is best to use the tool found here. In the end, this value is used to add special and extra effects after the attack, based on a mulititude of potential triggers and conditions.
Dice Formulas
As stated above, the API supports inline rolls using the Roll20 formulas. Those are documented on the Roll20 site here. However, if preferred, the API also interprets simple text for most dice formula needs. At the basic level, there are two parts to a “dice formula:” the dice to be rolled and optional special-effect commands. 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.