Merge pull request #1036 from myk002/myk_item_trigger

reinstate modtools/item-trigger
DFHack · Mar 12, 2024 · d4595d3 · d4595d3
2 parents 39c4723 + 2a5f715
commit d4595d3
Show file tree

Hide file tree

Showing 3 changed files with 342 additions and 388 deletions.
diff --git a/changelog.txt b/changelog.txt
@@ -30,6 +30,7 @@ Template for new versions:
 - `agitation-rebalance`: alter mechanics of irriation-related attacks so they are less constant and are more responsive to recent player bahavior
 - `fix/stuck-worship`: fix prayer so units don't get stuck in uninterruptible "Worship!" states
 - `instruments`: provides information on how to craft the instruments used by the player civilization.
+- `modtools/item-trigger`: (reinstated) modder's resource for triggering scripted content when specific items are used
 
 ## New Features
 - `gui/settings-manager`: add import, export, and autoload for work details

diff --git a/docs/modtools/item-trigger.rst b/docs/modtools/item-trigger.rst
@@ -3,73 +3,98 @@ modtools/item-trigger
 
 .. dfhack-tool::
     :summary: Run DFHack commands when a unit uses an item.
-    :tags: unavailable
-
-This powerful tool triggers DFHack commands when a unit equips, unequips, or
-attacks another unit with specified item types, specified item materials, or
-specified item contaminants.
-
-Arguments::
-
-    -clear
-        clear all registered triggers
-    -checkAttackEvery n
-        check the attack event at least every n ticks
-    -checkInventoryEvery n
-        check inventory event at least every n ticks
-    -itemType type
-        trigger the command for items of this type
-        examples:
-            ITEM_WEAPON_PICK
-            RING
-    -onStrike
-        trigger the command on appropriate weapon strikes
-    -onEquip mode
-        trigger the command when someone equips an appropriate item
-        Optionally, the equipment mode can be specified
-        Possible values for mode:
-            Hauled
-            Weapon
-            Worn
-            Piercing
-            Flask
-            WrappedAround
-            StuckIn
-            InMouth
-            Pet
-            SewnInto
-            Strapped
-        multiple values can be specified simultaneously
-        example: -onEquip [ Weapon Worn Hauled ]
-    -onUnequip mode
-        trigger the command when someone unequips an appropriate item
-        see above note regarding 'mode' values
-    -material mat
-        trigger the command on items with the given material
-        examples
-            INORGANIC:IRON
-            CREATURE:DWARF:BRAIN
-            PLANT:OAK:WOOD
-    -contaminant mat
-        trigger the command for items with a given material contaminant
-        examples
-            INORGANIC:GOLD
-            CREATURE:HUMAN:BLOOD
-            PLANT:MUSHROOM_HELMET_PLUMP:DRINK
-            WATER
-    -command [ commandStrs ]
-        specify the command to be executed
-        commandStrs
-            \\ATTACKER_ID
-            \\DEFENDER_ID
-            \\ITEM_MATERIAL
-            \\ITEM_MATERIAL_TYPE
-            \\ITEM_ID
-            \\ITEM_TYPE
-            \\CONTAMINANT_MATERIAL
-            \\CONTAMINANT_MATERIAL_TYPE
-            \\CONTAMINANT_MATERIAL_INDEX
-            \\MODE
-            \\UNIT_ID
-            \\anything -> \anything
-            anything -> anything
+    :tags: dev
+
+This powerful tool triggers DFHack commands when a unit equips or unequips
+items or attacks another unit with specified item types, specified item
+materials, or specified item contaminants.
+
+Usage
+-----
+
+::
+
+    modtools/item-trigger [<options>] --command [ <command> ]
+
+At least one of the following options must be specified when registering a
+trigger: ``--itemType``, ``--material``, or ``--contaminant``.
+
+Options
+-------
+
+``--clear``
+    Clear existing registered triggers before adding the specified trigger. If
+    no new trigger is specified, this option just clears existing triggers.
+
+``--checkAttackEvery <n>``
+    Check for attack events at least once every n ticks.
+
+``--checkInventoryEvery <n>``
+    Check for inventory events at least once every n ticks.
+
+``--itemType <type>``
+    Trigger the command for items of this type (as specified in the raws).
+    Examples::
+
+        ITEM_WEAPON_PICK
+        RING
+
+``--material <mat>``
+    Trigger the command on items with the given material. Examples::
+
+        INORGANIC:IRON
+        CREATURE:DWARF:BRAIN
+        PLANT:OAK:WOOD
+
+``--contaminant <mat>``
+    Trigger the command for items with a given material contaminant. Examples::
+
+        INORGANIC:GOLD
+        CREATURE:HUMAN:BLOOD
+        PLANT:MUSHROOM_HELMET_PLUMP:DRINK
+        WATER
+
+``--onStrike``
+    Trigger the command on appropriate weapon strikes.
+
+``--onEquip <mode>``
+    Trigger the command when someone equips an appropriate item. Optionally,
+    the equipment mode can be specified. Possible values for mode::
+
+        Hauled
+        Weapon
+        Worn
+        Piercing
+        Flask
+        WrappedAround
+        StuckIn
+        InMouth
+        Pet
+        SewnInto
+        Strapped
+
+    Multiple values can be specified simultaneously. Example::
+
+        -onEquip [ Weapon Worn Hauled ]
+
+``--onUnequip <mode>``
+    Trigger the command when someone unequips an appropriate item. Same mode
+    values as ``--onEquip``.
+
+``--command [ <commandStrs> ]``
+    Specify the command to be executed. The following tokens can be used in the
+    command and they will be replaced with appropriate values::
+
+        \\ATTACKER_ID
+        \\DEFENDER_ID
+        \\ITEM_MATERIAL
+        \\ITEM_MATERIAL_TYPE
+        \\ITEM_ID
+        \\ITEM_TYPE
+        \\CONTAMINANT_MATERIAL
+        \\CONTAMINANT_MATERIAL_TYPE
+        \\CONTAMINANT_MATERIAL_INDEX
+        \\MODE
+        \\UNIT_ID
+        \\anything -> \anything
+        anything -> anything