Using Saves

Sometimes when making a script you may need to store something, such as an achievement, for the player's future play sessions. This is where Funkin's Save system comes in.

This chapter will walk you through using the game's global save file to store your custom data.

Accessing the Save File

To access the currently used save file, you must first import the funkin.save.Save class in your script. Afterwards, you can do something like this to access the save file:

import funkin.save.Save;

// ...

    var charactersSeen:Array<String> = Save.instance.charactersSeen.value;
public override function onCreate(event:ScriptEvent)
{
    // Access the characters that are selectable in the Character Select menu.
    var charactersSeen:Array<String> = Save.instance.charactersSeen.value;

    // ... some functionality
}

With the save file, you can also access the player's stored tallies for both levels and songs. If the song you're looking for is a variation that isn't 'default' or 'erect', format the requested song by adding -[variation] at the end, with [variation] being the song variation you're looking for.

To do that, you can do something like this:

public override function onCreate(event:ScriptEvent)
{
    // Access the score for the Lit Up (BF Mix) hard chart.
    var score:Int = Save.instance.getSongScore("lit-up-bf", "hard")?.score ?? 0;
}

The main thing you'd want to access to store your custom values is Save.instance.modOptions. This is where your custom values should go, assigned to a key for a more convenient access.

Writing to and reading from the modOptions

You can store a value to the modOptions by doing something like the following example, in which a value would be stored in the player's save file with an appropriate key after they had met the criteria.

import funkin.play.PlayState;
import funkin.save.Save;

// ...

public override function onSongEnd(event:ScriptEvent)
{
    // Store the completion of a song if the player's score is higher than 100,000.
    if (PlayState.instance.songScore > 100000)
    {
        Save.instance.modOptions.set("hasMoreThan100k", true);
        Save.instance.flush();
    }
}

To access the stored value, you can to something like this. It is important to account for the player not having any stored value in their save file and, if so, returning a fallback.

public override function onCreate(event:ScriptEvent)
{
    // Check if the player had met the previously established criteria.
    var hasMetCriteria:Bool = false;
    if (Save.instance.modOptions.exists("hasMoreThan100k"))
    {
        hasMetCriteria = Save.instance.modOptions.get("hasMoreThan100k");
    }

    // ... some check or functionality here
}