[feature] Add Lua mod infrastructure (OnMonsterDeath, OnItemUse hooks)

Source/CMakeLists.txt

@@ -118,6 +118,7 @@ set(libdevilutionx_SRCS
   lua/modules/dev/search.cpp
   lua/modules/dev/towners.cpp
   lua/modules/floatingnumbers.cpp
+  lua/modules/game.cpp
   lua/modules/i18n.cpp
   lua/modules/items.cpp
   lua/modules/log.cpp

Source/inv.cpp

@@ -13,10 +13,10 @@
 #include <SDL3/SDL_keyboard.h>
 #include <SDL3/SDL_rect.h>
 #else
 #include <SDL.h>
 #endif
 
 #include <fmt/format.h>
 
 #include "DiabloUI/ui_flags.hpp"
 #include "controls/control_mode.hpp"
@@ -29,25 +29,26 @@
 #include "engine/render/clx_render.hpp"
 #include "engine/render/text_render.hpp"
 #include "engine/size.hpp"
 #include "hwcursor.hpp"
 #include "inv_iterators.hpp"
 #include "levels/tile_properties.hpp"
 #include "levels/town.h"
+#include "lua/lua_global.hpp"
 #include "minitext.h"
 #include "options.h"
 #include "panels/ui_panels.hpp"
 #include "player.h"
 #include "plrmsg.h"
 #include "qol/stash.h"
 #include "stores.h"
 #include "towners.h"
 #include "utils/display.h"
 #include "utils/format_int.hpp"
 #include "utils/is_of.hpp"
 #include "utils/language.h"
 #include "utils/sdl_geometry.h"
 #include "utils/str_cat.hpp"
 #include "utils/utf8.hpp"
 
 namespace devilution {
 
@@ -75,7 +76,7 @@
  * 47 48 49 50 51 52 53 54
  * @endcode
  */
 const Rectangle InvRect[] = {
 	// clang-format off
 	//{   X,   Y }, {  W,  H }
 	{ { 132,   2 }, { 58, 59 } }, // helmet
@@ -154,9 +155,9 @@
 		const int rowGridIndex = invGridIndex + pitch * y;
 		for (int x = 0; x < itemSize.width; x++) {
 			if (x == 0 && y == itemSize.height - 1)
 				player.InvGrid[rowGridIndex + x] = invListIndex;
 			else
 				player.InvGrid[rowGridIndex + x] = -invListIndex; // use negative index to denote it's occupied but it's not the top-left cell.
 		}
 	}
 
@@ -2178,6 +2179,10 @@
 		return true;
 	}
 
+	if (LuaEventCancellable("OnItemUse", &player, item)) {
+		return true;
+	}
+
 	const int idata = ItemCAnimTbl[item->_iCurs];
 	if (item->_iMiscId == IMISC_BOOK)
 		PlaySFX(SfxID::ReadBook);

Source/lua/lua_global.cpp

@@ -12,8 +12,10 @@
 #include "appfat.h"
 #include "effects.h"
 #include "engine/assets.hpp"
+#include "items.h"
 #include "lua/modules/audio.hpp"
 #include "lua/modules/floatingnumbers.hpp"
+#include "lua/modules/game.hpp"
 #include "lua/modules/hellfire.hpp"
 #include "lua/modules/i18n.hpp"
 #include "lua/modules/items.hpp"
@@ -281,6 +283,7 @@ void LuaInitialize()
 	    "devilutionx.dev", LuaDevModule(lua),
 #endif
 	    "devilutionx.version", PROJECT_VERSION,
+	    "devilutionx.game", LuaGameModule(lua),
 	    "devilutionx.i18n", LuaI18nModule(lua),
 	    "devilutionx.items", LuaItemModule(lua),
 	    "devilutionx.log", LuaLogModule(lua),
@@ -350,11 +353,40 @@ void LuaEvent(std::string_view name, const Monster *monster, int arg1, int arg2)
 	CallLuaEvent(name, monster, arg1, arg2);
 }
 
