Healing & attack scripts: manage status markers & health- or exhaustion-related temporary restrictions

[phylll]

We're missing a script to process healing or energy boosts in ways that automatically remove exhaustion or injury markers set by our attack scripts.

Once/if we add such a script, we could easily also automate the annoying handling of temporary restrictions to endurance or movement based on injury or exhaustion levels:

• the defense scripts would put a certain restriction into effect by making the change (to B or AP, for example) while storing the previous value (which might be unequal to .max) in some temporary attribute.
• the healing script(s) would roll back such restrictions the same way they would roll back injury or exhaustion status markers, drawing on the temporary attributes to collect the missing information.

[phylll]

Requires #32

[phylll]

Requires https://github.com/michael-buschbeck/mychs-macro-magic/issues/160

[phylll]

A new applyHealing script is part of efb5db2bf07cd152cb16bf073027048296c90971, with temporary restrictions left on the todo list

[phylll]

When a temporary restriction begins, e.g. defense reduces health to below 50%, which triggers a cap on endurance at 50%, as well:

• The token's current level of health is saved in an attribute m3mgd_token[ID]_[attr] whose name needs to include both the token_id and the attribute being limited (in its name, since otherwise we won't be able to store more than one restricted attribute per token) and the number of endurance points or movement units (in "current") since generic NPC tokens do not offer storage unique to each token.
• The token's health bar is reduced to the new ceiling.
• For this particular example, the most common one, the yellow circle marker indicates the status. For other cases, there should also be a visual indicator for easy tracking.

Generic NPCs usually never recover, they just die or become incapacitated. There needs to be a way to clean up the storage sheet, though. Otherwise it will soon be full of attributes relating to long-dead orcs. The challenge is that MMM scripts can only access attributes if they know their names, so auto-cleanup is possible only as long as the token in question is subject to a script. One solution would be for the GM to operate a die script to clean up after each token.

Individual NPCs or PCs will recover, either through rest or applyHealing of one kind or another. In practice, the most common case in which endurance exceeds health is after significant rest. In that case,

• Through the status marker and token_id-based centrally stored attribute, the script recognizes that a temporary ceiling is in place on some attribute(s). If the ceiling remains in place, the restricted attribute cannot exceed the ceiling, and e.g. the good night's rest brings the character only up to half their endurance as long as they haven't recovered from their major injuries.
• When the status improves, the ceiling is lifted by restoring the token's attribute to its previous value pulled from the attribute, and both status marker and the temporary storage attribute are removed.

[phylll]

From the list of combat-related temporary attribute restrictions ...

• Exhaustion (endurance is 0): -4 on everything
• Serious injury (health <50%): endurance and movement reduced to half
• Close to death (health <= 3): movement limited to 4
• Dying (health <= 0): movement limited to 0

... the only one we automate is endurance, so it should be enough for now to manage that.

[phylll]

So far, new functions m3mgdSetAttrCeiling(tokenID, enduranceAttr, enduranceCeiling) and m3mgdReleaseAttrCeiling(tokenID, enduranceAttr) work as intended.

Remaining issues:

• Confusion between using the bar2 or the AP attribute. If the set and release scripts happen to use different ones, the release script cannot find the stored value. Resolved for now through an ugly workaround in _m3mgdGetStoredAttr().
• User output and order of execution. If a token loses endurance through a hit and then gets their endurance further reduced through a ceiling (because its health falls below 50%), the various pieces of output don't fit perfectly, yet.
• So far, only m3mgdModifyHealth() implements the setting and releasing of ceilings. While a ceiling is in place, however, m3mgdModifyEndurance() also needs to respect it: an energy drink or a full night's sleep won't provide endurance gain beyond the ceiling. Done, including necessary UX improvements in rest and applyHealing to let players know why their expensive energy drinks don't work.
• Roll20's UI for managing attributes sucks and gets quite seriously confused by the long attribute names. (But logging out and in again helps, so fine.)
• Cleanup: no way without MMM allowing the deletion of attributes -- see https://github.com/michael-buschbeck/mychs-macro-magic/issues/171.

[phylll]

Closing, except für the very last bullet point in the last comment, which is moved to #40