Lua: Add a player usertype

Source/lua/metadoc.hpp

@@ -18,6 +18,13 @@ inline std::string LuaDocstringKey(std::string_view key)
 	return StrCat("__doc_", key);
 }
 
+template <typename U, typename T>
+void SetDocumented(sol::usertype<U> &table, std::string_view key, std::string_view signature, std::string_view doc, T &&value)
+{
+	table[key] = std::forward<T>(value);
+	// TODO: figure out a way to set signature and docstring.
+}
+
 template <typename T>
 void SetDocumented(sol::table &table, std::string_view key, std::string_view signature, std::string_view doc, T &&value)
 {

Source/lua/modules/player.cpp

@@ -1,16 +1,45 @@
 #include "lua/modules/player.hpp"
 
+#include <optional>
+
 #include <sol/sol.hpp>
 
 #include "engine/point.hpp"
 #include "lua/metadoc.hpp"
 #include "player.h"
 
 namespace devilution {
+namespace {
+void InitPlayerUserType(sol::state_view &lua)
+{
+	sol::usertype<Player> playerType = lua.new_usertype<Player>(sol::no_constructor);
+	SetDocumented(playerType, "name", "",
+	    "Player's name (readonly)",
+	    sol::readonly_property(&Player::name));
+	SetDocumented(playerType, "addExperience", "(experience: integer, monsterLevel: integer = nil)",
+	    "Adds experience to this player based on the current game mode",
+	    [](Player &player, uint32_t experience, std::optional<int> monsterLevel) {
+		    if (monsterLevel.has_value()) {
+			    player.addExperience(experience, *monsterLevel);
+		    } else {
+			    player.addExperience(experience);
+		    }
+	    });
+	SetDocumented(playerType, "characterLevel", "",
+	    "Character level (writeable)",
+	    sol::property(&Player::getCharacterLevel, &Player::setCharacterLevel));
+}
+} // namespace
 
 sol::table LuaPlayerModule(sol::state_view &lua)
 {
+	InitPlayerUserType(lua);
 	sol::table table = lua.create_table();
+	SetDocumented(table, "self", "()",
+	    "The current player",
+	    []() {
+		    return MyPlayer;
+	    });
 	SetDocumented(table, "walk_to", "(x: integer, y: integer)",
 	    "Walk to the given coordinates",
 	    [](int x, int y) {

Source/player.h

@@ -10,6 +10,7 @@
 
 #include <algorithm>
 #include <array>
+#include <string_view>
 
 #include "diablo.h"
 #include "engine/actor_position.hpp"
@@ -369,6 +370,11 @@ struct Player {
 	uint16_t wReflections;
 	ItemSpecialEffectHf pDamAcFlags;
 
+	[[nodiscard]] std::string_view name() const
+	{
+		return _pName;
+	}
+
 	/**
 	 * @brief Convenience function to get the base stats/bonuses for this player's class
 	 */