Loading and saving data

The Disk API allows you to persistently store and retrieve data for players or general use. Useful for tracking stats, progress, or saving any kind of JSON-compatible values between server restarts.

---

Overview

Method	Description
DiskApi.loadFile(fileName, async, global)	Loads the contents of a file into memory. Must be called before accessing any stored values with getVar
DiskApi.saveFile(fileName, async, global)	Saves the in-memory data for the specified file to disk. Call this to persist changes made via setVar . This will also clear the data from the memory (ram)
DiskApi.getVar(fileName, key, fallbackValue, global)	Retrieves the value associated with key from the in-memory file. If the key doesn't exist, returns fallbackValue
DiskApi.setVar(fileName, key, value, global)	Sets the value of key to value in the in-memory file. This does not save to disk until saveFile is called

When storing and loading player data, make sure to separate the files for each player. Also, always save the player's file when they leave to prevent memory leaks from accumulating as new players join!

---

Parameters

Parameter	Type	Description
fileName	String	Name of the file (no extension). Should be unique per player or purpose.
key	String	The variable name to store or retrieve.
value	Any	Value to be saved. Will be serialized using JSON.stringify.
fallbackValue	Any	Value to return if the key does not exist.
async	Boolean	If true, runs the load/save operation in a separate thread.
global	Boolean	If true, the file is shared across all scripts; otherwise script-specific.

---

Async Explained

Setting async = true will cause the file operation to run in a separate thread, preventing lag or stalling the main server thread.

However, since file I/O will be delayed, you should wait before accessing or modifying data by using:

task.spawn(function(){ /* Your logic here */ })

Using registerSchedule with the second parameter set to 0 ensures the code runs in a separated thread.

If you're using task.spawn(function() {}) to run your logic off the main thread, you should set async = false in your DiskApi methods. This avoids double-threading and ensures data is loaded and available in the same thread.

---

Global vs Local Storage

• global = false: Data is saved per script, useful for isolated storage.

• global = true: Data is shared across scripts, use for shared access.

---

Example Usage

var ValueName = "destroyedBlocks"

function getFileName(player) {
    return player.getUniqueId() + "_data"
}

registerEvent("org.bukkit.event.player.PlayerJoinEvent", function(event) {
    task.spawn(function() {
        var player = event.getPlayer();
        var fileName = getFileName(player);
        DiskApi.loadFile(fileName, false, false);
        var breakedBlocks = DiskApi.getVar(fileName, ValueName, 0, false);
        player.sendMessage("You destroyed "+breakedBlocks+" blocks!")
    });
})

registerEvent("org.bukkit.event.player.PlayerQuitEvent", function(event) {
    task.spawn(function() {
        var player = event.getPlayer();
        var fileName = getFileName(player);
        log.info("Saving player data...")
        DiskApi.saveFile(fileName, false, false);
        log.info("Data saved!")
    })
})

registerEvent("org.bukkit.event.block.BlockBreakEvent", function(event) {
    var player = event.getPlayer()
    var fileName = getFileName(player);
    var destroyedBlocks = DiskApi.getVar(fileName, ValueName, 0, false) + 1
    DiskApi.setVar(fileName, "destroyedBlocks", destroyedBlocks, false)
    event.getPlayer().sendMessage("You destroyed " + destroyedBlocks + " blocks!");
});

---

Tips

• Always load the file before using getVar() or setVar()

• For frequent access, store fileName in a variable to avoid recalculating

• For large data sets or many players, prefer async = true and threading logic using task.spawn()

• Data that is still in memory will automatically save as soon as the plugin gets disabled/shutdown