@dimzxzzx07/mc-headless

Platform Support

MC-Headless runs perfectly on all platforms above:

• Pterodactyl - Popular game hosting panel
• Ubuntu/Debian - Most popular Linux servers
• Linux - All distributions (CentOS, Fedora, Arch, etc.)
• Windows - Windows Server with PowerShell
• Termux - Turn your Android into a Minecraft server
• macOS - Darwin / Mac OS X

Table of Contents

• What is MC-Headless?
• What's New in 2.2.5
• Features
• Why MC-Headless?
• Installation
• Quick Start
• Server Startup Flow Diagram
• Pterodactyl Setup (No Egg Required)
• How to Connect from Minecraft
• Configuration Guide
• API Reference
• Usage Examples
• Server Types
• Platform Options
• Memory Management
• Network Settings
• World Configuration
• Plugins & Boosters
• RAM Disk & Symlink System
• Folder Structure
• Backup System
• Event System
• Commands
• Player Management
• Cross-Play (Geyser)
• ViaVersion Support
• SkinRestorer Support
• Portable Java
• Performance Tuning
• Termux Setup
• Troubleshooting
• Contributing
• License

What is MC-Headless?

MC-Headless is a powerful Node.js library that simplifies running Minecraft servers (Java, Bedrock, or Cross-play) with a clean, promise-based API. No more dealing with complex Java commands, server.properties files, or manual downloads - just simple JavaScript methods.

Built specifically for developers, sysadmins, and Minecraft enthusiasts who want to automate server management, run headless servers on VPS/Pterodactyl/Termux, or integrate Minecraft servers into their applications.

Keywords for Search Engine Optimization

• Minecraft server hosting
• Minecraft server manager
• Minecraft headless server
• PaperMC server setup
• Minecraft VPS hosting
• Pterodactyl Minecraft egg
• Minecraft server automation
• Minecraft cross-play server
• Java portable Minecraft
• Minecraft Termux server
• Minecraft Ubuntu server
• Minecraft Docker container
• Minecraft server control panel
• Minecraft server API
• Minecraft hosting solution

What's New in 2.2.5

Version 2.2.5 - March 2026

• Plugin Manager System - Auto-download and install popular plugins:
  • ProtocolLib
  • TCPShield
  • Spigot-Optimizers
  • Spark (profiler)
  • ViewDistanceTweaks
  • FarmControl
  • EntityDetection
• RAM Disk Technology - Run worlds, plugins, and addons in RAM for lightning-fast performance
• Symlink Master Storage - Secure master folder with symbolic links for data protection
• Auto RAM Backup - Automatically backup RAM data to disk every 5 minutes
• RAM Restore on Crash - Automatically restore data from master storage after crash
• Network Optimization Suite:
  • TCP_NODELAY enabled by default
  • Adjustable compression threshold (64-512)
  • Velocity proxy support
  • BungeeCord mode
• Java Arguments Optimization:
  • -XX:+UseG1GC -XX:MaxGCPauseMillis=50
  • -XX:+UseStringDeduplication
  • -Djava.net.preferIPv4Stack=true
  • -Djava.net.tcpFastOpen=true
  • -Djava.net.tcp.nodelay=true
  • -Dio.netty.recycler.maxCapacity.default=0
  • -Dio.netty.leakDetectionLevel=disabled
• Pterodactyl Port Sharing - Geyser can run on same port as Java when only one port available
• Auto UDP Detection - Warns if Bedrock port needs UDP configuration
• Stream Finished Guarantee - Ensures downloads complete properly with stream.finished
• 1-Second Download Delay - Prevents plugin corruption during simultaneous downloads
• Auto-cleanup Paper Remapped - Automatically removes corrupt .paper-remapped folders
• Memory Safety - Uses 90% of cgroup limit to prevent OOM killer
• Smart Restart - Only restarts when no players online

Features