+void LuaEvent(std::string_view name, const Monster *monster, int arg1)
+{
+	CallLuaEvent(name, monster, arg1);
+}
+
 void LuaEvent(std::string_view name, const Player *player, uint32_t arg1)
 {
 	CallLuaEvent(name, player, arg1);
 }
 
+bool LuaEventCancellable(std::string_view name, const Player *player, const Item *item)
+{
+	if (!CurrentLuaState.has_value()) {
+		return false;
+	}
+
+	const auto trigger = CurrentLuaState->events.traverse_get<std::optional<sol::object>>(name, "trigger");
+	if (!trigger.has_value() || !trigger->is<sol::protected_function>()) {
+		LogError("events.{}.trigger is not a function", name);
+		return false;
+	}
+	const sol::protected_function fn = trigger->as<sol::protected_function>();
+	const sol::protected_function_result result = fn(player, item);
+	if (!result.valid()) {
+		const std::string error = result.get_type() == sol::type::string
+		    ? StrCat("Lua error: ", result.get<std::string>())
+		    : "Unknown Lua error";
+		LogError(error);
+		return false;
+	}
+	const sol::object retVal = result;
+	return retVal.is<bool>() && retVal.as<bool>();
+}
+
 sol::state &GetLuaState()
 {
 	return CurrentLuaState->sol;

Source/lua/lua_global.hpp

@@ -8,6 +8,7 @@
 
 namespace devilution {
 
+struct Item;
 struct Player;
 struct Monster;
 
@@ -18,7 +19,14 @@ void LuaEvent(std::string_view name);
 void LuaEvent(std::string_view name, std::string_view arg);
 void LuaEvent(std::string_view name, const Player *player, int arg1, int arg2);
 void LuaEvent(std::string_view name, const Monster *monster, int arg1, int arg2);
+void LuaEvent(std::string_view name, const Monster *monster, int arg1);
 void LuaEvent(std::string_view name, const Player *player, uint32_t arg1);
+
+/**
+ * @brief Fires a cancellable Lua event.
+ * @return true if any handler returned true (i.e. default behaviour should be cancelled).
+ */
+bool LuaEventCancellable(std::string_view name, const Player *player, const Item *item);
 sol::state &GetLuaState();
 sol::environment CreateLuaSandbox();
 sol::object SafeCallResult(sol::protected_function_result result, bool optional);

Source/lua/modules/game.cpp

@@ -0,0 +1,34 @@
+#include "lua/modules/game.hpp"
+
+#include <sol/sol.hpp>
+
+#include "lua/metadoc.hpp"
+#include "monster.h"
+#include "multi.h"
+#include "quests.h"
+#include "tables/objdat.h"
+
+namespace devilution {
+
+sol::table LuaGameModule(sol::state_view &lua)
+{
+	sol::table table = lua.create_table();
+
+	LuaSetDocFn(table, "prepDoEnding", "()",
+	    "Triggers the game-ending sequence (win condition). Safe to call in multiplayer.",
+	    PrepDoEnding);
+
+	LuaSetDocFn(table, "isQuestDone", "(questId: integer) -> boolean",
+	    "Returns true if the quest with the given ID has been completed.",
+	    [](int questId) {
+		    return Quests[questId]._qactive == QUEST_DONE;
+	    });
+
+	LuaSetDocFn(table, "isMultiplayer", "() -> boolean",
+	    "Returns true when running in a multiplayer session.",
+	    []() { return gbIsMultiplayer; });
+
+	return table;
+}
+
+} // namespace devilution

Source/lua/modules/game.hpp

@@ -0,0 +1,9 @@
+#pragma once
+
+#include <sol/sol.hpp>
+
+namespace devilution {
+
+sol::table LuaGameModule(sol::state_view &lua);
+
+} // namespace devilution

Source/lua/modules/items.cpp

@@ -5,7 +5,9 @@
 #include <fmt/format.h>
 #include <sol/sol.hpp>
 
+#include "cursor.h"
 #include "data/file.hpp"
+#include "engine/point.hpp"
 #include "items.h"
 #include "lua/metadoc.hpp"
 #include "player.h"
@@ -465,6 +467,11 @@ void AddUniqueItemDataFromTsv(const std::string_view path, const int32_t baseMap
 	LoadUniqueItemDatFromFile(dataFile, path, baseMappingId);
 }
 
+void LuaSpawnQuestItem(int itemIdx, int x, int y, bool sendmsg)
+{
+	SpawnQuestItem(static_cast<_item_indexes>(itemIdx), Point { x, y }, 0, SelectionRegion::Bottom, sendmsg);
+}
+
 } // namespace
 
 sol::table LuaItemModule(sol::state_view &lua)
@@ -484,6 +491,10 @@ sol::table LuaItemModule(sol::state_view &lua)
 
 	LuaSetDocFn(table, "addItemDataFromTsv", "(path: string, baseMappingId: number)", AddItemDataFromTsv);
 	LuaSetDocFn(table, "addUniqueItemDataFromTsv", "(path: string, baseMappingId: number)", AddUniqueItemDataFromTsv);
+	LuaSetDocFn(table, "spawnQuestItem",
+	    "(itemIdx: ItemIndex, x: integer, y: integer, sendmsg: boolean = true)",
+	    "Spawns a quest item at the given world coordinates. Pass sendmsg=true to sync with other clients.",
+	    LuaSpawnQuestItem);
 
 	// Expose enums through the module table
 	table["ItemIndex"] = lua["ItemIndex"];

Source/lua/modules/monsters.cpp

@@ -42,6 +42,16 @@ void InitMonsterUserType(sol::state_view &lua)
 	    [](const Monster &monster) {
 		    return static_cast<int>(reinterpret_cast<uintptr_t>(&monster));
 	    });
