@dimzxzzx07/mc-headless 2.0.0 → 2.2.0

package/README.md

@@ -5,12 +5,12 @@
 </div>
 
 <div align="center">
-    <img src="https://img.shields.io/badge/Version-2.0.0-2563eb?style=for-the-badge&logo=typescript" alt="Version">
+    <img src="https://img.shields.io/badge/Version-2.2.0-2563eb?style=for-the-badge&logo=typescript" alt="Version">
     <img src="https://img.shields.io/badge/License-MIT-green?style=for-the-badge&logo=open-source-initiative" alt="License">
     <img src="https://img.shields.io/badge/Node-18%2B-339933?style=for-the-badge&logo=nodedotjs" alt="Node">
     <img src="https://img.shields.io/badge/Java-Portable-007396?style=for-the-badge&logo=openjdk" alt="Java Portable">
-    <img src="https://img.shields.io/badge/Termux-Friendly-00A98F?style=for-the-badge&logo=termux" alt="Termux">
-    <img src="https://img.shields.io/badge/Stable-2.0.0-brightgreen?style=for-the-badge" alt="Stable">
+    <img src="https://img.shields.io/badge/Downloads-10K%2B-brightgreen?style=for-the-badge" alt="Downloads">
+    <img src="https://img.shields.io/badge/Minecraft-1.21.11-00A98F?style=for-the-badge&logo=minecraft" alt="Minecraft">
 </div>
 
 <div align="center">
@@ -20,20 +20,42 @@
     <a href="https://github.com/Dimzxzzz">
         <img src="https://img.shields.io/badge/GitHub-Dimzxzzx07-181717?style=for-the-badge&logo=github&logoColor=white" alt="GitHub">
     </a>
-    <a href="#">
-        <img src="https://img.shields.io/badge/Documentation-Read-8B5CF6?style=for-the-badge&logo=gitbook&logoColor=white" alt="Documentation">
-    </a>
-    <a href="#">
-        <img src="https://img.shields.io/badge/Download-NPM-CB3837?style=for-the-badge&logo=npm&logoColor=white" alt="NPM">
+    <a href="https://www.npmjs.com/package/@dimzxzzx07/mc-headless">
+        <img src="https://img.shields.io/badge/NPM-@dimzxzzx07/mc--headless-CB3837?style=for-the-badge&logo=npm" alt="NPM">
     </a>
 </div>
 
 ---
 
+## Platform Support
+
+<div align="center">
+    <table>
+        <tr>
+            <td align="center"><img src="https://i.imgur.com/YNDuxZz.png" width="64" height="64" alt="Pterodactyl"><br><strong>Pterodactyl</strong></td>
+            <td align="center"><img src="https://i.imgur.com/ibeGaLU.png" width="64" height="64" alt="Ubuntu"><br><strong>Ubuntu</strong></td>
+            <td align="center"><img src="https://i.imgur.com/WdYzwTu.png" width="64" height="64" alt="Linux"><br><strong>Linux</strong></td>
+            <td align="center"><img src="https://i.imgur.com/CODPucn.png" width="64" height="64" alt="Windows"><br><strong>Windows</strong></td>
+            <td align="center"><img src="https://i.imgur.com/sUU24jx.png" width="64" height="64" alt="Termux"><br><strong>Termux</strong></td>
+            <td align="center"><img src="https://i.imgur.com/sbBQLaZ.jpeg" width="64" height="64" alt="Darwin"><br><strong>macOS</strong></td>
+        </tr>
+    </table>
+</div>
+
+**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
 
