Merge branch 'soul_set_lua' into 'master'

Allow Soul values on Misc Items to be set by Lua

See merge request OpenMW/openmw!2927

apps/openmw/mwlua/types/misc.cpp

@@ -1,5 +1,6 @@
 #include "types.hpp"
 
+#include <components/esm3/loadcrea.hpp>
 #include <components/esm3/loadmisc.hpp>
 #include <components/lua/luastate.hpp>
 #include <components/misc/resourcehelpers.hpp>
@@ -25,6 +26,25 @@ namespace MWLua
 
         addRecordFunctionBinding<ESM::Miscellaneous>(miscellaneous, context);
 
+        miscellaneous["setSoul"] = [](const GObject& object, std::string_view soulId) {
+            ESM::RefId creature = ESM::RefId::deserializeText(soulId);
+            const MWWorld::ESMStore& store = MWBase::Environment::get().getWorld()->getStore();
+
+            if (!store.get<ESM::Creature>().search(creature))
+            {
+                // TODO: Add Support for NPC Souls
+                throw std::runtime_error("Cannot use non-existent creature as a soul: " + std::string(soulId));
+            }
+
+            object.ptr().getCellRef().setSoul(creature);
+        };
+        miscellaneous["soul"] = [](const Object& object) -> sol::optional<std::string> {
+            ESM::RefId soul = object.ptr().getCellRef().getSoul();
+            if (soul.empty())
+                return sol::nullopt;
+            else
+                return soul.serializeText();
+        };
         sol::usertype<ESM::Miscellaneous> record
             = context.mLua->sol().new_usertype<ESM::Miscellaneous>("ESM3_Miscellaneous");
         record[sol::meta_function::to_string]

files/lua_api/openmw/types.lua

@@ -802,6 +802,18 @@
 -- @param #any objectOrRecordId
 -- @return #MiscellaneousRecord
 
+---
+-- Returns the read-only soul of a miscellaneous item
+-- @function [parent=#Miscellaneous] soul
+-- @param openmw.core#GameObject object
+-- @return #string
+
+---
+-- Sets the soul of a miscellaneous item, intended for soul gem objects; Must be used in a global script.
+-- @function [parent=#Miscellaneous] setSoul
+-- @param openmw.core#GameObject object
+-- @param #string soulId Record ID for the soul of the creature to use
+
 ---
 -- @type MiscellaneousRecord
 -- @field #string id The record ID of the miscellaneous item