(docs) damage and armour trigger pages

docs/Gemfile.lock

@@ -227,12 +227,12 @@ GEM
     mutex_m (0.2.0)
     net-http (0.4.1)
       uri
+    nokogiri (1.16.3-x86_64-linux)
+      racc (~> 1.4)
     nokogiri (1.16.5-x64-mingw-ucrt)
       racc (~> 1.4)
     nokogiri (1.16.5-x86_64-linux)
       racc (~> 1.4)
-    nokogiri (1.16.3-x86_64-linux)
-      racc (~> 1.4)
     octokit (4.25.1)
       faraday (>= 1, < 3)
       sawyer (~> 0.9)

docs/pages/effects/triggers/APCalc.md

@@ -5,11 +5,81 @@ parent: Scripts
 nav_order: 17
 grand_parent: Active Effects
 ---
+
+This trigger runs after Armour has been computed into layers on the various hit locations. You can use this script to add more layers.
+
+Note that the scripts below don't actually manipulate `args` directly, but call a helper function to handle adding armour layers.
+
 ## Key
 
 `APCalc`
 
 ## Arguments 
 
+```js
+args.AP = {
+            head: {
+                value: 0,
+                layers: [],
+                label: game.i18n.localize("Head"),
+                show: true,
+            },
+            body: {
+                value: 0,
+                layers: [],
+                label: game.i18n.localize("Body"),
+                show: true
+            },
+            rArm: {
+                value: 0,
+                layers: [],
+                label: game.i18n.localize("Right Arm"),
+                show: true
+            },
+            lArm: {
+                value: 0,
+                layers: [],
+                label: game.i18n.localize("Left Arm"),
+                show: true
+            },
+            rLeg: {
+                value: 0,
+                layers: [],
+                label: game.i18n.localize("Right Leg"),
+                show: true
+
+            },
+            lLeg: {
+                value: 0,
+                layers: [],
+                label: game.i18n.localize("Left Leg"),
+                show: true
+            },
+            shield: 0,
+            shieldDamage: 0
+        }
+```
+
 ## Examples
 
+### Add AP to all locations
+
+**Usage**: Adds 2 to all AP locations. 
+
+```js
+this.actor.system.status.addArmour(2, {source: this.effect})
+```
+
+**Notes**: You can add the `locations` property to the second argument, i.e. `locations: ["head", "lArm", "body"]`, as well as `magical: true`
+
+---
+
+### Add AP to the Head location
+
+**Usage**: Adds 1 magical AP to the head location. 
+
+```js
+this.actor.system.status.addArmour(1, {locations : "head", source : this.effect, magical : true})
+```
+
+

docs/pages/effects/triggers/applyDamage.md

@@ -5,11 +5,108 @@ parent: Scripts
 nav_order: 19
 grand_parent: Active Effects
 ---
+
+This trigger runs when an Actor applies damage (via opposed test) to another Actor, specifically after all the modifiers and reductions are applied, but before the Actor is updated and the result is displayed in chat, letting us modify values right before they are applied. 
+
 ## Key
 
 `applyDamage`
 
 ## Arguments 
 
+`args.actor` - The Actor *taking damage*
+
+`args.attacker` - The Actor *doing damage*
+
+`args.opposedTest` - The Opposed Test that was used to calculate damage
+
+`args.damageType` - Whether to ignore AP, TB, or both. This argument is obsolete and has already been derived into `applyAP` and `applyTB`
+
+`args.weaponProperties` - What properties (qualities and flaws) the weapon has. This can be modified to add properties to the calculation. (e.g. `args.weaponProperties.qualities.damaging` or `args.weaponProperties.flaws.unbalanced`)
+
+`args.applyAP` - Whether armour was used to reduce the incoming damage
+
+`args.applyTB` - Whether Toughness bonus was used to reduce the incoming damage
+
+`args.totalWoundLoss` - This will *eventually* be the actual amount of wounds deducted from the Actor. At this point in the process, it is the raw damage value from the test. 
+
+`args.AP` - The data of the location taking damage. See [Armour Calculation](./APCalc.md) to see the object structure.
+
+`args.modifiers` - Modifiers for armour, toughness, and damage. Note that these modifiers have *already been applied* and modifications in this trigger will not be reflected in the damage values. See [Compute Apply Damage Modifiers](./computeApplyDamageModifiers.md) to see the object structure (modifiers generally should be changed in that trigger, not this one).
+
+`args.extraMessages` - Array of strings that can be added to for displaying in chat.
+
+`args.ward` - Ward value of the Actor (If ward is some number, a roll is made and if that roll is greater or eual to the ward value, the damage is ignored)
+
+`args.wardRoll` - The Ward roll is determined, but only checked if ward isn't null. This occurs after this trigger runs. 
+
+`args.abort` - Set this to a string value to abort the process (with the string being the message shown in chat)
+
+
 ## Examples
 