+	LuaSetDocReadonlyProperty(monsterType, "typeId", "integer",
+	    "Monster type ID matching monsters.MonsterID constants (readonly)",
+	    [](const Monster &monster) {
+		    return static_cast<int>(monster.type().type);
+	    });
+	LuaSetDocReadonlyProperty(monsterType, "name", "string",
+	    "Monster's display name (readonly)",
+	    [](const Monster &monster) -> std::string_view {
+		    return monster.name();
+	    });
 }
 
 } // namespace

Source/lua/modules/player.cpp

@@ -12,6 +12,7 @@
 #include "items.h"
 #include "lua/metadoc.hpp"
 #include "player.h"
+#include "sound_effect_enums.h"
 
 namespace devilution {
 namespace {
@@ -111,13 +112,52 @@ void InitPlayerUserType(sol::state_view &lua)
 	LuaSetDocReadonlyProperty(playerType, "maxMana", "number",
 	    "Maximum mana (readonly)",
 	    [](Player &player) { return player._pMaxMana >> 6; });
+	LuaSetDocReadonlyProperty(playerType, "isMyPlayer", "boolean",
+	    "Whether this is the locally controlled player (readonly)",
+	    [](const Player &player) { return &player == MyPlayer; });
+	LuaSetDocReadonlyProperty(playerType, "level", "integer",
+	    "Current dungeon level the player is on (readonly)",
+	    [](const Player &player) { return static_cast<int>(player.plrlevel); });
+	LuaSetDocFn(playerType, "isOnLevel", "(level: integer) -> boolean",
+	    "Returns true if the player is on the given dungeon level",
+	    [](const Player &player, int level) {
+		    return player.isOnLevel(static_cast<uint8_t>(level));
+	    });
+	LuaSetDocFn(playerType, "say", "(speechId: HeroSpeech) -> void",
+	    "Makes the player character say the given speech line",
+	    [](Player &player, HeroSpeech speechId) {
+		    player.Say(speechId);
+	    });
+}
+
+void RegisterHeroSpeechEnum(sol::state_view &lua)
+{
+	lua.new_enum<HeroSpeech>("HeroSpeech",
+	    {
+	        { "ICantUseThisYet", HeroSpeech::ICantUseThisYet },
+	        { "ThatWontWorkHere", HeroSpeech::ThatWontWorkHere },
+	        { "ThatWontWork", HeroSpeech::ThatWontWork },
+	        { "VengeanceIsMine", HeroSpeech::VengeanceIsMine },
+	        { "JustWhatIWasLookingFor", HeroSpeech::JustWhatIWasLookingFor },
+	        { "ICantCarryAnymore", HeroSpeech::ICantCarryAnymore },
+	        { "IHaveNoRoom", HeroSpeech::IHaveNoRoom },
+	        { "ItsTooBig", HeroSpeech::ItsTooBig },
+	        { "ItsTooHeavy", HeroSpeech::ItsTooHeavy },
+	        { "No", HeroSpeech::No },
+	        { "Yes", HeroSpeech::Yes },
+	        { "Die", HeroSpeech::Die },
+	        { "TimeToDie", HeroSpeech::TimeToDie },
+	        { "OhTooEasy", HeroSpeech::OhTooEasy },
+	    });
 }
 } // namespace
 
 sol::table LuaPlayerModule(sol::state_view &lua)
 {
 	InitPlayerUserType(lua);
+	RegisterHeroSpeechEnum(lua);
 	sol::table table = lua.create_table();
+	table["HeroSpeech"] = lua["HeroSpeech"];
 	LuaSetDocFn(table, "self", "()",
 	    "The current player",
 	    []() {

Source/monster.cpp

@@ -1499,6 +1499,7 @@ void ShrinkLeaderPacksize(const Monster &monster)
 void MonsterDeath(Monster &monster)
 {
 	monster.var1++;
+	LuaEvent("OnMonsterDeath", &monster, monster.var1);
 	if (monster.type().type == MT_DIABLO) {
 		if (monster.position.tile.x < ViewPosition.x) {
 			ViewPosition.x--;

assets/lua/devilutionx/events.lua

@@ -40,6 +40,42 @@ local function CreateEvent()
   }
 end
 
+---Creates a cancellable event. If any handler returns true the trigger returns true.
+local function CreateCancellableEvent()
+  local functions = {}
+  return {
+    ---@param func function
+    add = function(func)
+      table.insert(functions, func)
+    end,
+
+    ---@param func function
+    remove = function(func)
+      for i, f in ipairs(functions) do
+        if f == func then
+          table.remove(functions, i)
+          break
+        end
+      end
+    end,
+
+    ---Triggers the event. Returns true if any handler cancelled the default behaviour.
+    ---@param ... any
+    ---@return boolean
+    trigger = function(...)
+      local cancelled = false
+      local args = {...}
+      for _, func in ipairs(functions) do
+        if func(table.unpack(args)) == true then
+          cancelled = true
+        end
+      end
+      return cancelled
+    end,
+    __sig_trigger = "(...) -> boolean",
+  }
+end
+
 local events = {
   ---Called after all mods have been loaded.
   LoadModsComplete = CreateEvent(),
@@ -84,6 +120,15 @@ local events = {
   ---Called when Player gains experience.
   OnPlayerGainExperience = CreateEvent(),
   __doc_OnPlayerGainExperience = "Called when Player gains experience.",
+
+  ---Called each frame of a monster's death animation. Arguments: monster, deathFrame (integer).
+  OnMonsterDeath = CreateEvent(),
+  __doc_OnMonsterDeath = "Called each frame of a monster's death animation. Arguments: monster, deathFrame.",
+
+  ---Called when a player is about to use an item. Arguments: player, item.
+  ---If any handler returns true the default item-use behaviour is cancelled.
+  OnItemUse = CreateCancellableEvent(),
+  __doc_OnItemUse = "Called when a player uses an item. Return true to cancel default behaviour.",
 }
 
 ---Registers a custom event type with the given name.