Storage

We've been told that people playing games want to save their progress as they go, allowing them to come back where they left off and continue their epic journey of power.

Yeah, roguelikes. Even you.

Discord's storage manager lets you save data mapped to a key for easy reading, writing, and deleting both synchronously and asynchronously. It's saved to a super special directory, the Holy Grail of file mappings, that's unique per Discord user — no need to worry about your little brother overwriting your save file.

Creating this manager will also spawn an IO thread for async reads and writes, so unless you really want to be blocking, you don't need to be!

If you want to take that save data on your players' computers and save it to those BIG COMPUTERS in the cloud, look no further! All you need to do is head over to your manifest config file and set the following property:

javascript
{
  "storage": {
    "sync": true
  }
}

Yup, that's it! Don't know what this file is? Go read Branches and Builds.

Returns the filepath to which Discord saves files if you were to use the SDK's storage manager. Discord has branch-specific, user-specific saves, so you and your little brother will never overwrite each others' save files. If your game already has save file writing logic, you can use this method to get that user-specific path and help users protect their save files.

Returns a string.

None

cs
var savePath = storageManager.GetPath();
Console.WriteLine("You should write your save files to {0}", savePath);

Reads data synchronously from the game's allocated save file into a buffer. The file is mapped by key value pairs, and this function will read data that exists for the given key name.

Returns a UInt32.

Reads data asynchronously from the game's allocated save file into a buffer.

Returns a Discord.Result and a byte[] containing the data via callback.

cs
storeManager.ReadAsync("high_score", (result, data) =>
{
  if (result == Discord.Result.OK) {
    LoadHighScore(data);
  }
});

Reads data asynchronously from the game's allocated save file into a buffer, starting at a given offset and up to a given length.

Returns a Discord.Result and byte[] containing the data via callback.

cs
storeManager.ReadAsyncPartial("high_score", 10, 8, (result, data) =>
{
  if (result == Discord.Result.OK) {
    LoadHighScore(data);
  }
});

Writes data synchronously to disk, under the given key name.

Returns void.

cs
storageManager.Write("high_score", Encoding.UTF8.GetBytes("9999"));

Writes data asynchronously to disk under the given keyname.

Returns a Discord.Result via callback.

cs
storageManager.WriteAsync("high_score", Encoding.UTF8.GetBytes("9999"), (result) =>
{
  if (result == Discord.Result.OK)
  {
    Console.WriteLine("Wrote data");
  }
});

Deletes written data for the given key name.

Returns void.

cs
storageManager.Delete("high_score");
// Because you cheated. Jerk.

Checks if data exists for a given key name.

Returns bool.

cs
var highScore = storageManager.Exists("high_score");
if (!highScore)
{
  Console.WriteLine("Couldn't find any highscore for you. Did you cheat? Jerk.");
}

Returns file info for the given key name.

Returns a FileStat.

cs
var file = storageManager.Stat("high_score");
Console.WriteLine("File {0} is {1} in size and was last edited at {2}", file.Name, file.Size, file.LastModified);

Returns the count of files, for iteration.

Returns an Int32.

None

cs
var numFiles = storageManager.Count();
for (int i = 0; i < numFiles; i++)
{
  Console.WriteLine("We're at file {0}", i);
}

Returns file info for the given index when iterating over files.

Returns a FileStat.

cs
var numFiles = storageManager.Count();
for (int i = 0; i < numFiles; i++)
{
  var file = storageManager.StatAt(i);
  Console.WriteLine("File is {0}", file.Name);
}

cs
var discord = new Discord.Discord(clientId, Discord.CreateFlags.Default);
var storageManager = discord.GetStorageManager();

// Create some nonsense data
var contents = new byte[20000];
var random = new Random();
random.NextBytes(contents);

// Write the data asynchronously
storageManager.WriteAsync("foo", contents, res =>
{
    // Get our list of files and iterate over it
    for (int i = 0; i < storageManager.Count(); i++)
    {
        var file = storageManager.StatAt(i);
        Console.WriteLine("file: {0} size: {1} last_modified: {2}", file.Filename, file.Size, file.LastModified);
    }

    // Let's read just a small chunk of data from the "foo" key
    storageManager.ReadAsyncPartial("foo", 400, 50, (result, data) =>
    {
        Console.WriteLine("partial contents of foo match {0}", Enumerable.SequenceEqual(data, new ArraySegment<byte>(contents, 400, 50)));
    });

    // Now let's read all of "foo"
    storageManager.ReadAsync("foo", (result, data) =>
    {
        Console.WriteLine("length of contents {0} data {1}", contents.Length, data.Length);
        Console.WriteLine("contents of foo match {0}", Enumerable.SequenceEqual(data, contents));

        // We just read it, but let's make sure "foo" exists
        Console.WriteLine("foo exists? {0}", storageManager.Exists("foo"));

        // Now delete it
        storageManager.Delete("foo");

        // Make sure it was deleted
        Console.WriteLine("post-delete foo exists? {0}", storageManager.Exists("foo"));
    });
});