Modding:Chunk Moddata: Difference between revisions
(Give more information about the accessors) |
(Update the format of the custom data the mod writes) |
||
Line 55: | Line 55: | ||
<!--T:7--> | <!--T:7--> | ||
In this example mod we'll show you how to store custom data to chunks represented on the server side. We'll create a mod that keeps track of how many times players have died on a given chunk, | In this example mod we'll show you how to store custom data to chunks represented on the server side. We'll create a mod that keeps track of how many times players have died on a given chunk. Every time a player tries to sleep in a bed, the sum of total deaths on the chunk will be used to inflict damage onto the player! Spooky! | ||
Logically the count of deaths in a chunk is an integer. However, as described earlier, for serialization purposes, that int needs to be stored as a byte array on the chunk. But, an int is more convenient for processing outside serialization purposes. So we'll | Logically the count of deaths in a chunk is an integer. However, as described earlier, for serialization purposes, that int needs to be stored as a byte array on the chunk. But, an int is more convenient for processing outside serialization purposes. So we'll wrap the integer in a '''HauntingChunkData''' class. The '''[ProtoContract]''' and lets the serializer know that it is allowed to serialize the class. The '''[ProtoMember(1)]''' assigns an identifier to the '''Deaths''' field. Any previously unused identifier can be used. The identifier is used to track the field in case the field is later renamed, removed, or new fields are added. Since this is the first version of the mod, such versioning concerns do not apply. | ||
<syntaxhighlight lang='c#'> | |||
[ProtoContract] | |||
public class HauntingChunkData { | |||
[ProtoMember(1)] | |||
public int Deaths; | |||
} | |||
</syntaxhighlight> | |||
Since all of the death tracking and bed tracking logic runs on the server side, the '''HauntingChunkData''' will be stored in the server mod data instead of the shared mod data. | |||
Every time a bed is used, this mod will find the chunk containing the block, then look up the number of deaths in the chunk. Each time a bed is used, it would be possible to deserialize the '''HauntingChunkData''' directly from the server mod data in the chunk. Using a bed occurs rarely enough that the deserialization cost of this approach would be acceptable. However, for pedagogical purposes, this mod uses a more CPU efficient approach: the mod adds a separate dictionary to directly look up the deaths for cached chunks. Later this tutorial will explain how to synchronize '''_hauntedChunks''' with the server mod data dictionary. | |||
<syntaxhighlight lang='c#'> | |||
private readonly ConditionalWeakTable<IServerChunk, HauntingChunkData> _hauntedChunks = new(); | |||
</syntaxhighlight> | |||
'''LiveModData''' contains unserialized objects. This example mod does not store the death count in '''LiveModData''', because '''LiveModData''' serializes its entries to the shared mod data dictionary. However, for mods that use the shared mod data, the performance of directly reading from '''LiveModData''' is lower than directly reading from the server mod data, because reading from '''LiveModData''' skips the deserialization stage for already loaded chunks. However, a mod specific cached chunk dictionary is still faster, because it can skip the string hash call necessary to look up an entry in '''LiveModData''' (in exchange for a cheap '''IServerChunk''' hash call). | |||
<!--T:8--> | <!--T:8--> |
Revision as of 06:34, 15 July 2024
This page was last verified for Vintage Story version 1.12.
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
Custom mod data can be attached to individual chunks. Alternatively, mods can store custom save game mod data that applies to the entire save game.
Each chunk has two dictionaries where custom mod data can be attached. The shared mod data dictionary and the server mod data dictionary. Both of these dictionaries have a string key and a byte array value. Logically LiveModData is another accessor for the shared mod dictionary, but technically it is third dictionary. Every time the chunk is serialized, all of the entries in LiveModData are serialized into byte arrays and stored in the shared mod data dictionary, overriding any existing entries with the same key.
Dictionary | Readable on | Writable on | Serialized to | Accessors |
---|---|---|---|---|
shared mod data | client and server | server |
|
|
server mod data | server | server |
|
Both the server mod data dictionary and shared mod data dictionary are have string keys and byte array values. IWorldChunk.LiveModData internally uses SerializerUtil
to convert rich types into byte arrays. SetServerModdata does not have such a convenience wrapper. So developers need to manually use a serializer such as SerializerUtil.Serialize to convert a rich object into byte array to give SetServerModdata.
Implementation-wise any string can be used as a key in the mod data dictionaries, but the best practice is to use a string that starts with the mod identifier, which is "haunting" in this tutorial.
Custom Chunk Data
In this example mod we'll show you how to store custom data to chunks represented on the server side. We'll create a mod that keeps track of how many times players have died on a given chunk. Every time a player tries to sleep in a bed, the sum of total deaths on the chunk will be used to inflict damage onto the player! Spooky!
Logically the count of deaths in a chunk is an integer. However, as described earlier, for serialization purposes, that int needs to be stored as a byte array on the chunk. But, an int is more convenient for processing outside serialization purposes. So we'll wrap the integer in a HauntingChunkData class. The [ProtoContract] and lets the serializer know that it is allowed to serialize the class. The [ProtoMember(1)] assigns an identifier to the Deaths field. Any previously unused identifier can be used. The identifier is used to track the field in case the field is later renamed, removed, or new fields are added. Since this is the first version of the mod, such versioning concerns do not apply.
[ProtoContract]
public class HauntingChunkData {
[ProtoMember(1)]
public int Deaths;
}
Since all of the death tracking and bed tracking logic runs on the server side, the HauntingChunkData will be stored in the server mod data instead of the shared mod data.
Every time a bed is used, this mod will find the chunk containing the block, then look up the number of deaths in the chunk. Each time a bed is used, it would be possible to deserialize the HauntingChunkData directly from the server mod data in the chunk. Using a bed occurs rarely enough that the deserialization cost of this approach would be acceptable. However, for pedagogical purposes, this mod uses a more CPU efficient approach: the mod adds a separate dictionary to directly look up the deaths for cached chunks. Later this tutorial will explain how to synchronize _hauntedChunks with the server mod data dictionary.
private readonly ConditionalWeakTable<IServerChunk, HauntingChunkData> _hauntedChunks = new();
LiveModData contains unserialized objects. This example mod does not store the death count in LiveModData, because LiveModData serializes its entries to the shared mod data dictionary. However, for mods that use the shared mod data, the performance of directly reading from LiveModData is lower than directly reading from the server mod data, because reading from LiveModData skips the deserialization stage for already loaded chunks. However, a mod specific cached chunk dictionary is still faster, because it can skip the string hash call necessary to look up an entry in LiveModData (in exchange for a cheap IServerChunk hash call).
When the game saves, we iterate through our Dictionary<IServerChunk, int>
, convert the number of death integers into byte arrays, and attach each byte array to its corresponding chunk. Vintage Story will take care of saving that mod data in the game save file.
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 ChunkDataStorage
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.GameContent;
using Vintagestory.API.Common;
using Vintagestory.API.Server;
using Vintagestory.API.Util;
namespace Vintagestory.ServerMods
{
internal class ChunkDataStorage : ModSystem
{
private ICoreServerAPI serverApi;
private Dictionary<IServerChunk, int> hauntedChunks;
public override void StartServerSide(ICoreServerAPI api)
{
serverApi = api;
api.Event.SaveGameLoaded += OnSaveGameLoading;
api.Event.GameWorldSave += OnSaveGameSaving;
api.Event.PlayerDeath += OnPlayerDeath;
api.Event.DidUseBlock += OnUseBlock;
}
}
}
In this class, we declare the field serverApi
for the server api, and hauntedChunks
which will be a list of hunated chunks and their haunting level. We also create an override for the StartServerSide
method, which is a member of ModSystem
and is called for all mods on the Server side by the game.
The Core Server API contains an additional API for Event
registration; this object contains a list of server sided events that we can attach our delegates to, which will be invoked every time the event fires. We do this by assigning a delegate to an exposed event with the +=
operator. In our case, we register to four seperate events, each with their own delegates that we'll define later. The purpose of each is as follows:
api.Event.SaveGameLoaded += OnSaveGameLoading;
We create a blank, new instance of ahauntedChunks
when the game loads.api.Event.GameWorldSave += OnSaveGameSaving;
We'll store each chunk's haunting level as custom chunk data.api.Event.PlayerDeath += OnPlayerDeath;
When a player dies, we want to increase haunting level on the chunk they died in by 1.api.Event.DidUseBlock += OnUseBlock;
We check if the player used a bed, if so we try damaging them according to how haunted the chunk is.
Let us now define these event delegates!
Load and Save delegates
Let's begin by defining the delegates that fire when the game loads and when the game saves:
private void OnSaveGameLoading()
{
hauntedChunks = new Dictionary<IServerChunk, int>();
}
private void OnSaveGameSaving()
{
foreach (KeyValuePair<IServerChunk, int> chunk in hauntedChunks)
{
if(chunk.Value == 0) continue;
chunk.Key.SetServerModdata("haunting", SerializerUtil.Serialize(chunk.Value));
}
}
With OnSaveGameLoading
we simply create a new instance of a Dictionary
in which we hold all the haunted chunks as IServerChunk
for the key, and the chunk's haunting level as int
for the value.
OnSaveGameSaving
has the purpose of going through every chunk we've collected from the last time the server launched, storing the haunting level as byte[]
. We do this with a foreach
loop that iterates through all the entries of hauntedChunks
and sets custom data for each entry's chunk according to its haunting level. The SetServerModdata
method's first argument is an arbitrary string
key, which we choose to name "haunting"; the second argument passed is an array of byte
, which we get by using the Serialize
method of the SerializerUtil
class. This simply turns data (in our case an int
) into a byte[]
.
Let's now define the other two delegates!
Player death and block use delegates
private void OnPlayerDeath(IServerPlayer byPlayer, DamageSource damageSource)
{
IServerChunk chunk = serverApi.WorldManager.GetChunk(byPlayer.Entity.ServerPos.AsBlockPos);
if (!hauntedChunks.ContainsKey(chunk))
{
AddChunkToDictionary(chunk);
}
hauntedChunks[chunk]++;
}
The OnPlayerDeath
delegate that we used to listen for player death events, will first retrieve the chunk the player died on, by calling the GetChunk
method of the server's WorldManager
, an object that is used for a myriad of game world functionality such as accessors for Blocks, Chunks and more. For more information, check out the documentation here. Once we have the chunk's instance as IServerChunk
, we check to see if we're not already holding this chunk in memory by seeing if hauntedChunks
contains it. If it doesn't we'll add it with a method we'll call AddChunkToDictionary
, and this method should look like this:
private void (IServerChunk chunk)
{
byte[] data = chunk.GetServerModdata("haunting");
int haunting = data == null ? 0 : SerializerUtil.Deserialize<int>(data);
hauntedChunks.Add(chunk, haunting);
}
Here we simply call GetServerModdata
, which returns the data stored in the exposing chunk in the form of a byte[]
, or null if nothing is stored under the given string
identifier. In our case we pass it "haunting" which is what we chose to save our haunting level under. We then declare a new int
called haunting, and use a ternary operator to assign 0 if data is null and if not we use the Deserialize<T>
method to convert data into type T
(in our case, an integer).
Hint: Holding custom data as byte[]
means we don't know know the type that is stored. This warrants extra attention when using it, and we should make sure we're always storing and retrieving the same type under for a given key.
Now let's handle our final delegate.
private void OnUseBlock(IServerPlayer byPlayer, BlockSelection blockSel)
{
if (serverApi.World.BlockAccessor.GetBlock(blockSel.Position).GetType() != typeof(BlockBed))
{
return;
}
IServerChunk chunk = serverApi.WorldManager.GetChunk(blockSel.Position);
if (!hauntedChunks.ContainsKey(chunk))
{
AddChunkToDictionary(chunk);
}
int haunting = hauntedChunks[chunk];
if (haunting > 0)
{
byPlayer.Entity.ReceiveDamage(new DamageSource()
{
Source = EnumDamageSource.Void,
Type = EnumDamageType.BluntAttack
}, haunting);
}
}
We begin by checking whether or not the block used is of type BlockBed
, which is a block class defined in the game's Survival mod that corresponds to all beds in the base game. We find the block the player is using by using the GetBlock
method of the World's BlockAccessor
object which holds a lot of ingame block functionality, such as getting, removing and replacing blocks. Check out the documentation for more info. If the block being used by the player is not a bed, there's no need to go further so we return.
Hint: Note that the BlockAccessor
is part of the World
object, which is not to be confused with the aforementioned WorldManager
object. The main difference being that WorldManager is only Server sided, while World
is on both Client and Server side, and contains functionality to access more general aspects of the game world and has a broader scope.
We then get the chunk, the same way we got it previously by exposing GetChunk
, but this time we pass it the position of the bed block. We then check if the hauntedChunks
list contains the chunk, if not we add it with AddChunkToDictionary
.
Finally, we check if the chunk's haunting level is above 0, and if so we damage the player by using the ReceiveDamage
method of the player's Entity
. This method takes two arguments. The first one is the DamageSource
which we pass in as newly created instance. The Source
and Type
fields we populate determine how the player's entity will handle this damage. For instance, damage of type Heal
will increase the entity's health points! The second argument passed is the amount of damage we want the entity to receive, in our case this number will be the haunting level of this chunk, aka the amount of player deaths that happened on the chunk.
The mod is now complete!
Conclusion
If you followed the steps correctly, you should have the following code:
using System.Collections.Generic;
using Vintagestory.GameContent;
using Vintagestory.API.Common;
using Vintagestory.API.Server;
using Vintagestory.API.Util;
namespace Vintagestory.ServerMods
{
internal class ChunkDataStorage : ModSystem
{
private ICoreServerAPI serverApi;
private Dictionary<IServerChunk, int> hauntedChunks;
public override void StartServerSide(ICoreServerAPI api)
{
serverApi = api;
api.Event.SaveGameLoaded += OnSaveGameLoading;
api.Event.GameWorldSave += OnSaveGameSaving;
api.Event.PlayerDeath += OnPlayerDeath;
api.Event.DidUseBlock += OnUseBlock;
}
private void OnSaveGameLoading()
{
hauntedChunks = new Dictionary<IServerChunk, int>();
}
private void OnSaveGameSaving()
{
foreach (KeyValuePair<IServerChunk, int> chunk in hauntedChunks)
{
if(chunk.Value == 0) continue;
chunk.Key.SetServerModdata("haunting", SerializerUtil.Serialize(chunk.Value));
}
}
private void OnPlayerDeath(IServerPlayer byPlayer, DamageSource damageSource)
{
IServerChunk chunk = serverApi.WorldManager.GetChunk(byPlayer.Entity.ServerPos.AsBlockPos);
if (!hauntedChunks.ContainsKey(chunk))
{
AddChunkToDictionary(chunk);
}
hauntedChunks[chunk]++;
}
private void OnUseBlock(IServerPlayer byPlayer, BlockSelection blockSel)
{
if (serverApi.World.BlockAccessor.GetBlock(blockSel.Position).GetType() != typeof(BlockBed))
{
return;
}
IServerChunk chunk = serverApi.WorldManager.GetChunk(blockSel.Position);
if (!hauntedChunks.ContainsKey(chunk))
{
AddChunkToDictionary(chunk);
}
int haunting = hauntedChunks[chunk];
if (haunting > 0)
{
byPlayer.Entity.ReceiveDamage(new DamageSource()
{
Source = EnumDamageSource.Void,
Type = EnumDamageType.BluntAttack
}, haunting);
}
}
private void AddChunkToDictionary(IServerChunk chunk)
{
byte[] data = chunk.GetServerModdata("haunting");
int haunting = data == null ? 0 : SerializerUtil.Deserialize<int>(data);
hauntedChunks.Add(chunk, haunting);
}
}
}
Testing
Let's run the mod now! Once you're ingame, enter the command /kill. From now on, you will receive 1 damage every time you sleep in the chunk you died in.
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.19.8: File:HauntedChunks.zip
![Icon Sign.png](/images/thumb/1/15/Icon_Sign.png/32px-Icon_Sign.png)
Wondering where some links have gone?
The modding navbox is going through some changes! Check out Navigation Box Updates for more info and help finding specific pages.
Modding | |
---|---|
Modding Introduction | Getting Started • Theme Pack |
Content Modding | Content Mods • Developing a Content Mod • Basic Tutorials • Intermediate Tutorials • Advanced Tutorials • Content Mod Concepts |
Code Modding | Code Mods • Setting up your Development Environment |
Property Overview | Item • Entity • Block • Block Behaviors • Block Classes • Block Entities • Block Entity Behaviors • World properties |
Workflows & Infrastructure | Modding Efficiency Tips • Mod-engine compatibility • Mod Extensibility • VS Engine |
Additional Resources | Community Resources • Modding API Updates • Programming Languages • List of server commands • List of client commands • Client startup parameters • Server startup parameters Example Mods • API Docs • GitHub Repository |