MCX Documentation

v1.0.4 Complete guide for MCX - Minecraft C++ Experience Layer

What is MCX?

MCX is a server-side scripting platform for Minecraft Java Edition. It enables you to create custom game modes, manage players, and build unique multiplayer experiences without requiring client modifications.

Installation

Windows

# 1. Download the latest release
# Visit: https://github.com/alanparesys/MCX/releases

# 2. Extract the ZIP file
# Right-click → Extract All

# 3. Run the launcher
python mcx-launcher.py

Linux

curl -L -o mcx.zip https://github.com/alanparesys/MCX/releases/latest/download/mcx-v1.0.4-pro.zip
unzip mcx.zip
cd mcx
./mcx --server

Quick Start

After installation, you can start MCX in several ways:

GUI Mode: Run python mcx-launcher.py for the graphical interface
CLI Mode: Run ./mcx --server for command-line operation
Setup Wizard: Run ./mcx --setup for initial configuration

Your First Server

1. Start the launcher with python mcx-launcher.py

2. Click "Start Server" to open the configuration window

3. Set your server name, port (default: 25565), and max players

4. Click "Start Server" in the config window

5. Open Minecraft and connect to localhost:25565

Using the GUI Launcher

The GUI launcher provides:

One-click server start/stop
Auto-update checker with progress bar
Configuration window with all settings
Console output viewer

Configuration Basics

Edit config.json to customize your server:

{
  "serverName": "My MCX Server",
  "port": 25565,
  "maxPlayers": 20,
  "demoMode": false,
  "rcon": {
    "enabled": true,
    "port": 25575,
    "password": "secure_password"
  }
}

Event System

MCX uses an event-driven architecture. Events include:

PLAYER_JOIN - When a player connects
PLAYER_QUIT - When a player disconnects
CHAT_MESSAGE - When a player sends a message
COMMAND_EXECUTED - When a command is run

Lua Scripting

Create custom behaviors with Lua scripts in the scripts/ folder:

-- scripts/welcome.lua
function onEvent(event)
    if event.type == "player_join" then
        local name = event.player.name
        MCX.broadcast("Welcome, " .. name .. "!")
    end
end

Creating Modules

Extend MCX with C++ modules:

// my_module.cpp
#include <mcx/imodule.hpp>

class MyModule : public mcx::IModule {
public:
    void OnEvent(const Event& event, ActionList& actions) override {
        // Handle events
    }
};

API Reference

The MCX API provides access to:

PlayerRegistry: Manage online players
EconomyManager: Handle in-game currency
SceneManager: Switch between game modes
EventBus: Subscribe to events

Architecture

MCX is built with a modular C++20 core:

Core event loop and networking
Lua runtime for scripting
Module system for extensions
WebSocket server for web integration

Performance

MCX is designed for high performance:

Async I/O for networking
Thread pool for background tasks
Minimal memory footprint
Efficient event batching

Building from Source

Requirements

C++20 compiler (GCC 10+, MSVC 2019+, Clang 12+)
CMake 3.16+
OpenGL + GLFW (for GUI)

Build Steps

git clone https://github.com/alanparesys/MCX.git
cd MCX
mkdir build && cd build
cmake .. -DBUILD_GUI=ON
cmake --build . --parallel

Contributing

We welcome contributions!

Fork the repository
Create a feature branch
Make your changes
Submit a pull request

Release Process

MCX follows semantic versioning:

Major: Breaking changes
Minor: New features
Patch: Bug fixes