Notes and instructions (sort of) about the HERO combat system scripts for Roll20

instructions

HERO combat system scripts for Roll20


There are 5 scripts in total: heroturntracker2.0, autocombat, effects, recovery, locations.

The first manages the turn tracker, subdividing the turns into phases in which it shows only the tokens acting during those phases depending on their SPD attribute. It supports delayed actions (by putting a "d" in place of the Dex of the token). It also keeps track of status like stunned, deeply stunned, bleeding, movement, actions, etc.

The second manages the weapon and their effects (or spells that damage the opponent). It can be used for modern weapons and for fantasy ones. Any spell that does damage can be
emulated by this script.

The third takes care of effects that can take place every segment/phase/turn/minute/hour/day. Of course I consider only up to minutes (any number) during combat. These effects can be anything: damage from starvation, from low/high temperature, from a blast, from poison, etc. It manages also effects like Drain, Aid, Regeneration or Entangle.

The fourth has the recovery function and parses some other commands, the fifth is used to create the locations rollable table (more about it below).

First of all, in order for the scripts to work, you need to have a couple of tokens in any of your pages where the combat will take place, called XPin and combathelper, respectively. They are needed by the scripts. XPin is a classic pin image that I use to track the position of the tokens when they move (since I allow the players to see where they started their movement. It is needed because the script will tell a player when he/she is moving more than half their RUN value, so it is much easier if they can see their original position in order to adjust their movement). It will be hidden by the script once the combat starts or ends. The second is needed as a helper for the GM. The red bar can be used to put a modifier in it, that will be applied to the OCV of the acting token (if you DON'T want that particular player to hit the monster boss, you put a neat -10 in it ;). The green bar is used to aim. When a player states that he/she wants to aim a specific part of the target, you just put the corresponding number in the green box of the combathelper token before the player attacks.

Secondly, all the tokens involved in combat must have a character journal associated. These journals must have all the HERO attributes (in no specific order), PLUS these three: 

tempOCV, tempDCV, tempRange. They are used for the martial aneuver bonuses/maluses, if any.
Moreover, all the attributes must have their max set to the same value than the current value. This is because a lot of calculations are made, and also because AID and Drain effects need to know the max value. Use a script to generate the character journals and it won't be a pain anymore.

Lastly (and this is the part that it is a bit of a pain), you have to create a rollable table containing the hit locations for the HERO System.
Use the !tableinsert script to automatically create a rollable table called “locs” (it has to be named like that) with 10 locations and the right weights for each of them. Unfortunately the links are for my images on my account, you will have to insert the 10 images by hand.
Here you can find a rar with the images I used, but you can use any image you like:

https://drive.google.com/folderview?id=0ByaA8fUc1mzKXzRfOXJzY2t3Qnc&usp=sharing

Once you have inserted them into the corresponding locations in the rollable table just created, you have to use the command !tableread. This command will dump into the API output console YOUR “locs” rollable table contents, including YOUR correct links to the images inserted. Copy these lines and replace the ones around line 1170 in autocombat.js with them, removing the brackets before and after each line of course.

Once you have done all of that, it ~should~ work. Mind that it is a work in progress (I could write it in my spare time during the last 4 weeks), with badly written code, full of bugs, barren of error-trapping. It doesn't use the state object (yet), so if if throws an exception, you have to start the combat again. I started writing a 150-lines script that just managed the turnorder in a more HERO-like way, and kept adding and adding without much of a plan or analysis. The only part which I sat and designed a bit about was the effects script (and you can see it is neater than the rest). I am playing two campaigns at the moment, and it all works for us (with some glitches here and there as we are basically testing it while playing). That said, it can be a real pain if something goes wrong. To finish with, I used a lot of variables declared globally (outside any function). Chances are that some of the names I have used for them coincide with other variables used in some of your scripts. In this case you will have further problems of course. You are warned: use it at your own risk.

To start combat, type !combatstart.
To advance a phase, type !nextphase
To end combat, type !combatend

And remember that in order for a token to be able to act, it has to be selected in the Turn Tracker.

WEAPONS/DAMAGING SPELLS

All combat actions are driven by a macro (that the players can copy-paste from a common journal entry and modify with the name of their weapons). The macro get some data (attacker name, defender name, last-minute optional attack modifier). It is:

!heroHit WEAPONNAME;@{selected|token_name};@{target|token_name};?{other modifiers to hit|0}

If you need to make the player manually input the distance to his target, just  add ";?{distance to target|0}" at the end of it. The system computes automatically the distance between the 2 tokens, but in some scenarios it could be needed to input an arbitrary value.

For weapons that can autofire, add “;shots?{shots fired|1}” at the end of it.

Be careful, as the order of the first 3 parameters is important (WEAPONNAME;@{selected|token_name};@{target|token_name})!

Ok, once players have made their own macroes they need only to change "WEAPONNAME" to their actual weapon names. They can be anything, but the simpler the better. In my Campaign, they usually have names like "sword", "bow", "pistol", "holysword", and so on.
The name they input in the macro will be the name the GM MUST USE in the weapon string of their token. Every single player cannot have duplicate weapon names, of course.

Example: Player Mark, controlling the token named John, copy-pastes the macro above creating his own macro, and changes "WEAPONNAME" to "sword". You have to put the corresponding weapon string in token John's gmnotes and call it "sword", like this:

{sword}2|efftype:p|damtype:k|currammo100|maxammo100|end3|norange|str13|wo1{/sword}

The name in parenthesis is the name that the macro will look for (that's why it has to be the very same than the one in the macro). There are some minimum parameters in case of a weapon (or a spell that deals damage): dice of damage, efftype and damtype. The others are optional. Only the dice of damage has to be always present and the first parameter of the string, everything else can be in any order.

The values in the example string above are:

2 = 2 dice of damage
efftype:p = physical damage
damtype:k = killing damage
currammo100 = OPTIONAL - current durability for melee weapons/current ammo for ranged ones
maxammo100 = OPTIONAL - max durability for melee weapons/max ammo for ranged ones
end3 = OPTIONAL - the END cost to use the weapon (you have to compute it depending on the 	 min STR or the active points of the spell)
norange = OPTIONAL - a melee weapon
str13 = OPTIONAL - 13 STR minimum weapon
wo1 = OPTIONAL - +1 OCV from weapon

For other parameters, have a look at the comments in autocombat.js

Similarly, a firebolt spell dealing normal damage would be like this:

{firebolt}6|efftype:e|damtype:n|end3{/firebolt}

For a 6d6 normal energy damage firebolt that costs 3 End to cast. 

OTHER MODIFIERS

you can put some other strings in the attacker and/or defender gmnotes. These can be:

For the Attacker (example):   {mods}ocv2{/mods} or {mods}omcv2{/mods}
where the number 2 is the value that will be applied to every attack until you remove the string entirely

Defender (example): {mods}dcv2{/mods} or some others (have a look at the comments in the autocombat script.

{nostun} - target doesn't take STUN damage;
{nobleed} - Target doesn't bleed;
{damagereduction}{/damagereduction} – read the description in the autocombat script
{nohitlocs} - Target always takes BODYx1 and STUNx3 in case of Killing damage, and no multipliers in case of Normal damage

Once a weapon reaches half its maximum durability, a message is sent to the player – the weapon lost one damage class. The weapon string is automatically changed by the script, reducing its damage, and adding a “DEGn” at the end of the string, with n representing the original damage of the weapon. You have to manually change it in order to restore the original value (once a weaponsmith repaired it, maybe?)

ARMOR

Armor is simply a string into a token's gmnotes. It has to be like this:

{armor}head/10/10/|6|6#hand/10/10/|6|6#arm/10/10/|6|6#shoulder/10/10/|6|6#chest/10/10/|6|6#abdomen/10/10/|6|6#vitals/10/10/|6|6#thigh/10/10/|6|6#leg/10/10/|4|4#foot/10/10/|4|4{/armor}

Let's examine it in detail:

head  = the name of the location
/10/10/  = the durability (current/max) of the armor part
|6|6    = the PD and ED of (resistant) protection that the part grants.

If you omit the durability part (i.e. head|6|6) means that part of the armor is indestructible.

EFFECTS

Effects are applied mainly by tokens using a weapon macro like this:

{paralysis}0|spellroll-4|end3|los|psi{/paralysis}
This is an entangle based on EGO, but the string above is just the "weapon" part, or the part that manages the to-hit roll (and in this case the spell roll).
Any weapon  that has "0" as the first value (the number of dice of damage) is interpreted by the scripts as a special spell (a spell that applies some effects - not direct damage).
"spellroll-4" means that the spell has a spell roll to be done in order to cast it, and
 there is a modifier of -4 to the roll (because of 40 active points of spell). "end3" is the END cost, "los" means line of sight (no range modifiers), and "psi" means that OMCV is used instead of OCV.
Note that in case of a spell roll, the character must have an ability named "spellroll" containing the value of his spell skill. I.e. a character with a skill of 18- would have 18 in the content of the ability named "spellroll".

A drain would be basically the same, maybe without the "psi" and "los" bits, and with possibly different "spellroll" and end "values".

Now, for the Effects another string is needed, this time in the character's abilities. It must have the same  name than the "weapon" name, but between square parenthesis. In the example above, it would be:

[paralysis]

Its content would be:

{effect}ent:2d|ego|hasdef:no|freq:p|duration:5m|counter:0|on|desc:Paralysis|fishing-net|def2{/effect}

An Entangle is a special case of the Effects. Please read the comments in the effects script.

ent:2d = entangle, 2 dice
ego = attribute used to break free
hasdef:no = no defence applies
freq:p = frequency of effect: phase. For entangles it has to be phase, so the token affected will try to 	  break free every phase in which it is acting
duration:5m = 5 minutes duration before the spell goes off by its own
counter:0 = it is needed by the script, it must start at 0
on = means that the spell is active, used to stop the spells or suspend them
desc:Paralysis = description used in the messages
fishing-net = status activated on target when the Effect lands
def2 = argument needed for the Entangle, it is the defence of the entangle (pd/ed) applied against the checks done by the victim

A drain would be like this:
{effect}dam:8f|dex/spd|hasdef:no|freq:o|duration:5m|counter:0|on|desc:Befuddle|snail{/effect}

This spell removes 8 points (the "f" means fixed - no dice are thrown) of DEX and 8 points of SPD. This fixed value will be divided by the cost of the Attribute, though (so the SPD drained will be 0.8).
freq:o = frequency: once. This must be used for Drains/AID.
duration:5m = for Drain/AID this is the interval after which a recovery/loss is triggered (usually 5 points).
An Effect like being inside a volcano that damages everybody every turn would be like this:
{effect}dam:2d|normal|hasdef:ed|freq:t|duration:1d|counter:0|on|desc:Fire|nostatus{/effect}
This means that 2 dice of normal damage will
 be applied to the token every turn. Token's ED can be applied against this damage. duration:1d means 1 day. It is really high so it will reasonably last until the players move their tokens out of the place.

BE CAREFUL: the effect string MUST have the first 9 parameters in that particular order (so up to the status icon to use included), and they are ALL needed for the effect to work!

Since the effects are written automatically in the token's gmnotes AND in the array used by the scripts during combat, in order to cancel a spell you need to use another command:

!updateeffect;effectid;action 

Another macro here is handy:

!updateeffect;?{Effect ID|0};?{Action (delete/off)|delete}

Select the token with the effect first, look into the gmnotes the id of the effect (the first number after {effect}) that you want to stop, then click on the macro, and it will ask whether you want to put it off or delete it.
The difference is that some spells are "sustained", meaning that at the end of the duration the caster consumes the end specified with the "end" optional argument. If the caster doesn't want to keep the spell on AFTER the current duration, it must be set to "off". Otherwise, if you want to cancel a spell, it needs to be deleted, with the command "delete".

Since the Effects are loaded at the beginning of the combat, in case you need to manually insert a custom effect "on the fly", use this macro:

!inserteffect;?{damage or aid (dam/aid/ent)|dam}:?{value of effect|1}?{dice or fixed (d / f)|d}|?{type of damage|normal}|hasdef:?{defense applies|no}|freq:?{frequency (o=once, s=segment, p=phase, t=turn, m=minute, h=hour, d=day, w=week)|t}|duration:?{duration (n[p,t,m,h,d])|1t}|counter:0|on|desc:?{description|}|?{marker|nostatus}

It will write the effect into the gmnotes of the selected token and apply it (if already in combat).

So, to recap:

Basically the macro that the players have to use for each of their weapon/spell takes care of the parameters needed by the To-Hit-Roll.

The weapon/spell string in their token's gmnotes contains the details of their weapon/spell.

In case of a special spell (a non-directly damaging one), another string is needed, think of it as a spell formula, and has to be in character's journal abilities. This contains the details of the spell.

So:
Macro → gmnotes' string (weapon or spell)  → (optional) special spell in abilities

Armors and other special modifiers are always strings in tokens' gmnotes.

NOTES:

The scripts take care of a lot of variables, and use some status icons to represent different situations in combat. They are:

status_red

Bleeding. Every body wound in HERO causes bleeding. The script will take care of it, at the end of phase 12. If the bleeding stops, the icon is removed.

status_archery-target

Once a token has acted, this icon shows up. It cannot act again unless the icon is removed (it is automatically removed once its following action phase comes up).

status_sleepy

Stunned. When a token gets more than its CON in Stun with a single blow, it is stunned and can only recover during the following phase. Since it could have not moved yet (hence it could recover straight away), and because there can be a number of other reasons it wouldn't be wise, there is no automatic removal of the status. The GM can use the command !recovery (after having selected the token) to apply its Rec in recovery (End and Stun) and remove the status automatically (usually when the player says he/she is recovering and he/she is allowed to do that).

status_pummeled

When a token is between 0 and -10 stun it's deeply stunned, and will automatically recover its first available phase. It is automatically taken care of by the system.

status_dead

When a token's Stun goes below -10 or Body goes below 0. The recovery actions (when allowed), can get it out of this state automatically only if the Body value is >= 0, otherwise some form of healing is needed.

status_fishing-net

The token is entangled. It cannot act. It is automatically removed when it manages to break free (automatically managed by the scripts). For entangle spells, the fishing-net marker MUST be used.

status_interdiction

When a token moved more than half its Run attribute during a phase, it cannot attack or do any other combat maneuver.
status_half-heart

Impaired. When a token gets half or more of its total body (before or after the modifiers) in a single attack, that location is “impaired”. The exact effects have to be applied manually.

status_broken-heart

Disabled. When a token gets all of his body (or more) of damage from a single attack, that location is “disabled”. The exact effects have to be applied manually.

status_spanner

Out of ammo. Bow or rifle, when the weapon consumes all of its ammo, this marker shows up and doesn't allow the token to attack until it is removed (even if the player wants to use another weapon, the marker has to be removed manually by the GM or the system won't allow it – in case the player tries to use again an “empty” weapon, the marker is up again automatically).
This also happens for weapons without ammo but with durability. When it reaches 0 the weapon breaks and the spanner marker pops up.