search

tposney / midi-qol

Other
5 stars 0 forks source link

readme

This is not the actual midi-qol repository.

It has been setup for me to test migrating from gitlab to github but is not up to date

Please go to https://giblab.com/tposney/midi-qol to report issues

Breaking News

Addehttps://gitlab.com/tposney/midi-qol/d a ko-fi donation link https://ko-fi.com/tposney

Custom Sounds rewritten

You will have to change your configuration

Midi-qol is a module designed to help automate various parts of your game, specifically rolling attacks/casting spells and applying damage/effects.

It has LOTS of configuration options which can be daunting.

Bug reports

Important When submitting a bug report ALWAYS include your exported (from the misc tab) midi-qol settings. I really can't work out what is going on without them.

The export settings exports all of your midi-qol settings, plus a list of the active modules you have installed. No world information is exported. The list of active modules can be very useful to me in debugging.

midi-qol

Midi-qol is a replacement for minor-qol and you should not have both modules active at the same time. (Both can be INSTALLED at the same time, but only one should be ACTIVATED.) Because there are some subtle differences in the way the midi-qol works compared to minor-qol you will need to experiment with the settings.

HELP! My midi-qol disappeared.

If you've just updated midi-qol and it disappears from your in-game list of modules you probably need to update your dnd5e system to the latest one.

I just upgraded and nothing works anymore.

I've seen a couple of cases where after migration of foundry versions the per player setting "enable workflow automation" gets set to off. This flag being unset causes midi to do nothing with rolls (hence the nothing works). Also note that this is a per player setting, so each user needs to make sure it is on.

Midi works for some players and not for others....

Same problem as above - check workflow automation is enabled on all clients. You can use the module SocketSettings to force set the setting on all clients.

Items I bring in from the sample compendium don't work.

Some of the items require creating a DamageBonusMacro, make sure that is enabled in the midi settings. Also, if the damage bonus macro effect runs an ItemMacro.ItemName, the name of the feature needs to match the name of the item macro being run. For example Rage MQ0.8.9, will have to be renamed Rage when equipped on a character or the damage bonus macro won't run. I know this is not ideal, but I wanted to make clear when the version of the items changed.

How do I write macros for this module?

Have a look at Notes for Macro writers which I try to update if new things occur. I've included some examples and if I do something I think is maybe useful, will add it to this section going forwards.

I have a macro that works and just want to call it when using an item.

If you have a standalone macro, or one from (say) the community macros collection that you want to call when using an item, create an item and set it's onUse macro to the macro's name and set the pass to preamble complete.

If you want to get fancier then change the point at which it is called and have a look at the data passed to onUse macros. Or use a macro.execute (some changes may be required) which is only called if active effects are applied to the target.

MidiQOL sample items compendium

midi-qol is an automation tool that is meant to make it possible to automate some/many facets of your game. It is not a library of items that you can plug and play into your game and many great macro modules that play well with midi-qol (too many for me to list and I'm sure I don't know them all).

Similarly there are some excellent tools for animation effects, beyond those supported directly by dae/midi. I don't know them all and I have no doubt that there are some gems that I simply have not discovered, but do use Automated Animations in my game as well as Token Magic FX.

midi-qol combined with DAE has lots of ways for you to implement items/spells/features you might want. Sometimes that will require writing macros, and sometimes not.

Over time I have come up with some items that I use in my game, which I think others might find useful, or which might have some interesting ideas for other to develop their own items. I have created a sample items compendium of these which you are free to use in any way you want. The warning is that whilst they work in my game, they may not in yours and there is no certification that they are fit for purpose. Feel free to try them and if they work for you great, if not make them better and share with the community - I am always happy to receive suggestions for inclusion. I try to add a version number to items to indicate the midi-qol version in which they were updated. You don't have to keep the version number in your game.

[TOC]

Changes in dnd5e 1.5:

Enhanced dnd5e critical damage effects.

You can make most of the changes that midi-qol supports for critical hits via the new game settings (max base dice, double modifiers as well as dice) and per weapon settings (additional dice). If you want to use the dnd5e critical damage fields set the midi-qol critical damage to "dnd5e default"

You will need to experiment to confirm the interaction of the dnd5e critical damage flags and the midi-qol settings, however if you use the dnd5e default setting in midi-qol the rolls will not be modified by midi in any way and the dnd5e system will operate.

Midi-qol supports exploding dice for critical hit dice if enabled.

Changelog

https://gitlab.com/tposney/midi-qol/-/blob/master/Changelog.md