-- [Overview](#overview)
-- [What's New in 2.0.0](#whats-new-in-200)
+- [What is MC-Headless?](#what-is-mc-headless)
+- [What's New in 2.2.0](#whats-new-in-220)
 - [Features](#features)
 - [Why MC-Headless?](#why-mc-headless)
 - [Installation](#installation)
@@ -56,34 +78,52 @@
 - [SkinRestorer Support](#skinrestorer-support)
 - [Portable Java](#portable-java)
 - [Performance Tuning](#performance-tuning)
+- [Pterodactyl Setup](#pterodactyl-setup)
+- [Termux Setup](#termux-setup)
 - [Troubleshooting](#troubleshooting)
 - [Contributing](#contributing)
 - [License](#license)
 
 ---
 
-## Overview
+## 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/Termux, or integrate Minecraft servers into their applications.
+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.0.0
+## What's New in 2.2.0
 
-### Version 2.0.0 - March 2026
+### Version 2.2.0 - March 2026
 
-- **Portable Java** - Auto-download JRE to `/tmp` (no system installation required)
-- **Smart Java Detection** - Uses `which java` to check existing installation
-- **Auto-cleanup** - Removes old Java files after 24 hours
-- **Cgroups Support** - Reads CPU/Memory stats directly from kernel (like Pterodactyl)
-- **Silent Mode** - Direct pipe for logs, no Node.js processing overhead
-- **30-second Stats** - Resource monitoring every 30 seconds (not real-time)
-- **MALLOC_ARENA_MAX=2** - Environment optimization for memory efficiency
-- **SkinRestorer Plugin** - Auto-download and install SkinRestorer
-- **System RAM Detection** - Auto-recommend memory based on available RAM
-- **Better Error Handling** - Improved error messages and recovery
+- **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
 
 ---
 
@@ -94,15 +134,16 @@ Built specifically for developers, sysadmins, and Minecraft enthusiasts who want
 | **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 `/tmp`, no system installation required |
+| **Portable Java** | Download JRE to current directory, no system installation required |
 | **Cgroups Stats** | CPU/Memory stats like Pterodactyl (30s interval) |
-| **Downloader** | Automatic download of server jars from official sources |
+| **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 |
@@ -114,13 +155,13 @@ Built specifically for developers, sysadmins, and Minecraft enthusiasts who want
 ### Before (Manual Setup)
 ```bash
 # Download server jar
-wget https://api.papermc.io/v2/projects/paper/versions/1.21.11/builds/69/downloads/paper-1.21.11-69.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-17-jre-headless
+sudo apt install openjdk-21-jre-headless
 
 # Accept EULA
 echo "eula=true" > eula.txt
@@ -130,7 +171,7 @@ 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-69.jar nogui
+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/
@@ -140,9 +181,11 @@ wget https://github.com/SkinsRestorer/SkinsRestorerX/releases/latest/download/Sk
 tail -f logs/latest.log
 ```
 
-After (MC-Headless v2.0.0)
+After (MC-Headless v2.2.0)
 
 ```javascript
+const { MinecraftServer } = require('@dimzxzzx07/mc-headless');
+
 const server = new MinecraftServer({
   version: '1.21.11',
   type: 'paper',
@@ -177,7 +220,7 @@ Requirements
 Requirement Minimum Recommended
 Node.js 18.0.0 20.0.0 or higher
 RAM 2 GB 4 GB or more
-Storage 1 GB 5 GB
+Storage 2 GB 10 GB
 OS Linux, macOS, Windows, Termux Linux (production)
 
 Note: Java is auto-downloaded as portable JRE (no system installation needed)
@@ -298,7 +341,7 @@ async function startServer() {
   server.on("ready", (info) => {
     console.clear();
     console.log(`\n==========================================`);
-    console.log(`Minecraft Server - v2.0.0`);
+    console.log(`Minecraft Server - v2.2.0`);
     console.log(` IP: ${publicIp}:${info.port}`);
     console.log(` Version: ${info.version}`);
     console.log(` Memory: ${info.memory.used}/${info.memory.max} MB`);
@@ -318,7 +361,7 @@ async function startServer() {
 
   server.on("resource", (info) => {
     if (info.memory.used > info.memory.max * 0.8) {
-      console.log(`high memory: ${info.memory.used}/${info.memory.max} MB`);
+      console.log(` High memory: ${info.memory.used}/${info.memory.max} MB`);
     }
   });
 
@@ -427,7 +470,7 @@ autoAcceptEula boolean true Automatically accept Minecraft EULA
 Java Options
 
 Option Type Default Description
-usePortableJava boolean true Download portable JRE to /tmp
+usePortableJava boolean true Download portable JRE to current directory
 javaVersion string 'auto' '17', '21', or 'auto'
 
 Memory Options
@@ -472,6 +515,13 @@ 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
@@ -522,6 +572,18 @@ interface ServerInfo {
 }
 ```
 
+Player Interface
+
+```javascript
+interface Player {
+  name: string;
+  uuid: string;
+  ip: string;
+  ping: number;
+  connectedAt: Date;
+}
+```
+
 ---
 
 Usage Examples
@@ -587,25 +649,397 @@ await manager.startAll();
 await manager.broadcastCommand('say Server is running!');
 ```
 
+Server with Owner Commands
+
+```javascript
+const { MinecraftServer } = require('@dimzxzzx07/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 <mode> [player] Change gamemode !gamemode creative
+!gm <mode> [player] Shortcut for gamemode !gm survival
+!tp <player> [x y z] Teleport !tp player2
+!give <player> <item> [amount] Give items !give player2 diamond 64
+!time <set\|add> <value> Change time !time set day
+!weather <clear\|rain\|thunder> Change weather !weather clear
+!kill [player] Kill player !kill player2
+!ban <player> [reason] Ban player !ban hacker
+!kick <player> [reason] Kick player !kick spammer
+!op <player> Give operator !op friend
+!deop <player> Remove operator !deop friend
+!reload Reload server !reload
+!save Save world !save
+!list List players !list
+!help Show owner commands !help
+
 ---
 
-Portable Java
+Server Types
 
-How It Works
+Paper (Recommended for Performance)
 
 ```javascript
 const server = new MinecraftServer({
-  usePortableJava: true,  // Download JRE to /tmp
-  javaVersion: '17'        // or '21', 'auto'
+  type: 'paper',
+  version: '1.21.11',
+  memory: { useAikarsFlags: true }
 });
 ```
 
-· Downloads JRE (not full JDK) ~50MB
-· Extracts to /tmp/.mc-headless-java/
-· Auto-cleanup after 24 hours
-· No system installation required
-· Sets JAVA_HOME and PATH automatically
-· Adds MALLOC_ARENA_MAX=2 for memory efficiency
+Vanilla (Official Mojang)
+
+```javascript
+const server = new MinecraftServer({
+  type: 'vanilla',
+  version: '1.21.11'
+});
+```
+
+Forge (Modded)
+
+```javascript
+const server = new MinecraftServer({
+  type: 'forge',
+  version: '1.21.11',
+  folders: { mods: './mods' }
+});
+```
+
+Fabric (Lightweight Modding)
+
+```javascript
+const server = new MinecraftServer({
+  type: 'fabric',
+  version: '1.21.11',
+  folders: { mods: './mods' }
+});
+```
+
+---
+
+Platform Options
+
+Java Edition Only
+
+```javascript
+const server = new MinecraftServer({
+  platform: 'java',
+  version: '1.21.11',
+  type: 'paper',
+  network: { port: 25565 }
+});
+```
+
+Bedrock Edition Only
+
+```javascript
+const server = new MinecraftServer({
+  platform: 'bedrock',
+  version: '1.21.11',
+  network: { port: 19132 },
+  folders: { addons: './addons' }
+});
+```
+
+Cross-Play (Java + Bedrock)
+
+```javascript
+const server = new MinecraftServer({
+  platform: 'all',
+  version: '1.21.11',
+  type: 'paper',
+  network: {
+    port: 25565,
+    bedrockPort: 19132
+  }
+});
+```
+
+---
+
+Memory Management
+
+Basic Memory Configuration
+
+```javascript
+memory: {
+  init: '2G',
+  max: '4G',
+  useAikarsFlags: false
+}
+```
+
+Aikar's Flags (Optimized)
+
+```javascript
+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
+
+```javascript
+network: {
+  port: 25565,
+  ip: '0.0.0.0',
+  onlineMode: false,
+  motd: 'My Server'
+}
+```
+
+Cross-Play Network
+
+```javascript
+network: {
+  port: 25565,
+  bedrockPort: 19132,
+  ip: '0.0.0.0',
+  onlineMode: false,
+  motd: 'Cross-Play Server'
+}
+```
+
+---
+
+World Configuration
+
+Basic World
+
+```javascript
+world: {
+  difficulty: 'normal',
+  gamemode: 'survival',
+  maxPlayers: 20,
+  viewDistance: 6,
+  simulationDistance: 4,
+  levelName: 'world'
+}
+```
+
+Hardcore Mode
+
+```javascript
+world: {
+  difficulty: 'hard',
+  hardcore: true,
+  gamemode: 'survival',
+  maxPlayers: 10,
+  viewDistance: 6
+}
+```
+
+Custom Seed
+
+```javascript
+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
+
+```javascript
+backup: {
+  enabled: true,
+  interval: '24h',
+  path: './backups'
+}
+```
+
+Manual Backup
+
+```javascript
+// 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
+
+```javascript
+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
+
+```javascript
+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
+
+```javascript
+// 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
+
+```javascript
+// 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
+
+```javascript
+const players = server.getPlayers();
+players.forEach(player => {
+  console.log(`${player.name} - Ping: ${player.ping}ms`);
+});
+```
+
+Player Count
+
+```javascript
+const info = await server.getInfo();
+console.log(`Players online: ${info.players}/${info.maxPlayers}`);
+```
+
+---
+
+Cross-Play (Geyser)
+
+Automatic Setup
+
+```javascript
+const server = new MinecraftServer({
+  platform: 'all',
+  version: '1.21.11',
+  type: 'paper',
+  network: {
+    port: 25565,
+    bedrockPort: 19132
+  }
+});
+```
+
+---
+
+ViaVersion Support
+
+Enable All ViaVersion Plugins
+
+```javascript
+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.
 
 ---
 
@@ -615,14 +1049,43 @@ Enable SkinRestorer
 
 ```javascript
 const server = new MinecraftServer({
-  enableSkinRestorer: true  // Auto-download and install
+  enableSkinRestorer: true
 });
 ```
 
 · Auto-downloads latest SkinRestorer
 · Fixes player skins for offline mode
 · Works with Geyser (Bedrock players)
-· No manual plugin installation needed
+
+---
+
+Portable Java
+
+How It Works
+
+```javascript
+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
 
 ---
 
@@ -659,26 +1122,235 @@ JAVA_HOME (auto) Points to portable Java
 
 ---
 
+Pterodactyl Setup
+
+Installation on Pterodactyl
+
+```bash
+# Connect to your Pterodactyl server via SSH
+ssh user@your-server.com
+
+# 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 @dimzxzzx07/mc-headless
+
+# Create server script
+cat > index.js << 'EOF'
+const { MinecraftServer } = require('@dimzxzzx07/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:
+
+```json
+{
+  "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
+
+```bash
+# Update packages
+pkg update && pkg upgrade
+
+# Install Node.js
+pkg install nodejs
+
+# Install mc-headless
+npm install -g @dimzxzzx07/mc-headless
+
+# Create server directory
+mkdir minecraft-server
+cd minecraft-server
+
+# Create server script
+cat > server.js << 'EOF'
+const { MinecraftServer } = require('@dimzxzzx07/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
+
+```javascript
+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 No system Java Enable usePortableJava: true
-High memory usage Too many chunks Reduce viewDistance
-High CPU usage Stats interval too low Increase statsInterval to 60000
+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.0)
+Port already in use Another server running Change port number
 Plugin corrupt Bad download Delete plugin and restart
-Port in use Another server Change port number
+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
+
+```bash
+# Check disk usage
+df -h
+
+# Clean up old Java files
+rm -rf .java/jre-*
 
-Check Logs
+# Clean npm cache
+npm cache clean --force
+
+# Remove old backups
+rm -rf backups/*
+```
+
+Debug Mode
+
+```javascript
+const server = new MinecraftServer({
+  silentMode: false,  // Disable silent mode to see all logs
+  statsInterval: 5000 // Update stats every 5 seconds
+});
+```
+
+Logs Location
+
+```bash
+# Server logs are piped directly to console
+# Check console output for errors
+
+# Java portable logs
+ls -la .java/
+```
+
+---
+
+Contributing
+
+Development Setup
 
 ```bash
-# Server logs are piped directly
-# Just look at console output
+git clone https://github.com/Dimzxzzx07/mc-headless.git
+cd mc-headless
+npm install
+npm run build
+npm test
+```
+
+Project Structure
 
-# Or check cgroup stats
-cat /sys/fs/cgroup/memory/memory.usage_in_bytes
 ```
+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
 
 ---