Roll20 Wiki

API ScriptAuthor: Timmaugh
Version: 1.2
Last Modified: 2020-06-21
Code: HeroRoller
Dependencies: None
Conflicts: None

HeroRoller

Hero Roller (or, heroll, for short), is an API to be used for "Hero System 6e" or "Hero System 6e Heroic", and works with the corresponding Roll20 "Hero" character sheet.

It takes a command line of arguments to describe the Hero power you want to use, then spits out all of the parameters that the roll would produce in game... hopefully in a visually appealing package.

See the Readme page for the most up-to-date instructions.

Syntax

The HERO ROLLER engine (a.k.a., HeRoll, HeRoller) is triggered by the api call to "heroll", and accepts a number of optional arguments after:

   !heroll [--{argAlias | argAlias:val}...]

The available arguments can be referenced by aliases, and they accept a given range of possible inputs. This information is contained in the HEROLL ARGUMENTS table.

HEROLL ARGUMENTS
	Aliases	Valid Options	Default	Flag Value	Notes
act	a act activation	[number]	(none)	--
dice	d dice	[value] [inline] [roll equation] check	1d6	--
dbody	db dbody doesbody	y yes n no t true f false	[template]	true	whether an attack should report BODY damage; also whether a Points-output should derive points from BODY
dkb	dkb dknockback doesknockback	y yes n no t true f false	[template]	true
dstun	ds dstun doesstun	y yes n no t true f false	[template]	true	whether an attack should report STUN damage; also whether a Points-output should derive points from STUN (default)
extradice	xd xdice extradice	[number]	0	--
kbdicemod	xkb extrakb kbdice kbdicemod	[number]	0	--
loc	l loc location	any random none [hit location] [special shot]	none	--
mechanic	rm rollmech rollmechanic m mech mechanic	n k l u	[template]	--	This can be set in any of three places; see the Mechanic section in the Readme.
outputformat	of output format outputformat sc	tall sc	tall	sc
pointslabel	pl plbl plabel ptsl ptslbl ptslabel pointsl pointslbl pointslabel	[string]	[template]	--
powername	pn pname powername	[string]	[template]	--
primarycolor	c col color pc primarycolor	[3- or 6-digit hex, with or without #]	[template]	--
stunmod	xs xstun extrastun stunmod	[number]	0	--
template	p pwr pow power t tmp template	[see table below]	c	--
useomcv	mental um omcv useomcv	y yes n no t true f false	false	true
ocv	o ocv	[number]	(none)	--	supply an OCV to override any checking of a character sheet (including when you don't have a character sheet). This flattens all OCV mods to 0 including any originating from a called-shot. Including the location argument will still invoke BODY and STUN multipliers.
verbose	v verbose	y yes n no t true f false	false	true
recall	r rc recall	last [valid id]	[current]	[current]

Understanding the Table

Use the following guidelines for interpreting the table, above.

[bracketed text] presents a set of options you can choose from. For example, [number] requires you to enter a valid number.

plain text represents a static option that could be invoked typing it exactly as it appears. For instance, tall could be used exactly as the value portion of the argument pair --of:tall.

(parenthetical text) represents information for you, but which you cannot change. For instance, (none) could inform you that there is no default for a given argument.

FLAG VALUE represents the value invoked if an alias of that argument is used as a flag, i.e., without the : or a value portion. For instance, --of:sc is functionally the same as --sc, producing a sidecar-formatted output. (Note: sc is not only an alias of the outputformat argument, it is also a valid value for the argument (sc). We are NOT using the value in place of the argument to invoke the flag; we are instead using another alias of the argument, in this case one that reads perhaps more intuitively ("sidecar"). Consider the full equality: --of:sc is the same as --sc:sc is the same as --sc.

Script Use

For a more thorough discussion of the ways to use the HeRoll engine, see the README file (you will need markdown reader; there are extensions that will let you open these in Chrome, for instance). Here are some example implementations from the Readme:

The following implements a 4d6 flash named Cosmic Flare, with notes describing mechanics, and designates a blue color:

!heroll --d:4d6 --t:f --a:14 --pn:Cosmic Flare --n:flash to common sight, AoE (16m) Non-Selective --c:4b688b

Here is a similar implementation except using the *check* value to not output the results bar. This one also references an attribute called "color1" where the color for the panel is stored (for easy color coding or changing at a later date):

    !heroll --d:check --pn:Way of the Mountain --n:does 9m of shove --t:ha --col:@{Heretic|Color1}

The next utilizes the xd (extradice) argument to read the velocity from the character's sheet and feed that as a modifier to a martial throw. It sends the output as the sidecar format:

    !heroll --d:6.5d6 --t:ha --pn:Way of the Wind --n:throw, target falls --sc --xd:[[@{Heretic|velocity}/10]] --col:@{Heretic|color1}

Another example using the ''check'' value to validate that the character created a wall of given size:
<pre style="overflow:auto;">
    !heroll  --p:pts --pn:Wall of Light --d:check --of:tall --pl:Wall of Light --n:8 PD, 8 ED, 6m long, 4m tall, .5m thick, dismiss, choose either not anchored or mobile --c:@{Prism|pwrcol}

The next example demonstrates a power the player can choose to "push" by a given amount. The player is asked for input, and the result is fed into the xd argument:

    !heroll  --p:b --pn:Light Stix --d:10d6 --of:TALL --c:@{Duo|pwrcol} --xd:[[?{Supercharge Points|30}/10]] --n:4m radius select attack, no range, IIF vs PD