Symbiotic Modules

I don't spend a lot of time examining all of the modules that are written (and there are hundreds) so it is almost certain that other modules can substitute for the Highly Recommended/Good to Have just as well. If your favorite module is not in the list, it probably means I just don't know about it, so don't take the absence of a module from this list as a negative - it simply reflects my ignorance.

Required Modules

You have to have these, period.

Almost Required

You can probably survive without these but midi pretty much assumes they are installed.

Highly Recommended

Good To Have

(In)Compatibilities?

As already mentioned I don't look at lots of modules, so there will be others that do/don't work with midi. As they come to my attention I'll try and update the list.

Dice So Nice

Midi generally works with dice so nice, but the interactions are more complicated with the merge card.

Let Me Roll That For You

Midi-qol can use Let Me Roll That For You for player/gm saving throws and is the preferred roller. There is a "feature" that LMRTFY returns the roll result to midi before the 3d dice have finished rolling, so you may see the saves display before the dice finish doing their thing.

Monks Token Bar

Midi-qol can use Monk's Token Bar to roll saves. Update adv/dis advantage for magic resistance/concentration now work with MTB.

Dfreds Quality of Life

Midi supports the foundry template targeting, DF Qol has support for rules as written template targeting behaviour. There is an option in midi's AoE auto target to use DF QoL's template targeting, which disables midi's internal template targeting. You should only enable one sort of template targeting since mid/df-qol will fight over who gets to do the targeting which will lead to confusing results.

As of version 1.6.0, DF QoL does not seem to have a wall blocking option, so if that is important you'll need to use midi's targeting or another module that supports both.

Convenient Effects

Midi supports the application of Convenient Effects spell/item effects (configuration setting - Apply Convenient Effects) and matches those by name. For example, if you cast the spell Bless midi will see if there is a convenient effect "Bless" and apply it to any targets that were hit by the spell.

If you have apply convenient effects set and use items from the with DAE effects, you will get a double up of the effect. You need to choose how you want the item to behave, if using convenient effects, delete the DAE effects. The double up problem is intentional, since you might wish to augment the Convenient Effect definition with your own extra effects on the item.

If you generally use hand crafted effects I suggest setting apply convenient effects to false and then enabling convenient effects on an item by item basis (using the setting below). If you generally use convenient effects you would disable the convenient effect for the items that you want to use from DAE hand crafted effects.

There is an additional check box available on the item sheet, for items that have corresponding convenient effects. The check box reverses the "apply convenient effects setting" for that item. If you have "auto apply convenient effect" set to true, the check box will disable the auto application for that one item. Similarly, if you have "auto apply convenient effect" set to false, the check box will enable the auto application for that one item.

levels

levelVolumeticTemplates

Furnace (deprecated for Foundry 0.8.x - Use Advanced Macros)

If you intend to make use of any of the macro features in midi-qol you will need to install the Advanced Macros module. As of 0.9.56 there is no dependency on advanced macros/furnace.

Better Rolls

If you are using Better Rolls (which is a great module), midi-qol takes over once the hit/damage card is placed by Better Rolls. This means that resource consumption, template placement, critical/fumble determination are all handled by Better Rolls before midi-qol kicks in. Midi-qol checks hits, saves, applies damage, and calls active effects. When using Better rolls flags.midi-qol should be applied. As of foundry v10/dnd5e 2.0.0 better rolls is no longer supported. At some point I will look at supporting Ready, Set, Roll (the better rolls successor).

Magic Items

(Thanks to @simone for his help) Midi-qol is mostly compatible with magic-items. The only issue is that spell templates for spells in a magic item are not auto-placed on casting. Once placed everything works as expected. Spells/features that can be rolled will work.
Items that create changes by being present in the characters inventory (i.e. passive/transfer effects) won't behave as expected since they are actually held in the characters inventory, this includes transfer active effects.

Mess

Midi-qol and Mess dnd5e effects are not compatible. Template effects and the other features of that excellent module should work. If you want Mess attack/damage cards don't use midi-qol.

Cozy player

Minor-qol was not compatible with cozy-player, with targets being lost before attack/damage rolls were made. I have done only limited testing but it seems that there are no problems with cozy-player and midi-qol.

Cautious GM

Midi-qol breaks the blind chats by hidden GM feature of cautious GM.

Chat Portraits

If using Chat Portraits, the changes made by midi-qol to the token/actor name in chat cards are overwritten/lost. Choose which sort of highlighting you want - only one will work. Otherwise, all seems to work.

Ez-Roller

