Using Macros

HM3 for Foundry VTT has rich support for extensibility via macros. Macros are available for individual skills, psionics, spells, and ritual invocations. You may specify a macro for the character or creature which will be called whenever certain sorts of rolls, such as shock rolls, occur. These are perfect for when you have a specific action you want to occur for a particular item or character.

In addition, you can create "Hook Macros", which are macros that are not specific to a given character or item, but that get called whenever any character or item performs that type of roll. Hook Macros allow you to create global actions that occur whenever a given type of roll (e.g., a Shock Roll) occurs without having to enter that macro into each character or item.

See Example Macros for some examples of useful macros.

The rollResult object

Whenever there is a dice roll, the results of that dice roll are available via the "rollResult" object. The format of this object is:

Element	Description
type	Roll type (see below)
title	Human readable title for the roll
origTarget	The original target value for success (before modifier)
modifier	The modifier (if any) to the dice roll
modifiedTarget	The target value after modifiers applied
rollValue	The total value that was rolled
isCritical	Indicates whether the roll was a critical
isSuccess	Indicates whether the roll succeeded
result	CS (Critical Success), MS (Moderate Success), MF (Moderate Failure), CF (Critical Failure)
description	A textual description of the result
notes	The rendered notes string after all variables have been evaluated

Advanced Macros

While it is possible to do simple actions without detailed knowledge of Foundry VTT, most significant macros require some understanding of the methods and data structures available via Foundry VTT. For this, it is recommended you review the Foundry VTT API.

In particular, the following are helpful:

• Actor class
• Item class
• ChatMessage class
• Dialog class - In particular, Dialog.prompt() and Dialog.confirm() are very useful
• actor.type provides the type of actor (character, creature, or container)
• actor.name provides the name of the actor
• actor.data.data contains all of the data associated with the actor, such as ability scores and everything located in the data model from template.json
• item.type provides the type of item (skill, spell, invocation, psionic, weapongear, containergear, missilegear, armorgear, miscgear, injury, armorlocation, trait)
• item.name provides the name of the item
• item.data.data contains all of the data associated with the item, such as effectiveMasteryLevel and other fields

Going into the details of how to write macros is beyond the scope of this page, but you can find more assistance in writing macros on the Foundry VTT discord.

Macro Types

There are three basic types of macros:

• Item Macros - These are macros specific to a particular skill, spell, psionic talent, or ritual invocation, and activate when a roll is made.
• Actor Macro - This macro is run whenever a Stumble Roll, Fumble Roll, or Shock Roll occurs on the character or creature where the macro is placed.
• Hook Macros - These macros are run when a particular type of event occurs, such as a Shock Roll (regardless of which character actually performs the roll). These are useful as "generic" macros for actions you want to occur the same way across all characters or creatures.

Item Macros

Each skill, psionic talent, spell, and ritual invocation has a "Macro" tab in its detail page. This tab allows you to enter in a macro that will be run when that item is clicked (e.g., a Skill Roll, or a Spell Roll). Each macro will have access to a number of variables:

Variable	Description
rollResult	A "rollResult" object (see above)
item	The item that the roll was made for
actor	The actor the item belongs to
token	If the actor is a token on the canvas, this will be non-null
speaker	The "speaker" object (used for sending chat messages)
character	The controlled character

Actor Macros

Each actor has a "Macro" tab. This tab allows you to enter in a macro that will be run when any of a variety of rolls are made; specifically, Shock Roll, Stumble Roll, or Fumble Roll.

Variable	Description
rollResult	A "rollResult" object (see above)
actor	The actor the roll is happening on
token	If the actor is a token on the canvas, this will be non-null
speaker	The "speaker" object (used for sending chat messages)
character	The controlled character

Post-roll Hook Macros

Hook macros allow you to specify actions that occur when a particular type of roll occurs, regardless of which actor or item it takes place on.

In order to create a hook macro, create a new macro with the exact name of the hook. The hooks available and the resulting variables are shown below.

All hook macros include the following variables:

Variable	Description
rollResult	A "rollResult" object (see above)
rollData	"Roll Data": The information passed to the roll before the roll was performed
actor	The actor the roll is happening on
token	If the actor is a token on the canvas, this will be non-null
speaker	The "speaker" object (used for sending chat messages)
character	The controlled character

In addition, some hook macros include an item variable referencing the item associated with the roll.

Hook	Additional information
hm3.onSkillRoll	includes item
hm3.onSpellRoll	includes item
hm3.onInvocationRoll	includes item
hm3.onPsionicsRoll	includes item
hm3.onAbilityRollD6
hm3.onAbilityRollD100
hm3.onDamageRoll
hm3.onMissileDamageRoll
hm3.onWeaponAttackRoll	includes item
hm3.onWeaponDefendRoll	includes item
hm3.onMissileAttackRoll	includes item
hm3.onInjuryRoll
hm3.onHealingRoll	includes item
hm3.onDodgeRoll
hm3.onShockRoll
hm3.onStumbleRoll
hm3.onFumbleRoll
hm3.onDamageRoll

Functions

A number of system capabilities are available as functions so you can automate your use of this system with script macros. All of these macro functions are avaialable via game.hm3.macros.<function>. The following macros are defined:

Function	Description
skillRoll(itemName, noDialog)	roll against skill EML
castSpellRoll(itemName, noDialog)	spell casting roll against spell EML
invokeRitualRoll(itemName, noDialog)	ritual invocation roll against invocation EML
usePsionicRoll(itemName, noDialog)	psionic talent roll against talent EML
testAbilityD6Roll(abilityName, noDialog)	3d6 roll against a specific ability
testAbilityD100Roll(ability, noDialog)	1d100 roll against a specific ability
weaponDamageRoll(itemName)	damage roll, using attributes from a particular melee weapon
missileDamageRoll(itemName)	damage roll, using attributes from a particular missile weapon
weaponAttackRoll(itemName, noDialog)	weapon attack roll, using attributes from a particular melee weapon
weaponDefendRoll(itemName, noDialog)	weapon defend roll, using attributes from a particular melee weapon
missileAttackRoll(itemName)	missile attack roll, using attributes froma particular missile weapon
injuryRoll()	injury roll
healingRoll(itemName, noDialog)	healing roll for the specific injury specified
dodgeRoll(noDialog)	dodge roll
shockRoll(noDialog)	shock roll
stumbleRoll(noDialog)	stumble roll
fumbleRoll(noDialog)	fumble roll
genericDamageRoll()	damage roll not specific to any weapon (you must enter details of the attack)
changeMissileQuanity(missileName, newQty)	Change missile quantity: +XX to increase, -XX to decrease, XX to change to exact value
changeFatigue(newValue)	Change fatigue value: +XX to increase, -XX to decrease, XX to change to exact value
setSkillDevelopmentFlag(skillName)	Set the flag for a Skill Development Roll (only set, not unset)
weaponAttack(weaponName)	Initiate melee attack from current combatant against selected token with weapon
missileAttack(missileName)	Initiate missile attack from current combatant against selected token with missile
weaponAttackResume(atkTokenId, defTokenId, action, attackAML, attackAim, attackWpnAspect, attackImpactModification)	Continue attack with defender. "action" can be one of "dodge", "block", "counterstrike", or "ignore".

itemName = name (or id) of the item to affect

noDialog = [optional] flag whether or not to display dialog; if noDialog is true, all defaults will be used. Note that not all rolls support this, because some require input to operate.