@devadevkiyuru/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.1
• Features
• Why MC-Headless?
• Installation
• Quick Start
• Configuration Guide
• API Reference
• Usage Examples
• Server Types
• Platform Options
• Memory Management
• Network Settings
• World Configuration
• Folder Structure
• Backup System
• Event System
• Commands
• Player Management
• Cross-Play (Geyser)
• ViaVersion Support
• SkinRestorer Support
• Portable Java
• Performance Tuning
• Pterodactyl Setup
• 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.1

Version 2.2.1 - March 2026

• Pterodactyl Optimized - Full compatibility with Pterodactyl panel
• No curl/wget required - Pure Node.js downloader works everywhere
• Better error handling - Clear messages for disk space issues
• Smaller Java downloads - Uses JRE instead of full JDK (saves 150MB)
• Automatic disk space check - Warns before downloading
• Improved platform detection - Works on all Linux distros
• Fallback URLs - Multiple mirrors for Java downloads
• Corrupted file detection - Auto-retry on bad downloads
• Memory limit awareness - Respects cgroup limits in containers

Features

| Category | Features | |----------|----------| | Server Types | Paper, Purpur, Vanilla, Spigot, Forge, Fabric | | Platforms | Java Edition, Bedrock Edition, Cross-play (Geyser) | | Auto Setup | Automatic Java detection, EULA acceptance, server.properties generation | | Portable Java | Download JRE to current directory, no system installation required | | Cgroups Stats | CPU/Memory stats like Pterodactyl (30s interval) | | Downloader | Pure Node.js downloader (no curl/wget needed) | | 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 | | Pterodactyl Ready | Optimized for panel hosting | | 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.1)

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

const server = new MinecraftServer({
  version: '1.21.11',
  type: 'paper',
  usePortableJava: true,
  memory: { init: '4G', max: '12G' },
  enableViaVersion: true,
  enableSkinRestorer: true
});

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 @devadevkiyuru/mc-headless

# Install globally
npm install -g @devadevkiyuru/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)

Quick Start

Basic Java Server with Portable Java

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

