Add API function to invoke player respawn

closes #12272

doc/lua_api.txt

@@ -7099,6 +7099,8 @@ object you are working with still exists.
         * `intensity` sets the intensity of the shadows from 0 (no shadows, default) to 1 (blackness)
 * `get_lighting()`: returns the current state of lighting for the player.
     * Result is a table with the same fields as `light_definition` in `set_lighting`.
+* `respawn()`: Respawns the player using the same mechanism as the death screen,
+  including calling on_respawnplayer callbacks.
 
 `PcgRandom`
 -----------

src/script/lua_api/l_object.cpp

@@ -2323,6 +2323,21 @@ int ObjectRef::l_get_lighting(lua_State *L)
 	return 1;
 }
 
+// respawn(self)
+int ObjectRef::l_respawn(lua_State *L)
+{
+	NO_MAP_LOCK_REQUIRED;
+	ObjectRef *ref = checkobject(L, 1);
+	RemotePlayer *player = getplayer(ref);
+	if (player == nullptr)
+		return 0;
+
+	getServer(L)->RespawnPlayer(player->getPeerId());
+	lua_pushboolean(L, true);
+	return 1;
+}
+
+
 ObjectRef::ObjectRef(ServerActiveObject *object):
 	m_object(object)
 {}
@@ -2478,5 +2493,7 @@ luaL_Reg ObjectRef::methods[] = {
 	luamethod(ObjectRef, set_minimap_modes),
 	luamethod(ObjectRef, set_lighting),
 	luamethod(ObjectRef, get_lighting),
+	luamethod(ObjectRef, respawn),
+
 	{0,0}
 };

src/script/lua_api/l_object.h

@@ -382,4 +382,7 @@ private:
 	
 	// get_lighting(self)
 	static int l_get_lighting(lua_State *L);
+
+	// respawn(self)
+	static int l_respawn(lua_State *L);
 };

src/server.cpp

@@ -2784,9 +2784,10 @@ void Server::RespawnPlayer(session_t peer_id)
 			<< playersao->getPlayer()->getName()
 			<< " respawns" << std::endl;
 
-	playersao->setHP(playersao->accessObjectProperties()->hp_max,
+	const auto *prop = playersao->accessObjectProperties();
+	playersao->setHP(prop->hp_max,
 			PlayerHPChangeReason(PlayerHPChangeReason::RESPAWN));
-	playersao->setBreath(playersao->accessObjectProperties()->breath_max);
+	playersao->setBreath(prop->breath_max);
 
 	bool repositioned = m_script->on_respawnplayer(playersao);
 	if (!repositioned) {

src/server.h

@@ -336,6 +336,8 @@ public:
 
 	void setLighting(RemotePlayer *player, const Lighting &lighting);
 
+	void RespawnPlayer(session_t peer_id);
+
 	/* con::PeerHandler implementation. */
 	void peerAdded(con::Peer *peer);
 	void deletingPeer(con::Peer *peer, bool timeout);
@@ -529,7 +531,6 @@ private:
 	*/
 
 	void HandlePlayerDeath(PlayerSAO* sao, const PlayerHPChangeReason &reason);
-	void RespawnPlayer(session_t peer_id);
 	void DeleteClient(session_t peer_id, ClientDeletionReason reason);
 	void UpdateCrafting(RemotePlayer *player);
 	bool checkInteractDistance(RemotePlayer *player, const f32 d, const std::string &what);