From 370ffe274f46175048c750991e569a259d6ebc34 Mon Sep 17 00:00:00 2001
From: Tachytaenius <henryfthomson@gmail.com>
Date: Thu, 1 Dec 2022 23:25:01 +0000
Subject: [PATCH] Add Lua API docs for action timer API

---
 docs/dev/Lua API.rst | 43 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/docs/dev/Lua API.rst b/docs/dev/Lua API.rst
index 37865394e..bbc56b03b 100644
--- a/docs/dev/Lua API.rst	
+++ b/docs/dev/Lua API.rst	
@@ -1548,6 +1548,49 @@ Units module
 
   Returns a table of the cutoffs used by the above stress level functions.
 
+Action Timer API
+~~~~~~~~~~~~~~~~
+
+This is an API to allow manipulation of unit action timers, to speed them up or slow them down.
+All functions in this API have overflow/underflow protection when modifying action timers (the value will cap out).
+``affectedActionType`` parameters are integers from the DF enum ``unit_action_type``. E.g. ``df.unit_action_type.Move``.
+``affectedActionTypeGroup`` parameters are integers from the (custom) DF enum ``unit_action_type_group``. They are as follows:
+
+  * ``All`` (does not include unknown unit action types)
+  * ``Movement``
+  * ``MovementFeet`` (check if the unit is not on ground before using this one?)
+  * ``Combat`` (includes bloodsucking)
+  * ``Work``
+
+API functions:
+
+* ``subtractActionTimers(unit, amount, affectedActionType)``
+
+  Subtract ``amount`` (32-bit integer) from the timers of any actions the unit is performing of ``affectedActionType``
+  (usually one or zero actions in normal gameplay).
+
+* ``subtractGroupActionTimers(unit, amount, affectedActionTypeGroup)``
+
+  Subtract ``amount`` (32-bit integer) from the timers of any actions the unit is performing that match the ``affectedActionTypeGroup`` category.
+
+* ``multiplyActionTimers(unit, amount, affectedActionType)``
+
+  Multiply the timers of any actions of ``affectedActionType`` the unit is performing by ``amount`` (float)
+  (usually one or zero actions in normal gameplay).
+
+* ``multiplyGroupActionTimers(unit, amount, affectedActionTypeGroup)``
+
+  Multiply the timers of any actions that match the ``affectedActionTypeGroup`` category the unit is performing by ``amount`` (float).
+
+* ``setActionTimers(unit, amount, affectedActionType)``
+
+  Set the timers of any action the unit is performing of ``affectedActionType`` to ``amount`` (32-bit integer)
+  (usually one or zero actions in normal gameplay).
+
+* ``setGroupActionTimers(unit, amount, affectedActionTypeGroup)``
+
+  Set the timers of any action the unit is performing that match the ``affectedActionTypeGroup`` category to ``amount`` (32-bit integer).
+
 Items module
 ------------