async function startServer() {
  // Auto-detect system RAM
  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('@devadevkiyuru/mc-headless');
const axios = require('axios');
const os = require('os');

async function startServer() {
  // Get public IP
  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");
  }

  // Auto-detect RAM
  const totalRam = Math.floor(os.totalmem() / 1024 / 1024 / 1024);
  const recommendedMax = Math.min(12, Math.max(2, Math.floor(totalRam * 0.7)));

  const server = new MinecraftServer({
    platform: "all",
    version: "1.21.11",
    type: "paper",
    autoAcceptEula: true,
    
    // Java options
    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
    },
    
    // Plugins
    enableViaVersion: true,
    enableViaBackwards: true,
    enableViaRewind: true,
    enableSkinRestorer: true,
    
    // Monitoring
    memoryMonitor: {
      enabled: true,
      threshold: 85,
      interval: 30000,
      action: 'warn'
    },
    
    // Performance
    silentMode: true,
    statsInterval: 30000
  });

  server.on("ready", (info) => {
    console.clear();
    console.log(`\n==========================================`);
    console.log(`Minecraft Server - v2.2.1`);
    console.log(` IP: ${publicIp}:${info.port}`);
    console.log(` Version: ${info.version}`);
    console.log(` Memory: ${info.memory.used}/${info.memory.max} MB`);
    console.log(` CPU: ${info.cpu || 0}%`);
    console.log(` Players: ${info.players}/${info.maxPlayers}`);
    console.log(`==========================================\n`);
  });

  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`);
  });

  server.on("resource", (info) => {
    if (info.memory.used > info.memory.max * 0.8) {
      console.log(` High memory: ${info.memory.used}/${info.memory.max} MB`);
    }
  });

  await server.start();
}

startServer();

Configuration Guide

Complete Configuration Example

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

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

  // Java Options
  usePortableJava: true,
  javaVersion: 'auto',

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

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

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

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

  // Plugins
  enableViaVersion: true,
  enableViaBackwards: true,
  enableViaRewind: true,
  enableSkinRestorer: true,

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

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

  // Performance
  silentMode: true,
  statsInterval: 30000
});

await server.start();

Configuration Options Reference

Platform Options

Option Type Default Description platform string 'java' 'java', 'bedrock', or 'all' version string '1.21.11' Minecraft version type string 'paper' paper, purpur, vanilla, spigot, forge, fabric autoAcceptEula boolean true Automatically accept Minecraft EULA

Java Options

Option Type Default Description usePortableJava boolean true Download portable JRE to current directory javaVersion string 'auto' '17', '21', or 'auto'

Memory Options

Option Type Default Description memory.init string '2G' Initial heap size memory.max string '4G' Maximum heap size memory.useAikarsFlags boolean true Use Aikar's optimized GC flags

Network Options

Option Type Default Description network.port number 25565 Java edition server port network.bedrockPort number 19132 Bedrock edition server port network.ip string '0.0.0.0' Bind IP address network.onlineMode boolean false Enable Mojang authentication network.motd string 'Minecraft Server' Message of the day

World Options

Option Type Default Description world.difficulty string 'normal' peaceful, easy, normal, hard world.hardcore boolean false Enable hardcore mode world.gamemode string 'survival' survival, creative, adventure, spectator world.seed string undefined World generation seed world.maxPlayers number 20 Maximum player count world.viewDistance number 6 Chunk view distance world.simulationDistance number 4 Simulation distance world.levelName string 'world' World folder name

Plugin Options

Option Type Default Description enableViaVersion boolean false Enable ViaVersion plugin enableViaBackwards boolean false Enable ViaBackwards plugin enableViaRewind boolean false Enable ViaRewind plugin enableSkinRestorer boolean false Enable SkinRestorer plugin

Performance Options

Option Type Default Description silentMode boolean true Direct pipe logs (no Node.js processing) statsInterval number 30000 Stats update interval in ms

Owner Options

Option Type Default Description owners array [] List of owner usernames ownerCommands.prefix string '!' Command prefix for owners ownerCommands.enabled boolean true Enable owner commands

API Reference

MinecraftServer Class

class MinecraftServer extends EventEmitter {
  constructor(config: Partial<MinecraftConfig>);
  
  // Methods
  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>;
  
  // Events
  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';
}

Player Interface

interface Player {
  name: string;
  uuid: string;
  ip: string;
  ping: number;
  connectedAt: Date;
}

Usage Examples

Server with Auto RAM Detection

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

const totalRam = Math.floor(os.totalmem() / 1024 / 1024 / 1024);
const maxRam = Math.min(12, Math.floor(totalRam * 0.7));

const server = new MinecraftServer({
  version: '1.21.11',
  type: 'paper',
  usePortableJava: true,
  memory: {
    init: `${Math.floor(maxRam * 0.3)}G`,
    max: `${maxRam}G`
  }
});

server.on('ready', (info) => {
  console.log(`Server running with ${info.memory.max} MB max`);
});

server.start();

Multiple Servers with Different Versions

const { ServerManager } = require('@devadevkiyuru/mc-headless');

const manager = new ServerManager();

// Create servers
manager.createServer('lobby', {
  version: '1.21.11',
  type: 'paper',
  network: { port: 25565 }
});

manager.createServer('survival', {
  version: '1.21.11',
  type: 'paper',
  network: { port: 25566 },
  world: { levelName: 'survival' }
});

manager.createServer('creative', {
  version: '1.21.11',
  type: 'paper',
  network: { port: 25567 },
  world: { gamemode: 'creative' }
});

// Start all
await manager.startAll();

// Broadcast command
await manager.broadcastCommand('say Server is running!');

Server with Owner Commands

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

const server = new MinecraftServer({
  version: '1.21.11',
  type: 'paper',
  owners: ['dimzxind', 'admin1', 'tesuser'],
  ownerCommands: {
    prefix: '!',
    enabled: true
  }
});

server.on('player-join', (player) => {
  if (['dimzxind', 'admin1', 'tesuser'].includes(player.name)) {
    server.sendCommand(`tellraw ${player.name} {"text":"Welcome Owner! Use !help for commands","color":"gold"}`);
  }
});

server.start();

Owner Commands Available

Command Description Example !gamemode [player] Change gamemode !gamemode creative !gm [player] Shortcut for gamemode !gm survival !tp [x y z] Teleport !tp player2 !give [amount] Give items !give player2 diamond 64 !time <set|add> Change time !time set day !weather <clear|rain|thunder> Change weather !weather clear !kill [player] Kill player !kill player2 !ban [reason] Ban player !ban hacker !kick [reason] Kick player !kick spammer !op Give operator !op friend !deop Remove operator !deop friend !reload Reload server !reload !save Save world !save !list List players !list !help Show owner commands !help

Server Types

Paper (Recommended for Performance)

const server = new MinecraftServer({
  type: 'paper',
  version: '1.21.11',
  memory: { useAikarsFlags: true }
});

Vanilla (Official Mojang)

const server = new MinecraftServer({
  type: 'vanilla',
  version: '1.21.11'
});

Forge (Modded)

const server = new MinecraftServer({
  type: 'forge',
  version: '1.21.11',
  folders: { mods: './mods' }
});

Fabric (Lightweight Modding)

const server = new MinecraftServer({
  type: 'fabric',
  version: '1.21.11',
  folders: { mods: './mods' }
});

Platform Options

Java Edition Only

const server = new MinecraftServer({
  platform: 'java',
  version: '1.21.11',
  type: 'paper',
  network: { port: 25565 }
});

Bedrock Edition Only

const server = new MinecraftServer({
  platform: 'bedrock',
  version: '1.21.11',
  network: { port: 19132 },
  folders: { addons: './addons' }
});

Cross-Play (Java + Bedrock)

const server = new MinecraftServer({
  platform: 'all',
  version: '1.21.11',
  type: 'paper',
  network: {
    port: 25565,
    bedrockPort: 19132
  }
});

Memory Management

Basic Memory Configuration

memory: {
  init: '2G',
  max: '4G',
  useAikarsFlags: false
}

Aikar's Flags (Optimized)

memory: {
  init: '2G',
  max: '8G',
  useAikarsFlags: true
}

Memory Recommendations

Players RAM Init Max 1-10 2 GB 1G 2G 10-20 4 GB 2G 4G 20-50 8 GB 4G 8G 50-100 16 GB 8G 16G

Network Settings

Basic Network

network: {
  port: 25565,
  ip: '0.0.0.0',
  onlineMode: false,
  motd: 'My Server'
}

Cross-Play Network

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

World Configuration

Basic World

world: {
  difficulty: 'normal',
  gamemode: 'survival',
  maxPlayers: 20,
  viewDistance: 6,
  simulationDistance: 4,
  levelName: 'world'
}

Hardcore Mode

world: {
  difficulty: 'hard',
  hardcore: true,
  gamemode: 'survival',
  maxPlayers: 10,
  viewDistance: 6
}

Custom Seed

world: {
  seed: 'my-amazing-seed-12345',
  levelName: 'custom_world'
}

Folder Structure

server/
├── plugins/          # Paper/Spigot plugins
├── mods/             # Forge/Fabric mods
├── addons/           # Bedrock addons
├── world/            # World data
├── logs/             # Server logs
├── backups/          # Backup files
└── .java/            # Portable Java (if enabled)

Backup System

Enable Automatic Backups

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

Manual Backup

// Full backup
const fullPath = await server.backup('full');

// World only backup
const worldPath = await server.backup('world');

// Plugins only backup
const pluginsPath = await server.backup('plugins');

Event System

Server Events

server.on('ready', (info) => {
  console.log('Server ready at', info.port);
});

server.on('stop', ({ code }) => {
  console.log('Server stopped with code', code);
});

server.on('resource', (info) => {
  console.log(`Memory: ${info.memory.used}/${info.memory.max} MB`);
});

Player Events

server.on('player-join', (player) => {
  console.log(`${player.name} joined from ${player.ip}`);
  server.sendCommand(`say Welcome ${player.name}!`);
});

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

Commands

Built-in Commands

// Send any Minecraft command
server.sendCommand('say Hello world');
server.sendCommand('time set day');
server.sendCommand('weather clear');
server.sendCommand('difficulty hard');
server.sendCommand('gamemode creative @a');

Console Commands

// Stop server
server.sendCommand('stop');

// Save world
server.sendCommand('save-all');

// List players
server.sendCommand('list');

// Ban player
server.sendCommand('ban Notch');

Player Management

Get Player List

const players = server.getPlayers();
players.forEach(player => {
  console.log(`${player.name} - Ping: ${player.ping}ms`);
});

Player Count

const info = await server.getInfo();
console.log(`Players online: ${info.players}/${info.maxPlayers}`);

Cross-Play (Geyser)

Automatic Setup

const server = new MinecraftServer({
  platform: 'all',
  version: '1.21.11',
  type: 'paper',
  network: {
    port: 25565,
    bedrockPort: 19132
  }
});

ViaVersion Support

Enable All ViaVersion Plugins

const server = new MinecraftServer({
  version: '1.21.11',
  type: 'paper',
  enableViaVersion: true,
  enableViaBackwards: true,
  enableViaRewind: true
});

What Each Plugin Does

Plugin Function ViaVersion Allows newer clients to connect to older servers ViaBackwards Allows older clients to connect to newer servers ViaRewind Adds support for 1.7.x - 1.8.x clients

With ViaVersion enabled, your server can accept connections from Minecraft versions 1.7.x through 1.21.x.

SkinRestorer Support

Enable SkinRestorer

const server = new MinecraftServer({
  enableSkinRestorer: true
});

· Auto-downloads latest SkinRestorer · Fixes player skins for offline mode · Works with Geyser (Bedrock players)

Portable Java

How It Works

const server = new MinecraftServer({
  usePortableJava: true,  // Download JRE to .java folder
  javaVersion: 'auto'      // Auto-detect required version
});

· Downloads JRE (not full JDK) ~50MB · Extracts to .java/jre-{version}/ in current directory · Auto-cleanup after 24 hours · No system installation required · Sets JAVA_HOME and PATH automatically · Adds MALLOC_ARENA_MAX=2 for memory efficiency

Java Version Requirements

Minecraft Version Java Version 1.21.x Java 21 1.20.x Java 17 1.19.x Java 17 1.18.x Java 17 1.17.x Java 16 1.16.x Java 8

Performance Tuning

Optimized Configuration

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
  },
  silentMode: true,
  statsInterval: 30000
});

Environment Optimizations

Variable Value Effect MALLOC_ARENA_MAX 2 Prevents memory fragmentation _JAVA_OPTIONS -Xmx... Global Java memory limit JAVA_HOME (auto) Points to portable Java

Pterodactyl Setup

Installation on Pterodactyl

# Connect to your Pterodactyl server via SSH
ssh [email protected]

# Create directory for your server
mkdir minecraft-server
cd minecraft-server

# Install Node.js (if not available)
curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
apt install -y nodejs

# Install mc-headless
npm init -y
npm install @devadevkiyuru/mc-headless

# Create server script
cat > index.js << 'EOF'
const { MinecraftServer } = require('@devadevkiyuru/mc-headless');

const server = new MinecraftServer({
  version: '1.21.11',
  type: 'paper',
  usePortableJava: true,
  memory: {
    init: '2G',
    max: '4G'
  },
  network: {
    port: 25565
  }
});

server.on('ready', (info) => {
  console.log(`Server ready on port ${info.port}`);
});

server.start();
EOF

# Run server
node index.js

Pterodactyl Egg Configuration

If you want to create a custom Pterodactyl egg:

{
  "name": "MC-Headless",
  "description": "Minecraft Headless Server Manager",
  "docker_images": {
    "node:20": "node:20"
  },
  "startup": "node /home/container/index.js",
  "environment": {
    "SERVER_VERSION": "1.21.11",
    "SERVER_TYPE": "paper",
    "MEMORY_INIT": "2G",
    "MEMORY_MAX": "4G"
  }
}

Termux Setup

Install in Termux

# Update packages
pkg update && pkg upgrade

# Install Node.js
pkg install nodejs

# Install mc-headless
npm install -g @devadevkiyuru/mc-headless

# Create server directory
mkdir minecraft-server
cd minecraft-server

# Create server script
cat > server.js << 'EOF'
const { MinecraftServer } = require('@devadevkiyuru/mc-headless');

const server = new MinecraftServer({
  platform: 'java',
  version: '1.21.11',
  type: 'paper',
  usePortableJava: true,
  memory: {
    init: '512M',
    max: '2G'
  }
});

server.start();
EOF

# Run server
node server.js

Termux Optimizations

const server = new MinecraftServer({
  version: '1.21.11',
  type: 'paper',
  usePortableJava: true,
  memory: {
    init: '512M',
    max: '2G'
  },
  world: {
    viewDistance: 4,
    simulationDistance: 3,
    maxPlayers: 10
  }
});

Troubleshooting

Common Issues

Issue Cause Solution Java not found Java not installed Enable usePortableJava: true ENOSPC: no space left Disk full Free disk space, reduce memory Download failed: 302 URL redirect Using Node.js downloader (fixed in v2.2.1) Port already in use Another server running Change port number Plugin corrupt Bad download Delete plugin and restart High CPU usage Too many chunks Reduce viewDistance to 4 Out of memory RAM too low Reduce max memory or add RAM

Disk Space Issues

# Check disk usage
df -h

# Clean up old Java files
rm -rf .java/jre-*

# Clean npm cache
npm cache clean --force

# Remove old backups
rm -rf backups/*

Debug Mode

const server = new MinecraftServer({
  silentMode: false,  // Disable silent mode to see all logs
  statsInterval: 5000 // Update stats every 5 seconds
});

Logs Location

# Server logs are piped directly to console
# Check console output for errors

# Java portable logs
ls -la .java/

Contributing

Development Setup

git clone https://github.com/DevaDev-Notsepuh/mc-headless.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
│   └── utils/
│       ├── Logger.ts
│       ├── FileUtils.ts
│       └── SystemDetector.ts
├── tests/
├── examples/
└── README.md

Pull Request Process

1. Fork the repository
2. Create feature branch
3. Commit changes
4. Push to branch
5. Open pull request

License

MIT License

Copyright (c) 2026 DevaDev

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.