| Category | Features | |----------|----------| | Server Types | Paper, Purpur, Vanilla, Spigot, Forge, Fabric | | Platforms | Java Edition, Bedrock Edition, Cross-play (Geyser) | | Plugins | ProtocolLib, TCPShield, Spark, ViewDistanceTweaks, FarmControl, EntityDetection | | RAM Disk | World/plugins/addons in RAM, auto backup to disk, restore after crash | | Symlink Master | Secure master storage with symbolic links | | Architecture Support | x64, ARM64, ARM (Raspberry Pi, Oracle Cloud) | | Pterodactyl Integration | Auto-detect, port sharing, environment variables, 90% memory safety | | Auto Setup | Automatic Java detection, EULA acceptance, server.properties generation | | Portable Java | Download JRE to /home/container/.java (Pterodactyl) or /tmp/.mc-headless | | Smart Storage | Detects Pterodactyl, warns on low RAM for /tmp usage | | Streaming Download | Download and extract simultaneously, no temporary files | | Cgroups Stats | CPU/Memory stats like Pterodactyl (30s interval) | | Downloader | Pure Node.js with rotating user-agents, retry logic, stalled detection | | Memory Management | Custom memory allocation, Aikar's flags optimization | | Backup System | Automatic scheduled backups, manual backup triggers | | Monitoring | Real-time CPU/memory usage, player tracking, server events | | Cross-play | Built-in Geyser & Floodgate support for Bedrock clients | | ViaVersion | Built-in ViaVersion, ViaBackwards, ViaRewind support | | SkinRestorer | Auto-download and install SkinRestorer plugin | | Termux Friendly | Optimized for Android/Termux environments | | Headless Ready | No GUI required, perfect for servers and automation | | Silent Mode | Direct log piping for minimal CPU usage |

Why MC-Headless?

Before (Manual Setup)

# Download server jar
wget https://api.papermc.io/v2/projects/paper/versions/1.21.11/builds/196/downloads/paper-1.21.11-196.jar

# Check if Java installed
which java || echo "Java not found"

# Install Java manually if needed
sudo apt install openjdk-21-jre-headless

# Accept EULA
echo "eula=true" > eula.txt

# Create server.properties
echo "server-port=25565" > server.properties
echo "max-players=20" >> server.properties

# Run server with complex Java flags
java -Xms4G -Xmx12G -XX:+UseG1GC -jar paper-1.21.11-196.jar nogui

# Download plugins manually
wget https://github.com/ViaVersion/ViaVersion/releases/download/5.7.2/ViaVersion-5.7.2.jar -P plugins/
wget https://github.com/SkinsRestorer/SkinsRestorerX/releases/latest/download/SkinsRestorer.jar -P plugins/

# Monitor manually
tail -f logs/latest.log

After (MC-Headless v2.2.5)

const { MinecraftServer } = require('@dimzxzzx07/mc-headless');

const server = new MinecraftServer({
  version: '1.21.11',
  type: 'paper',
  usePortableJava: true,
  memory: { init: '4G', max: '12G' },
  enableViaVersion: true,
  enableSkinRestorer: true,
  enableProtocolLib: true,
  enableSpark: true,
  ramdisk: {
    enabled: true,
    world: true,
    plugins: true,
    backupInterval: 300000
  }
});

server.on('ready', () => console.log('Server ready!'));
server.on('player-join', (player) => console.log(`${player.name} joined`));

await server.start();

Installation

From NPM

# Install as dependency
npm install @dimzxzzx07/mc-headless

# Install globally
npm install -g @dimzxzzx07/mc-headless

Requirements

Requirement Minimum Recommended Node.js 18.0.0 20.0.0 or higher RAM 2 GB 4 GB or more Storage 2 GB 10 GB OS Linux, macOS, Windows, Termux Linux (production)

Note: Java is auto-downloaded as portable JRE (no system installation needed). On Pterodactyl, Java is stored in /home/container/.java to save RAM.

Quick Start

Basic Java Server with Portable Java

const { MinecraftServer } = require('@dimzxzzx07/mc-headless');
const os = require('os');

