Merge remote-tracking branch 'upstream/develop' into SquidHack

Author: realSquidCoder

docs/about/Authors.rst

@@ -43,6 +43,7 @@ Cameron Ewell           Ozzatron
 Carter Bray             Qartar
 Chris Dombroski         cdombroski
 Chris Parsons           chrismdp
+Christian Doczkal       chdoc
 cjhammel                cjhammel
 Clayton Hughes
 Clément Vuchener        cvuchener

docs/changelog.txt

@@ -55,16 +55,23 @@ Template for new versions:
 
 ## New Features
 
+- `nestboxes`: allow limiting egg protection to nestboxes inside a designated burrow
+
 ## Fixes
+- ``Units::getReadableName`` will no longer append a comma to the names of histfigs with no profession
 
 ## Misc Improvements
 
 ## Documentation
 
 ## API
+- ``Job``: new functions ``createLinked`` and ``assignToWorkshop``
+- ``Units``: new functions ``getFocusPenalty``, ``unbailableSocialActivity``, ``isJobAvailable``
 
 ## Lua
 
+- New functions: ``dfhack.jobs.createLinked``, ``dfhack.jobs.assignToWorkshop``, ``dfhack.units.getFocusPenalty``, ``dfhack.units.unbailableSocialActivity``, and ``dfhack.units.isJobAvailable``
+
 ## Removed
 
 # 52.03-r1.1
@@ -100,6 +107,7 @@ Template for new versions:
 ## Documentation
 
 ## API
+- Adjusted the logic inside ``Military::removeFromSquad`` to more closely match the game's own behavior
 
 ## Lua
 
@@ -165,6 +173,7 @@ Template for new versions:
 ## API
 
 ## Lua
+- ``widgets.Slider``: new mouse-controlled single-headed slider widget
 
 ## Removed
 

docs/dev/Lua API.rst

@@ -1313,6 +1313,10 @@ Job module
 
   Creates a deep copy of the given job.
 
+* ``dfhack.job.createLinked()``
+
+  Create a job and immediately link it into the global job list.
+
 * ``dfhack.job.printJobDetails(job)``
 
   Prints info about the job.
@@ -1338,6 +1342,12 @@ Job module
 
   Searches for a specific_ref with the given type.
 
+* ``dfhack.job.assignToWorkshop(job, workshop)``
+
+  Assign job to workshop (i.e. establish the bidirectional link between the job
+  and the workshop). Does nothing and returns ``false`` if the workshop already
+  has the maximum of ten jobs.
+
 * ``dfhack.job.getHolder(job)``
 
   Returns the building holding the job.
@@ -1628,7 +1638,7 @@ Units module
   Returns true if the unit is within a box defined by the
   specified coordinates.
 
-``dfhack.units.getUnitsInBox(pos1, pos2[, filter])``
+* ``dfhack.units.getUnitsInBox(pos1, pos2[, filter])``
 * ``dfhack.units.getUnitsInBox(x1,y1,z1,x2,y2,z2[,filter])``
 
   Returns a table of all units within the specified coordinates.
@@ -1894,6 +1904,22 @@ Units module
   Return the ``df.activity_entry`` or ``df.activity_event`` representing the
   unit's current social activity.
 
+* ``dfhack.units.hasUnbailableSocialActivity(unit)``
+
+  Unit has an uninterruptible social activity (e.g. a purple "Socialize!").
+
+* ``dfhack.units.isJobAvailable(unit [, interrupt_social])``
+
+  Check whether a unit can be assigned to (i.e. is looking for) a job. Will
+  return ``true`` if the unit is engaged in "green" social activities, unless
+  the boolean ``interrupt_social`` is true.
+
+* ``dfhack.units.getFocusPenalty(unit, need_type [, need_type, ...])``
+
+  Get largest (i.e. most negative) focus penalty associated to a collection of
+  ``df.need_type`` arguments. Returns a number strictly greater than 400 if the
+  unit does not have any of the requested needs.
+
 * ``dfhack.units.getStressCategory(unit)``
 
   Returns a number from 0-6 indicating stress. 0 is most stressed; 6 is least.