+### Set Ablaze
+
+**Usage**: If a Wound is dealt, also add an Ablaze condition
+
+```js
+if (args.totalWoundLoss > 0)
+{
+    args.actor.addCondition('ablaze')
+} 
+```
+
+**Notes**: Since all the reductions have been calculated at this point, we can check `totalWoundLoss` for the actual damage amount taken. 
+
+---
+
+### Prompt a Message
+
+**Usage**: If a Wound is dealt, prompt a message about contracting a disease.
+
+```js
+if (args.totalWoundLoss > 0)
+{
+    this.script.message(`<b>${args.actor.name}</b> must pass an <b>Easy (+40) Endurance</b> Test or gain a @UUID[Compendium.wfrp4e-core.items.kKccDTGzWzSXCBOb]{Festering Wound}`, {whisper: ChatMessage.getWhisperRecipients("GM")})
+}
+
+```
+
+**Notes**: Use the whisper option if you don't want players to see this message. 
+
+---
+
+### Prompt a Test
+
+**Usage**: If a Wound is dealt, Make an Endurance Test, if failed, gain a Stunned Condition
+
+```js
+if (args.totalWoundLoss > 0)
+{
+    let test = await args.actor.setupSkill(game.i18n.localize("NAME.Endurance"), {skipTargets: true, appendTitle :  ` - ${this.effect.name}`});
+    await test.roll();
+    if (test.failed)
+    {
+	    args.actor.addCondition("stunned");
+    }
+}
+```
+
+**Notes**: It's important to use `args.actor` instead of `this.actor`.
+
+---
+
+### Add Damage to Daemonic
+
+**Usage**: Add 3 Damage if the target is Daemonic
+
+```js
+if (args.actor.has("Daemonic")) 
+{
+  args.modifiers.other.push({label: this.effect.name, value: 3});
+  args.totalWoundLoss += 3;
+}
+```
+
+**Notes**: This script isn't optimal here, it would be better placed in [Compute Apply Damage Modifiers](./computeApplyDamageModifiers.md), where we wouldn't need to modify `args.totalWoundLoss`. However, it showcases that we *can* still use the `args.modifiers.other` array. The value is not used in the calculation because modifiers have already been processed, but the label and value will still show in the damage breakdown tooltip. In summary, if you need to modify `totalWoundLoss` in this trigger, you can use `args.modifiers.other` to show that to the user. 
+

docs/pages/effects/triggers/preAPCalc.md

@@ -5,6 +5,9 @@ parent: Scripts
 nav_order: 16
 grand_parent: Active Effects
 ---
+
+This trigger runs after the armour (AP) objcet has been initialized (as shown below).
+
 ## Key
 
 `preAPCalc`