async function startServer() {
  const totalRam = Math.floor(os.totalmem() / 1024 / 1024 / 1024);
  const recommendedMax = Math.min(12, Math.max(2, Math.floor(totalRam * 0.7)));

  console.log(`System RAM: ${totalRam}GB, Recommended: ${recommendedMax}GB`);

  const server = new MinecraftServer({
    platform: 'java',
    version: '1.21.11',
    type: 'paper',
    usePortableJava: true,
    memory: {
      init: '4G',
      max: `${recommendedMax}G`,
      useAikarsFlags: true
    }
  });

  server.on('ready', (info) => {
    console.log(`Server ready on port ${info.port}`);
    console.log(`Memory: ${info.memory.used}/${info.memory.max} MB`);
    console.log(`CPU: ${info.cpu}%`);
  });

  await server.start();
}

startServer();

Complete Server with All Features

const { MinecraftServer } = require('@dimzxzzx07/mc-headless');
const axios = require('axios');
const os = require('os');

async function startServer() {
  let publicIp = "127.0.0.1";
  try {
    const res = await axios.get('https://api.ipify.org?format=json');
    publicIp = res.data.ip;
  } catch (err) {
    console.log("Using default IP");
  }

  const server = new MinecraftServer({
    platform: "all",
    version: "1.21.11",
    type: "paper",
    autoAcceptEula: true,
    
    usePortableJava: true,
    javaVersion: "auto",
    
    memory: {
      init: "4G",
      max: "12G",
      useAikarsFlags: true
    },
    
    network: {
      ip: "0.0.0.0",
      port: 25565,
      bedrockPort: 19132,
      motd: "Minecraft 1.21.11 Server",
      onlineMode: false
    },

    world: {
      difficulty: "normal",
      maxPlayers: 20,
      levelName: "world",
      viewDistance: 6,
      simulationDistance: 4
    },
    
    // New plugins in 2.2.5
    enableViaVersion: true,
    enableViaBackwards: true,
    enableViaRewind: true,
    enableSkinRestorer: true,
    enableProtocolLib: true,
    enableTCPShield: true,
    enableSpigotOptimizers: true,
    enableSpark: true,
    enableViewDistanceTweaks: true,
    enableFarmControl: true,
    enableEntityDetection: true,
    
    // RAM Disk (NEW)
    ramdisk: {
      enabled: true,
      world: true,
      plugins: true,
      addons: true,
      backupInterval: 300000,
      masterStorage: '/home/minecraft-master'
    },
    
    // Symlink Master (NEW)
    symlinkMaster: '/home/minecraft-master',
    
    // Network Optimization (NEW)
    networkOptimization: {
      tcpFastOpen: true,
      tcpNoDelay: true,
      preferIPv4: true,
      compressionThreshold: 64,
      bungeeMode: false,
      velocity: {
        enabled: false,
        secret: ''
      }
    },
    
    memoryMonitor: {
      enabled: true,
      threshold: 85,
      interval: 30000,
      action: 'warn'
    },
    
    silentMode: true,
    statsInterval: 30000
  });

  server.on("ready", (info) => {
    console.clear();
    console.log(`
==========================================
Minecraft Server - v2.2.5
 IP: ${publicIp}:${info.port}
 Version: ${info.version}
 Memory: ${info.memory.used}/${info.memory.max} MB
 CPU: ${info.cpu}%
 Players: ${info.players}/${info.maxPlayers}
 RAM Disk: Active
 Plugins: 7 boosters installed
==========================================
    `);
  });

  server.on("player-join", (player) => {
    console.log(`${player.name} joined`);
    server.sendCommand(`tellraw ${player.name} {"text":"Welcome!","color":"aqua"}`);
  });

  server.on("player-leave", (name) => {
    console.log(`${name} left`);
  });

  await server.start();
}

startServer();

Server Startup Flow Diagram

┌─────────────────────────────────────────────────────────────────┐
│                     SERVER STARTUP FLOW                         │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────┐
│  detectEnvironment │
│  • Pterodactyl?    │
│  • Set ports       │
└────────┬─────────┘
         ↓
