Persisting Data

When creating more advanced mods you will find the need to persist data between play sessions. This is easily done anywhere there are save and write functions provided. Even when they are not there are means to ensure data is persisted.

Regardless of where the data is being saved and loaded you will always be working with a DataStream. A DataStream works by saving/loading data piece by piece. Such as DataStream.writeUint32() is used to save a unsigned integer.


Always be sure to save and load the exact same data in the same order!

Here is an example of saving and loading some data.

def write(self, stream):

def read(self, stream):
    self.location = stream.readUint8()
    self.entityId = stream.readUint32()
    self.bagIndex = stream.readUint8()
    self.index = stream.readUint8()
    self.toolSlot = stream.readUint8()
    self.slot = stream.readString()
    self.reserve = stream.readString()
    self.customLocation = stream.readString()

Persisting Means

World Saving/Loading

There are several ways to persist data. Components and plants provide read and write functions that are given a DataStream.

Sometimes you will want to save data outside of these. The world_saved() event can be listened to anytime you need to add a new subsystem or system to persist data. Using the world_save will require you to create your own DataStream as well as save it with FileManager.asyncWrite() or This will save the data into a new file.

Use the world_created() event to load this saved data. You should always check that the file exists with File.exists() and load it with File.load().


Always be sure to save a version with the data to support backwards compability!

def _getPath(self, world):
    return os.path.join(world.path, "merchant")

def _saveData(self, world, asynchronous):
    contentStash = game.content
    entityManager = game.entity
    stream = DataStream()
    self.wares.write(stream, contentStash, entityManager)
    self.daily.write(stream, contentStash, entityManager)
    if asynchronous:
        game.file.asyncWrite(self._getPath(world), FileOnCompleteHandler.create(), stream, useCompression=False)
    else:, stream)

def _loadData(self, world):
    if File.exists(self._getPath(world)):
        stream = DataStream()
        File.load(self._getPath(world), stream)
        version = stream.readUint16()
        contentStash = game.content
        entityManager = game.entity, contentStash, entityManager), contentStash, entityManager)

def register():
    merchant = MerchantSystem()
    game.registerSystem(MerchantSystem.NAME, merchant)
    if NetworkManager.isHost():
        # We only want to save the data on the host (server)['world_saved'].listen(merchant._saveData)['world_created'].listen(merchant._loadData)

def unregister():
    if NetworkManager.isHost():['world_saved'].remove(game.merchant._saveData)['world_created'].remove(game.merchant._loadData)


This will work even without a system or subsystem.

Character Saving/Loading

Sometimes you will want data to be saved with characters but not in a component. This is accomplished using World.addPlayerDataHandlers(). The provided reader and writer callbacks are called when a player is being saved or loaded. Each reader/writer pair is associated with a key and if that key cannot be found when loading then it skips the saved data.

def testReader(player, stream):
   value = stream.readString()

def testWriter(player, stream):

def register():
   World.get().addPlayerDataHandlers("test", testReader, testWriter)