SuperDB - Basic Usage

SuperDB is a custom database system for storing complex player data persistently.

Why SuperDB?

The challenge with Minecraft data is persistence - server restarts lose everything. Scoreboards work for numbers but not complex data. SuperDB solves this by storing JavaScript objects as files, so data survives restarts. Use it for player stats, inventories, achievements, settings - anything important.

Key advantage: You store regular JavaScript objects and they're automatically saved to disk. No complex database language needed.

Initialize SuperDB

import { SuperDB } from "@minecraft/server"; // Custom module

// Create database instance
const playerDB = new SuperDB({
  name: "playerData",
  immediateWrite: true // Save immediately on changes
});

// Create a named database
const economyDB = new SuperDB({
  name: "economy",
  immediateWrite: true
});

Store Data

// Store simple data
playerDB.set("player_uuid_1", {
  name: "PlayerName",
  level: 10,
  experience: 500,
  lastLogin: Date.now()
});

// Store complex nested data
playerDB.set("player_uuid_2", {
  name: "AnotherPlayer",
  stats: {
    kills: 25,
    deaths: 5,
    playtime: 3600 // seconds
  },
  inventory: [
    { id: "diamond_sword", enchantments: ["sharpness:2"] },
    { id: "golden_apple", amount: 3 }
  ],
  achievements: ["first_kill", "diamond_miner"]
});

Retrieve Data

// Get player data
const playerData = playerDB.get("player_uuid_1");

if (playerData) {
  console.log(`${playerData.name} is level ${playerData.level}`);
}

// Get with defaults
const data = playerDB.get("player_uuid_1") || {
  name: "New Player",
  level: 1,
  experience: 0
};

// Get all keys
const allPlayers = playerDB.keys();
console.log(`${allPlayers.length} players in database`);

// Iterate over all data
playerDB.forEach((key, value) => {
  console.log(`${value.name} (${key})`);
});

Update Data

// Get data, modify, and save
const player = playerDB.get("player_uuid_1");
if (player) {
  player.level += 1;
  player.experience = 0;
  playerDB.set("player_uuid_1", player);
}

// Atomic update
const player2 = playerDB.get("player_uuid_2");
if (player2) {
  player2.stats.kills += 1;
  player2.lastUpdated = Date.now();
  playerDB.set("player_uuid_2", player2);
}

Delete Data

// Remove player data
playerDB.delete("player_uuid_1");

// Check if exists
if (playerDB.has("player_uuid_1")) {
  console.log("Player exists");
} else {
  console.log("Player deleted");
}

// Clear all data
playerDB.clear();

Integration with Players

import { world } from "@minecraft/server";

// Save player data on join
world.afterEvents.playerJoin.subscribe((event) => {
  const player = event.player;
  const playerId = player.nameTag; // Use unique ID
  
  // Check if new player
  if (!playerDB.has(playerId)) {
    playerDB.set(playerId, {
      name: player.nameTag,
      level: 1,
      experience: 0,
      joinDate: Date.now(),
      firstLogin: true
    });
    player.sendMessage("§aWelcome! You are a new player!");
  }
});

// Save player data on leave
world.afterEvents.playerLeave.subscribe((event) => {
  const player = event.player;
  const playerData = playerDB.get(player.nameTag);
  
  if (playerData) {
    playerData.lastLogout = Date.now();
    playerDB.set(player.nameTag, playerData);
  }
});

Backup & Export

// Export all data to JSON
function exportDatabase(dbName) {
  const db = new SuperDB({ name: dbName });
  const exported = {};
  
  db.forEach((key, value) => {
    exported[key] = value;
  });
  
  return JSON.stringify(exported);
}

// Get database size
function getDatabaseSize(db) {
  let count = 0;
  db.forEach(() => count++);
  return count;
}

console.log(`Database has ${getDatabaseSize(playerDB)} players`);

Best Practices

• Use unique identifiers - Use player UUID or unique name as key
• Structure data - Organize related data in objects
• Save frequently - Enable immediateWrite for critical data
• Validate data - Check data integrity on load
• Archive old data - Periodically clean up inactive players

Common Patterns

// Increment counter
const player = playerDB.get(playerId);
player.killCount = (player.killCount || 0) + 1;
playerDB.set(playerId, player);

// Array operations
const player2 = playerDB.get(playerId2);
player2.items = player2.items || [];
player2.items.push("diamond_sword");
playerDB.set(playerId2, player2);

// Search by property
function findPlayerByName(name) {
  let found = null;
  playerDB.forEach((key, player) => {
    if (player.name === name) found = player;
  });
  return found;
}