From 8dc50e159a0d4959510dd4033d4f3f278f3f2219 Mon Sep 17 00:00:00 2001 From: unboundlopez <47876628+unboundlopez@users.noreply.github.com> Date: Sun, 25 Jan 2026 17:14:19 -0600 Subject: [PATCH 1/6] Document external TTS usage --- flavor-text.lua | 176 ++++++++++++++++++++++++++++++++++++++++++++++++ flavor-text.rst | 27 ++++++++ 2 files changed, 203 insertions(+) create mode 100644 flavor-text.lua create mode 100644 flavor-text.rst diff --git a/flavor-text.lua b/flavor-text.lua new file mode 100644 index 000000000..9d171e9b7 --- /dev/null +++ b/flavor-text.lua @@ -0,0 +1,176 @@ +-- Writes the currently viewed unit or item flavor text to a file. +-- +-- Usage: +-- flavor-text + +local folder = 'flavor text' +local filename = 'read flavor.txt' +local filepath = folder .. '/' .. filename + +local function clear_output_file() + local ok, err = pcall(dfhack.filesystem.mkdir_recursive, folder) + if not ok then + qerror(('Failed to create folder "%s": %s'):format(folder, err)) + end + local file, open_err = io.open(filepath, 'w') + if not file then + qerror(('Failed to open file "%s" for writing: %s'):format(filepath, open_err)) + end + file:write('') + file:close() +end + +local function reformat(str) + local cleaned = str:gsub('%[B%]', '') + :gsub('%[P%]', '') + :gsub('%[R%]', '') + :gsub('%[C:%d+:%d+:%d+%]', '') + :gsub('%s+', ' ') + :gsub('^%s+', '') + :gsub('%s+$', '') + return cleaned +end + +local function collect_lines(entries) + local lines = {} + for _, entry in ipairs(entries) do + if entry.value ~= '' then + local cleaned = reformat(dfhack.df2utf(entry.value)) + if cleaned ~= '' then + table.insert(lines, cleaned) + end + end + end + return lines +end + +local function get_health_text(view_sheets) + if #view_sheets.unit_health_raw_str == 0 then + return nil + end + local lines = collect_lines(view_sheets.unit_health_raw_str) + if #lines == 0 then + return nil + end + return table.concat(lines, '\n') +end + +local function get_personality_text(view_sheets) + if #view_sheets.personality_raw_str == 0 then + return nil + end + local lines = collect_lines(view_sheets.personality_raw_str) + if #lines == 0 then + return nil + end + return table.concat(lines, '\n') +end + +local UNIT_SHEET_SUBTAB = { + HEALTH = 2, + PERSONALITY = 10, +} + +local HEALTH_ACTIVE_TAB = { + STATUS = 0, + WOUNDS = 1, + TREATMENT = 2, + HISTORY = 3, + DESCRIPTION = 4, +} + +local PERSONALITY_ACTIVE_TAB = { + TRAITS = 0, + VALUES = 1, + PREFERENCES = 2, + NEEDS = 3, +} + +local function get_unit_flavor_text(view_sheets) + local unit = df.unit.find(view_sheets.active_id) + if not unit then + qerror('Unable to resolve the active unit.') + end + + if view_sheets.active_sub_tab == UNIT_SHEET_SUBTAB.HEALTH then + local health_text = get_health_text(view_sheets) + if health_text then + return unit, 'Health', health_text + end + clear_output_file() + qerror('No text found on the Health tab.') + end + + if view_sheets.active_sub_tab == UNIT_SHEET_SUBTAB.PERSONALITY + and (view_sheets.personality_active_tab == PERSONALITY_ACTIVE_TAB.TRAITS + or view_sheets.personality_active_tab == PERSONALITY_ACTIVE_TAB.VALUES + or view_sheets.personality_active_tab == PERSONALITY_ACTIVE_TAB.PREFERENCES + or view_sheets.personality_active_tab == PERSONALITY_ACTIVE_TAB.NEEDS) + then + local text = get_personality_text(view_sheets) + if text then + return unit, 'Personality', text + end + clear_output_file() + qerror('No text found on the Personality subtab (Traits/Values/Preferences/Needs).') + end + + clear_output_file() + qerror('Open Health, Personality or an item window before running this script.') +end + +local function get_item_flavor_text(view_sheets) + local item = dfhack.gui.getSelectedItem(true) + if not item then + qerror('Select an item or open an item view sheet before running this script.') + end + + local description = view_sheets.raw_description or '' + if description == '' then + qerror('No item description text found on the item view sheet.') + end + + return item, 'Item', reformat(dfhack.df2utf(description)) +end + +local view_sheets = df.global.game.main_interface.view_sheets +if not view_sheets.open then + clear_output_file() + qerror('Open a unit or item view sheet before running this script.') +end + +local screen = dfhack.gui.getDFViewscreen() +local is_unit_sheet = dfhack.gui.matchFocusString('dwarfmode/ViewSheets/UNIT', screen) +local is_item_sheet = dfhack.gui.matchFocusString('dwarfmode/ViewSheets/ITEM', screen) + +local subject, flavor_type, text +if is_unit_sheet then + subject, flavor_type, text = get_unit_flavor_text(view_sheets) +elseif is_item_sheet then + subject, flavor_type, text = get_item_flavor_text(view_sheets) +else + clear_output_file() + qerror('Open a unit or item view sheet before running this script.') +end + +local ok, err = pcall(dfhack.filesystem.mkdir_recursive, folder) +if not ok then + qerror(('Failed to create folder "%s": %s'):format(folder, err)) +end + +local file, open_err = io.open(filepath, 'w') +if not file then + qerror(('Failed to open file "%s" for writing: %s'):format(filepath, open_err)) +end + +file:write(text) +file:close() + +local name +if is_unit_sheet then + name = dfhack.df2console(dfhack.units.getReadableName(subject)) +else + name = dfhack.df2console(dfhack.items.getDescription(subject, 0, true)) +end + +print(('Wrote %s flavor text for %s to "%s".'):format(flavor_type, name, filepath)) diff --git a/flavor-text.rst b/flavor-text.rst new file mode 100644 index 000000000..9a6a5a4c0 --- /dev/null +++ b/flavor-text.rst @@ -0,0 +1,27 @@ +flavor-text +=========== + +Overview +-------- +The ``flavor-text`` script writes the currently viewed unit or item flavor text to +``flavor text/read flavor.txt``. + +Usage +----- +Run the script from DFHack: + +:: + + flavor-text + +Notes +----- +- The file is overwritten each time the script runs. +- If the wrong window is open, the script clears the output file. +- Supported unit tabs: + - Health (Status/Wounds/Treatment/History/Description) + - Personality (Traits/Values/Preferences/Needs) +- Supported item window: item view sheets. +- You must use your own text-to-speech (TTS) program to read the output. + On Windows 11, Voice Attack works well, and a profile with the launch command + can be included for others to use. From b2c63f5fb4f46110f927174de372ba9ee172c617 Mon Sep 17 00:00:00 2001 From: unboundlopez <47876628+unboundlopez@users.noreply.github.com> Date: Sun, 25 Jan 2026 17:25:08 -0600 Subject: [PATCH 2/6] Delete flavor-text.lua --- flavor-text.lua | 176 ------------------------------------------------ 1 file changed, 176 deletions(-) delete mode 100644 flavor-text.lua diff --git a/flavor-text.lua b/flavor-text.lua deleted file mode 100644 index 9d171e9b7..000000000 --- a/flavor-text.lua +++ /dev/null @@ -1,176 +0,0 @@ --- Writes the currently viewed unit or item flavor text to a file. --- --- Usage: --- flavor-text - -local folder = 'flavor text' -local filename = 'read flavor.txt' -local filepath = folder .. '/' .. filename - -local function clear_output_file() - local ok, err = pcall(dfhack.filesystem.mkdir_recursive, folder) - if not ok then - qerror(('Failed to create folder "%s": %s'):format(folder, err)) - end - local file, open_err = io.open(filepath, 'w') - if not file then - qerror(('Failed to open file "%s" for writing: %s'):format(filepath, open_err)) - end - file:write('') - file:close() -end - -local function reformat(str) - local cleaned = str:gsub('%[B%]', '') - :gsub('%[P%]', '') - :gsub('%[R%]', '') - :gsub('%[C:%d+:%d+:%d+%]', '') - :gsub('%s+', ' ') - :gsub('^%s+', '') - :gsub('%s+$', '') - return cleaned -end - -local function collect_lines(entries) - local lines = {} - for _, entry in ipairs(entries) do - if entry.value ~= '' then - local cleaned = reformat(dfhack.df2utf(entry.value)) - if cleaned ~= '' then - table.insert(lines, cleaned) - end - end - end - return lines -end - -local function get_health_text(view_sheets) - if #view_sheets.unit_health_raw_str == 0 then - return nil - end - local lines = collect_lines(view_sheets.unit_health_raw_str) - if #lines == 0 then - return nil - end - return table.concat(lines, '\n') -end - -local function get_personality_text(view_sheets) - if #view_sheets.personality_raw_str == 0 then - return nil - end - local lines = collect_lines(view_sheets.personality_raw_str) - if #lines == 0 then - return nil - end - return table.concat(lines, '\n') -end - -local UNIT_SHEET_SUBTAB = { - HEALTH = 2, - PERSONALITY = 10, -} - -local HEALTH_ACTIVE_TAB = { - STATUS = 0, - WOUNDS = 1, - TREATMENT = 2, - HISTORY = 3, - DESCRIPTION = 4, -} - -local PERSONALITY_ACTIVE_TAB = { - TRAITS = 0, - VALUES = 1, - PREFERENCES = 2, - NEEDS = 3, -} - -local function get_unit_flavor_text(view_sheets) - local unit = df.unit.find(view_sheets.active_id) - if not unit then - qerror('Unable to resolve the active unit.') - end - - if view_sheets.active_sub_tab == UNIT_SHEET_SUBTAB.HEALTH then - local health_text = get_health_text(view_sheets) - if health_text then - return unit, 'Health', health_text - end - clear_output_file() - qerror('No text found on the Health tab.') - end - - if view_sheets.active_sub_tab == UNIT_SHEET_SUBTAB.PERSONALITY - and (view_sheets.personality_active_tab == PERSONALITY_ACTIVE_TAB.TRAITS - or view_sheets.personality_active_tab == PERSONALITY_ACTIVE_TAB.VALUES - or view_sheets.personality_active_tab == PERSONALITY_ACTIVE_TAB.PREFERENCES - or view_sheets.personality_active_tab == PERSONALITY_ACTIVE_TAB.NEEDS) - then - local text = get_personality_text(view_sheets) - if text then - return unit, 'Personality', text - end - clear_output_file() - qerror('No text found on the Personality subtab (Traits/Values/Preferences/Needs).') - end - - clear_output_file() - qerror('Open Health, Personality or an item window before running this script.') -end - -local function get_item_flavor_text(view_sheets) - local item = dfhack.gui.getSelectedItem(true) - if not item then - qerror('Select an item or open an item view sheet before running this script.') - end - - local description = view_sheets.raw_description or '' - if description == '' then - qerror('No item description text found on the item view sheet.') - end - - return item, 'Item', reformat(dfhack.df2utf(description)) -end - -local view_sheets = df.global.game.main_interface.view_sheets -if not view_sheets.open then - clear_output_file() - qerror('Open a unit or item view sheet before running this script.') -end - -local screen = dfhack.gui.getDFViewscreen() -local is_unit_sheet = dfhack.gui.matchFocusString('dwarfmode/ViewSheets/UNIT', screen) -local is_item_sheet = dfhack.gui.matchFocusString('dwarfmode/ViewSheets/ITEM', screen) - -local subject, flavor_type, text -if is_unit_sheet then - subject, flavor_type, text = get_unit_flavor_text(view_sheets) -elseif is_item_sheet then - subject, flavor_type, text = get_item_flavor_text(view_sheets) -else - clear_output_file() - qerror('Open a unit or item view sheet before running this script.') -end - -local ok, err = pcall(dfhack.filesystem.mkdir_recursive, folder) -if not ok then - qerror(('Failed to create folder "%s": %s'):format(folder, err)) -end - -local file, open_err = io.open(filepath, 'w') -if not file then - qerror(('Failed to open file "%s" for writing: %s'):format(filepath, open_err)) -end - -file:write(text) -file:close() - -local name -if is_unit_sheet then - name = dfhack.df2console(dfhack.units.getReadableName(subject)) -else - name = dfhack.df2console(dfhack.items.getDescription(subject, 0, true)) -end - -print(('Wrote %s flavor text for %s to "%s".'):format(flavor_type, name, filepath)) From 178cfe15e16dc9baf1a5591bdca5b6d9590931b2 Mon Sep 17 00:00:00 2001 From: unboundlopez <47876628+unboundlopez@users.noreply.github.com> Date: Sun, 25 Jan 2026 17:25:24 -0600 Subject: [PATCH 3/6] Delete flavor-text.rst --- flavor-text.rst | 27 --------------------------- 1 file changed, 27 deletions(-) delete mode 100644 flavor-text.rst diff --git a/flavor-text.rst b/flavor-text.rst deleted file mode 100644 index 9a6a5a4c0..000000000 --- a/flavor-text.rst +++ /dev/null @@ -1,27 +0,0 @@ -flavor-text -=========== - -Overview --------- -The ``flavor-text`` script writes the currently viewed unit or item flavor text to -``flavor text/read flavor.txt``. - -Usage ------ -Run the script from DFHack: - -:: - - flavor-text - -Notes ------ -- The file is overwritten each time the script runs. -- If the wrong window is open, the script clears the output file. -- Supported unit tabs: - - Health (Status/Wounds/Treatment/History/Description) - - Personality (Traits/Values/Preferences/Needs) -- Supported item window: item view sheets. -- You must use your own text-to-speech (TTS) program to read the output. - On Windows 11, Voice Attack works well, and a profile with the launch command - can be included for others to use. From 251888749328437202fd217df7cf69636d4636a8 Mon Sep 17 00:00:00 2001 From: unboundlopez <47876628+unboundlopez@users.noreply.github.com> Date: Mon, 26 Jan 2026 22:22:27 -0600 Subject: [PATCH 4/6] Create door-toggle.rst --- docs/door-toggle.rst | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 docs/door-toggle.rst diff --git a/docs/door-toggle.rst b/docs/door-toggle.rst new file mode 100644 index 000000000..319a36b36 --- /dev/null +++ b/docs/door-toggle.rst @@ -0,0 +1,35 @@ +Door Toggle +=========== + +``door-toggle`` is a DFHack Lua tool that bulk locks or unlocks doors and +hatches within a rectangular area. It opens a small GUI where you choose a +mode and then select two corners on the map to apply the action to all targets +in that rectangle. + +Usage +----- + +- ``door-toggle`` + Opens the GUI and waits for the user to pick two corners. +- ``door-toggle lock`` + Opens the GUI with the mode set to lock. +- ``door-toggle open`` + Opens the GUI with the mode set to unlock. + +Behavior +-------- + +- The first click sets the starting corner. +- Moving the mouse shows a live preview of the rectangle to be processed. +- The second click applies the action to any doors or hatches within the + rectangle on the current z-level. +- Right-click clears the first corner if already set, or closes the tool if + no corner is active. + +Notes +----- + +- Locking is implemented by setting the building's ``door_flags.forbidden`` + to ``true``. Unlocking clears that flag. +- The tool keeps selection mode active by default so you can perform multiple + selections without reopening the UI. From d5f919dc0c1f80c33643f0dfede6f20b214cca36 Mon Sep 17 00:00:00 2001 From: unboundlopez <47876628+unboundlopez@users.noreply.github.com> Date: Mon, 26 Jan 2026 22:27:09 -0600 Subject: [PATCH 5/6] Add files via upload --- door-toggle.lua | 250 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 250 insertions(+) create mode 100644 door-toggle.lua diff --git a/door-toggle.lua b/door-toggle.lua new file mode 100644 index 000000000..c4af8b6c0 --- /dev/null +++ b/door-toggle.lua @@ -0,0 +1,250 @@ +-- door-toggle.lua +-- DFHack tool: bulk lock/unlock doors and hatches in a selected rectangle +-- Usage: +-- door-toggle -> opens GUI +-- door-toggle lock -> preselect lock, start selection +-- door-toggle open -> preselect unlock, start selection + +local gui = require('gui') +local guidm = require('gui.dwarfmode') +local widgets = require('gui.widgets') + +-- ============================= +-- Core logic +-- ============================= + +local function bounds_from(pos1, pos2) + return { + x1=math.min(pos1.x, pos2.x), + x2=math.max(pos1.x, pos2.x), + y1=math.min(pos1.y, pos2.y), + y2=math.max(pos1.y, pos2.y), + z1=math.min(pos1.z, pos2.z), + z2=math.max(pos1.z, pos2.z), + } +end + +local function is_pos_in_bounds(pos, b) + return pos.x >= b.x1 and pos.x <= b.x2 + and pos.y >= b.y1 and pos.y <= b.y2 + and pos.z >= b.z1 and pos.z <= b.z2 +end + +local function is_toggle_target(bld) + local t = bld:getType() + return t == df.building_type.Door or t == df.building_type.Hatch +end + +local function apply_to_doors_in_rect(pos1, pos2, mode) + local b = bounds_from(pos1, pos2) + local changed = 0 + local skipped = 0 + + for _, bld in ipairs(df.global.world.buildings.all) do + if is_toggle_target(bld) then + local pos = {x=bld.centerx, y=bld.centery, z=bld.z} + if is_pos_in_bounds(pos, b) then + if bld.door_flags then + if mode == 'lock' then + bld.door_flags.forbidden = true + else -- mode == 'open' + bld.door_flags.forbidden = false + end + end + changed = changed + 1 + else + skipped = skipped + 1 + end + end + end + + return changed, skipped +end + +local function get_action_text(mark) + local str = mark and 'opposite' or 'first' + return ('Select the %s corner with the mouse.'):format(str) +end + +-- ============================= +-- Preview overlay +-- ============================= + +local to_pen = dfhack.pen.parse +local SELECTION_PEN = to_pen{ + tile=dfhack.screen.findGraphicsTile('CURSORS', 1, 2), +} + +-- ============================= +-- Window +-- ============================= + +DoorToggleWindow = defclass(DoorToggleWindow, widgets.Window) +DoorToggleWindow.ATTRS{ + frame_title='Door Toggle', + frame={w=44, h=13, r=2, t=18}, + resizable=true, + autoarrange_subviews=true, + autoarrange_gap=1, + mode='lock', + status_text='', + selecting=true, + mark=nil, + on_cancel=DEFAULT_NIL, +} + +function DoorToggleWindow:init() + if self.status_text == '' then + self.status_text = 'Select the first corner with the mouse.' + end + self:addviews{ + widgets.WrappedLabel{ + view_id='status', + text_to_wrap=function() return self.status_text end, + }, + widgets.CycleHotkeyLabel{ + view_id='mode', + label='Mode:', + key='CUSTOM_S', + options={ + {label='Lock', value='lock', pen=COLOR_RED}, + {label='Unlock', value='open', pen=COLOR_GREEN}, + }, + initial_option=(self.mode == 'open') and 2 or 1, + }, + widgets.HotkeyLabel{ + label='Cancel', + key='LEAVESCREEN', + on_activate=function() + if self.on_cancel then self.on_cancel() end + end, + }, + widgets.WrappedLabel{ + text_to_wrap=function() + if not self.selecting then return '' end + return get_action_text(self.mark) + end, + pen=COLOR_LIGHTCYAN, + }, + } +end + +function DoorToggleWindow:onInput(keys) + if DoorToggleWindow.super.onInput(self, keys) then return true end + + if keys.LEAVESCREEN then + if self.on_cancel then self.on_cancel() end + return true + end + + if keys._MOUSE_R then + if self.mark then + self.mark = nil + self.status_text = 'Select the first corner with the mouse.' + self:updateLayout() + return true + end + if self.on_cancel then self.on_cancel() end + return true + end + self.selecting = true + + local pos = nil + if keys._MOUSE_L and not self:getMouseFramePos() then + pos = dfhack.gui.getMousePos() + end + if not pos then return false end + + if self.mark then + local mode = self.subviews.mode:getOptionValue() + local changed, skipped = apply_to_doors_in_rect(self.mark, pos, mode) + self.status_text = string.format( + '%s %d doors/hatches.', + (mode == 'lock') and 'Locked' or 'Unlocked', + changed + ) + self.mark = nil + self:updateLayout() + else + self.mark = pos + self.status_text = get_action_text(self.mark) + self:updateLayout() + end + + return true +end + +-- ============================= +-- Screen +-- ============================= + +DoorToggleScreen = defclass(DoorToggleScreen, gui.ZScreen) +DoorToggleScreen.ATTRS{ + focus_path='door-toggle', + pass_movement_keys=true, + pass_mouse_clicks=false, + mode='lock', + start_selection=false, +} + +function DoorToggleScreen:init() + local screen = self + self.window = DoorToggleWindow{ + mode=self.mode, + on_cancel=function() screen:dismiss() end, + } + self:addviews{self.window} + if self.start_selection then + self.window.selecting = true + self.window.status_text = 'Select the first corner with the mouse.' + self.window:updateLayout() + end +end + +function DoorToggleScreen:onRenderFrame(dc, rect) + DoorToggleScreen.super.onRenderFrame(self, dc, rect) + + if not dfhack.screen.inGraphicsMode() and not gui.blink_visible(500) then + return + end + + if not self.window then return end + if not self.window.selecting or not self.window.mark then return end + if self.window:getMouseFramePos() then return end + + local mouse_pos = dfhack.gui.getMousePos() + if not mouse_pos then return end + + local start_pos = self.window.mark + local preview_pos = {x=mouse_pos.x, y=mouse_pos.y, z=start_pos.z} + local bounds = bounds_from(start_pos, preview_pos) + bounds.z1 = start_pos.z + bounds.z2 = start_pos.z + + local function get_overlay_pen(pos) + if is_pos_in_bounds(pos, bounds) then + return SELECTION_PEN + end + end + + guidm.renderMapOverlay(get_overlay_pen, bounds) +end + +-- ============================= +-- Entrypoint +-- ============================= + +local args = {...} + +local function start_gui_with_mode(mode, start_selection) + local screen = DoorToggleScreen{mode=mode or 'lock', start_selection=start_selection} + dfhack.screen.show(screen) +end + +if #args == 0 then + start_gui_with_mode('lock', false) +elseif args[1] == 'lock' or args[1] == 'open' then + start_gui_with_mode(args[1], true) +else + qerror('Usage: door-toggle [lock|open]') +end From d038db533f99ebb365cbb3be5cba4b644d72b598 Mon Sep 17 00:00:00 2001 From: unboundlopez <47876628+unboundlopez@users.noreply.github.com> Date: Mon, 26 Jan 2026 22:27:24 -0600 Subject: [PATCH 6/6] Add files via upload