Advanced Usage

For simplicity this page will be using the FileType Yaml. All file formats have full parity so whichever you use is up to you.

Optimized Setting/Removing

Crate is designed to provide the best performance possible. In normal use-cases, it can reach up to 3x the speed of the Bukkit/Bungee API.

The library also provides some methods to further increase performance if needed.

Mass Setting Values

Consider the following code:

config.set("Key-1", "Value-1");
config.set("Key-2", "Value-2");
config.set("Key-3", "Value-3");

This is bad for performance since the file will be written to three times.

Instead, one could do this:

config.getFileData().insert("Key-1", "Value-1");
config.getFileData().insert("Key-2", "Value-2");
config.set("Key-3", "Value-3");

This is good for performance since the file will only be written to once.

Serializing/Deserializing Objects Into/From Files

The serialization-system in Crate is designed to be as simple & intuitive as possible. It is also easy to port to different API's because the classes that should be serialized don't need to extend any interfaces. This makes it possible to serialize classes that you don't have access to.

Register Serializable

In this example we have a class named PlayerData which gets serialized into this Json.

{
    "dc2d9d9a-fc16-4045-81f6-b988b0c93978": {
        "location": {},
        "firstjoin": "2023-06-13",
        "lastjoin": "2023-06-13"
    }
}

You can register classes as serializable using CrateSerializer.

CrateSerializer.registerSerializable(new CrateSerializable<PlayerData>() {
    /**
     * Deserialize player data into object
     * */
    @Override
    public PlayerData deserialize(@NotNull Object uncastData, String key) throws ClassCastException {
        var data = ((Map<String, Object>) uncastData);
 
        Player p = Bukkit.getPlayer(UUID.fromString(key));
 
        final String firstJoin = (String) data.getOrDefault("firstjoin", LocalDate.now().toString());
        final String lastJoin = (String) data.getOrDefault("lastjoin", LocalDate.now().toString());
        final HashMap<String, Location> locations = new HashMap<>();
        Map<String, Object> configLocations = (Map<String, Object>) data.getOrDefault("location", new HashMap<>());
        configLocations.forEach((worldname, location) -> {
            locations.put(worldname, Location.deserialize((Map<String, Object>) location));
        });
 
        return new PlayerData(p, firstJoin, lastJoin, locations); // Return object
    }
 
    /**
     * Serialize player data for saving
     * */
    @Override
    public Object serialize(@NonNull PlayerData playerData) throws ClassCastException {
        Map<String, Object> data = new HashMap<>();
 
        data.put("firstjoin", playerData.firstJoin);
        
        data.put("lastjoin", playerData.lastJoin);
 
        Map<String, Object> locationData = new HashMap<>();
        playerData.location.forEach((worldname, location) -> {
            locationData.put(worldname, location.serialize());
        });
        data.put("location", locationData);
 
        return data;
    }
 
    @Override
    public Class<PlayerData> getClazz() {
        return PlayerData.class;
    }
});

Serialize

You can serialize your object with with setSerializable:

config.setSerializable("Key-1", object);

Deserialize

You can deserialize your object with with getSerializable:

config.getSerializable("Key-1", PlayerModel.class);

Basic Usage