Modding:SaveGame ModData: Difference between revisions
No edit summary |
|||
Line 38: | Line 38: | ||
serverApi = api; | serverApi = api; | ||
api.Event.SaveGameLoaded += OnSaveGameLoading; | |||
api.Event.GameWorldSave += OnSaveGameSaving; | api.Event.GameWorldSave += OnSaveGameSaving; | ||
api.RegisterCommand("lfg", "List or join the lfg list", "[list|join|leave]", OnLfg); | api.RegisterCommand("lfg", "List or join the lfg list", "[list|join|leave]", OnLfg); | ||
Line 53: | Line 53: | ||
Let's create these event delegates! | Let's create these event delegates! | ||
== Storing | == Retrieving and Storing the List == | ||
When the game loads, <code>OnSaveGameLoading</code> gets called and attempts to get our list of players looking for group. The Core Server Api has a member called <code>WorldManager</code> which we use to access everything World related, including our <code>SaveGame</code>. | |||
<syntaxhighlight lang="c#"> | <syntaxhighlight lang="c#"> | ||
private void | private void OnSaveGameLoading() | ||
{ | { | ||
byte[] data = serverApi.WorldManager.SaveGame.GetData("lfg"); | |||
lfgList = data == null ? new List<string>() : SerializerUtil.Deserialize<List<string>>(data); | |||
} | } | ||
</syntaxhighlight> | </syntaxhighlight> | ||
We attempt to get our list by exposing the <code>GetData</code> method and passing it an identifier for our custom data, in this case our "lfg" list. | |||
'''Hint''': If nothing is found stored under the key we provide, the <code>GetData</code> method returns null. In our mod example, this will happen until at least one player enters the list! | |||
<code>byte[] data = serverApi.WorldManager.SaveGame.GetData("lfg");</code> | |||
As you can see, we're retrieving an array of bytes, which is the data type we actually store on the <code>SaveGame</code>. Let's convert it to a <code>List</code> of strings: | |||
< | <code>lfgList = data == null ? new List<string>() : SerializerUtil.Deserialize<List<string>>(data);</code> | ||
Here we use a ternary operator to assign our <code>lfgList</code> field a new <code>List<string></code> if there was nothing stored under the "lfg" key. | |||
If <code>data</code> is not null, we expose the <code>Deserialize<T></code> method of the <code>SerializerUtil</code> class. This method will deserialize an array of bytes into an instance of the type argument we pass it. Now that we have a delegate that fetches our list of players "lfg", let's create the delegate that stores this list when the Game World is saved: | |||
<syntaxhighlight lang="c#"> | |||
private void OnSaveGameSaving() | |||
{ | |||
serverApi.WorldManager.SaveGame.StoreData("lfg", SerializerUtil.Serialize(lfgList)); | |||
} | } | ||
</syntaxhighlight> | </syntaxhighlight> | ||
Here we call the <code>StoreData</code> method to save our list under the "lfg" key for later retrieval! Because we can only store data in the form of <code>byte[]</code>, we use the <code>Serialize</code> method of the <code>SerializerUtil</code> class to turn <code>lfgList</code> back to an array of bytes, which we pass as the second argument. | |||
<code> | |||
<code> | We now have implemented a way to assign our list from storageto <code>lfgList</code> when the <code>SaveGame</code> is loaded, and a way to store this list once the game is saved. In between these two events, we want players to be added or removed from <code>lfgList</code> via our command. Let's create our command delegate! | ||
== Handling the Command == | |||
Server chat commands have three parameters: the player issuing the command, the group in which this command was entered, and the arguments sent for the command. | |||
<syntaxhighlight lang="c#"> | <syntaxhighlight lang="c#"> | ||
private void OnLfg(IServerPlayer player, int groupId, CmdArgs args) | private void OnLfg(IServerPlayer player, int groupId, CmdArgs args) | ||
{ | { | ||
string cmd = args.PopWord(); | string cmd = args.PopWord(); | ||
switch (cmd) | switch (cmd) | ||
{ | { | ||
Line 132: | Line 117: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
We use the <code>PopWord</code> of our <code>CmdArgs</code> parameter to collect the first argument passed (ignoring anything subsequent). We then start a switch statement for our valid arguments, and default to showing these to the player if none of them match. | We use the <code>PopWord</code> of our <code>CmdArgs</code> parameter to collect the first argument passed (ignoring anything subsequent). We then start a switch statement for our valid arguments, and default to showing these to the player if none of them match or <code>cmd</code> is null. | ||
Let's handle each of these: | Let's handle each of these: | ||
Line 138: | Line 123: | ||
<syntaxhighlight lang="c#"> | <syntaxhighlight lang="c#"> | ||
case "join": | case "join": | ||
if ( | if (lfgList.Contains(player.PlayerUID)) | ||
{ | { | ||
player.SendMessage(groupId, "You're already in | player.SendMessage(groupId, "You're already in the list!", EnumChatType.CommandError); | ||
} | } | ||
else | else | ||
{ | { | ||
lfgList.Add(player.PlayerUID); | |||
player.SendMessage(groupId, "Successfully joined.", EnumChatType.CommandSuccess); | |||
player.SendMessage(groupId, "Successfully joined | |||
} | } | ||
break; | break; | ||
</syntaxhighlight> | </syntaxhighlight> | ||
If <code>/lfg join</code> was entered, we'll first check if the player is already on the "lfg" list, letting the player know if so. Alternatively, we add the player's unique identifier to the list | If <code>/lfg join</code> was entered, we'll first check if the player is already on the "lfg" list, letting the player know if so. Alternatively, we add the player's unique identifier to the list and show a success message. | ||
'''Hint:''' We do not want to store player names directly. This is because player names may change, therefore our list could become inaccurate. | |||
Next we handle <code>/lfg leave</code>: | |||
<syntaxhighlight lang="c#"> | <syntaxhighlight lang="c#"> | ||
case "leave": | case "leave": | ||
if (! | if (!lfgList.Remove(player.PlayerUID)) | ||
{ | { | ||
player.SendMessage(groupId, "You're not in the list!", EnumChatType. | player.SendMessage(groupId, "You're not in the list!", EnumChatType.CommandError); | ||
} | } | ||
else | else | ||
{ | { | ||
player.SendMessage(groupId, "Successfully left.", EnumChatType.CommandSuccess); | |||
player.SendMessage(groupId, "Successfully left | |||
} | } | ||
break; | break; | ||
</syntaxhighlight> | </syntaxhighlight> | ||
The <code>Remove</code> method returns false if nothing matching the argument passed to it was found | The <code>Remove</code> method returns false if nothing matching the argument passed to it was found and removed, and true if it was. We let the player know if they were not on the list, or if they were and got successfully taken out of it. | ||
Finally, we handle <code>/lfg list</code>: | Finally, we handle <code>/lfg list</code>: | ||
Line 183: | Line 160: | ||
<syntaxhighlight lang="c#"> | <syntaxhighlight lang="c#"> | ||
case "list": | case "list": | ||
if ( | if (lfgList.Count == 0) | ||
{ | { | ||
player.SendMessage(groupId, "Noone is looking for group | player.SendMessage(groupId, "Noone is looking for a group.", EnumChatType.CommandSuccess); | ||
} | } | ||
else | |||
{ | { | ||
lfgList += "\n" + serverApi.World.PlayerByUid(playerUid).PlayerName; | string response = "Players looking for group:"; | ||
lfgList.ForEach((playerUid) => | |||
{ | |||
response += "\n" + serverApi.World.PlayerByUid(playerUid).PlayerName; | |||
}); | |||
player.SendMessage(groupId, response, EnumChatType.CommandSuccess); | |||
} | |||
break; | break; | ||
</syntaxhighlight> | </syntaxhighlight> | ||
In this case we simply let the player know if | In this case we simply let the player know if there is noone on the list, but if there are we build a string with all the player names on the list. | ||
== Conclusion == | == Conclusion == | ||
Line 216: | Line 194: | ||
{ | { | ||
ICoreServerAPI serverApi; | ICoreServerAPI serverApi; | ||
List<string> lfgList; | |||
public override void StartServerSide(ICoreServerAPI api) | public override void StartServerSide(ICoreServerAPI api) | ||
{ | { | ||
serverApi = api; | serverApi = api; | ||
api.RegisterCommand("lfg", " | api.Event.SaveGameLoaded += OnSaveGameLoading; | ||
api.Event.GameWorldSave += OnSaveGameSaving; | |||
api.RegisterCommand("lfg", "Access the lfg list.", "[list|join|leave]", OnLfg); | |||
} | } | ||
private void | private void OnSaveGameLoading() | ||
{ | { | ||
byte[] data = serverApi.WorldManager.SaveGame.GetData("lfg"); | byte[] data = serverApi.WorldManager.SaveGame.GetData("lfg"); | ||
lfgList = data == null ? new List<string>() : SerializerUtil.Deserialize<List<string>>(data); | |||
} | |||
private void OnSaveGameSaving() | |||
{ | |||
serverApi.WorldManager.SaveGame.StoreData("lfg", SerializerUtil.Serialize(lfgList)); | |||
} | |||
private void OnLfg(IServerPlayer player, int groupId, CmdArgs args) | |||
{ | |||
string cmd = args.PopWord(); | string cmd = args.PopWord(); | ||
switch (cmd) | switch (cmd) | ||
{ | { | ||
case "join": | case "join": | ||
if ( | if (lfgList.Contains(player.PlayerUID)) | ||
{ | { | ||
player.SendMessage(groupId, "You're already in | player.SendMessage(groupId, "You're already in the list!", EnumChatType.CommandError); | ||
} | } | ||
else | else | ||
{ | { | ||
lfgList.Add(player.PlayerUID); | |||
player.SendMessage(groupId, "Successfully joined.", EnumChatType.CommandSuccess); | |||
player.SendMessage(groupId, "Successfully joined | |||
} | } | ||
break; | break; | ||
case "leave": | case "leave": | ||
if (! | if (!lfgList.Remove(player.PlayerUID)) | ||
{ | { | ||
player.SendMessage(groupId, "You're not in the list!", EnumChatType. | player.SendMessage(groupId, "You're not in the list!", EnumChatType.CommandError); | ||
} | } | ||
else | else | ||
{ | { | ||
player.SendMessage(groupId, "Successfully left.", EnumChatType.CommandSuccess); | |||
player.SendMessage(groupId, "Successfully left | |||
} | } | ||
break; | break; | ||
case "list": | case "list": | ||
if ( | if (lfgList.Count == 0) | ||
{ | { | ||
player.SendMessage(groupId, "Noone is looking for group | player.SendMessage(groupId, "Noone is looking for a group.", EnumChatType.CommandSuccess); | ||
} | } | ||
else | |||
{ | { | ||
lfgList += "\n" + serverApi.World.PlayerByUid(playerUid).PlayerName; | string response = "Players looking for group:"; | ||
lfgList.ForEach((playerUid) => | |||
{ | |||
response += "\n" + serverApi.World.PlayerByUid(playerUid).PlayerName; | |||
}); | |||
player.SendMessage(groupId, response, EnumChatType.CommandSuccess); | |||
} | |||
break; | break; | ||
case null: | |||
default: | default: | ||
player.SendMessage(groupId, "/lfg [list|join|leave]", EnumChatType.CommandError); | player.SendMessage(groupId, "/lfg [list|join|leave]", EnumChatType.CommandError); | ||
return; | |||
} | } | ||
} | } | ||
} | } | ||
} | } | ||
</syntaxhighlight> | </syntaxhighlight> | ||
Revision as of 10:04, 15 April 2020
Before starting, you should have a development environment set up. If you don't have one already you should read the tutorial Setting up your Development Environment. Furthermore, we assume that you have a basic understanding of the C# language and Object Oriented Programming. Let's get started!
Introduction
VintageStory allows you to set and retrieve custom data to the world's game save as well as individual chunks. The way it works is actually quite simple!
Custom data is stored as an array of bytes to save space, but we can easily convert any valid C# type to byte[]
with a very convenient class in the VintageStory API: SerializerUtil
. This class provides us with two static methods that allow us to quickly Serialize
into byte arrays, and Deserialize<T>
them into other types.
You can check out the methods for storing and retrieving these arrays of bytes for Chunks and for SaveGame
Custom Data in SaveGame
Let us show you this powerful set of tools by making an example mod in which we implement an open list of players currently looking for a group to play with ingame.
This list will be a List<string>
of players which will be stored to the world's SaveGame
. Anyone can join it, leave it, or see who needs a group. We'll store this list as an array of bytes, and it can be accessed by the key "lfg".
Preparation
Let's start by creating a new .cs file for this mod, and adding our imports and the VintageStory.ServerMods
namespace to wrap our class in. Additionally, we'll declare the class LookingForGroup
that will inherit from ModSystem
which is the base class for mod systems. You can read more about this here.
using System.Collections.Generic;
using Vintagestory.API.Common;
using Vintagestory.API.Server;
using Vintagestory.API.Util;
namespace Vintagestory.ServerMods
{
class LookingForGroup : ModSystem
{
ICoreServerAPI serverApi;
List<string> lfgList;
public override void StartServerSide(ICoreServerAPI api)
{
serverApi = api;
api.Event.SaveGameLoaded += OnSaveGameLoading;
api.Event.GameWorldSave += OnSaveGameSaving;
api.RegisterCommand("lfg", "List or join the lfg list", "[list|join|leave]", OnLfg);
}
}
}
In this class, we create an override for the StartServerSide
method. This method of the ModSystem
is called for all mods on the Server side by the game.
When the Server side starts, we add two event delegates that will retrieve our list from the SaveGame
when the we game loads, and that will save the list when the game saves. We also register a command that players will use to access our list of those looking for group. This will be /lfg
with the arguments list, join or leave.
Let's create these event delegates!
Retrieving and Storing the List
When the game loads, OnSaveGameLoading
gets called and attempts to get our list of players looking for group. The Core Server Api has a member called WorldManager
which we use to access everything World related, including our SaveGame
.
private void OnSaveGameLoading()
{
byte[] data = serverApi.WorldManager.SaveGame.GetData("lfg");
lfgList = data == null ? new List<string>() : SerializerUtil.Deserialize<List<string>>(data);
}
We attempt to get our list by exposing the GetData
method and passing it an identifier for our custom data, in this case our "lfg" list.
Hint: If nothing is found stored under the key we provide, the GetData
method returns null. In our mod example, this will happen until at least one player enters the list!
byte[] data = serverApi.WorldManager.SaveGame.GetData("lfg");
As you can see, we're retrieving an array of bytes, which is the data type we actually store on the SaveGame
. Let's convert it to a List
of strings:
lfgList = data == null ? new List<string>() : SerializerUtil.Deserialize<List<string>>(data);
Here we use a ternary operator to assign our lfgList
field a new List<string>
if there was nothing stored under the "lfg" key.
If data
is not null, we expose the Deserialize<T>
method of the SerializerUtil
class. This method will deserialize an array of bytes into an instance of the type argument we pass it. Now that we have a delegate that fetches our list of players "lfg", let's create the delegate that stores this list when the Game World is saved:
private void OnSaveGameSaving()
{
serverApi.WorldManager.SaveGame.StoreData("lfg", SerializerUtil.Serialize(lfgList));
}
Here we call the StoreData
method to save our list under the "lfg" key for later retrieval! Because we can only store data in the form of byte[]
, we use the Serialize
method of the SerializerUtil
class to turn lfgList
back to an array of bytes, which we pass as the second argument.
We now have implemented a way to assign our list from storageto lfgList
when the SaveGame
is loaded, and a way to store this list once the game is saved. In between these two events, we want players to be added or removed from lfgList
via our command. Let's create our command delegate!
Handling the Command
Server chat commands have three parameters: the player issuing the command, the group in which this command was entered, and the arguments sent for the command.
private void OnLfg(IServerPlayer player, int groupId, CmdArgs args)
{
string cmd = args.PopWord();
switch (cmd)
{
case "join":
break;
case "leave":
break;
case "list":
break;
default:
player.SendMessage(groupId, "/lfg [list|join|leave]", EnumChatType.CommandError);
break;
}
}
We use the PopWord
of our CmdArgs
parameter to collect the first argument passed (ignoring anything subsequent). We then start a switch statement for our valid arguments, and default to showing these to the player if none of them match or cmd
is null.
Let's handle each of these:
case "join":
if (lfgList.Contains(player.PlayerUID))
{
player.SendMessage(groupId, "You're already in the list!", EnumChatType.CommandError);
}
else
{
lfgList.Add(player.PlayerUID);
player.SendMessage(groupId, "Successfully joined.", EnumChatType.CommandSuccess);
}
break;
If /lfg join
was entered, we'll first check if the player is already on the "lfg" list, letting the player know if so. Alternatively, we add the player's unique identifier to the list and show a success message.
Hint: We do not want to store player names directly. This is because player names may change, therefore our list could become inaccurate.
Next we handle /lfg leave
:
case "leave":
if (!lfgList.Remove(player.PlayerUID))
{
player.SendMessage(groupId, "You're not in the list!", EnumChatType.CommandError);
}
else
{
player.SendMessage(groupId, "Successfully left.", EnumChatType.CommandSuccess);
}
break;
The Remove
method returns false if nothing matching the argument passed to it was found and removed, and true if it was. We let the player know if they were not on the list, or if they were and got successfully taken out of it.
Finally, we handle /lfg list
:
case "list":
if (lfgList.Count == 0)
{
player.SendMessage(groupId, "Noone is looking for a group.", EnumChatType.CommandSuccess);
}
else
{
string response = "Players looking for group:";
lfgList.ForEach((playerUid) =>
{
response += "\n" + serverApi.World.PlayerByUid(playerUid).PlayerName;
});
player.SendMessage(groupId, response, EnumChatType.CommandSuccess);
}
break;
In this case we simply let the player know if there is noone on the list, but if there are we build a string with all the player names on the list.
Conclusion
If you followed the steps correctly, you should have the following code:
using System.Collections.Generic;
using Vintagestory.API.Common;
using Vintagestory.API.Server;
using Vintagestory.API.Util;
namespace Vintagestory.ServerMods
{
class LookingForGroup : ModSystem
{
ICoreServerAPI serverApi;
List<string> lfgList;
public override void StartServerSide(ICoreServerAPI api)
{
serverApi = api;
api.Event.SaveGameLoaded += OnSaveGameLoading;
api.Event.GameWorldSave += OnSaveGameSaving;
api.RegisterCommand("lfg", "Access the lfg list.", "[list|join|leave]", OnLfg);
}
private void OnSaveGameLoading()
{
byte[] data = serverApi.WorldManager.SaveGame.GetData("lfg");
lfgList = data == null ? new List<string>() : SerializerUtil.Deserialize<List<string>>(data);
}
private void OnSaveGameSaving()
{
serverApi.WorldManager.SaveGame.StoreData("lfg", SerializerUtil.Serialize(lfgList));
}
private void OnLfg(IServerPlayer player, int groupId, CmdArgs args)
{
string cmd = args.PopWord();
switch (cmd)
{
case "join":
if (lfgList.Contains(player.PlayerUID))
{
player.SendMessage(groupId, "You're already in the list!", EnumChatType.CommandError);
}
else
{
lfgList.Add(player.PlayerUID);
player.SendMessage(groupId, "Successfully joined.", EnumChatType.CommandSuccess);
}
break;
case "leave":
if (!lfgList.Remove(player.PlayerUID))
{
player.SendMessage(groupId, "You're not in the list!", EnumChatType.CommandError);
}
else
{
player.SendMessage(groupId, "Successfully left.", EnumChatType.CommandSuccess);
}
break;
case "list":
if (lfgList.Count == 0)
{
player.SendMessage(groupId, "Noone is looking for a group.", EnumChatType.CommandSuccess);
}
else
{
string response = "Players looking for group:";
lfgList.ForEach((playerUid) =>
{
response += "\n" + serverApi.World.PlayerByUid(playerUid).PlayerName;
});
player.SendMessage(groupId, response, EnumChatType.CommandSuccess);
}
break;
case null:
default:
player.SendMessage(groupId, "/lfg [list|join|leave]", EnumChatType.CommandError);
return;
}
}
}
}
Testing
Let's test our mod. Once you're ingame, try entering /lfg join
. Now quit the game and join back in. Upon entering /lfg list
, you should see your name on the list; this means that your custom data has persisted in the SaveGame
!
Distribution
To distribute this mod, you may run the following command in the modtools cli pack <your mod id>, then copy the .zip file into your VintageStory mods folder.
Here are the official versions:
- for VS v1.12.4: LookingForGroup_vs1.12.4_v1.0.0.zip
- for VS v1.6: LookingForGroup_vs1.6_v1.0.0.zip