The 'send to chat log' feature of ez-roller will disable combo cards in midi-qol.

Combat Utility Belt

CUB concentrator and midi-qol concentration automation are incompatible. Choose one or the other. If you want concentration to expire at the end of the spell you need to install times-up and use midi-qol concentration automation.

Maestro

Maestro looks for the attack roll chat card in the chat log to play its critical/attack/fumble sounds. If you are using the merge card then the attack roll card is never created and Maestro can't play its sounds. You can use the midi-qol custom sounds instead.

Item Macro

You can create itemMacro macros with this module and call them from midi's onUse/DamageBonus macro fields by adding ItemMacro (case-sensitive) in the macro field.

If you have installed itemmacro please make sure you disable the ItemMacro config settings:

Dnd5e-helpers

Midi-qol has configuration options (in the optional rules section) to incorporate the AC bonus calculated by dnd5e-helpers. There are two settings dnd5e-helpers which allows an attack if any of the 4 corners of the target are visible and dnd5e-helpers+AC which will include the AC bonus from armor when calculating a hit. The bonus AC on the target will be displayed in the to hit card.

Warpgate

Some items in the midi sample items compendium use warpgate and won't function otherwise. It is also a very useful module for handling creating tokens on the canvas

DDB Game Log.

DDG Game Log sends rolls from dnd beyond to foundry. If DDB Game Log is enabled in the optional settings section of midi, making an attack roll (or damage roll if there is no attack roll) will trigger a midi-qol workflow for the attack. Hits will be checked, saving throws asked for and damage applied as per the rest of the midi-qol settings, except that midi will wait for dnd beyond and will resolve when the dnd beyond roll is made.

You can run mixed games with some/all players/monsters on dnd beyond and some on foundry only. It's really up to you.

Things to keep in mind:

FVTTEncounterStats.

This module keeps very detailed stats about each encounter you run and is fully compatible with midi-qol. If keeping game stats is your thing it's worth a look. Much better and more informative than the midi inbuilt rollStats.

Minor Roll Enhancements.

Advantage Reminder for dnd5e

If you don't fast-forward rolls this does a good job of highlight the default advantage/disadvantage/critical status of a roll.
Reminders also lets you highlight when a saving throw might meet advantage which midi can't process (e.g. advantage on poison saves).
Thanks to @kaelad for highlighting a midi problem, as of 0.9.11 midi is compatible with Advantage Reminder for attack and damage rolls.

GM Paranoia

Midi-qol is not compatible with GM paranoia.

Short Guide to configuration settings

The heading says short, but it really isn't.

Workflow settings

If speed rolls are off, all of the ctrl/alt|meta/shift keys and roll behaviour are the same as in core. There is one additional feature: if you click on a damage button in chat, CTRL+ALT click will use the critical/normal hit status from the midi-qol roll data.

If speed rolls are enabled you need to assign the keys yourself. If you enable speed ability rolls as well, your key mappings will apply to ability check, save and skill rolls as well.

If you have speed item rolls enabled Caps-Lock behaves as if advantage & disadvantage are both pressed, which will invert the fast-forward automation setting for rolls.

If you assign a key multiple meanings the behaviour is going to be confusing at best.

Display

Targeting

Almost everywhere midi-qol uses the targeted tokens to apply hits/saves/damage not selected tokens. Targeted tokens have 4 arrows pointing at the token and selected tokens have a box around them.

Saving Throws

Saving Throw Multiplier You can ignore this section until you find spells/weapons that don't do what you'd expect. TL;DR: If you are just using standard items you can just leave things at the default and most saves will do 1/2 damage as you'd expect, monsters (like a giant spider) will (if Roll Other Damage is enabled) do base weapon damage and have a save applied to the bonus poison damage.

For those who have a lot of weapons set up with a save and want the default damage on save to be full damage (which is what a previous version enabled when search spell description was enabled) just edit the items and set the save to full damage on save (preferred) or set the default save multiplier to 1.

Hits

You can enable auto checking of hits. Fumbles automatically miss and criticals automatically hit. As GM you can mouse over the name of the hit target to highlight the token and click to select it. This is useful if you are not auto applying damage, since you can do all the damage application from the chat log, by clicking on the targets name, then clicking on the appropriate damage button.

Damage

You can configure how much resistance reduces damage or how much vulnerability increases damage. Defaults to the dnd setting of 0.5 and 2. These figures multiply the damage done of the appropriate type by the multiplier

Roll Other formula for rwak/mwak Roll Other formula for spells

