docs: explain SafeScripts limits when changing hit damage

Author: Elektryk-Andrzej

Code/ValueSystem/PropertySystem/ReferencePropertyRegistry.cs

@@ -324,7 +324,7 @@ public static void Initialize()
         Register<DamageHandlerBase, NumberValue>(
             "damage",
             h => new NumberValue((decimal)((h as StandardDamageHandler)?.Damage ?? -1)),
-            "Damage amount, -1 if not applicable. Can be changed for standard damage handlers.",
+            "Damage amount, -1 if not applicable. To change a standard hit in a Hurting script, disable SafeScripts and set this before any pause.",
             (h, value) =>
             {
                 if (h is not StandardDamageHandler standard)

docs/guides/flags-events-and-commands.md

@@ -97,6 +97,30 @@ server.
 
 :::
 
+### Change a hit's damage
+
+In a `Hurting` script, change the damage amount to keep the hit's original
+attacker:
+
+```ser
+!-- OnEvent Hurting
+-- require *evDamageHandler
+
+*evDamageHandler -> damage = 25
+```
+
+:::warning SafeScripts and hit damage
+
+This changes the current hit only with SafeScripts disabled and before any
+`Wait` or other pause. With SafeScripts enabled, the hit continues before the
+script can change it. Keep SafeScripts enabled for general scripts; turn it off
+only after checking every active script for loops that can freeze the server.
+
+:::
+
+Only standard damage handlers have a damage amount to change. Other handlers
+return an error if you try to set this property.
+
 ## ProjectMER events
 
 When ProjectMER is installed: