Config Files (storage with default values)

What is commonly referred to as configuration files are in Asphalt nothing more than storages with prefined default values. Therefore read and understand how storages in general work before you read any further!

Defining the default values

For this purpose, an array of default values is defined in the code, in asphalt these are the so called KeyDefaultValues.

Every time the mod is started, the system checks whether the storage already exists, otherwise it is created.

On the other hand, the keys in the storage are compared with the KeyDefaultValues defined in the code. If one of the defined keys is missing, it is then added to the storage with its corresponding default value. If there is a key in storage that does not exist in the default values, it is removed from storage. This ensures that even with a newer version of Mod, in which the required default values have changed, the config created in the previous version can still be used in the most cases.

These KeyDefaultValues are defined in a static method as follows:

public static KeyDefaultValue[] GetConfigValues()
{
    return new KeyDefaultValue[]
    {
        new KeyDefaultValue("local-chat-radius", 100.0),
        new KeyDefaultValue("local-chat-mask","<color=yellow>[L]</color> <color=white>{0}: {1}</color>"),
        ...
        new KeyDefaultValue("msg-from-mask","<color=#FF1493>From {0}: {1}</color>")
    };
}

The method name can be chosen as you like, it is only used to define the storage field/property later on. For example purposes GetConfigValues is used.

Defining the storage

Creating a storage with default values does not differ much from creating a normal storage.

[Inject]
[StorageLocation("config")]
[DefaultValues(nameof(GetConfigValues))]
public static IStorage Config { get; set; }

The only difference is the [DefaultValues(...)]-attribute. The parameters of this attribute now contain the name of the previously created method with the KeyDefaultValues. In the example GetConfigValues is used.

That's about it. Asphalt takes care of everything else in the process. As with any other storage, the values can also be read and set (see Data Storage). It is important to ensure that only values defined in the default value method are used.

Other Storage Types

The applications for other storage types, such as the storage collection or the user storage collection, are similar to the one described above.

[Inject]
[StorageLocation("player_settings")]
[DefaultValues(nameof(GetPlayerSettingsValues))]
public static IUserStorageCollection PlayerSettings { get; set; }

The big difference with storage collections is that the default values are mirrored into an added _default.json file. If the value is now read out and a value other than the default value was previously assigned for the storage, this value is returned. If the value for the selected storage was not previously changed, then simply the value defined in the _default.json is returned.

This allows server owners and modpacks to make changes to the default values for the storage collection.

It also helps to save memory space, as a new file is only created when the value is modified and otherwise only the standard values are processed.