Modding:Chunk Moddata

This page was last verified for Vintage Story version 1.19.8.

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	save game on disk client over network	IWorldChunk.LiveModData IWorldChunk.SetModdata - has serialization race conditions. Use LiveModData instead. IWorldChunk.GetModdata
server mod data	server	server	save game on disk	IServerChunk.GetServerModdata IServerChunk.SetServerModdata

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.

Chunk Serialization Triggers

When a chunk is marked as modified, it is eventually serialized into the save game on disk. A chunk is marked as modified in many conditions, such as when an entity is created in it, or a block is modified. However, when storing custom mod data in the chunk, the safest option is to directly marked as modified by calling IWorldChunk.MarkModified. This example mod relies on the player dying to mark the chunk as modified.

Modified chunks will get serialized by the next save game event. They will get serialized sooner if the chunk is unloaded. Both of these operations run on the chunk thread (not the main thread). Care must be taken with updating the mod data dictionaries at the right time. The dictionaries should be updated right before they are serialized. If the dictionaries are updated too early before the chunk is locked, then the main thread can further modify the chunk before the serialization. Then the chunk will be in an inconsistent state. Maybe the compressed blocks will be newer than the mod data. Although for most mods, small race conditions like this would be unnoticeable.

LiveModData serializes its fields at exactly the right time: on the chunk thread while the chunk is locked for serialization. There are no other events one can hook into to trigger serialization at the correct time. This is why LiveModData is strongly recommended over IWorldChunk.SetModdata.

There is no equivalent to LiveModData for the server mod data. So instead this example mod stores a fake entry in LiveModData with a [ProtoBeforeSerialization] callback. It uses that callback to update the server mod data dictionary right before the chunk is serialized.

[ProtoContract]
public class SerializationCallback {
  public delegate void OnSerializationDelegate(IServerChunk chunk);

  readonly private IServerChunk _chunk;
  public OnSerializationDelegate OnSerialization;

  public SerializationCallback(IServerChunk chunk) {
    _chunk = chunk;
  }

  [ProtoBeforeSerialization]
  private void BeforeSerialization() {
    OnSerialization(_chunk);
  }
}
...
    if (!chunk.LiveModData.TryGetValue("haunting", out object serializerObj) || serializerObj is not SerializationCallback serializer) {
      serializer = new(chunk);
      chunk.LiveModData["haunting"] = serializer;
    }
    serializer.OnSerialization += chunk => chunk.SetServerModdata("haunting", SerializerUtil.Serialize(chunkData));

An earlier version of haunting mod relied the IServerEventAPI.GameWorldSave event. However, that event is not called before chunks are unloaded. It is also called too early in the save game process, such that the chunk can be modified again before it is serialized.

In addition to saving chunks to disk, nearby chunks are sent to clients when they first join the server, or when they walk into range of the chunk. When using shared mod data, the data may need to be sent more often by calling IWorldManagerAPI.BroadcastChunk. Note that marking a chunk as modified only triggers saving it to disk; it does not trigger sending the modified chunk to clients.

Preparation

Let's start by creating a new .cs file for this mod, and adding our imports and the HauntedChunks namespace to wrap our class in. Additionally, we'll declare the class HauntedChunks 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 HauntedChunks;

public class HauntedChunks : ModSystem {
  private ICoreServerAPI _serverApi;

  public override void StartServerSide(ICoreServerAPI api) {
    _serverApi = api;
  }
}

The StartServerSide method is a member of ModSystem and is called for all mods on the Server side by the game. It is given a ICoreServerAPI, which the mod will need later. So the mod overrides the method and saves it in _serverApi. hauntedChunks will be a list of hunated chunks and their haunting level.

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 two separate events, each with their own delegates that we'll define later. The purpose of each is as follows:

• 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. Note that DidUseBlock is called any time any block is right clicked. A more efficient -- but complicated -- approach would be to create a behavior that intercepts OnBlockInteractStart, and install it on just the bed block.

Let us now define these event 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.TryGetValue(chunk, out HauntingChunkData chunkData)) {
      chunkData = AddChunkToDictionary(chunk, true);
    }

    chunkData.Deaths++;
  }

The OnPlayerDeath delegate that we used to listen for player death events, will first retrieve the chunk the player died on, by calling IWorldManager.GetChunk. 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 HauntingChunkData AddChunkToDictionary(IServerChunk chunk, bool create) {
    HauntingChunkData chunkData;
    byte[] data = chunk.GetServerModdata("haunting");
    if (data != null) {
      chunkData = SerializerUtil.Deserialize<HauntingChunkData>(data);
    } else if(!create) {
      return null;
    } else {
      chunkData = new();
    }

    _hauntedChunks.Add(chunk, chunkData);
    if (!chunk.LiveModData.TryGetValue("haunting", out object serializerObj) || serializerObj is not SerializationCallback serializer) {
      serializer = new(chunk);
      chunk.LiveModData["haunting"] = serializer;
    }
    serializer.OnSerialization += chunk => chunk.SetServerModdata("haunting", SerializerUtil.Serialize(chunkData));
    return chunkData;
  }

_hauntedChunks acts like a cache. If the cache does not have the entry, maybe it already exists on disk. GetServerModdata is called to read the entry from disk (technically it is already in memory but not deserialized into _hauntedChunks yet). GetServerModdata returns a byte[].

If GetServerModdata returned non-null, then it deserializes the previous haunting level from disk into a HauntingChunkData object. If GetServerModdata returned null, then that means the mod has never attached a haunting level to the chunk. In this case, the create parameter indicates whether a new default HauntingChunkData should be attached to the chunk, or whether it should return null to indicate no data is attached.

