Plugin: Vault

CHANGELOG.md

@@ -11,7 +11,7 @@ https://github.com/nwnxee/unified/compare/build8193.34...HEAD
 - N/A
 
 ##### New Plugins
-- N/A
+- Vault: a plugin that provides various character/servervault functions.
 
 ##### New NWScript Functions
 - N/A

Plugins/Vault/CMakeLists.txt

@@ -0,0 +1,2 @@
+add_plugin(Vault
+        "Vault.cpp")

Plugins/Vault/NWScript/nwnx_vault.nss

@@ -0,0 +1,110 @@
+/// @addtogroup vault Vault
+/// @brief Provides various character/servervault related functions.
+/// @{
+/// @file nwnx_vault.nss
+#include "nwnx"
+
+const string NWNX_Vault = "NWNX_Vault"; ///< @private
+
+/// @brief A structure containing vault character data.
+struct NWNX_Vault_Character
+{
+    string sFileName;
+    string sUUID; ///< May be empty
+
+    string sFirstName;
+    string sLastName;
+
+    int nPortraitId;
+    string sPortrait;
+
+    int nClass1Id; ///< Will be CLASS_TYPE_INVALID on error.
+    int nClass1Level;
+    int nClass2Id; ///< Will be CLASS_TYPE_INVALID if no second class.
+    int nClass2Level;
+    int nClass3Id; ///< Will be CLASS_TYPE_INVALID if no third class.
+    int nClass3Level;
+
+    int nRace;
+    int nGender;
+    int nExperience;
+    int nGold;
+};
+
+/// @brief Get the number of characters in oPlayer's vault.
+/// @param oPlayer The player.
+/// @return The number of characters in the vault or 0 on error.
+int NWNX_Vault_GetVaultSize(object oPlayer);
+
+
+/// @brief Load the character vault of oPlayer.
+/// @note Will overwrite a previously loaded vault. Will return 0 for (Player)DMs.
+/// @param oPlayer The player.
+/// @return The number of characters in the vault or 0 on error.
+int NWNX_Vault_LoadVault(object oPlayer);
+
+/// @brief Get the data of the character at nIndex in the last loaded vault.
+/// @param nIndex The index.
+/// @return A NWNX_Vault_Character struct.
+struct NWNX_Vault_Character NWNX_Vault_GetCharacterData(int nIndex);
+
+/// @brief Switch oPlayer's character to another one from their vault.
+/// @warning THIS FUNCTION IS EXPERIMENTAL, BACKUP YOUR SERVERVAULT BEFORE EVEN ATTEMPTING TO USE THIS.
+/// @warning Do not switch between characters with the same UUID, bad things will happen.
+/// @note If something goes catastrophically wrong the player will be disconnected.
+/// @param oPlayer The player.
+/// @param sBICFileName The bic filename without .bic.
+/// @return The new creature object or OBJECT_INVALID on error.
+object NWNX_Vault_SwitchCharacter(object oPlayer, string sBICFileName);
+
+/// @}
+
+int NWNX_Vault_GetVaultSize(object oPlayer)
+{
+    NWNX_PushArgumentObject(oPlayer);
+    NWNX_CallFunction(NWNX_Vault, "GetVaultSize");
+
+    return NWNX_GetReturnValueInt();
+}
+
+int NWNX_Vault_LoadVault(object oPlayer)
+{
+    NWNX_PushArgumentObject(oPlayer);
+    NWNX_CallFunction(NWNX_Vault, "LoadVault");
+
+    return NWNX_GetReturnValueInt();
+}
+
+struct NWNX_Vault_Character NWNX_Vault_GetCharacterData(int nIndex)
+{
+    NWNX_PushArgumentInt(nIndex);
+    NWNX_CallFunction(NWNX_Vault, "GetCharacterData");
+
+    struct NWNX_Vault_Character str;
+    str.nGold = NWNX_GetReturnValueInt();
+    str.nExperience = NWNX_GetReturnValueInt();
+    str.nGender = NWNX_GetReturnValueInt();
+    str.nRace = NWNX_GetReturnValueInt();
+    str.nClass3Level = NWNX_GetReturnValueInt();
+    str.nClass3Id = NWNX_GetReturnValueInt();
+    str.nClass2Level = NWNX_GetReturnValueInt();
+    str.nClass2Id = NWNX_GetReturnValueInt();
+    str.nClass1Level = NWNX_GetReturnValueInt();
+    str.nClass1Id = NWNX_GetReturnValueInt();
+    str.sPortrait = NWNX_GetReturnValueString();
+    str.nPortraitId = NWNX_GetReturnValueInt();
+    str.sLastName = NWNX_GetReturnValueString();
+    str.sFirstName = NWNX_GetReturnValueString();
+    str.sUUID = NWNX_GetReturnValueString();
+    str.sFileName = NWNX_GetReturnValueString();
+
+    return str;
+}
+
+object NWNX_Vault_SwitchCharacter(object oPlayer, string sBICFileName)
+{
+    NWNX_PushArgumentString(sBICFileName);
+    NWNX_PushArgumentObject(oPlayer);
+    NWNX_CallFunction(NWNX_Vault, "SwitchCharacter");
+    return NWNX_GetReturnValueObject();
+}

Plugins/Vault/README.md

@@ -0,0 +1,18 @@
+@page vault Readme
+@ingroup vault
+
+Provides various character/servervault functions.
+
+## NWNX_Vault_SwitchCharacter Notes
+
+### Before even attempting to do anything with this function, make sure to (regularly) backup your servervault. You have been warned.
+
+Things of note:
+
+* **Regularly backup your servervault.**
+* Disable the NWNX_TWEAKS_TURD_BY_CDKEY tweak, NWNX_Vault will associate TURDs by CDKey+UUID/CharacterName instead.
+* Do not switch between characters with the same UUID, bad things will happen.
+* Will disconnect the player if something goes catastrophically wrong.
+* OnClientEnter/Leave and OnAreaEnter/Exit will fire for the appropriate creature objects.
+* Probably has weird quirks and/or bugs.
+* **Regularly backup your servervault.**