mcworker

README

MineWorker

[!WARNING] 🚧 Under Construction — This project is currently in active development. Features and APIs may change without notice.

A terminal-based Minecraft server management tool built with Go and Bubble Tea.

Features

• 🌍 World Management — Create, configure, and manage multiple Minecraft server worlds with an intuitive form-based interface
• ⚙️ Server Support — Vanilla, Fabric, and Forge servers with automatic JAR downloading
• ☕ Java Management — Automatic Java version detection and installation (Eclipse Temurin) per world
• ⌨️ Script Generation — Auto-generates start scripts for Windows (.bat) and Unix (.sh) with proper JVM flags
• 🤖 Server Configuration — Full control over RAM allocation, port, gamemode, difficulty, PVP, and more
• 🖥️ Session Management — Run servers in tmux sessions or foreground mode
• 📊 Progress Tracking — Real-time creation progress with stage indicators and scrollable logs
• 🎨 Beautiful TUI — Full-screen terminal interface powered by Bubble Tea with modern styling

Installation

From Source

# Clone the repository
git clone https://github.com/neuronexul/mcworker.git
cd mineworker-go

# Build
go build -o mcworker ./cmd/cli

# Run
./mcworker

Requirements

• Go 1.25 or later
• Linux, macOS, or Windows
• tmux (optional, for background server sessions)

Usage

Simply run the mcworker command to launch the interactive TUI:

mcworker

All functionality is driven through the TUI with proper interactive elements — no subcommands required.

Keyboard Shortcuts

Key	Action
↑ / k	Navigate up
↓ / j	Navigate down
1-4	Quick select menu item
Enter	Confirm selection
Tab	Next field (in forms)
Shift+Tab	Previous field (in forms)
q	Quit

Server Creation Workflow

When creating a new world, MineWorker automatically handles:

1. Directory Setup — Creates the world directory structure
2. Java Runtime — Downloads and installs the required Java version (if not present)
3. Server Download — Fetches the server JAR for your selected server type and version
4. EULA Acceptance — Automatically accepts the Minecraft EULA
5. Script Generation — Creates start scripts with optimized JVM arguments
6. Configuration — Saves the world configuration and generates server.properties
7. Network Setup — Configures port and DNS settings

World Configuration

Each world is a self-contained unit with its own worker.json configuration:

{
  "world": {
    "name": "my-survival-world",
    "path": "./",
    "minecraft_version": "1.21.11",
    "description": "This is my survival forever world"
  },
  "server": {
    "type": "fabric",
    "jar": "fabric-server-1.21.11-0.18.4.jar",
    "eula_accepted": true
  },
  "java": {
    "version": "21",
    "vendor": "temurin",
    "path": "/home/neuronexul/.mcworker/java/temurin-21/bin/java"
  },
  "resources": {
    "ram": {
      "min": "2G",
      "max": "4G"
    },
    "cpu": {}
  },
  "network": {
    "port": 25565,
    "dns": "mc.nexul.in"
  },
  "backups": {}
}

Architecture

┌──────────────────────────────┐
│        Bubble Tea TUI        │  ← Main menu, create world form, progress screen
└──────────────▲───────────────┘
               │
┌──────────────┴───────────────┐
│     Application / Tasks      │  ← Server creation orchestration
└──────────────▲───────────────┘
               │
┌──────────────┴───────────────┐
│      Domain / Core Logic     │  ← World, server types, validation
└──────────────▲───────────────┘
               │
┌──────────────┴───────────────┐
│  Runtime / System Services   │  ← Java, scripts, sessions, network
└──────────────────────────────┘

Project Structure

mineworker-go/
├── cmd/cli/                    # Entry point
├── internal/
│   ├── app/                    # Application orchestration
│   │   └── create.go           # Server creation workflow
│   ├── domain/                 # Pure business logic
│   │   ├── server/             # Server type definitions
│   │   └── world/              # World configuration & validation
│   ├── network/                # Network configuration
│   ├── runtime/                # System integrations
│   │   ├── java/               # Java installation & management
│   │   ├── scripts/            # Start script generation
│   │   └── session/            # Process & session management
│   ├── servers/                # Server type implementations
│   │   ├── vanilla/            # Vanilla server support
│   │   ├── fabric/             # Fabric server support
│   │   └── forge/              # Forge server support
│   ├── tui/                    # Bubble Tea UI components
│   │   ├── root.go             # Root model & screen management
│   │   ├── main_menu.go        # Main menu screen
│   │   ├── create_world.go     # World creation form
│   │   ├── creation_progress.go # Progress tracking screen
│   │   └── styles.go           # UI styles & theming
│   └── utils/                  # Cross-platform utilities
│       └── paths.go            # Path management
└── assets/                     # Screenshots & media

Supported Server Types

Server Type	Description
Vanilla	Official Minecraft server from Mojang
Fabric	Lightweight modding toolchain
Forge	Popular modding platform

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Bubble Tea — TUI framework
• Lip Gloss — Style definitions
• Charm — For the amazing terminal tools ecosystem
• Eclipse Temurin — Java runtime distribution