┌─────────────────┐
│  setupSymlinkMaster │
│  • Create /home/    │
│    minecraft-master │
└────────┬─────────┘
         ↓
┌─────────────────┐
│   restoreFromMaster  │
│  • Check RAM disk    │
│  • Copy from master  │
│    if RAM empty      │
└────────┬─────────┘
         ↓
┌─────────────────┐
│    setupRamdisk     │
│  • Create symlinks  │
│  • Schedule backups │
└────────┬─────────┘
         ↓
┌─────────────────┐
│   ensureJava       │
│  • Check system    │
│  • Download JRE    │
│    if needed       │
└────────┬─────────┘
         ↓
┌─────────────────┐
│   download server  │
│  • Paper/Vanilla   │
│    etc.            │
└────────┬─────────┘
         ↓
┌─────────────────┐
│   setup geyser     │
│  • If platform all │
│  • Configure ports │
└────────┬─────────┘
         ↓
┌─────────────────┐
│  install plugins   │
│  • ProtocolLib     │
│  • TCPShield       │
│  • Spark           │
│  • ViewDistance    │
│  • FarmControl     │
│  • EntityDetection │
└────────┬─────────┘
         ↓
┌─────────────────┐
│   setup viaversion │
│  • ViaVersion      │
│  • ViaBackwards    │
│  • ViaRewind       │
└────────┬─────────┘
         ↓
┌─────────────────┐
│    launch server   │
│  • Build Java args │
│  • Set environment │
│  • Spawn process   │
└────────┬─────────┘
         ↓
┌─────────────────┐
│    monitor logs    │
│  • Wait for "Done" │
│  • Track players   │
└────────┬─────────┘
         ↓
┌─────────────────┐
│   server ready     │
│  • Emit 'ready'    │
│  • Start monitoring│
└─────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                    BACKGROUND PROCESSES                          │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│  RAM Disk Backup │    │  Log Cleanup    │    │ Memory Monitor  │
│  Every 5 min     │    │  Every 3 hours  │    │ Every 30 sec    │
│  RAM → Master    │    │  Delete old     │    │ Check usage     │
│                  │    │  logs           │    │ Warn if high    │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Pterodactyl Setup (No Egg Required)

Step 1: Create Server Files

Create the following files in your Pterodactyl server directory (/home/container):

index.js

const { MinecraftServer } = require('@dimzxzzx07/mc-headless');

async function startServer() {
  const server = new MinecraftServer({
    platform: "all",
    version: "1.21.11",
    type: "paper",
    autoAcceptEula: true,
    usePortableJava: false,
    
    memory: {
      init: process.env.SERVER_MEMORY_INIT || "2G",
      max: process.env.SERVER_MEMORY_MAX || "4G",
      useAikarsFlags: true
    },
    
    network: {
      ip: "0.0.0.0",
      port: parseInt(process.env.SERVER_PORT || "25565"),
      bedrockPort: process.env.BEDROCK_PORT ? parseInt(process.env.BEDROCK_PORT) : undefined,
      motd: process.env.SERVER_MOTD || "Minecraft Server",
      onlineMode: false
    },

    world: {
      difficulty: "normal",
      maxPlayers: 20,
      levelName: "world",
      viewDistance: 6,
      simulationDistance: 4
    },
    
    // Enable all plugins
    enableViaVersion: true,
    enableViaBackwards: true,
    enableViaRewind: true,
    enableSkinRestorer: true,
    enableProtocolLib: true,
    enableTCPShield: true,
    enableSpigotOptimizers: true,
    enableSpark: true,
    enableViewDistanceTweaks: true,
    enableFarmControl: true,
    enableEntityDetection: true,
    
    // RAM Disk for Pterodactyl
    ramdisk: {
      enabled: true,
      world: true,
      plugins: true,
      backupInterval: 300000,
      masterStorage: '/home/minecraft-master'
    },
    
    networkOptimization: {
      tcpFastOpen: true,
      tcpNoDelay: true,
      compressionThreshold: 64
    }
  });

  server.on("ready", (info) => {
    console.log(`
==========================================
Minecraft Server - Pterodactyl
IP: ${info.ip}:${info.port}
Version: ${info.version}
Memory: ${info.memory.used}/${info.memory.max} MB
CPU: ${info.cpu}%
Players: ${info.players}/${info.maxPlayers}
RAM Disk: Active
==========================================
    `);
  });

  await server.start();
}