@@ -6515,10 +6541,24 @@ change, the ``RangeSlider`` appearance will adjust automatically.
 :get_left_idx_fn: The function used by the RangeSlider to get the notch index on which
                   to display the left handle.
 :get_right_idx_fn: The function used by the RangeSlider to get the notch index on which
-                   to display the right handle.
+                  to display the right handle.
 :on_left_change: Callback executed when moving the left handle.
 :on_right_change: Callback executed when moving the right handle.
 
+Slider class
+-----------------
+
+This widget implements a mouse-interactable slider. The player can move the handle to
+set the value of the slider. The parent widget owns the slider value, and can control
+it independently (e.g., with a ``CycleHotkeyLabel``). If the value changes, the ``Slider``
+appearance will adjust automatically.
+
+:num_stops: Used to specify the number of "notches" in the slider, the places
+            where the handle can stop. (This should match the parents' number of options.)
+:get_idx_fn: The function used by the Slider to get the notch index on which
+                  to display the handle.
+:on_change: Callback executed when moving the handle.
+
 DimensionsTooltip class
 -----------------------
 

docs/plugins/nestboxes.rst

@@ -10,9 +10,16 @@ This plugin will automatically scan for and forbid fertile eggs incubating in a
 nestbox so that dwarves won't come to collect them for eating. The eggs will
 hatch normally, even when forbidden.
 
+You can control which eggs are collected and which eggs are protected by placing
+the nestboxes whose contents should be protected inside a burrow and running
+``nestboxes burrow <burrow_name>``. The default behavior of protecting all
+fertile eggs in nest boxes can be reestablished by running ``nestboxes all``.
+
 Usage
 -----
 
 ::
 
     enable nestboxes
+    nestboxes burrow <burrow_name>
+    nestbox all

docs/plugins/orders.rst

@@ -151,7 +151,7 @@ game does not provide sufficient order conditions. Please enable ``automilk``,
 types of jobs.
 
 Note that the jugs are specifically made out of wood. This is so, as long as
-you don't may any other "Tools" out of wood, you can have a stockpile just for
+you don't make any other "Tools" out of wood, you can have a stockpile just for
 jugs by restricting a finished goods stockpile to only take wooden tools.
 
 Armok's additional note: "shleggings? Yes,

library/LuaApi.cpp

@@ -69,6 +69,7 @@ distribution.
 #include "df/building_civzonest.h"
 #include "df/building_stockpilest.h"
 #include "df/building_tradedepotst.h"
+#include "df/building_workshopst.h"
 #include "df/burrow.h"
 #include "df/caravan_state.h"
 #include "df/construction.h"
@@ -116,6 +117,7 @@ distribution.
 #include <string>
 #include <vector>
 #include <filesystem>
+#include <stdexcept>
 
 namespace DFHack {
     DBG_DECLARE(core, luaapi, DebugCategory::LINFO);
@@ -629,7 +631,7 @@ void Lua::Push(lua_State *L, const Screen::Pen &info)
         return;
     }
 
-    new (L) Pen(info);
+    Lua::make_lua_userdata<Pen>(L, info);
 
     lua_rawgetp(L, LUA_REGISTRYINDEX, &DFHACK_PEN_TOKEN);
     lua_setmetatable(L, -2);
@@ -1128,7 +1130,7 @@ static int dfhack_random_init(lua_State *L)
 
 static int dfhack_random_new(lua_State *L)
 {
-    new (L) MersenneRNG();
+    Lua::make_lua_userdata<MersenneRNG>(L);
 
     lua_rawgetp(L, LUA_REGISTRYINDEX, &DFHACK_RANDOM_TOKEN);
     lua_setmetatable(L, -2);
@@ -1212,19 +1214,19 @@ static int dfhack_random_perlin(lua_State *L)
     switch (size)
     {
         case 1: {
-            auto pdata = new (L) PerlinNoise1D<float>();
+            auto pdata = Lua::make_lua_userdata<PerlinNoise1D<float>>(L);
             pdata->init(*prng);
             lua_pushcclosure(L, eval_perlin_1, 1);
             break;
         }
         case 2: {
-            auto pdata = new (L) PerlinNoise2D<float>();
+            auto pdata = Lua::make_lua_userdata<PerlinNoise2D<float>>(L);
             pdata->init(*prng);
             lua_pushcclosure(L, eval_perlin_2, 1);
             break;
         }
         case 3: {
-            auto pdata = new (L) PerlinNoise3D<float>();
+            auto pdata = Lua::make_lua_userdata<PerlinNoise3D<float>>(L);
             pdata->init(*prng);
             lua_pushcclosure(L, eval_perlin_3, 1);
             break;
@@ -1903,6 +1905,8 @@ static const LuaWrapper::FunctionReg dfhack_job_module[] = {
     WRAPM(Job,disconnectJobItem),
     WRAPM(Job,disconnectJobGeneralRef),
     WRAPM(Job,removeJob),
+    WRAPM(Job,createLinked),
+    WRAPM(Job,assignToWorkshop),
     WRAPN(is_equal, jobEqual),
     WRAPN(is_item_equal, jobItemEqual),
     { NULL, NULL }
@@ -2129,6 +2133,8 @@ static const LuaWrapper::FunctionReg dfhack_units_module[] = {
     WRAPM(Units, setGroupActionTimers),
     WRAPM(Units, getUnitByNobleRole),
     WRAPM(Units, unassignTrainer),
+    WRAPM(Units, hasUnbailableSocialActivity),
+    WRAPM(Units, isJobAvailable),
     { NULL, NULL }
 };
 
@@ -2322,6 +2328,25 @@ static int units_getProfessionName(lua_State *L) {
     return 1;
 }
 
+int32_t units_getFocusPenalty(lua_State *L) {
+  auto unit = Lua::GetDFObject<df::unit>(L, 1);
+  Units::need_type_set needs;
+  auto top = lua_gettop(L);
+  if (top < 2) {
+    luaL_argerror(L, 2, "Expected at least one need type");
+  } else {
+    for (int i = 2; i <= top; ++i) {
+      try {
+        needs.set(luaL_checkint(L, i));
+      } catch ([[maybe_unused]] const std::out_of_range &e) {
+        luaL_argerror(L, i, "Expected a need type");
+      }
+    }
+    Lua::Push(L, Units::getFocusPenalty(unit, needs));
+  }
+  return 1;
+}
+
 static const luaL_Reg dfhack_units_funcs[] = {
     { "getPosition", units_getPosition },
     { "getOuterContainerRef", units_getOuterContainerRef },
@@ -2336,6 +2361,7 @@ static const luaL_Reg dfhack_units_funcs[] = {
     { "getReadableName", units_getReadablename },
     { "getVisibleName", units_getVisibleName },
     { "getProfessionName", units_getProfessionName },
+    { "getFocusPenalty", units_getFocusPenalty },
     { NULL, NULL }
 };
 

library/LuaWrapper.cpp

@@ -168,12 +168,15 @@ static void BuildTypeMetatable(lua_State *state, const type_identity *type);
 void LuaWrapper::push_object_ref(lua_State *state, void *ptr)
 {
     // stack: [metatable]
-    auto ref = (DFRefHeader*)lua_newuserdata(state, sizeof(DFRefHeader));
-    ref->ptr = ptr;
-    ref->field_info = NULL;
-    ref->tag_ptr = NULL;
-    ref->tag_identity = NULL;
-    ref->tag_attr = NULL;
+    void* stg = lua_newuserdata(state, sizeof(DFRefHeader));
+    new (stg) DFRefHeader
+    {
+        .ptr = ptr,
+        .field_info = NULL,
+        .tag_ptr = NULL,
+        .tag_identity = NULL,
+        .tag_attr = NULL,
+    };
 
     lua_swap(state);
     lua_setmetatable(state, -2);

library/include/LuaTools.h

@@ -44,11 +44,6 @@ distribution.
 #include <lua.h>
 #include <lauxlib.h>
 
-/// Allocate a new user data object and push it on the stack
-inline void *operator new (std::size_t size, lua_State *L) {
-    return lua_newuserdata(L, size);
-}
-
 namespace DFHack {
     class function_identity_base;
     struct MaterialInfo;
@@ -67,6 +62,20 @@ namespace DFHack::Lua {
      */
     DFHACK_EXPORT lua_State *Open(color_ostream &out, lua_State *state = NULL);
 
+    /**
+     * Allocate a lua userdata and construct a C++ object in that userdata's storage space
+     * The C++ object must be trivially destructible as lua GC will _not_ call the object's destructor
+     * be aware that the created userdata is left on the Lua stack as well as returned to the caller
+     */
+    template <typename T, typename... Args>
+        requires (std::is_trivially_destructible_v<T>)
+    T* make_lua_userdata(lua_State* L, Args&&... args)
+    {
+        void* stg = lua_newuserdata(L, sizeof(T));
+        T * obj = ::new (stg) T(std::forward<Args>(args)...);
+        return obj;
+    }
+
     DFHACK_EXPORT void PushDFHack(lua_State *state);
     DFHACK_EXPORT void PushBaseGlobals(lua_State *state);
 

library/include/modules/Job.h

@@ -31,6 +31,7 @@ distribution.
 #include "Types.h"
 #include "DataDefs.h"
 
+#include "df/building_workshopst.h"
 #include "df/item_type.h"
 #include "df/job_item_ref.h"
 
@@ -94,7 +95,13 @@ namespace DFHack
         DFHACK_EXPORT void checkBuildingsNow();
         DFHACK_EXPORT void checkDesignationsNow();
 
+        // link the job into the global job list, passing ownership to DF
         DFHACK_EXPORT bool linkIntoWorld(df::job *job, bool new_id = true);
+        // create a job and immediately link it into the global job list
+        DFHACK_EXPORT df::job* createLinked();
+
+        // assign job to workshop, returns false if workshop already has the maximum of ten jobs
+        DFHACK_EXPORT bool assignToWorkshop(df::job *job, df::building_workshopst *workshop);
 
         // Flag this job's posting as "dead" and set its posting_index to -1
         // If remove_all is true, flag all postings pointing to this job

library/include/modules/Units.h

@@ -39,12 +39,14 @@ distribution.
 #include "df/job_skill.h"
 #include "df/mental_attribute_type.h"
 #include "df/misc_trait_type.h"
+#include "df/need_type.h"
 #include "df/physical_attribute_type.h"
 #include "df/unit_action.h"
 #include "df/unit_action_type_group.h"
 #include "df/unit_path_goal.h"
 
 #include <ranges>
+#include <bitset>
 
 namespace df {
     struct activity_entry;
@@ -339,6 +341,17 @@ DFHACK_EXPORT bool isGoalAchieved(df::unit *unit, size_t goalIndex = 0);
 DFHACK_EXPORT df::activity_entry *getMainSocialActivity(df::unit *unit);
 DFHACK_EXPORT df::activity_event *getMainSocialEvent(df::unit *unit);
 
+// get largest (i.e. most negative) focus penalty for a set of needs
+using need_type_set = std::bitset<ENUM_LAST_ITEM(need_type)+1UL>;
+DFHACK_EXPORT int32_t getFocusPenalty(df::unit* unit, need_type_set need_types);
+// get focused penalty for a single need
+DFHACK_EXPORT int32_t getFocusPenalty(df::unit* unit, df::need_type need_type);
+
+// unit has an unbailable social activity (e.g. "Socialize!")
+DFHACK_EXPORT bool hasUnbailableSocialActivity(df::unit *unit);
+// unit can be assigned a job
+DFHACK_EXPORT bool isJobAvailable(df::unit *unit, bool interrupt_social);
+
 // Stress categories. 0 is highest stress, 6 is lowest.
 DFHACK_EXPORT extern const std::vector<int32_t> stress_cutoffs;
 DFHACK_EXPORT int getStressCategory(df::unit *unit);