@@ -57,3 +60,4 @@ args.AP = {
 
 ## Examples
 
+There are no scripts that currently use this trigger. Generally modifications to AP is used in [Armour Calculation](./APCalc.md)

docs/pages/effects/triggers/preApplyDamage.md

@@ -5,11 +5,83 @@ parent: Scripts
 nav_order: 18
 grand_parent: Active Effects
 ---
+
+This trigger runs when an Actor applies damage (via opposed test) to another Actor. The arguments provided allow us to modify how this is handled. 
+
 ## Key
 
 `preApplyDamage`
 
 ## Arguments 
 
+`args.actor` - The Actor *taking damage*
+
+`args.attacker` - The Actor *doing damage*
+
+`args.opposedTest` - The Opposed Test that was used to calculate damage
+
+`args.damageType` - Whether to ignore AP, TB, or both. This argument is obsolete and has already been derived into `applyAP` and `applyTB`
+
+`args.weaponProperties` - What properties (qualities and flaws) the weapon has. This can be modified to add properties to the calculation. (e.g. `args.weaponProperties.qualities.damaging` or `args.weaponProperties.flaws.unbalanced`)
+
+`args.applyAP` - Whether to apply armour to reduce the incoming damage
+
+`args.applyTB` - Whether to apply Toughness bonus to reduce the incoming damage
+
+`args.totalWoundLoss` - This will *eventually* be the actual amount of wounds deducted from the Actor. At this point in the process, it is the raw damage value from the test. 
+
+`args.AP` - The data of the location taking damage. See [Armour Calculation](./APCalc.md) to see the object structure.
+
+`args.modifiers` - Modifiers for armour, toughness, and damage. See [Compute Apply Damage Modifiers](./computeApplyDamageModifiers.md) to see the object structure (modifiers generally should be changed in that trigger, not this one).
+
+`args.extraMessages` - Array of strings that can be added to for displaying in chat.
+
+`args.ward` - Ward value of the Actor (If ward is some number, a roll is made and if that roll is greater or eual to the ward value, the damage is ignored)
+
+`args.wardRoll` - The Ward roll is determined at the beginning of damage application, but only checked if needed.
+
+`args.abort` - Set this to a string value to abort the process (with the string being the message shown in chat)
+
+
+
 ## Examples
 
+### Ignore AP
+
+**Usage**: Ignore AP when applying this damage.
+
+```js
+args.applyAP = false;
+```
+
+**Notes**: This is what the vast majority of `preApplyDamage` scripts do, changing `applyAP` or `applyTB` is ideal here as neither has been used at this point in the process to reduce the damage applied. 
+
+---
+
+### Add Impale
+
+**Usage**: Add Impale if the location struck has no AP.
+
+```js
+if (args.AP.value == 0)
+{
+    args.weaponProperties.impale = true;
+    args.extraMessages.push(`<strong>${this.item.name}</strong>: Impale Added`)
+}
+```
+
+**Notes**: Changing `weaponProperties` is ideal in `preApplyDamage` as it has not been used to modify damage at this stage.
+
+---
+
+### Add Damage conditionally
+
+**Usage**: Add 5 Damage if the target is a spellcaster (has Spell items)
+
+```js
+if (args.actor.itemTypes.spell.length > 0)
+{
+	args.modifiers.other.push({label : this.effect.name, value : 5, details : "Target is a Spellcaster"});
+}
+```
+**Notes**: `args.modifiers.other` is for adding any sort of arbitrary generic damage. Can also be done in [Compute Apply Damage Modifiers](./computeApplyDamageModifiers.md)

modules/actor/actor-wfrp4e.js

@@ -506,7 +506,6 @@ export default class ActorWFRP4e extends WarhammerActor
 
     // Start message update string
     let updateMsg = `<b>${game.i18n.localize("CHAT.DamageApplied")}</b><span class = 'hide-option'>: `;
-    let messageElements = [] // unused and deprecated
 
     let modifiers = {
       tb : 0,
@@ -770,8 +769,7 @@ export default class ActorWFRP4e extends WarhammerActor
       }
     }
     catch (e) { warhammer.utility.log("Sound Context Error: " + e, true) } // Ignore sound errors
-
-    let scriptArgs = { actor, opposedTest, totalWoundLoss, AP, applyAP, applyTB, damageType, updateMsg, messageElements, modifiers, ward, wardRoll, attacker, extraMessages, abort }
+    let scriptArgs = { actor, attacker, opposedTest, totalWoundLoss, AP, applyAP, applyTB, damageType, updateMsg, modifiers, ward, wardRoll, attacker, extraMessages, abort }
     await Promise.all(actor.runScripts("takeDamage", scriptArgs))
     await Promise.all(attacker.runScripts("applyDamage", scriptArgs))
     await Promise.all(opposedTest.attackerTest.item?.runScripts("applyDamage", scriptArgs))