Storage

Storage Skill — Paper

Purpose

Reference this skill to choose the right storage mechanism for a Paper plugin. Covers when to use config files, PersistentDataContainer (PDC), or a full database, and links to detailed implementation guides for each.

When to Use This Skill

• Deciding where to persist plugin data
• Storing per-entity or per-block metadata
• Managing plugin configuration that users can edit
• Setting up a database for large-scale or cross-server data

API Quick Reference

Storage Decision Guide

Code Pattern

package com.yourorg.myplugin.storage;

import org.bukkit.configuration.file.FileConfiguration;
import org.bukkit.persistence.PersistentDataContainer;
import org.bukkit.persistence.PersistentDataType;
import org.bukkit.NamespacedKey;
import org.bukkit.entity.Player;
import org.bukkit.plugin.java.JavaPlugin;

public class StorageExamples {

    private final JavaPlugin plugin;

    // --- Config ---

    public void loadConfig() {
        plugin.saveDefaultConfig();                    // write defaults if absent
        FileConfiguration config = plugin.getConfig();
        String greeting = config.getString("messages.greeting", "Welcome!");
        int maxPlayers = config.getInt("limits.max-players", 50);
    }

    // --- PersistentDataContainer ---

    private final NamespacedKey killKey;

    public StorageExamples(JavaPlugin plugin) {
        this.plugin = plugin;
        this.killKey = new NamespacedKey(plugin, "kill_count");
    }

    public void incrementKills(Player player) {
        PersistentDataContainer pdc = player.getPersistentDataContainer();
        int current = pdc.getOrDefault(killKey, PersistentDataType.INTEGER, 0);
        pdc.set(killKey, PersistentDataType.INTEGER, current + 1);
        // No manual save needed — persisted automatically with the player data
    }

    public int getKills(Player player) {
        return player.getPersistentDataContainer()
            .getOrDefault(killKey, PersistentDataType.INTEGER, 0);
    }
}

Common Pitfalls

• Not calling saveConfig() after set(): getConfig().set(key, value) modifies only the in-memory object. Call saveConfig() to persist to disk, or data is lost on restart.

• Creating NamespacedKey with plugin-unrelated namespaces: Always use new NamespacedKey(plugin, "name"). Using NamespacedKey.minecraft("name") will create keys in the minecraft: namespace, which may conflict with vanilla data or other plugins.

• Reading PDC on async threads: PDC reads/writes are technically possible off the main thread, but the entity must not be modified concurrently. Safest: always access PDC on the main thread.

• Using raw Java HashMap for persistent data: In-memory maps are cleared on restart. Use PDC for entity-bound data or a database for anything that must survive restarts.

• Blocking the main thread with database queries: All SQL calls must run asynchronously. See database-hikari.md for the async pattern.

Version Notes

• 1.21: PersistentDataType added LIST and TAG_CONTAINER compound types for nested structured data.
• 1.21.1: No breaking changes to storage API.
• Both: config.yml + YAML API is unchanged from older Paper versions.

Related Skills

• config-yml.md — Full FileConfiguration and multi-file config setup
• pdc.md — PersistentDataContainer deep dive including custom types
• database-hikari.md — HikariCP setup, async queries, SQLite/MySQL
• ../OVERVIEW.md — Platform setup and Gradle template