Add lua events for monsters, useItem, spawnItem and helpers

Author: yuripourre

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

@@ -33,6 +33,7 @@
 #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"
@@ -2178,6 +2179,10 @@ bool UseInvItem(int cii)
 		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
@@ -52,6 +62,7 @@ sol::table LuaMonstersModule(sol::state_view &lua)
 	sol::table table = lua.create_table();
 	LuaSetDocFn(table, "addMonsterDataFromTsv", "(path: string)", AddMonsterDataFromTsv);
 	LuaSetDocFn(table, "addUniqueMonsterDataFromTsv", "(path: string)", AddUniqueMonsterDataFromTsv);
+
 	return table;
 }
 

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--;