From 89e0c9c3c2f80e54cc40e35c69f68a6219a9c432 Mon Sep 17 00:00:00 2001
From: Myk Taylor <myk002@yahoo.com>
Date: Mon, 30 Oct 2023 02:00:23 -0700
Subject: [PATCH 1/2] add sync-windmills

---
 changelog.txt           |  1 +
 docs/sync-windmills.rst | 32 ++++++++++++++++++++++++++++++++
 sync-windmills.lua      | 32 ++++++++++++++++++++++++++++++++
 3 files changed, 65 insertions(+)
 create mode 100644 docs/sync-windmills.rst
 create mode 100644 sync-windmills.lua

diff --git a/changelog.txt b/changelog.txt
index ba1435d045..6bcec1b704 100644
--- a/changelog.txt
+++ b/changelog.txt
@@ -27,6 +27,7 @@ Template for new versions:
 # Future
 
 ## New Tools
+- `sync-windmills`: synchronize or randomize movement of active windmills
 
 ## New Features
 
diff --git a/docs/sync-windmills.rst b/docs/sync-windmills.rst
new file mode 100644
index 0000000000..5696b82694
--- /dev/null
+++ b/docs/sync-windmills.rst
@@ -0,0 +1,32 @@
+sync-windmills
+==============
+
+.. dfhack-tool::
+    :summary: Synchronize or randomize windmill movement.
+    :tags: fort buildings
+
+This tool can adjust the appearance of running windmills so that they are
+either all in synchronization or are all completely randomized.
+
+Usage
+-----
+
+::
+
+    sync-windmills [<options>]
+
+Examples
+--------
+
+``sync-windmills``
+    Make all active windmills synchronize their turning.
+``sync-windmills -r``
+    Randomize the movement of all active windmills.
+
+Options
+-------
+
+``-q``, ``--quiet``
+    Suppress non-error console output.
+``-r``, ``--randomize``
+    Randomize windmill state.
diff --git a/sync-windmills.lua b/sync-windmills.lua
new file mode 100644
index 0000000000..a50e6fdbe1
--- /dev/null
+++ b/sync-windmills.lua
@@ -0,0 +1,32 @@
+local argparse = require('argparse')
+
+local function process_windmills(rotate_fn, timer_fn)
+    for _, bld in ipairs(df.global.world.buildings.other.WINDMILL) do
+        if bld.is_working ~= 0 then
+            bld.visual_rotated = rotate_fn()
+            bld.rotate_timer = timer_fn()
+        end
+    end
+end
+
+local opts = {}
+argparse.processArgsGetopt({...}, {
+    { 'h', 'help', handler = function() opts.help = true end },
+    { 'q', 'quiet', handler = function() opts.quiet = true end },
+    { 'r', 'randomize', handler = function() opts.randomize = true end },
+})
+
+if opts.help then
+    print(dfhack.script_help())
+    return
+end
+
+process_windmills(
+    opts.randomize and function() return math.random(1, 2) == 1 end or function() return false end,
+    opts.randomize and function() return math.random(0, 74) end or function() return 0 end)
+
+if not opts.quiet then
+    print(('%d windmills %s'):format(
+        #df.global.world.buildings.other.WINDMILL,
+        opts.randomize and 'randomized' or 'synchronized'))
+end

From 61599905d062dc888e0d0714ed0f858c4a7f851b Mon Sep 17 00:00:00 2001
From: Myk Taylor <myk002@yahoo.com>
Date: Mon, 30 Oct 2023 13:05:13 -0700
Subject: [PATCH 2/2] add --timing-only option for synchronizing timing but not
 polarity

---
 docs/sync-windmills.rst | 17 +++++++++++++----
 sync-windmills.lua      |  9 +++++++--
 2 files changed, 20 insertions(+), 6 deletions(-)

diff --git a/docs/sync-windmills.rst b/docs/sync-windmills.rst
index 5696b82694..21bf44e156 100644
--- a/docs/sync-windmills.rst
+++ b/docs/sync-windmills.rst
@@ -5,8 +5,15 @@ sync-windmills
     :summary: Synchronize or randomize windmill movement.
     :tags: fort buildings
 
-This tool can adjust the appearance of running windmills so that they are
-either all in synchronization or are all completely randomized.
+Windmills cycle between two graphical states to simulate movement. This is the
+polarity of the appearance. Each windmill also has a timer that controls when
+the windmill switches polarity. Each windmill's timer starts from zero at the
+instant that it is built, so two different windmills will rarely have exactly
+the same state. This tool can adjust the alignment of polarity and timers
+across your active windmills to your preference.
+
+Note that this tool will not affect windmills that have just been activated and
+are still rotating to adjust to the regional wind direction.
 
 Usage
 -----
@@ -19,7 +26,7 @@ Examples
 --------
 
 ``sync-windmills``
-    Make all active windmills synchronize their turning.
+    Synchronize movement of all active windmills.
 ``sync-windmills -r``
     Randomize the movement of all active windmills.
 
@@ -29,4 +36,6 @@ Options
 ``-q``, ``--quiet``
     Suppress non-error console output.
 ``-r``, ``--randomize``
-    Randomize windmill state.
+    Randomize the polarity and timer value for all windmills.
+``-t``, ``--timing-only``
+    Randomize windmill polarity, but synchronize windmill timers.
diff --git a/sync-windmills.lua b/sync-windmills.lua
index a50e6fdbe1..cc25703395 100644
--- a/sync-windmills.lua
+++ b/sync-windmills.lua
@@ -14,6 +14,7 @@ argparse.processArgsGetopt({...}, {
     { 'h', 'help', handler = function() opts.help = true end },
     { 'q', 'quiet', handler = function() opts.quiet = true end },
     { 'r', 'randomize', handler = function() opts.randomize = true end },
+    { 't', 'timing-only', handler = function() opts.timing = true end },
 })
 
 if opts.help then
@@ -22,8 +23,12 @@ if opts.help then
 end
 
 process_windmills(
-    opts.randomize and function() return math.random(1, 2) == 1 end or function() return false end,
-    opts.randomize and function() return math.random(0, 74) end or function() return 0 end)
+    (opts.randomize or opts.timing) and
+        function() return math.random(1, 2) == 1 end or
+        function() return false end,
+    opts.randomize and not opts.timing and
+        function() return math.random(0, 74) end or
+        function() return 0 end)
 
 if not opts.quiet then
     print(('%d windmills %s'):format(