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

Difference between revisions of "Script:HeroRoller"

From Roll20 Wiki

Jump to: navigation, search
m (add category)
m (added general desc, direct link to README)
 
Line 1: Line 1:
== Installation and Configuration ==
+
{{script overview
 +
|name=HeroRoller
 +
|author=[[Timmaugh]]
 +
|version=1.2
 +
|lastmodified=2020-06-21}}
 +
==HeroRoller==
 +
'''Hero Roller''' (or, '''heroll''', for short), is an [[API]] to be used for "Hero System 6e", 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 '''{{repo|Roll20/roll20-api-scripts/tree/master/HeroRoller Readme page}}''' for the most up-to-date instructions.
 +
 
 +
__TOC__
 +
=== Installation and Configuration ===
 
Copy the script's code, stored at Roll20's [https://github.com/Roll20/roll20-api-scripts/tree/master/HeroRoller API GitHub Repository]. Paste the code into a new script in your campaign's [[API:Use_Guide#The_Script_Editor|API Script Editor]]. Save the new script and it will be available inside your campaign.
 
Copy the script's code, stored at Roll20's [https://github.com/Roll20/roll20-api-scripts/tree/master/HeroRoller API GitHub Repository]. Paste the code into a new script in your campaign's [[API:Use_Guide#The_Script_Editor|API Script Editor]]. Save the new script and it will be available inside your campaign.
 +
 
== Syntax ==
 
== 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:
 
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:
Line 84: Line 99:
 
   
 
   
 
* <code>'''FLAG VALUE'''</code> represents the value invoked if an alias of that argument is used as a flag, i.e., without the <code>:</code> or a value portion. For instance, <code>--of:sc</code> is functionally the same as <code>--sc</code>, 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: <code>--of:sc</code> is the same as <code>--sc:sc</code> is the same as <code>--sc</code>.
 
* <code>'''FLAG VALUE'''</code> represents the value invoked if an alias of that argument is used as a flag, i.e., without the <code>:</code> or a value portion. For instance, <code>--of:sc</code> is functionally the same as <code>--sc</code>, 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: <code>--of:sc</code> is the same as <code>--sc:sc</code> is the same as <code>--sc</code>.
 +
 
== Script Use ==
 
== Script Use ==
For a more thorough discussion of the ways to use the HeRoll engine, see the README file stored with the script on the [https://github.com/Roll20/roll20-api-scripts API GitHub Repository] (you will need markdown reader; there are extensions that will let let you open these in Chrome, for instance). Here are some example implementations from the readme:
+
For a more thorough discussion of the ways to use the HeRoll engine, see the {{repo|Roll20/roll20-api-scripts/tree/master/HeroRoller README file}} (you will need markdown reader; there are extensions that will let 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:
 
The following implements a 4d6 flash named Cosmic Flare, with notes describing mechanics, and designates a blue color:
 
+
<pre style="overflow:auto;">
    !heroll --d:4d6 --t:f --a:14 --pn:Cosmic Flare --n:flash to common sight, AoE (16m) Non-Selective --c:4b688b
+
!heroll --d:4d6 --t:f --a:14 --pn:Cosmic Flare --n:flash to common sight, AoE (16m) Non-Selective --c:4b688b
 +
</pre>
  
 
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):
 
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):
 
+
<pre style="overflow:auto;">
 
     !heroll --d:check --pn:Way of the Mountain --n:does 9m of shove --t:ha --col:@{Heretic|Color1}
 
     !heroll --d:check --pn:Way of the Mountain --n:does 9m of shove --t:ha --col:@{Heretic|Color1}
 
+
</pre>
 
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:
 
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:
 
+
<pre style="overflow:auto;">
 
     !heroll --d:6.5d6 --t:ha --pn:Way of the Wind --n:throw, target falls --sc --xd:[[@{Heretic|velocity}/10]] --col:@{Heretic|color1}
 
     !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:
 
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}
 
     !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}
 
+
</pre>
 
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:   
 
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:   
 
+
<pre style="overflow:auto;">
 
     !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
 
     !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
 +
</pre>
 
== Changelog ==
 
== Changelog ==
 +
'''v1.2 (2020-06-21)'''
 +
* Implemented <code>--target</code> and <code>--selective</code> arguments. {{repo|Roll20/roll20-api-scripts/pull/1013 PR}}
 +
 
'''v1.0 (2020-06-12)'''
 
'''v1.0 (2020-06-12)'''
 
* Release
 
* Release

Latest revision as of 19:53, 18 February 2021

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

[edit] HeroRoller

Hero Roller (or, heroll, for short), is an API to be used for "Hero System 6e", 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 GitHubLogo.png for the most up-to-date instructions.

Contents

[edit] Installation and Configuration

Copy the script's code, stored at Roll20's API GitHub Repository. 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.

[edit] 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]

[edit] 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.

[edit] Script Use

For a more thorough discussion of the ways to use the HeRoll engine, see the GitHubLogo.png (you will need markdown reader; there are extensions that will let 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

[edit] Changelog

v1.2 (2020-06-21)

  • Implemented --target and --selective arguments. GitHubLogo.png

v1.0 (2020-06-12)

  • Release