From 4cacf13427f3a7a69cdb3920a99041b4821f3fda Mon Sep 17 00:00:00 2001 From: Squid Coder <92821989+realSquidCoder@users.noreply.github.com> Date: Sat, 12 Apr 2025 10:09:00 -0500 Subject: [PATCH 1/8] Update deathcause.lua make it more api-like --- deathcause.lua | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/deathcause.lua b/deathcause.lua index 953f36bd22..a735aee249 100644 --- a/deathcause.lua +++ b/deathcause.lua @@ -29,8 +29,7 @@ function displayDeathUnit(unit) str = str .. dfhack.units.getReadableName(unit) if not dfhack.units.isDead(unit) then - print(dfhack.df2console(str) .. " is not dead yet!") - return + return(dfhack.df2console(str) .. " is not dead yet!") end str = str .. (" %s"):format(getDeathStringFromCause(unit.counters.death_cause)) @@ -50,7 +49,7 @@ function displayDeathUnit(unit) end end - print(dfhack.df2console(str) .. '.') + return(dfhack.df2console(str) .. '.') end -- returns the item description if the item still exists; otherwise @@ -87,7 +86,7 @@ function displayDeathEventHistFigUnit(histfig_unit, event) end end - print(dfhack.df2console(str) .. '.') + return(dfhack.df2console(str) .. '.') end -- Returns the death event for the given histfig or nil if not found @@ -109,10 +108,10 @@ function displayDeathHistFig(histfig) end if not dfhack.units.isDead(histfig_unit) then - print(("%s is not dead yet!"):format(dfhack.df2console(dfhack.units.getReadableName(histfig_unit)))) + return(("%s is not dead yet!"):format(dfhack.df2console(dfhack.units.getReadableName(histfig_unit)))) else local death_event = getDeathEventForHistFig(histfig.id) - displayDeathEventHistFigUnit(histfig_unit, death_event) + return displayDeathEventHistFigUnit(histfig_unit, death_event) end end @@ -155,7 +154,7 @@ elseif hist_figure_id == -1 then if not selected_unit then qerror("Cause of death not available") end - displayDeathUnit(selected_unit) + print(displayDeathUnit(selected_unit)) else - displayDeathHistFig(df.historical_figure.find(hist_figure_id)) + print(displayDeathHistFig(df.historical_figure.find(hist_figure_id))) end From c4483b557f10c4c7c4a625badd4cb02cd572d1c3 Mon Sep 17 00:00:00 2001 From: Squid Coder <92821989+realSquidCoder@users.noreply.github.com> Date: Sat, 12 Apr 2025 10:20:03 -0500 Subject: [PATCH 2/8] Update deathcause.lua Remove the console formatting Signed-off-by: Squid Coder <92821989+realSquidCoder@users.noreply.github.com> --- deathcause.lua | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/deathcause.lua b/deathcause.lua index a735aee249..d07d62d866 100644 --- a/deathcause.lua +++ b/deathcause.lua @@ -29,7 +29,7 @@ function displayDeathUnit(unit) str = str .. dfhack.units.getReadableName(unit) if not dfhack.units.isDead(unit) then - return(dfhack.df2console(str) .. " is not dead yet!") + return(str .. " is not dead yet!") end str = str .. (" %s"):format(getDeathStringFromCause(unit.counters.death_cause)) @@ -49,7 +49,7 @@ function displayDeathUnit(unit) end end - return(dfhack.df2console(str) .. '.') + return(str .. '.') end -- returns the item description if the item still exists; otherwise @@ -86,7 +86,7 @@ function displayDeathEventHistFigUnit(histfig_unit, event) end end - return(dfhack.df2console(str) .. '.') + return( str .. '.') end -- Returns the death event for the given histfig or nil if not found @@ -108,7 +108,7 @@ function displayDeathHistFig(histfig) end if not dfhack.units.isDead(histfig_unit) then - return(("%s is not dead yet!"):format(dfhack.df2console(dfhack.units.getReadableName(histfig_unit)))) + return(("%s is not dead yet!"):format(dfhack.units.getReadableName(histfig_unit))) else local death_event = getDeathEventForHistFig(histfig.id) return displayDeathEventHistFigUnit(histfig_unit, death_event) From 2fb14b623074f9d4aeba73b2fb31feecc4e92fe8 Mon Sep 17 00:00:00 2001 From: Squid Coder <92821989+realSquidCoder@users.noreply.github.com> Date: Sat, 12 Apr 2025 10:23:48 -0500 Subject: [PATCH 3/8] Update deathcause.lua Format to keep old usage working Signed-off-by: Squid Coder <92821989+realSquidCoder@users.noreply.github.com> --- deathcause.lua | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/deathcause.lua b/deathcause.lua index d07d62d866..9ba2d73b34 100644 --- a/deathcause.lua +++ b/deathcause.lua @@ -154,7 +154,7 @@ elseif hist_figure_id == -1 then if not selected_unit then qerror("Cause of death not available") end - print(displayDeathUnit(selected_unit)) + print(dfhack.df2console(displayDeathUnit(selected_unit))) else - print(displayDeathHistFig(df.historical_figure.find(hist_figure_id))) + print(dfhack.df2console(displayDeathHistFig(df.historical_figure.find(hist_figure_id)))) end From cf4af78cc62114bdd478828d4573a0d05cabaf2b Mon Sep 17 00:00:00 2001 From: Squid Coder Date: Sat, 12 Apr 2025 17:25:10 -0500 Subject: [PATCH 4/8] Update deathcause.lua final fixes --- deathcause.lua | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/deathcause.lua b/deathcause.lua index 9ba2d73b34..d0a90dd6c9 100644 --- a/deathcause.lua +++ b/deathcause.lua @@ -1,4 +1,5 @@ -- show death cause of a creature +--@ module = true local DEATH_TYPES = reqscript('gui/unit-info-viewer').DEATH_TYPES @@ -29,7 +30,7 @@ function displayDeathUnit(unit) str = str .. dfhack.units.getReadableName(unit) if not dfhack.units.isDead(unit) then - return(str .. " is not dead yet!") + return str .. " is not dead yet!" end str = str .. (" %s"):format(getDeathStringFromCause(unit.counters.death_cause)) @@ -49,7 +50,7 @@ function displayDeathUnit(unit) end end - return(str .. '.') + return str .. '.' end -- returns the item description if the item still exists; otherwise @@ -86,7 +87,7 @@ function displayDeathEventHistFigUnit(histfig_unit, event) end end - return( str .. '.') + return str .. '.' end -- Returns the death event for the given histfig or nil if not found @@ -108,7 +109,7 @@ function displayDeathHistFig(histfig) end if not dfhack.units.isDead(histfig_unit) then - return(("%s is not dead yet!"):format(dfhack.units.getReadableName(histfig_unit))) + return ("%s is not dead yet!"):format(dfhack.units.getReadableName(histfig_unit)) else local death_event = getDeathEventForHistFig(histfig.id) return displayDeathEventHistFigUnit(histfig_unit, death_event) @@ -146,6 +147,10 @@ local function get_target() return selected_item.hist_figure_id, df.unit.find(selected_item.unit_id) end +if dfhack_flags.module then + return +end + local hist_figure_id, selected_unit = get_target() if not hist_figure_id then From add5d172d82b3d136529509a4963911694488975 Mon Sep 17 00:00:00 2001 From: Squid Coder Date: Sun, 13 Apr 2025 14:15:09 -0500 Subject: [PATCH 5/8] Update deathcause.lua --- deathcause.lua | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/deathcause.lua b/deathcause.lua index d0a90dd6c9..0ea44d24e7 100644 --- a/deathcause.lua +++ b/deathcause.lua @@ -4,7 +4,7 @@ local DEATH_TYPES = reqscript('gui/unit-info-viewer').DEATH_TYPES -- Gets the first corpse item at the given location -function getItemAtPosition(pos) +local function getItemAtPosition(pos) for _, item in ipairs(df.global.world.items.other.ANY_CORPSE) do if item.pos.x == pos.x and item.pos.y == pos.y and item.pos.z == pos.z then print("Automatically chose first corpse at the selected location.") @@ -13,11 +13,11 @@ function getItemAtPosition(pos) end end -function getRaceNameSingular(race_id) +local function getRaceNameSingular(race_id) return df.creature_raw.find(race_id).name[0] end -function getDeathStringFromCause(cause) +local function getDeathStringFromCause(cause) if cause == -1 then return "died" else @@ -25,7 +25,7 @@ function getDeathStringFromCause(cause) end end -function displayDeathUnit(unit) +function getDeathUnit(unit) local str = unit.name.has_name and '' or 'The ' str = str .. dfhack.units.getReadableName(unit) @@ -63,7 +63,7 @@ function getWeaponName(item_id, subtype) return dfhack.items.getDescription(item, 0, false) end -function displayDeathEventHistFigUnit(histfig_unit, event) +function getDeathEventHistFigUnit(histfig_unit, event) local str = ("The %s %s %s in year %d"):format( getRaceNameSingular(histfig_unit.race), dfhack.translation.translateName(dfhack.units.getVisibleName(histfig_unit)), @@ -102,7 +102,7 @@ function getDeathEventForHistFig(histfig_id) end end -function displayDeathHistFig(histfig) +function getDeathHistFig(histfig) local histfig_unit = df.unit.find(histfig.unit_id) if not histfig_unit then qerror("Cause of death not available") @@ -112,7 +112,7 @@ function displayDeathHistFig(histfig) return ("%s is not dead yet!"):format(dfhack.units.getReadableName(histfig_unit)) else local death_event = getDeathEventForHistFig(histfig.id) - return displayDeathEventHistFigUnit(histfig_unit, death_event) + return getDeathEventHistFigUnit(histfig_unit, death_event) end end @@ -159,7 +159,7 @@ elseif hist_figure_id == -1 then if not selected_unit then qerror("Cause of death not available") end - print(dfhack.df2console(displayDeathUnit(selected_unit))) + print(dfhack.df2console(getDeathUnit(selected_unit))) else - print(dfhack.df2console(displayDeathHistFig(df.historical_figure.find(hist_figure_id)))) + print(dfhack.df2console(getDeathHistFig(df.historical_figure.find(hist_figure_id)))) end From b86f9f03bdb8ca00afa17e6362ad18b4d7bd5ed4 Mon Sep 17 00:00:00 2001 From: Squid Coder Date: Fri, 18 Apr 2025 12:28:19 -0500 Subject: [PATCH 6/8] Update deathcause.lua localize some more functions and then rename the APIs and add comments --- deathcause.lua | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/deathcause.lua b/deathcause.lua index 0ea44d24e7..6c212821ac 100644 --- a/deathcause.lua +++ b/deathcause.lua @@ -25,7 +25,8 @@ local function getDeathStringFromCause(cause) end end -function getDeathUnit(unit) +-- Returns a cause of death given a unit +function getDeathCauseFromUnit(unit) local str = unit.name.has_name and '' or 'The ' str = str .. dfhack.units.getReadableName(unit) @@ -55,7 +56,7 @@ end -- returns the item description if the item still exists; otherwise -- returns the weapon name -function getWeaponName(item_id, subtype) +local function getWeaponName(item_id, subtype) local item = df.item.find(item_id) if not item then return df.global.world.raws.itemdefs.weapons[subtype].name @@ -63,7 +64,7 @@ function getWeaponName(item_id, subtype) return dfhack.items.getDescription(item, 0, false) end -function getDeathEventHistFigUnit(histfig_unit, event) +local function getDeathEventHistFigUnit(histfig_unit, event) local str = ("The %s %s %s in year %d"):format( getRaceNameSingular(histfig_unit.race), dfhack.translation.translateName(dfhack.units.getVisibleName(histfig_unit)), @@ -91,7 +92,7 @@ function getDeathEventHistFigUnit(histfig_unit, event) end -- Returns the death event for the given histfig or nil if not found -function getDeathEventForHistFig(histfig_id) +local function getDeathEventForHistFig(histfig_id) for i = #df.global.world.history.events - 1, 0, -1 do local event = df.global.world.history.events[i] if event:getType() == df.history_event_type.HIST_FIGURE_DIED then @@ -102,7 +103,8 @@ function getDeathEventForHistFig(histfig_id) end end -function getDeathHistFig(histfig) +-- Returns the cause of death given a histfig +function getDeathCauseFromHistFig(histfig) local histfig_unit = df.unit.find(histfig.unit_id) if not histfig_unit then qerror("Cause of death not available") @@ -159,7 +161,7 @@ elseif hist_figure_id == -1 then if not selected_unit then qerror("Cause of death not available") end - print(dfhack.df2console(getDeathUnit(selected_unit))) + print(dfhack.df2console(getDeathCauseFromUnit(selected_unit))) else - print(dfhack.df2console(getDeathHistFig(df.historical_figure.find(hist_figure_id)))) + print(dfhack.df2console(getDeathCauseFromHistFig(df.historical_figure.find(hist_figure_id)))) end From e8267fcbd4892d8120332ca466b77dd71c0970ac Mon Sep 17 00:00:00 2001 From: Squid Coder Date: Sat, 28 Jun 2025 17:27:21 -0500 Subject: [PATCH 7/8] Update changelog.txt --- changelog.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/changelog.txt b/changelog.txt index 9f0324d3aa..d669e7230b 100644 --- a/changelog.txt +++ b/changelog.txt @@ -29,6 +29,7 @@ Template for new versions: ## New Tools ## New Features +- `deathcause`: added functionality to this script to fetch cause of death programatically ## Fixes From 9f9ae7085b4d5d545e63d49ab26f683d97e9aa86 Mon Sep 17 00:00:00 2001 From: Squid Coder Date: Mon, 30 Jun 2025 12:19:30 -0500 Subject: [PATCH 8/8] add api docs --- docs/deathcause.rst | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/docs/deathcause.rst b/docs/deathcause.rst index c9a2ae0a06..20dddb11e6 100644 --- a/docs/deathcause.rst +++ b/docs/deathcause.rst @@ -14,3 +14,29 @@ Usage :: deathcause + +API +--- + +The ``deathcause`` script can be called programmatically by other scripts, either via the +commandline interface with ``dfhack.run_script()`` or via the API functions +defined in :source-scripts:`deathcause.lua`, available from the return value of +``reqscript('deathcause')``: + +* ``getDeathCauseFromHistFig(histfig)`` + +Returns a string with the historical figure's cause of death, sometimes with more information +than with a unit. + +* ``getDeathCauseFromUnit(unit)`` + +Returns a string with the unit's cause of death. + + API usage example:: + + local dc = reqscript('deathcause') + + -- Note: this is an arguably bad example because this is the same as running deathcause + -- from the launcher, but this would theoretically still work. + local deathReason = dc.getDeathCauseFromUnit(dfhack.gui.getSelectedUnit()) + print(deathReason)