Difference between revisions of "Script:HeroRoller"
From Roll20 Wiki
Andreas J. (Talk | contribs) m (add category) |
Andreas J. (Talk | contribs) 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 | + | 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 | |
| + | </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 | ||
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
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", 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.
Contents |
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.
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.
| 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 textrepresents a static option that could be invoked typing it exactly as it appears. For instance,tallcould 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 VALUErepresents 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:scis 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:scis the same as--sc:scis 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 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
--targetand--selectivearguments. PR
v1.0 (2020-06-12)
- Release
