Database Management for Minecraft Bedrock Development

@mxbe/database is a lightweight and flexible database solution for Minecraft Bedrock Edition (MCBE) add-ons. It provides a simple API for creating, reading, updating, and deleting data within your MCBE scripts using dynamic properties.

Features

• Dynamic Property Storage: Utilizes Minecraft's dynamic property system for persistent data storage
• Type-Safe Operations: Full TypeScript support with generic types for type safety
• Flexible Storage Types: Works with World, Entity, Player, and ItemStack storage
• Simple CRUD Operations: Easy-to-use create, read, update, and delete methods
• Advanced Querying: Find operations with custom predicates and key-value matching
• Automatic ID Generation: Built-in unique ID generation for records
• Memory Efficient: JSON serialization for optimal storage performance
• Collection Management: Named collections with size constraints (1-16 characters)

Installation

To install @mxbe/database in your Minecraft add-on project, choose one of the following methods:

Option 1: Using MXBE Project Manager (Recommended)

1. Open a terminal and navigate to your project's root directory
2. Initialize your project with the MXBE project manager:

npx @mxbe/project init

3. Select @mxbe/database from the dependencies list when prompted

Option 2: NPM Installation

1. Navigate to your project's root directory
2. Install the package via npm:

npm install @mxbe/database

3. Bundle your scripts using ESBuild or Webpack

Option 3: Manual Installation

1. Clone the repository:

git clone https://github.com/sausage404/mxbe-database.git

2. Copy the index.ts and index.d.ts files (or index.js for JavaScript) from the repository into your project's scripts folder

Basic Usage

Here's how to get started with the database in your Minecraft Bedrock add-on:

TypeScript Example

import * as mc from "@minecraft/server";
import Database from "@mxbe/database";

// Define your data structure
interface Player {
    name: string;
    level: number;
    experience: number;
    lastLogin: number;
}

// Initialize the database with World storage
const playerDB = new Database<Player>("players", mc.world);

// Create a new player record
const playerId = playerDB.create({
    name: "Steve",
    level: 10,
    experience: 2500,
    lastLogin: Date.now()
});

console.log(`Created player with ID: ${playerId}`);

// Find a specific player
const steve = playerDB.find(player => player.name === "Steve");
if (steve) {
    console.log(`Found player: ${steve.name}, Level: ${steve.level}`);
}

// Find all players above level 5
const highLevelPlayers = playerDB.findMany().filter(player => player.level > 5);

// Update a player's level
playerDB.update(
    player => player.name === "Steve",
    { level: 15, experience: 3000 }
);

// Count total players
const totalPlayers = playerDB.count();
console.log(`Total players: ${totalPlayers}`);

JavaScript Example

import * as mc from "@minecraft/server";
import Database from "@mxbe/database";

// Initialize database for storing item inventories
const inventoryDB = new Database("inventory", mc.world);

// Create an inventory record
const itemId = inventoryDB.create({
    itemType: "diamond",
    quantity: 64,
    durability: 100
});

// Find items by type
const diamonds = inventoryDB.findLike("itemType", "diamond");
console.log(`Found ${diamonds.length} diamond stacks`);

API Reference

Constructor

new Database<T>(collectionName: string, storageType: StorageType)

• collectionName: Name of your collection (1-16 characters)
• storageType: Storage target (World, Entity, Player, or ItemStack)

Methods

create(data: T): string

Creates a new record and returns the generated ID.

find(predicate: (data: DefaultPattern<T>) => boolean)

Finds the first record matching the predicate function.

findMany(): DefaultPattern<T>[]

Returns all records in the collection.

findLike<K>(key: K, value: DefaultPattern<T>[K]): DefaultPattern<T>[]

Finds all records where the specified key matches the given value.

update(predicate: function, data: Partial<DefaultPattern<T>>): void

Updates the first record matching the predicate with the provided data.

delete(predicate: (data: DefaultPattern<T>) => boolean): void

Deletes the first record matching the predicate function.

count(predicate?: function): number

Returns the total count of records, optionally filtered by a predicate.

clear(): void

Removes all records from the collection.

Storage Types

The database supports different storage types for various use cases:

• mc.world: Global world-persistent data
• mc.Entity: Entity-specific data that persists with the entity
• mc.Player: Player-specific data that persists across sessions
• mc.ItemStack: Item-specific data attached to items

Best Practices

1. Choose Appropriate Storage: Use World storage for global data, Player storage for user-specific data
2. Keep Collection Names Short: Collection names are limited to 16 characters
3. Handle Errors: Wrap database operations in try-catch blocks for production code
4. Optimize Queries: Use findLike for simple key-value searches instead of complex predicates when possible
5. Regular Cleanup: Use clear() method periodically if your data doesn't need to persist indefinitely

Example Use Cases

• Player Statistics: Track player achievements, scores, and progress
• World Configuration: Store world settings and configuration data
• Entity Data: Attach custom data to NPCs or custom entities
• Item Metadata: Store custom properties for special items

Error Handling

The database includes built-in error handling for common issues:

• Invalid collection names
• JSON parsing errors during initialization
• Storage operation failures

Always wrap your database operations in try-catch blocks for robust error handling.

Performance Considerations

• Data is stored in memory and synchronized to dynamic properties
• JSON serialization occurs on each write operation
• Consider the size limits of dynamic properties when storing large datasets
• Use efficient predicate functions to minimize search overhead

Contributing

Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests on the GitHub repository.

License

@mxbe/database is released under the GNU General Public License v3.

Support

If you encounter any problems or have questions:

• Check the GitHub Issues page
• Create a new issue for bugs or feature requests
• Join the community discussions for help and tips