High-Level System Architecture

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• CMakeLists.txt
• src/api/ApiServer.hpp
• src/api/ApiServer.cpp
• src/api/Command.hpp
• src/api/Command.cpp
• src/main.cpp

The mcpi-recompiled project is a source reconstruction and native port of Minecraft: Pi Edition 0.1.1 alpha. Its primary architecture is designed around reproducing the original game's behavior and programming interface on modern Linux and Windows x86-64 systems. The system emphasizes modularity, utilizing a core library to handle protocol compatibility while maintaining a clear separation between game logic and the external API.

The high-level architecture is currently in a bootstrap phase, focusing on a portable C++20 build system and a TCP-based API server that operates on port 4711. This server acts as the primary bridge for external scripts to interact with the game environment, mimicking the original Minecraft Pi API.
Sources: README.md:1-18, CMakeLists.txt:10-15

Core Components and Libraries

The project is structured into a core library (mcpi_core) and an executable entry point. The build system uses CMake to manage cross-platform compilation, linking necessary socket libraries (like ws2_32 on Windows) and threading support.

Component	Responsibility	Source Files
mcpi_core	Static library containing API server logic and command parsing.	src/api/ApiServer.cpp, src/api/Command.cpp
mcpi-recompiled	The main executable entry point that bootstraps the game.	src/main.cpp
ApiServer	Manages TCP connections and dispatches commands to handlers.	src/api/ApiServer.hpp
Command	Data structure and parser for the MCPI protocol.	src/api/Command.hpp

Sources: CMakeLists.txt:17-43, src/api/ApiServer.hpp:16-36

API Server Architecture

The ApiServer class implements a multi-threaded network listener using the PIMPL (Private Implementation) pattern to encapsulate platform-specific socket logic (Winsock for Windows, POSIX for Linux).

Connection Handling

The server starts a dedicated worker thread to accept incoming TCP connections. Once a client connects, it enters a request-response loop where it reads raw bytes, buffers them, and identifies individual command lines terminated by newline characters.

Logic and Data Flow

The server relies on a Handler functional object, which is provided during the start() call. This allows the network layer to remain decoupled from the actual game logic.

1. Input: A raw string from the network (e.g., "world.setBlock(1,2,3,1)\n").
2. Parsing: mcpi::api::parse_command validates the syntax and extracts the method name and arguments.
3. Execution: The Handler process the Command struct.
4. Output: If the handler returns a string, the server appends a newline and transmits it back to the client.

Sources: src/api/ApiServer.hpp:20-20, src/api/ApiServer.cpp:148-164

Protocol Parsing

The protocol parser is a critical component for maintaining compatibility with the Minecraft Pi API. It transforms raw string inputs into structured Command objects.

struct Command {
    std::string name;
    std::vector<std::string> arguments;
};

Sources: src/api/Command.hpp:12-15

The parser follows a specific logic:

• Trimming: Removes leading/trailing whitespace and newlines.
• Tokenization: Identifies the command name before the first parenthesis and extracts arguments separated by commas within the parentheses.
• Empty Handling: Correctly handles zero-argument calls (e.g., player.getPos()) and preserves empty string arguments if commas are present (e.g., chat.post()).

Sources: src/api/Command.cpp:26-66

System Integration and Threading

The architecture leverages C++20 standard threading and atomics to ensure safe shutdown and concurrent operation.

Summary of Architecture

The mcpi-recompiled project utilizes a clean separation between the networking layer and the game logic. By abstracting socket operations and protocol parsing into the mcpi_core library, the system provides a robust foundation for Phase 1 of the project: achieving full parity with the Minecraft Pi Edition 0.1.1 API. The use of a PIMPL-based ApiServer ensures that the architecture remains portable across Windows and Linux while providing a simple interface for the game engine to receive external commands.
Sources: README.md:21-35, src/main.cpp:7-22