As described earlier, a fake entry is added to LiveModData just to get a notification when the chunk is serialized. The mod responds to that notification by calling SetServerModdata to set the server mod data for the chunk. Note that the fake entry in LiveModData will still get serialized to disk (shown later in the tutorial), but the small overhead is worth getting notified at the correct time.

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.TryGetValue(chunk, out HauntingChunkData chunkData)) {
      chunkData = AddChunkToDictionary(chunk, false);
    }

    int haunting = chunkData?.Deaths ?? 0;
    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 in-game 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 then call AddChunkToDictionary to possibly add it. The second argument to AddChunkToDictionary is false, to indicate that it should only load the haunting data if it already exists in the chunk in the save file. If it does not exist, then AddChunkToDictionary returns null. The later chunkData?.Deaths ?? 0 converts a null into a 0.

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!

Viewing the raw mod data

It is possible to extract the raw mod data from the save game to verify it was written Deserializing_protobufs_from_the_command_line has more details about how to setup the tools to view the raw data.

The raw data shows that that the fake entry to the shared mod data (just called moddata in the save game) was written with an empty value. The real haunting count was written to the server mod data.

$ sqlite3 test_world.vcdbs "SELECT writefile('chunk_' || position || '.binpb', data) FROM chunk;"
92
92
92
...
$ protoc --decode ServerChunk --proto_path=$HOME $HOME/schema-1.19.8.proto <chunk_2147483664000.binpb
blocksCompressed: "\350\377\377\377\000\000\000\000r\032\000\000o\014\000\000~\014\000\000v\"\000\000y\"\000\000(\265/\375`\000/\245\001\000\350\377\377\377\377\000\000\000\377\377\377\000\000\000\001\000\000\377\377\377\000\000\000\001\000\000\000\001\000\000\010\020\000n\366\215\000\364CO\ry\373!\014\235\016\235\216\234\022\001"
lightCompressed: "(\265/\375`\000\017\215\000\0008\000\000\000\000\377\377\377\002\000\372\006\376\310S\200\010"
lightSatCompressed: "(\265/\375 \010A\000\000\000\000\000\000\026\000\000\000"
EntitiesCount: 1
BlockEntitiesCount: 1
BlockEntitiesSerialized: "\003Bed\001\004posx\000\320\007\000\001\004posy\003\000\000\000\001\004posz\003\320\007\000\005\tblockCode\023bed-wood-head-north\002\021mountedByEntityId\000\000\000\000\000\000\000\000\005\022mountedByPlayerUid\000\000"
moddata {
  key: "haunting"
  value: ""
}
ServerSideModdata {
  key: "haunting"
  value: "\010\002"
}
GameVersionCreated: "1.19.8"
DecorsSerialized: ""
savedCompressionVersion: 2
liquidsCompressed: "\000\000\000\000"
BlocksPlaced: 1

The mod data value has another layer of protobuf serialization. It is not easy to get the schema to properly decode it, but one can at least perform a raw decode to see the haunting value was 2 in this chunk. Note that the below syntax to parse the C-style escaped string only works on Linux.

$ echo -n $'\010\002' | protoc --decode_raw
1: 2

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;
using ProtoBuf;
using System.Runtime.CompilerServices;

namespace HauntedChunks;

[ProtoContract]
public class SerializationCallback {
  public delegate void OnSerializationDelegate(IServerChunk chunk);

  readonly private IServerChunk _chunk;
  public OnSerializationDelegate OnSerialization;

  public SerializationCallback(IServerChunk chunk) {
    _chunk = chunk;
  }

	[ProtoBeforeSerialization]
  private void BeforeSerialization() {
    OnSerialization(_chunk);
  }
}

[ProtoContract]
public class HauntingChunkData {
	[ProtoMember(1)]
  public int Deaths;
}

public class HauntedChunks : ModSystem {
  private ICoreServerAPI _serverApi;
  private readonly ConditionalWeakTable<IServerChunk, HauntingChunkData> _hauntedChunks = new();

  public override void StartServerSide(ICoreServerAPI api) {
    _serverApi = api;

    api.Event.PlayerDeath += OnPlayerDeath;
    api.Event.DidUseBlock += OnUseBlock;
  }

  private void OnPlayerDeath(IServerPlayer byPlayer,
                             DamageSource damageSource) {
    IServerChunk chunk =
        _serverApi.WorldManager.GetChunk(byPlayer.Entity.ServerPos.AsBlockPos);

    if (!_hauntedChunks.TryGetValue(chunk, out HauntingChunkData chunkData)) {
      chunkData = AddChunkToDictionary(chunk, true);
    }

    chunkData.Deaths++;
  }

  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.TryGetValue(chunk, out HauntingChunkData chunkData)) {
      chunkData = AddChunkToDictionary(chunk, false);
    }

    int haunting = chunkData?.Deaths ?? 0;
    if (haunting > 0) {
      byPlayer.Entity.ReceiveDamage(
          new DamageSource() { Source = EnumDamageSource.Void,
                               Type = EnumDamageType.BluntAttack },
          haunting);
    }
  }

  private HauntingChunkData AddChunkToDictionary(IServerChunk chunk, bool create) {
    HauntingChunkData chunkData;
    byte[] data = chunk.GetServerModdata("haunting");
    if (data != null) {
      chunkData = SerializerUtil.Deserialize<HauntingChunkData>(data);
    } else if(!create) {
      return null;
    } else {
      chunkData = new();
    }

    _hauntedChunks.Add(chunk, chunkData);
    if (!chunk.LiveModData.TryGetValue("haunting", out object serializerObj) || serializerObj is not SerializationCallback serializer) {
      serializer = new(chunk);
      chunk.LiveModData["haunting"] = serializer;
    }
    serializer.OnSerialization += chunk => chunk.SetServerModdata("haunting", SerializerUtil.Serialize(chunkData));
    return chunkData;
  }
}

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

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.