Character Vault
Any Concept / Any System
Compendium
Your System Come To Life
Roll20 for Android
Streamlined for your Tablet
Roll20 for iPad
Streamlined for your Tablet

Personal tools

Script:HeroRoller

From Roll20 Wiki

Jump to: navigation, search

HeroRoller

Hero Roller (or, heroll, for short), is an API to be used for GitHubLogo.png or GitHubLogo.png Roll20 character sheet, for the games with the same name.


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.

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

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

Contents

Installation and Configuration

Install from drop-down menu, or Copy the script's code from GitHubLogo.png. Paste the code into a new script in your campaign's API Script Editor. Save the new script and it will be available inside your campaign.

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

Changelog

v1.2 (2020-06-21)

  • Implemented --target and --selective arguments. PR

v1.0 (2020-06-12)

  • Release