startServer().catch(console.error);

package.json

{
  "name": "minecraft-server",
  "version": "1.0.0",
  "dependencies": {
    "@dimzxzzx07/mc-headless": "^2.2.5"
  }
}

start.sh

#!/bin/bash
echo "=========================================="
echo "MC-Headless Server - Pterodactyl v2.2.5"
echo "=========================================="
echo "Java Port: ${SERVER_PORT:-25565}"
if [ -n "$BEDROCK_PORT" ]; then
  echo "Bedrock Port: $BEDROCK_PORT (UDP)"
else
  echo "Bedrock Port: Sharing Java port (UDP must be enabled)"
fi
echo "Memory: ${SERVER_MEMORY_INIT:-2G} - ${SERVER_MEMORY_MAX:-4G}"
echo "Plugins: ProtocolLib, TCPShield, Spark, etc."
echo "RAM Disk: Active"
echo "=========================================="

# Clean up corrupt Paper cache
if [ -d "plugins" ]; then
  find plugins -type d -name ".paper-remapped*" -exec rm -rf {} + 2>/dev/null || true
fi

node index.js

Step 2: Upload Files via SFTP

# Connect to your server via SFTP and upload:
/home/container/
├── index.js
├── package.json
├── start.sh
└── node_modules/ (will be created by npm install)

Step 3: Install Dependencies

cd /home/container
npm install
chmod +x start.sh

Step 4: Configure Pterodactyl Panel

Startup Command:

bash start.sh

Docker Image:

node:20-slim

Environment Variables:

Variable Description Example SERVER_PORT Java edition port (TCP) 25565 BEDROCK_PORT Bedrock edition port (UDP) 19132 SERVER_MEMORY_INIT Initial memory 2G SERVER_MEMORY_MAX Max memory 4G SERVER_MOTD Message of the day My Server

Pterodactyl Memory Safety

The module automatically:

· Detects cgroup memory limits · Uses only 90% of available memory to prevent OOM killer · Adjusts -Xmx accordingly · Logs the adjusted memory value

Port Configuration Options

Option A: Separate Ports (Recommended)

· Add port 25565 (TCP) for Java · Add port 19132 (UDP) for Bedrock · Set both environment variables

Option B: Single Port (Port Sharing)

· Set only SERVER_PORT · Ensure port is configured for BOTH TCP and UDP in panel · Geyser will automatically share the same port · Warning appears if UDP not enabled

How to Connect from Minecraft

Java Edition Connection

1. Open Minecraft Java Edition
2. Click "Multiplayer" → "Add Server"
3. Server Address: your-server-ip:25565 (or your configured port)
4. Click "Done" and join

Bedrock Edition Connection

If you have separate Bedrock port (19132 UDP):

1. Open Minecraft Bedrock Edition
2. Click "Play" → "Servers" → "Add Server"
3. Server Address: your-server-ip
4. Port: 19132
5. Click "Save" and join

If using port sharing (same port as Java):

1. Open Minecraft Bedrock Edition
2. Click "Play" → "Servers" → "Add Server"
3. Server Address: your-server-ip
4. Port: 25565 (or your configured port)
5. IMPORTANT: Port must have UDP enabled in Pterodactyl panel
6. Click "Save" and join

Cross-Play (Java + Bedrock together)

With Geyser and Floodgate enabled, both Java and Bedrock players can join the same server simultaneously. Bedrock players will see Java players and vice versa.

