# @dimzxzzx07/mc-headless
---
## Platform Support
Pterodactyl |
Ubuntu |
Linux |
Windows |
Termux |
macOS |
**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-is-mc-headless)
- [What's New in 2.2.5](#whats-new-in-225)
- [Features](#features)
- [Why MC-Headless?](#why-mc-headless)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Server Startup Flow Diagram](#server-startup-flow-diagram)
- [Pterodactyl Setup (No Egg Required)](#pterodactyl-setup-no-egg-required)
- [How to Connect from Minecraft](#how-to-connect-from-minecraft)
- [Configuration Guide](#configuration-guide)
- [API Reference](#api-reference)
- [Usage Examples](#usage-examples)
- [Server Types](#server-types)
- [Platform Options](#platform-options)
- [Memory Management](#memory-management)
- [Network Settings](#network-settings)
- [World Configuration](#world-configuration)
- [Plugins & Boosters](#plugins--boosters)
- [RAM Disk & Symlink System](#ram-disk--symlink-system)
- [Folder Structure](#folder-structure)
- [Backup System](#backup-system)
- [Event System](#event-system)
- [Commands](#commands)
- [Player Management](#player-management)
- [Cross-Play (Geyser)](#cross-play-geyser)
- [ViaVersion Support](#viaversion-support)
- [SkinRestorer Support](#skinrestorer-support)
- [Portable Java](#portable-java)
- [Performance Tuning](#performance-tuning)
- [Termux Setup](#termux-setup)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
- [License](#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)
```bash
# 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)
```javascript
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
```bash
# 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
```javascript
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
```javascript
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
```javascript
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
```json
{
"name": "minecraft-server",
"version": "1.0.0",
"dependencies": {
"@dimzxzzx07/mc-headless": "^2.2.5"
}
}
```
start.sh
```bash
#!/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
```bash
# 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
```bash
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
```javascript
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
```javascript
class MinecraftServer extends EventEmitter {
constructor(config: Partial);
async start(): Promise;
async stop(): Promise;
sendCommand(command: string): void;
async getInfo(): Promise;
getPlayers(): Player[];
async backup(type?: 'full' | 'world' | 'plugins'): Promise;
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
```javascript
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:
```javascript
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
```javascript
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
```javascript
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
```bash
# 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
```javascript
// 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
```bash
# 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
```bash
# 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
```bash
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.
---
Powered By Dimzxzzx07
Copyright © 2026 Dimzxzzx07. All rights reserved.