Roll Other Damage has 3 options,

Most creature attacks with extra damage (poisonous bite) equate to the ifSave setting. Magic items that roll additional damage if a particular condition is true (slayer weapons) require the "activation" setting.

midi will evaluate the activation condition as an expression, providing, the actor, item and target actor's (@target) roll data. For example:

    target.details.type.value.includes("dragon")

will only roll if the target has a type of dragon.

The evaluation of conditions has changed, You do not need to put @ in front of fields, but still can. If the field is a a string then @ fields must be enclosed in quotes, i.e. "@target.details.type.value".includes("dragon").

Specifically midi will populate the expression data with:

An empty activation condition will evaluate as true. If you don't want a specific weapon to roll Other Damage set Activation Condition false.

You can add the above condition to the SRD slayer items to make the bonus damage automated based on target type.

If the weapon rolling the attack has ammunition AND the weapon does not have its own Other Roll defined, the Other activation condition, Other roll and saving throw from the ammunition will be used instead of the attacking weapon. (Arrow of Slaying).

There is a new weapon property "Crit Other Roll" which when set means that the "Other Damage" roll will be rolled as critical if the base roll is critical. Previously Other Damage would never roll critical damage. You can decide if your Arrow of Slaying can do critical damage or not.

Mark Wounded When damage falls below %. (Requires Convenient Effects) You can specify a percentage (0 disables) so that when the HP of a token falls below X% the Custom Convenient Effect wounded will be applied to the target. This is useful if you are not showing the HP status bar to players so they get some idea if a baddie is hurt or not. You must create the Wounded condition (Wounded is a localisable string so it may vary for you game).

If you are not using convenient effects you can set this up much more flexibly in Combat Utility Belt using Triggler.

Add defeated when HP === 0. The dnd5e defeated condition will automatically be added to the token if it's hp fall to 0.

Custom Sounds Complete rewrite as of v0.9.29

Existing custom sounds will be disabled.

Custom sounds apply to both merge and non-merge cards. Custom sounds Will play even with dice so nice active. The General Format is to specify a sound for

Custom Sound Settings

Other QOL settings

Optional Rules

Midi supports various optional rule settings that can be useful.

Requires LMRTFY and does not work with better rolls.

Settings for full auto mode:

If the above was discussion was all too tedious here are the settings I use.

midi-qol Alternate QuickStart Settings

contributed by dstein766 (aka OokOok on Foundry discord) Another collection of settings, designed to achieve these goals:

Workflow/Misc: CHECK (enable) the following OR select from the drop-down:

Some Features

Roll Statistics.

Concentration Checks

support for concentration automation. The is dependent on DAE being installed and of the right version and requires CUB concentration automation to be disabled. Midi will work with Convenient Effects, Combat Utility Belt or use its own effect for concentration.

Midi-qol will attempt to use Convenient Effects, then Combat Utility Belt, then an internal concentration effect (in that order) when applying and removing concentration.

Recently (Nov 2021) CUB supports its own system for removing concentration checks on failed saves so the two options midi/CUB are feature equivalent - just choose the one you prefer.

Magic Resistance

If the target token has the SRD feat "Magic Resistance" or a custom damage resistance trait equal to exactly magic-resistant the auto rolled saving throws against magic effects (item type spell) with be rolled with advantage. This is really intended for NPCs with magic resistance to have their auto rolled saving throws made with advantage.

Special Active Effect Expiry

Reactions

If the config settings for reaction checks is enabled midi will check a target that is hit by an attack for any items/features/spells that have an activation type of reaction and prompt the target if they want to use any of their reactions, which will then initiate a midi workflow for that item/feature/spell targeting the attacker (so hellish rebuke for example works).

Reaction spells must be prepared (if preparation is required for the spell) and you must have a spell slot of the appropriate level available for the spell to be included in the list of possible reactions.

There is an optional configuration on the optional tab to remove this restriction, if using some other mechanism to determine if a spell can be cast, e.g. spell points.

Instead of triggering on attacks reactions can trigger on damage application (e.g. hellish rebuke).

Midi supports 3 activation types, reaction (triggers if hit), reaction damage (triggers if damaged), reaction manual (midi will ignore this when prompting for reactions).

Items in the SRD have the activation type set to reaction for reaction spells/features, so you will need to edit them in your game.