Configuration Guide

Complete Configuration Example with New Features

const { MinecraftServer } = require('@dimzxzzx07/mc-headless');

const server = new MinecraftServer({
  platform: 'all',
  version: '1.21.11',
  type: 'paper',
  autoAcceptEula: true,

  usePortableJava: true,
  javaVersion: 'auto',

  memory: {
    init: '4G',
    max: '12G',
    useAikarsFlags: true
  },

  network: {
    port: 25565,
    bedrockPort: 19132,
    ip: '0.0.0.0',
    onlineMode: false,
    motd: 'Minecraft Server'
  },

  world: {
    difficulty: 'normal',
    hardcore: false,
    gamemode: 'survival',
    seed: 'my-secret-seed',
    maxPlayers: 20,
    viewDistance: 6,
    simulationDistance: 4,
    levelName: 'world'
  },

  folders: {
    addons: './addons',
    mods: './mods',
    plugins: './plugins',
    world: './world'
  },

  // Plugins (NEW in 2.2.5)
  enableViaVersion: true,
  enableViaBackwards: true,
  enableViaRewind: true,
  enableSkinRestorer: true,
  enableProtocolLib: true,
  enableTCPShield: true,
  enableSpigotOptimizers: true,
  enableSpark: true,
  enableViewDistanceTweaks: true,
  enableFarmControl: true,
  enableEntityDetection: true,

  // RAM Disk (NEW)
  ramdisk: {
    enabled: true,
    world: true,
    plugins: true,
    addons: true,
    backupInterval: 300000,
    masterStorage: '/home/minecraft-master'
  },

  // Symlink Master (NEW)
  symlinkMaster: '/home/minecraft-master',

  // Network Optimization (NEW)
  networkOptimization: {
    tcpFastOpen: true,
    tcpNoDelay: true,
    preferIPv4: true,
    compressionThreshold: 64,
    bungeeMode: false,
    velocity: {
      enabled: false,
      secret: ''
    }
  },

  autoRestart: true,
  backup: {
    enabled: true,
    interval: '24h',
    path: './backups'
  },

  memoryMonitor: {
    enabled: true,
    threshold: 85,
    interval: 30000,
    action: 'warn'
  },

  silentMode: true,
  statsInterval: 30000
});

await server.start();

New Configuration Options in 2.2.5

Plugin Options

Option Type Default Description enableProtocolLib boolean false ProtocolLib for packet manipulation enableTCPShield boolean false TCPShield DDoS protection enableSpigotOptimizers boolean false Performance optimization plugin enableSpark boolean false Spark profiler for performance monitoring enableViewDistanceTweaks boolean false Dynamic view distance adjustment enableFarmControl boolean false Farm entity limit control enableEntityDetection boolean false Entity tracking optimization

RAM Disk Options

Option Type Default Description ramdisk.enabled boolean false Enable RAM disk for worlds/plugins ramdisk.world boolean false Store world in RAM ramdisk.plugins boolean false Store plugins in RAM ramdisk.addons boolean false Store addons in RAM ramdisk.backupInterval number 300000 Backup interval in ms (5 minutes default) ramdisk.masterStorage string '/home/minecraft-master' Master storage path for backups

Symlink Master Options

Option Type Default Description symlinkMaster string undefined Master directory for symbolic links

Network Optimization Options

Option Type Default Description networkOptimization.tcpFastOpen boolean true Enable TCP Fast Open networkOptimization.tcpNoDelay boolean true Enable TCP_NODELAY networkOptimization.preferIPv4 boolean true Prefer IPv4 stack networkOptimization.compressionThreshold number 64 Network compression threshold networkOptimization.bungeeMode boolean false Enable BungeeCord mode networkOptimization.velocity.enabled boolean false Enable Velocity proxy support networkOptimization.velocity.secret string '' Velocity forwarding secret

API Reference

MinecraftServer Class

class MinecraftServer extends EventEmitter {
  constructor(config: Partial<MinecraftConfig>);
  
