From 8ae79a27b46296a2ee153e95d6cb7ac42a592e16 Mon Sep 17 00:00:00 2001 From: unboundlopez Date: Tue, 10 Jun 2025 16:49:47 -0500 Subject: [PATCH 1/6] Add z-adv-path-up-down script and documentation --- docs/z-adv-path-up-down.rst | 51 ++++++++++++++++ z-adv-path-up-down.lua | 115 ++++++++++++++++++++++++++++++++++++ 2 files changed, 166 insertions(+) create mode 100644 docs/z-adv-path-up-down.rst create mode 100644 z-adv-path-up-down.lua diff --git a/docs/z-adv-path-up-down.rst b/docs/z-adv-path-up-down.rst new file mode 100644 index 000000000..b713b50c9 --- /dev/null +++ b/docs/z-adv-path-up-down.rst @@ -0,0 +1,51 @@ +z-adv-path-up-down +================== + +Auto-path one Z-level up or down from your current Adventurer position by simulating one-step +movement commands. + +Synopsis +-------- + +:: + + z-adv-path-up-down + +Usage +----- + +Run from the DFHack Lua console while in **Adventurer** mode: + +:: + + [DFHack]# lua z-adv-path-up-down.lua + +1. You’ll be prompted with **Up**, **Down**, or **Cancel**. +2. Select **Up** to auto-path one level above your current Z; **Down** to auto-path one level below. +3. A “please do not press any keys” popup displays while the script works. +4. On success, a confirmation popup shows how many levels you moved; on failure, an error popup appears. + +Requirements +------------ +- DFHack 0.47.04 or later +- Modules: + - :mod:`gui.script` + - :mod:`dfhack.gui` +- Must be in **Adventurer** mode (i.e. `world.units.adv_unit` exists) +- A valid viewscreen to accept simulated input + +Example +------- + +.. code-block:: console + + [DFHack]# lua z-adv-path-up-down.lua + “Current z = 5. Which direction? (Cancel to exit)” + (Select “Up”) + “Auto-path in progress… Please do not press any keys.” + “Auto-path up 1 levels.” + +See Also +-------- +- :mod:`gui.script` — synchronous scripting API +- :mod:`dfhack.gui` — popup announcement utilities diff --git a/z-adv-path-up-down.lua b/z-adv-path-up-down.lua new file mode 100644 index 000000000..99f0f86d1 --- /dev/null +++ b/z-adv-path-up-down.lua @@ -0,0 +1,115 @@ +-- autopath_up_down_with_option1.lua +-- Usage: autopath_up_down_with_option1 +-- Presents an "Up/Down/Cancel" menu, then auto-paths one level at a time by simulating OPTION1 for each step, +-- shows a popup at start and a separate popup on success or failure using showPopupAnnouncement. + +local script = require('gui.script') +local gui = require('gui') +local dfgui = dfhack.gui +local world = df.global.world +local map = world.map +local delayFrames = 10 -- frames to wait for each simulated step + +script.start(function() + -- Initial checks + local you = world.units.adv_unit + if not you then + qerror("Error: No adventurer unit found.") + end + + local view = dfhack.gui.getCurViewscreen() + if not view then + qerror("Error: No current viewscreen to send input to.") + end + + local x, y, current_z = you.pos.x, you.pos.y, you.pos.z + + -- Show Up/Down/Cancel menu + local choices = { "Up", "Down", "Cancel" } + local ok, idx = script.showListPrompt( + "AutoPath", + string.format("Current z = %d. Which direction? (Cancel to exit)", current_z), + COLOR_WHITE, + choices, + nil, + true + ) + if not ok or idx == 3 then + return -- cancelled by user + end + + local goUp = (idx == 1) + local direction = goUp and "up" or "down" + + -- Determine scan range: Up scans from top down; Down scans from bottom up + local start_z, step, bound + if goUp then + start_z = map.z_count - 1 + step = -1 + bound = current_z + else + start_z = 0 + step = 1 + bound = current_z + end + + -- Popup to notify user not to press keys while running + dfgui.showPopupAnnouncement( + "Auto-path in progress... Please do not press any keys.", + COLOR_YELLOW + ) + + -- Iterate over z-levels synchronously + for z = start_z, bound, step do + -- Re-fetch pointers to ensure safety + you = world.units.adv_unit + if not you then + dfgui.showPopupAnnouncement( + "Error: Adventurer no longer found. Aborting auto-path.", + COLOR_RED + ) + return + end + + view = dfhack.gui.getCurViewscreen() + if not view then + dfgui.showPopupAnnouncement( + "Error: Viewscreeen unavailable. Aborting auto-path.", + COLOR_RED + ) + return + end + + -- Request path to (x, y, z) + you.path.dest.x = x + you.path.dest.y = y + you.path.dest.z = z + you.path.goal = 215 + + -- Simulate the OPTION1 (a) input (one-step move) This allows for the game to refresh you.path.path.x + gui.simulateInput(view, 'OPTION1') + + -- Wait for the step to be processed + script.sleep(delayFrames) + + local pd = you.path.path and you.path.path.x + local valid = pd and (#pd > 0) + if valid then + -- Commit to this step + you.path.dest.z = z + you.path.goal = 215 + local levels = math.abs(z - current_z) + dfgui.showPopupAnnouncement( + string.format("Auto-path %s %d levels.", direction, levels), + COLOR_GREEN + ) + return + end + end + + -- No valid path found + dfgui.showPopupAnnouncement( + string.format("No available auto-path %s from your position.", direction), + COLOR_RED + ) +end) From c1ab6b42b5d4dd16980e9f837ddfeb2bfdaa9e15 Mon Sep 17 00:00:00 2001 From: unboundlopez <47876628+unboundlopez@users.noreply.github.com> Date: Tue, 10 Jun 2025 17:07:11 -0500 Subject: [PATCH 2/6] Update z-adv-path-up-down.rst --- docs/z-adv-path-up-down.rst | 25 ------------------------- 1 file changed, 25 deletions(-) diff --git a/docs/z-adv-path-up-down.rst b/docs/z-adv-path-up-down.rst index b713b50c9..a290d5c4e 100644 --- a/docs/z-adv-path-up-down.rst +++ b/docs/z-adv-path-up-down.rst @@ -24,28 +24,3 @@ Run from the DFHack Lua console while in **Adventurer** mode: 2. Select **Up** to auto-path one level above your current Z; **Down** to auto-path one level below. 3. A “please do not press any keys” popup displays while the script works. 4. On success, a confirmation popup shows how many levels you moved; on failure, an error popup appears. - -Requirements ------------- -- DFHack 0.47.04 or later -- Modules: - - :mod:`gui.script` - - :mod:`dfhack.gui` -- Must be in **Adventurer** mode (i.e. `world.units.adv_unit` exists) -- A valid viewscreen to accept simulated input - -Example -------- - -.. code-block:: console - - [DFHack]# lua z-adv-path-up-down.lua - “Current z = 5. Which direction? (Cancel to exit)” - (Select “Up”) - “Auto-path in progress… Please do not press any keys.” - “Auto-path up 1 levels.” - -See Also --------- -- :mod:`gui.script` — synchronous scripting API -- :mod:`dfhack.gui` — popup announcement utilities From 616202cec2eefcb622418be6162b0331bdf828c4 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Tue, 10 Jun 2025 22:08:39 +0000 Subject: [PATCH 3/6] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/z-adv-path-up-down.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/z-adv-path-up-down.rst b/docs/z-adv-path-up-down.rst index a290d5c4e..accf65ffe 100644 --- a/docs/z-adv-path-up-down.rst +++ b/docs/z-adv-path-up-down.rst @@ -20,7 +20,7 @@ Run from the DFHack Lua console while in **Adventurer** mode: [DFHack]# lua z-adv-path-up-down.lua -1. You’ll be prompted with **Up**, **Down**, or **Cancel**. -2. Select **Up** to auto-path one level above your current Z; **Down** to auto-path one level below. -3. A “please do not press any keys” popup displays while the script works. +1. You’ll be prompted with **Up**, **Down**, or **Cancel**. +2. Select **Up** to auto-path one level above your current Z; **Down** to auto-path one level below. +3. A “please do not press any keys” popup displays while the script works. 4. On success, a confirmation popup shows how many levels you moved; on failure, an error popup appears. From 0f92ea40b70849302c50efb33988c9b84378cba6 Mon Sep 17 00:00:00 2001 From: unboundlopez <47876628+unboundlopez@users.noreply.github.com> Date: Tue, 10 Jun 2025 17:14:39 -0500 Subject: [PATCH 4/6] Update z-adv-path-up-down.lua I forgot to update the code before posting the PR --- z-adv-path-up-down.lua | 73 +++++++++++++++++------------------------- 1 file changed, 30 insertions(+), 43 deletions(-) diff --git a/z-adv-path-up-down.lua b/z-adv-path-up-down.lua index 99f0f86d1..d0161aafd 100644 --- a/z-adv-path-up-down.lua +++ b/z-adv-path-up-down.lua @@ -3,16 +3,15 @@ -- Presents an "Up/Down/Cancel" menu, then auto-paths one level at a time by simulating OPTION1 for each step, -- shows a popup at start and a separate popup on success or failure using showPopupAnnouncement. -local script = require('gui.script') -local gui = require('gui') -local dfgui = dfhack.gui -local world = df.global.world -local map = world.map +local script = require('gui.script') +local gui = require('gui') +local dfgui = dfhack.gui +local world = df.global.world +local map = world.map +local you = world.units.adv_unit local delayFrames = 10 -- frames to wait for each simulated step script.start(function() - -- Initial checks - local you = world.units.adv_unit if not you then qerror("Error: No adventurer unit found.") end @@ -59,22 +58,12 @@ script.start(function() COLOR_YELLOW ) - -- Iterate over z-levels synchronously - for z = start_z, bound, step do - -- Re-fetch pointers to ensure safety - you = world.units.adv_unit - if not you then + -- Recursive scan function + local function tryZ(z) + -- Bounds check: if passed bound without finding, fail + if (goUp and z < bound) or (not goUp and z > bound) then dfgui.showPopupAnnouncement( - "Error: Adventurer no longer found. Aborting auto-path.", - COLOR_RED - ) - return - end - - view = dfhack.gui.getCurViewscreen() - if not view then - dfgui.showPopupAnnouncement( - "Error: Viewscreeen unavailable. Aborting auto-path.", + string.format("No available auto-path %s from your position.", direction), COLOR_RED ) return @@ -86,30 +75,28 @@ script.start(function() you.path.dest.z = z you.path.goal = 215 - -- Simulate the OPTION1 (a) input (one-step move) This allows for the game to refresh you.path.path.x + -- Simulate the OPTION1 input (one-step move) gui.simulateInput(view, 'OPTION1') -- Wait for the step to be processed - script.sleep(delayFrames) - - local pd = you.path.path and you.path.path.x - local valid = pd and (#pd > 0) - if valid then - -- Commit to this step - you.path.dest.z = z - you.path.goal = 215 - local levels = math.abs(z - current_z) - dfgui.showPopupAnnouncement( - string.format("Auto-path %s %d levels.", direction, levels), - COLOR_GREEN - ) - return - end + dfhack.timeout(delayFrames, 'frames', function() + local pd = you.path.path and you.path.path.x + local valid = pd and (#pd > 0) + if valid then + -- Commit to this step + you.path.dest.z = z + you.path.goal = 215 + local levels = math.abs(z - current_z) + dfgui.showPopupAnnouncement( + string.format("Auto-path %s %d levels.", direction, levels), + COLOR_GREEN + ) + else + tryZ(z + step) + end + end) end - -- No valid path found - dfgui.showPopupAnnouncement( - string.format("No available auto-path %s from your position.", direction), - COLOR_RED - ) + -- Start scanning + tryZ(start_z) end) From 1aed8d35f5e656630b6f6b86e5cdbb975482c6e1 Mon Sep 17 00:00:00 2001 From: unboundlopez <47876628+unboundlopez@users.noreply.github.com> Date: Tue, 10 Jun 2025 21:09:40 -0500 Subject: [PATCH 5/6] Update z-adv-path-up-down.rst --- docs/z-adv-path-up-down.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/z-adv-path-up-down.rst b/docs/z-adv-path-up-down.rst index accf65ffe..76305b2bf 100644 --- a/docs/z-adv-path-up-down.rst +++ b/docs/z-adv-path-up-down.rst @@ -20,7 +20,7 @@ Run from the DFHack Lua console while in **Adventurer** mode: [DFHack]# lua z-adv-path-up-down.lua -1. You’ll be prompted with **Up**, **Down**, or **Cancel**. -2. Select **Up** to auto-path one level above your current Z; **Down** to auto-path one level below. -3. A “please do not press any keys” popup displays while the script works. +1. You’ll be prompted with **Up**, **Down**, or **Cancel**. +2. Select **Up** to auto-path to the highest level above your current Z; **Down** to auto-path to the lowest level. +3. A “please do not press any keys” popup displays while the script works. 4. On success, a confirmation popup shows how many levels you moved; on failure, an error popup appears. From 711e7cc37020c0835940ae0d15ea54b011ef54b9 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Wed, 11 Jun 2025 03:14:27 +0000 Subject: [PATCH 6/6] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/z-adv-path-up-down.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/z-adv-path-up-down.rst b/docs/z-adv-path-up-down.rst index 76305b2bf..10d08df4c 100644 --- a/docs/z-adv-path-up-down.rst +++ b/docs/z-adv-path-up-down.rst @@ -20,7 +20,7 @@ Run from the DFHack Lua console while in **Adventurer** mode: [DFHack]# lua z-adv-path-up-down.lua -1. You’ll be prompted with **Up**, **Down**, or **Cancel**. -2. Select **Up** to auto-path to the highest level above your current Z; **Down** to auto-path to the lowest level. -3. A “please do not press any keys” popup displays while the script works. +1. You’ll be prompted with **Up**, **Down**, or **Cancel**. +2. Select **Up** to auto-path to the highest level above your current Z; **Down** to auto-path to the lowest level. +3. A “please do not press any keys” popup displays while the script works. 4. On success, a confirmation popup shows how many levels you moved; on failure, an error popup appears.