If the item being used for the attack/or to cause damage has the flag (item.data.flags.midi-qol.noProvokeReaction set, it won't trigger reactions).

Reaction processing is much clearer when convenient effects is installed as there is a visual indicator when a reaction has been used.

Reaction processing REQUIRES some automation to be enabled.

Optional rule, Record Opportunity Attacks.

If an actor is not in combat attacks won't be recorded as reactions. The test for in combat covers all combats, not just the current combat.

To help macro writers creating reaction items, args[0] contains an additional field in args[0].workflowOptions which includes some data from the attack that triggered the reaction.

Item description text and saving throws

flags.midi-qol

Midi-qol supports a lot of flags values that alter how attacks/casts are rolled. They are supported by any modules that use item.rollI(), item.rollAttack(), item.rollDamage() or actor.useSpell() [the standard dnd5e rolls]. Usually you would apply these via active effects. Mostly they work with better rolls.

There is a handy spreadsheet that has a table of flags plus explanation thanks to (dstein766) https://docs.google.com/spreadsheets/d/1Vze_sJhhMwLZDj1IKI5w1pvfuynUO8wxE2j8AwNbnHE/edit?usp=sharing

As 0f 10.0.4 a number of flags have been enhanced to accept a condition expression as well as/instead of true/false. This allows you to model "the character has advantage on attacks against dragons" and so on. Details of the types have been added to the spreadsheet.

flags.midi-qol...... need to be set via CUSTOM or OVERRIDE. Core foundry behaviour (as of 0.8.something) ignores ADD if the target value is undefined. Flags are undefined until set, so add does not work.

Optional Bonus Effects

Optional flags cause a dialog to be raised when an opportunity to apply the effect comes up (i.e. the player is hit by an attack).

An optional attack bonus prompts the attacker after the attack roll is made, but before the attack is adjudicated, giving the attacker the option to modify the roll. Effects last for one application unless the count flag is set.

Values for the optional roll bonus flags include a dice expression (added to the roll), a number, reroll (rerolling the roll completely) reroll-max, reroll-min, reroll-kh (reroll with max dice, min dice, or reroll and keep the higher of the original/new roll) or success which changes the roll to 99 ensuring success.

Generally options.Name fields do not work with better rolls due to the way it creates rolls.

Enhanced traits.dr/di/dv

Spell Sculpting: flags.midi-qol.sculptSpell and flags.midi-qol.carefulSpell

If a spell caster with flags.midi-qol.sculptSpell set to 1, casts an area of effect (template or ranged) Evocation spell, any tokens targeted before casting the spell will always save against the spell and they take no damage from spells that would normally do 1/2 damage on a save. So if casting a fireball into an area with allies, target the allies before casting the spell and they will take no damage. If a spell caster with flags.midi-qol.carefulSpell set to 1, casts an area of effect (template or ranged) Evocation spell, any tokens targeted before casting the spell will always save against the spell and damage as if they had saved (no matter what they roll).

flags.midi-qol.OverTime (Overtime effects)

Intended for damage over time effects or until save effects, but can do a bunch of things.

flags.midi-qol.OverTime OVERRIDE specification

where specification is a comma separated list of fields.

Hold Person

MidiQOL.doOverTimeEffect

MidiQOL.doOverTimeEffect(actor: Actor5e, effect: ActiveEffect, turnStart: boolean), which will perform the overtime processing for the passed effect, turnStart === true, do turn=start changes, false do turn=end changes.

The effect does not need to be present on the actor to be processed.

If you are applying the effect via using an item @ fields are ambiguous, should they refer to the caster or the target? There are reasons to have both interpretations, an ongoing saving throw should refer to the caster, e.g. saveDC=@attributes.spelldc. Regeneration has applyCondition=@attributes.hp.value > 0, which should refer to the target.

Effects transferred via item usage, require DAE and use its evaluation to resolve the problem. Fields written as simple @ fields (@attributes.spelldc) ALWAYS refer to the caster.

If you want the @field to refer to the target, that requires use of a DAE feature, ##field will not be evaluated on the caster, but will be converted to an @field after the effect is applied to the target. The example appplyCondition=@attributes.hp.value > 0 would be written appplyCondition=##attributes.hp.value > 0.

Here's an example, if I add the following effect to a weapon, so that the effect is applied to the target when the weapon hits:

  flags.midi-qol.Overtime  OVERRIDE  applyCondition=@attributes.hp.value > 0
  flags.midi-qol.Overtime  OVERRIDE  applyCondition=##attributes.hp.value > 0

will result in an effect being created on the target (assuming the attacker has 75 hit points) 

  flags.midi-qol.Overtime  OVERRIDE  applyCondition=75 > 0
  flags.midi-qol.Overtime  OVERRIDE  applyCondition=@attributes.hp.value > 0

Overtime effects and macros.

There are two ways to have a macro effect applied to a target when using Overtime effects. The first is to have the macro as an additional change in an active effect (macro.execute/macro.ItemMacro). The second is as part of the overtime effect with macro="world macro name". The macro as an additional change is called once when the effect is applied and once when it is removed (with args[0]==="on"/"off" respectively - the normal macro.execute/macro.itemMacro behaviour). The macro="" macro is called each turn with the results of the save/targets etc. (see OnUse Macro data for details).

Bugs

probably many however....

Notes for Macro writers

For modules that want to call midi-qol it is easier than in minor-qol. Just call item.roll() and if you pass an event via item.roll({event}) you can have key accelerators. (the meanings of shift/ctrl/alt will be interpreted using the speed rolls settings) event.altKey: true => advantage roll event.ctrlKey: true => disadvantage roll event.shiftKey: true => auto roll the attack roll Additional workflow processing options to itemRoll(options). You can set

It takes the same arguments as midis item.roll:

Midi-qol called Hooks

The passed workflow is "live" so changes will affect subsequent actions. In particular preAttackRoll and preDamageRoll will affect the roll about to be done.

TrapWorkflow

midi-qol supports a TrapWorkflow, triggered by

new MidiQOL.TrapWorkflow(actor, item, [targets], {x:number, y:number})

Which will roll the attack/and or damage and apply to the passed targets. If the item has an area template it will be placed at x,y and targets auto selected inside the template.

Sample DoTrapAttack replacement:

// @Token[Fireball]@Trigger[click]@ChatMessage[/DoTrapAttack _Traps Fireball Fireball 2]

let tactor = game.actors.getName(args[0])
if (!tactor) return console.error(`DoTrap: Target token ${args[0]} not found`);
let item = tactor.items.getName(args[1])
if (!item) return console.error(`DoTrap: Item ${args[1]} not found`)
let trapToken = canvas.tokens.placeables.find(t=>t.name === args[2]);
const templateLocation = trapToken.center;
templateLocation.removeDelay = parseInt(args[3]) || 2;
new MidiQOL.TrapWorkflow(tactor, item, [token], templateLocation)
if (trapToken) await trapToken.update({"hidden" : true});

DamageOnlyWorkflow

let target = await fromUuid(args[0].hitTargetUuids[0] ?? "");
let numDice = 1 + args[0].spellLevel;
if (numDice > 5) numDice = 5;
// Apparently improved divine smite should not be added to the divine smite. Uncomment these lines if you want it to be included
// if (improvedDivineSmite) numDice += 1;
// let improvedDivineSmite = args[0].actor.items.find(i=> i.name ==="Improved Divine Smite");
let undead = ["undead", "fiend"].some(type => (target?.actor.data.data.details.type?.value || "").toLowerCase().includes(type));
if (undead) numDice += 1;
if (args[0].isCritical) numDice = numDice * 2;
let damageRoll = await new Roll(`${numDice}d8`).roll({async: true});
new MidiQOL.DamageOnlyWorkflow(actor, token, damageRoll.total, "radiant", target ? [target] : [], damageRoll, {flavor: "Divine Smite - Damage Roll (Radiant)", itemCardId: args[0].itemCardId})

Flavor is only used if you are not using combo cards.
The args[0].itemCardId passes the id of the item card that caused the macro to be rolled, i.e. for divine smite the ItemCard of the Divine Smite spell/feature. By passing this to the DamageOnlyWorkflow the damage roll can be added to the ItemCard making the whole effect look like an item damage roll (almost).

The itemCardId field is used to append the damage result to the item card that rolled the onUse macro (in this case the Divine Smite spell).

You can use this feature to roll custom damage via a macro for any item - just leave the item damage blank and roll the damage in a macro and then pass the itemCardId to the DamageOnlyWorkflow.

DummyWorkflow

OnUse Macro(per Item) and Damage Bonus Macro (actor special traits) fields

These field lets you specify a macro to call during the roll.

OnUse macros are called during the item workflow. The intention of this feature is that you can customise the behaviour of how a particular item behaves.

Midi-qol supports item based onUse macros, which are called when the item is rolled, and actor onUse macros which are called whenever any item is rolled, at various points in the workflow.

The interpretation of the field settings are identical in both actor and item onUse macros. For actor based onUse macros, ItemMacro will refer to the item being rolled, which is not useful, either specify a world macro or an ItemMacro.item name.

For actor onUse macros you can specify to call the macro by setting actor flags by hand or active effects, 

flags.midi-qol.onUseMacroName CUSTOM macroName,macroPass

which will call the specified macro on the specified macroPass. macroPass is taken from the list below.

The field should contain ONLY the macro name, or the string "ItemMacro" or "ItemMacro.ItemName".

You may specify the point at in the workflow when the macro is called.
The macro will be called with args[0] containing the current state information for the workflow (see below). There are some controls for macro writers to decide when their macro should get executed. 

    preItemRoll: Called before the item is rolled (*)
    templatePlaced: Only callled once a template is placed
    preambleComplete: Called after all targeting is complete
        preAttackRoll: Called before the attack roll is made
        preCheckHits: Called after the attack roll is made but before hits are adjudicated
        postAttackRoll: Called after the attack is adjudicated
        preDamageRoll: Called before damage is rolled
        postDamageRoll: Called after the damage roll is made
    preSave: Called before saving throws are rolled
        postSave: Called after saves are rolled
    damageBonus: Called when computing the actor damage bonus but the macro is only called when the specific item is rolled
        preDamageApplication: Called before Damage Application
        preActiveEffects: Called before applying active effects
        postActiveEffects: Called after applying active effects
        all: Called at each of the above

There are some addtional actor only onUse macro triggers that can be defined for an actor that trigger when the actor is the target of an attack/spell/feature use

  - the macro arguments have an additional parameter args[0].macroPass set to the pass being called, being one of:
    preItemRoll
    templatePlaced
    preambleComplete
    preAttackRoll
    preCheckHits
    postAttackRoll
    preSave
    postSave
    preDamageRoll
    postDamageRoll
    preDamageApplication
    preActiveEffects
    postActiveEffects

  - [All] is special, being called with each value of macroPass. You can differentiate via args[0].macroPass to decide which ones to act on.

  There are some additional actor onUse macro triggers (but NOT item triggers) available when the actor is the target of an attack/spell/feature use:
isAttacked: the actor is a target of an attack
isHit: the actor is a target of a hit
isSave: the actor makes a successful save in response to being targeted
isSaveSuccess: the actor makes a successful save in response to being targeted
isSaveFailure: the actor makes a failed save in response to being targeted
isDamaged: "the actor is damaged by an item roll

  - For these calls only args[0].options.actor will be the actor that was attackd/hit/damaged etc

  - The default pass is "preActiveEffects", to correspond to the original onUse macro behaviour.
  * Note: if you are creating a damage only workflow in your macro it is best to run it in "postActiveEffects".

  * If you wish to make changes to the workflow in these macros you will need to do:

const workflow = MidiQOL.Workflow.getWorkflow(args[0].uuid) workflow.XXX = .....


  * Remember that if the macro is an "Execute as GM" macro the macro may execute on a different client and the workflow may not be defined, i.e. the Workflow.getWorkflow may return undefined.

  * If you want to change the damage roll of a weapon have your macro run at the postDamageRoll onUse pass and do something like (this will work with better rolls - the damage will be changed, but the chat card for the item won't update)
  ```js
  if (args[0].tag === "OnUse" && args[0].macroPass === "postDamageRoll") {
    let workflow = MidiQOL.Workflow.getWorkflow(args[0].uuid); // this gets a copy of the "live" workflow
    const damageRoll = await new Roll("1d10").roll({async: true});
    workflow.setDamageRoll(damageRoll);
  }

which will replace the items normal damage roll with your custom roll.

Damage bonus macros are called after hits/misses/saves are adjudicated but BEFORE damage is applied, so you can specify extra damage if required, e.g. hunter's mark. The macro is not dependent on a particular item being rolled, but is called whenever damage is rolled by that character.
The intention is to support effects that are based on the character's state, rather than being related to a specific item. You can do whatever processing you want there, so could create a condition on some of the targets, do extra damage to specific creates/types of creatures and so on. Damage bonus macros can return an array of [{damageRoll: string, flavor: string}] which will be added to the damage of the attack. The damage roll is a roll expression and flavor should be a damage type, e.g. fire. Damage returned via the damage bonus will NOT be increased for critical hits.

Macro calls supply the following data

  actorData = actor.data (the actor using the item).
  actor = actor.data (same as above, kept for backwards compatibility)
  actorUuid = actor.uuid
  tokenId
  tokenUuid
  item = item.data (the item, i.e. spell/weapon/feat)
  itemUuid the item uuid
  targets: [token.docucment] (an array of token documents taken from game.user.targets)
  targetUuids: [uuid]
  hitTargets: [token.document] (an array of token documenta taken from targets that were hit)s  hitTargetUuids [uuid]
  saves: [token.document] (an array of token documents taken from targets that made a save)
  saveUuids = [uuid]
  failedSaves: [token.document] (an array of token document taken from targets that failed the save)
  failedSaveUuids = [uuid]
  criticalSaves: [token.document]
  criticalSaveUuids = [uuid]
  fumbleSaves: [token.document]
  fumbleSaveUuids = [uuid]
  damageRoll = the Roll object for the damage roll (if any)
  attackRoll = the Roll object for the attack roll (if any)
  itemCardId = the id of the chat message item card (see below)
  attackTotal: this.attackTotal,
  itemCardId: this.itemCardId,
  isCritical = true/false
  isFumble = true/false
  spellLevel = spell/item level
  damageTotal = damage total
  damageDetail = [type: string, damage: number] an array of the specific damage items for the attack/
  otherDamageTotal: damage total for "Other Roll" (if any)
  otherDamageDetail: damage detail for "the Other Roll" (if any)
  id: the id of the item that caused the workflow (if any)
  uuid: a unique Id for the workflow
  rollData: this.actor.getRollData(),
  tag: either "OnUse" or "DamageBonus" indicating where in the workflow it was called. You can use this to allow the same macro to be used in both cases
  templateId: the template.id field for the placed measured template (if any)
  concentrationData: getProperty(this.actor.data.flags, "midi-qol.concentration-data"),
  templateUuid - preferred over templateId

You can use the various target details to work out which tokens to apply the effect to, for example hitTargets is only those targets that the item roll "hit" if any.

The combo card has some special divs included to allow you to easily add data to the card.

    <div class="midi-qol-attack-roll"></div>
    <div class="midi-qol-damage-roll"></div>
    <div class="midi-qol-hits-display"></div>
    <div class="midi-qol-saves-display"></div>

Which it uses to update the card when things happen, like attacks, damage, saves, etc. You can take over those fields to create custom items.

This is the code that puts the hit roll detail on the item card

const chatMessage: ChatMessage = game.messages.get(args[0].itemCardId);
var content = duplicate(chatMessage.data.content);    
const searchString =  '<div class="midi-qol-hits-display"></div>';
const replaceString = `<div class="midi-qol-hits-display">${hitContent}</div>`
content = content.replace(searchString, replaceString);
chatMessage.update({content: content});

hitContent is just html, so you could insert whatever you want in any of the divs above.

Some Tricks you can do...

This is just a place where I'll write down some ideas that I think are cute. I'll assume that DAE/times-up is available as well.

Here's the effect setup
Spirit Guardian Effect Setup
and here's the Active Aura setup
Spirit Guardian Effect Setup

I've included the complete macro, but the general idea is:

Sample Chat Logs

No Combo Card Combo Card

Credits

The sound file fail1.ogg, distributed with this module is licensed under the following terms: Licensed under the Creative Commons v3.0: https://creativecommons.org/licenses/by/3.0/legalcode Obtained from https://freesound.org/s/178687/ from Freesound user Soundb. It has been converted from .wav to .ogg format.

The file success-drums.ogg distributed with this module is licensed under the following terms: Licensed under the Creative Commons v3.0: https://creativecommons.org/licenses/by/3.0/legalcode Obtained from https://freesound.org/people/LittleRobotSoundFactory/sounds/270467/ It has been converted from .wav to .ogg format.

The file drinkng.wav distributed with this module is licensed under the following terms: Licensed under the Creative Commons v3.0: https://creativecommons.org/licenses/by/3.0/legalcode Obtained from. https://freesound.org/people/dersuperanton/sounds/433645/ Not changes have been made to the file.

The file use.wav distributed with this module is licensed under the following terms: Licensed under the Creative Commons v3.0: https://creativecommons.org/licenses/by/3.0/legalcode Obtained from https://freesound.org/people/32cheeseman32/sounds/180831/. No changes have been made to the file

Code from the module Actually Private Rolls (https://github.com/syl3r86/Actually-Private-Rolls) written by felix.mueller.86@web.de has been included in midi-qol

concentrate icon by Chanut is Industries from the Noun Project. Licensed under the Creative Commons v3.0: https://creativecommons.org/licenses/by/3.0/legalcode Obtained from https://thenounproject.com/term/concentrate/2189896/

Bow and Arrow sound. Licensed under the ZapSplat standard license. Additional sound effects from https://www.zapsplat.com