  async start(): Promise<ServerInfo>;
  async stop(): Promise<void>;
  sendCommand(command: string): void;
  async getInfo(): Promise<ServerInfo>;
  getPlayers(): Player[];
  async backup(type?: 'full' | 'world' | 'plugins'): Promise<string>;
  
  on(event: 'ready', listener: (info: ServerInfo) => void): this;
  on(event: 'stop', listener: (data: { code: number }) => void): this;
  on(event: 'player-join', listener: (player: Player) => void): this;
  on(event: 'player-leave', listener: (name: string) => void): this;
  on(event: 'resource', listener: (info: ServerInfo) => void): this;
}

ServerInfo Interface

interface ServerInfo {
  pid: number;
  ip: string;
  port: number;
  bedrockPort?: number;
  version: string;
  type: string;
  platform: string;
  players: number;
  maxPlayers: number;
  uptime: number;
  memory: { used: number; max: number };
  cpu: number;
  status: 'starting' | 'running' | 'stopping' | 'stopped' | 'crashed';
}

Plugins & Boosters

Available Plugins in v2.2.5

Plugin Function Enable Option ProtocolLib Packet manipulation library enableProtocolLib: true TCPShield DDoS protection and proxy enableTCPShield: true Spigot-Optimizers Performance optimizations enableSpigotOptimizers: true Spark Performance profiling enableSpark: true ViewDistanceTweaks Dynamic view distance enableViewDistanceTweaks: true FarmControl Farm entity limits enableFarmControl: true EntityDetection Entity tracking optimization enableEntityDetection: true ViaVersion Cross-version support enableViaVersion: true ViaBackwards Backwards compatibility enableViaBackwards: true ViaRewind 1.7-1.8 support enableViaRewind: true SkinRestorer Player skin fixing enableSkinRestorer: true

Plugin Auto-Download

All plugins are automatically downloaded from official sources with:

· Stream finished guarantee · 1-second delay between downloads · Size verification (>100KB) · ZIP header validation · Auto-retry on failure

RAM Disk & Symlink System

How RAM Disk Works

When enabled, worlds/plugins/addons are stored in RAM (/dev/shm/minecraft) for lightning-fast access:

ramdisk: {
  enabled: true,
  world: true,      // World in RAM
  plugins: true,    // Plugins in RAM
  addons: true,     // Addons in RAM
  backupInterval: 300000, // Backup every 5 minutes
  masterStorage: '/home/minecraft-master' // Master storage
}

Crash Recovery Flow

┌─────────────────────────────────────────────────────────┐
│                  CRASH RECOVERY FLOW                     │
└─────────────────────────────────────────────────────────┘

1. Server crashes or VPS reboots
         ↓
2. RAM disk data lost (/dev/shm cleared)
         ↓
3. Server restarts
         ↓
4. restoreFromMaster() runs
         ↓
5. Checks if RAM disk is empty
         ↓
6. Copies from master storage to RAM
         ↓
7. World/plugins restored exactly as before
         ↓
8. Server starts with latest data

Benefits

· 10-50x faster world loading · Zero lag during chunk generation · Instant plugin loading · Automatic backup to disk every 5 minutes · Crash recovery - Data restored from master storage · Data safety - RAM data regularly saved to disk

Symlink Master System

symlinkMaster: '/home/minecraft-master'

Creates a secure master folder structure:

/home/minecraft-master/
├── worlds/
├── plugins/
├── addons/
└── mods/

Server folders become symbolic links pointing to master folders, providing:

· Data safety - Master data survives server resets · Easy backups - Backup only master folder · Multiple servers - Share plugins across instances · Quick restore - Just recreate symlinks

Performance Tuning

Optimized Configuration with New Features

