minecraft-core

Minecraft Server Manager

A powerful, environment-agnostic TypeScript library for managing, searching, and downloading various Minecraft server cores. Built with modern web standards and designed to work seamlessly in Node.js, Bun, and other JavaScript runtimes.

🚀 Features

• Multi-Provider Support: Unified API to interact with major Minecraft server providers.
• Environment Agnostic: Uses a FileSystemAdapter pattern, making it compatible with Node.js, Bun, and potentially Deno or browsers (with appropriate adapters).
• Type-Safe: Built with TypeScript and Zod for robust runtime validation.
• Hash Verification: Automatically verifies downloaded artifacts (SHA256, MD5, SHA1) when available.
• Flexible: Supports downloading binaries, installers, or fetching download paths depending on the provider.

📦 Installation

npm install minecraft-core
# or
bun add minecraft-core
# or
pnpm add minecraft-core

🛠️ Supported Providers

Provider	Key	Status	Description
Paper	paper	✅ Ready	High performance Spigot fork.
Purpur	purpur	✅ Ready	Drop-in replacement for Paper with more features.
Vanilla	vanilla	✅ Ready	Official Minecraft server software from Mojang.
Fabric	fabric	✅ Ready	Lightweight, modular modding toolchain (downloads Launcher JAR).
Forge	forge	✅ Ready	Massive modding API (downloads Installer JAR).
Mohist	mohist	✅ Ready	Hybrid server (Forge + Spigot/Paper).
Velocity	velocity	✅ Ready	The modern, high-performance Minecraft proxy.
Folia	folia	✅ Ready	Regionized multithreading dedicated server.
Waterfall	waterfall	✅ Ready	The BungeeCord fork by PaperMC.
Arclight	arclight	✅ Ready	Hybrid server (Forge + Spigot/Paper).
Magma	magma	🚧 Planned	Hybrid server (Forge + Spigot/Paper).

📖 Usage

1. Initialization

You must provide a FileSystemAdapter. A NodeAdapter is provided out-of-the-box which works for Node.js and Bun.

import { MinecraftServerManager, NodeAdapter } from 'minecraft-core';

// Initialize with the Node.js/Bun adapter
const manager = new MinecraftServerManager(new NodeAdapter());

2. Fetching Versions

Get a list of available Minecraft versions for a specific core.

const versions = await manager.getVersions('paper');
console.log(versions); // ['1.8.8', ..., '1.20.4', '1.21']

3. Downloading a Server

Download the latest build for a specific version.

try {
    const result = await manager.downloadServer({
        core: 'paper',
        version: '1.21',
        outputDir: './server',
        filename: 'server.jar' // Optional
    });

    console.log(`Downloaded to: ${result.path}`);
    console.log(`Hash: ${result.hash}`);
} catch (error) {
    console.error('Download failed:', error);
}

4. Advanced: Get Build Details

If you need specific build information before downloading.

const build = await manager.getLatestBuild('purpur', '1.20.4');

console.log(`Build ID: ${build.buildId}`);
console.log(`Timestamp: ${build.timestamp}`);
console.log(`Download URL: ${build.downloads.application.url}`);

🧩 Adapters

This library uses the Adapter Pattern to handle file system operations. This allows you to use the library in environments where fs might not be available or behaves differently.

Custom Adapter

Implement the FileSystemAdapter interface to create your own adapter:

import type { FileSystemAdapter } from 'minecraft-core';

class MyCustomAdapter implements FileSystemAdapter {
    join(...paths: string[]): string { /* ... */ }
    mkdir(path: string): Promise<void> { /* ... */ }
    writeStream(path: string, stream: any): Promise<void> { /* ... */ }
    // ... implement other methods
}

const manager = new MinecraftServerManager(new MyCustomAdapter());

🧪 Testing

The project includes a comprehensive test suite using bun test.

# Run all tests
bun test

# Run type checking
bun run typecheck

📄 License

MIT