Data Storage

Storage is generally defined here as any form of data storage. Even if currently only the saving of data in .json files is supported, the integration of databases is planned for the future.

Basic Storage

A basic storage file is very easy to define. We need a field or property of the type IStorage, to which we assign the necessary attributes.

[Inject]
[StorageLocation("file_name_without_extension")]
public IStorage SomeStorage { get; set; }

The [Inject]-attribute is needed in order for Asphalt to perform the Dependency-Injection later on.

The [StorageLocation(string)]-attribute defines where to save the storage. This could either be a file name e.g. "file" or a path e.g. "some_directory/file". This is based on the respective folder of the mod: Mods/<your_mod>/<the_location_you_defined>.

Thats about everything you have to do to initialize your storage. Everything else is done by Asphalt.

Storing values

The Storage works basicly like every other Key-Value Storage. The value is stored behind a specified memory address. For this, one of the following methods can be used:

method	purpose	example usage
void SetString(string key, string value)	stores a string to the respective key	SomeStorage.SetString("motd", "Hello World!");
void SetInt(string key, int value)	stores an int to the respective key	SomeStorage.SetInt("age", 27);
void Set(string key, object value)	stores an unspecified NullableDataType the respective key	SomeStorage.Set("pi-as-float", 3.1415927);

Reading values

Reading values is just as easy. For this, one of the following methods can be used:

method	purpose	example usage
string GetString(string key)	returns the string behind the respective key or null	SomeStorage.GetString("motd")
int GetInt(string key)	returns the int behind the respective key or throws exception	SomeStorage.GetInt("age")
object Get(string key)	returns the Data behind the respective key or null	SomeStorage.Get("pi-as-float")

If no entry for the respective key could be found null is returned.

Storage Collections

If not only individual data is stored, but entire data sets, then there are use cases in which you want to write each entry of this data set into a separate file and not together into one large file. In case several related files are to be used as data storage, Asphalt has the so-called StorageCollections.

These Storage Collections are just as simple to define as a single storage file. The Type of the Field/Property is now not an IStorage, it is an IStorageCollection. The [StorageLocation(...)]-attribute does not specify an individual file name, but the folder in which the different files are stored.

[Inject]
[StorageLocation("some_directory")]
public IStorageCollection SomeStorageCollection { get; set; }

The individual storages can now simply be called using the GetStorage(string fileName) method and used like a normal storage. e.g.:

SomeStorageCollection.GetStorage("shovel").GetInt("durability")

User Storage Collection

The UserStorageCollection is just one specific usecase of a StorageCollection we decided to include with Asphalt. It's used to store data regarding Users. It's defined as follows:

[Inject]
[StorageLocation("some_directory")]
public IUserStorageCollection SomeUserStorageCollection { get; set; }

The user storage can be accessed by using the GetUserStorage(User user) method. e.g.:

SomeUserStorageCollection.GetUserStorage(someUser).GetString("nickname")