const server = new MinecraftServer({
  version: '1.21.11',
  type: 'paper',
  usePortableJava: true,
  memory: {
    init: '4G',
    max: '12G',
    useAikarsFlags: true
  },
  world: {
    viewDistance: 6,
    simulationDistance: 4,
    maxPlayers: 20
  },
  
  // Enable performance plugins
  enableSpigotOptimizers: true,
  enableSpark: true,
  enableViewDistanceTweaks: true,
  enableFarmControl: true,
  enableEntityDetection: true,
  
  // RAM Disk for speed
  ramdisk: {
    enabled: true,
    world: true,
    plugins: true,
    backupInterval: 300000
  },
  
  // Network optimizations
  networkOptimization: {
    tcpFastOpen: true,
    tcpNoDelay: true,
    compressionThreshold: 64
  },
  
  silentMode: true,
  statsInterval: 30000
});

Java Arguments Added in 2.2.5

# Base memory and GC
-Xms4G -Xmx12G
-XX:+UseG1GC
-XX:MaxGCPauseMillis=50
-XX:+UseStringDeduplication
-XX:G1MixedGCLiveThresholdPercent=90

# Network optimizations
-Djava.net.preferIPv4Stack=true
-Djava.net.tcpFastOpen=true
-Djava.net.tcp.nodelay=true
-Dnetwork-compression-threshold=64

# Netty optimizations
-Dio.netty.recycler.maxCapacity.default=0
-Dio.netty.leakDetectionLevel=disabled

# Terminal settings (Pterodactyl)
-Dterminal.jline=false
-Dterminal.ansi=true

Pterodactyl Memory Safety

// Automatically applied in Pterodactyl
if (isPterodactyl && cgroupMemory > 0) {
  const safeMem = Math.floor(cgroupMemory * 0.9);
  memMax = Math.min(memMax, safeMem);
  // Uses 90% of cgroup limit to prevent OOM killer
}

Troubleshooting

Common Issues in 2.2.5

Issue Cause Solution plugins/.paper-remapped error Corrupt plugin cache Auto-fixed in v2.2.5 Bedrock cannot connect UDP not enabled Ensure port has UDP enabled RAM disk not working /dev/shm not available Check system RAM disk support Plugins not downloading Network issues Auto-retry in v2.2.5 High memory usage RAM disk + worlds Reduce viewDistance or disable RAM disk Java update available Older Java Auto-downloads latest Server OOM killed Memory too high Module auto-reduces to 90% of limit

RAM Disk Issues

# Check if RAM disk is mounted
df -h /dev/shm

# Check RAM disk usage
du -sh /dev/shm/minecraft

# Manual backup
cp -r /dev/shm/minecraft/* /home/minecraft-master/

# Restore from master
cp -r /home/minecraft-master/* /dev/shm/minecraft/

Plugin Verification

# List installed plugins
ls -la plugins/

# Check plugin sizes (should be >100KB)
du -sh plugins/*.jar

# Check for corrupt plugins
find plugins -name "*.jar" -size -100k -delete

Pterodactyl Memory Logs

Look for this line in startup logs:

Adjusted memory to 3686MB (90% of cgroup limit)

This confirms the module is protecting your server from OOM killer.

Contributing

Development Setup

git clone https://github.com/Dimzxzzx07/Minecraft-Server-Integration-Node.js.git
cd mc-headless
npm install
npm run build
npm test

Project Structure

mc-headless/
├── src/
│   ├── core/
│   │   ├── MinecraftServer.ts
│   │   ├── ConfigHandler.ts
│   │   ├── JavaChecker.ts
│   │   └── ServerManager.ts
│   ├── engines/
│   │   ├── PaperEngine.ts
│   │   ├── VanillaEngine.ts
│   │   ├── ForgeEngine.ts
│   │   └── FabricEngine.ts
│   ├── platforms/
│   │   ├── GeyserBridge.ts
│   │   ├── ViaVersion.ts
│   │   ├── SkinRestorer.ts
│   │   └── PluginManager.ts
│   └── utils/
│       ├── Logger.ts
│       ├── FileUtils.ts
│       └── SystemDetector.ts
├── tests/
├── examples/
└── README.md

License

MIT License

Copyright (c) 2026 Dimzxzzx07

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.