DFHack::Units: new function setGoal

docs/changelog.txt

@@ -66,8 +66,12 @@ Template for new versions:
 
 ## API
 
+- ``DFHack::Units``: new function ``setPathGoal``
+
 ## Lua
 
+- ``dfhack.units``: new function ``setPathGoal``
+
 ## Removed
 
 # 50.14-r1

docs/dev/Lua API.rst

@@ -1703,6 +1703,11 @@ Units module
   ``dfhack.units.isOwnCiv`` or another appropriate predicate on the unit
   in question.
 
+* ``dfhack.units.setPathGoal(unit, pos, goal)``
+
+  Set target coordinates and goal (of type ``df.unit_path_goal``) for the given
+  unit. In case of a change, also clears the unit's current path.
+
 * ``dfhack.units.create(race, caste)``
 
   Creates a new unit from scratch. The unit will be added to the

library/LuaApi.cpp

@@ -2065,6 +2065,7 @@ static const LuaWrapper::FunctionReg dfhack_units_module[] = {
     WRAPM(Units, getIdentity),
     WRAPM(Units, getNemesis),
     WRAPM(Units, makeown),
+    WRAPM(Units, setPathGoal),
     WRAPM(Units, create),
     WRAPM(Units, getPhysicalAttrValue),
     WRAPM(Units, getMentalAttrValue),

library/include/modules/Units.h

@@ -42,6 +42,7 @@ distribution.
 #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>
 
@@ -238,6 +239,9 @@ DFHACK_EXPORT bool unassignTrainer(df::unit *unit);
 /// to determine if the makeown operation was successful.
 DFHACK_EXPORT void makeown(df::unit *unit);
 
+// Set the units target location and goal, clearing any existing goal or path
+DFHACK_EXPORT void setPathGoal(df::unit *unit, df::coord pos, df::unit_path_goal goal);
+
 /// Create new unit and add to all units vector (but not active). No HF, nemesis, pos,
 /// labors, or group associations. Will have race, caste, name, soul, body, and mind.
 DFHACK_EXPORT df::unit *create(int16_t race, int16_t caste);

library/modules/Units.cpp

@@ -73,6 +73,7 @@ distribution.
 #include "df/unit_action_type_group.h"
 #include "df/unit_inventory_item.h"
 #include "df/unit_misc_trait.h"
+#include "df/unit_path_goal.h"
 #include "df/unit_relationship_type.h"
 #include "df/unit_skill.h"
 #include "df/unit_soul.h"
@@ -933,6 +934,27 @@ void Units::makeown(df::unit *unit) {
     (*f)(unit);
 }
 
+// functionality reverse-engineered from DF's unitst::set_goal
+void Units::setPathGoal(df::unit *unit, df::coord pos, df::unit_path_goal goal)
+{
+    if (unit->path.dest != pos || unit->path.goal != goal)
+    {
+        unit->path.dest = pos;
+        unit->path.goal = goal;
+        unit->path.path.clear();
+    }
+
+    if (unit->flags1.bits.rider && unit->mount_type == df::rider_positions_type::STANDARD)
+    {
+        if (auto mount = df::unit::find(unit->relationship_ids[df::unit_relationship_type::RiderMount]))
+        {
+            mount->path.dest = pos;
+            mount->path.goal = goal;
+            mount->path.path.clear();
+        }
+    }
+}
+
 df::unit *Units::create(int16_t race, int16_t caste) {
     auto fp = df::global::unitst_more_convenient_create;
     CHECK_NULL_POINTER(fp);