MCPI Protocol Compatibility Specification
Relevant source files
The following files were used as context for generating this wiki page:
The MCPI Protocol Compatibility Specification defines the networking and parsing requirements for reproducing the Minecraft: Pi Edition 0.1.1 programming API. The primary objective is to maintain parity with the original game's behavior by supporting TCP-based communication on port 4711, enabling external scripts and tools to interact with the recompiled game engine.
This specification covers the request-response lifecycle, command string parsing logic, and the socket-based server architecture used to facilitate communication between the game and external clients. Sources: README.md:9-16, src/main.cpp:8-10
Network Architecture
The protocol operates over a standard TCP/IP socket connection. By default, the system listens on port 4711. The architecture utilizes a dedicated worker thread to handle incoming client connections without blocking the main game loop. Sources: README.md:14, src/api/ApiServer.cpp:211-213
Server Lifecycle
The ApiServer class manages the lifecycle of the protocol listener. It supports cross-platform socket initialization (Winsock for Windows and POSIX sockets for Linux) and utilizes an asynchronous worker thread to accept clients. Sources: src/api/ApiServer.cpp:142-219, src/api/ApiServer.hpp:22-29
The server allows for dynamic port assignment by passing 0 to the constructor, which is utilized primarily during integration testing to avoid port conflicts. Sources: tests/api_server_tests.cpp:94-102, src/api/ApiServer.cpp:184-197
Command Protocol
The MCPI protocol is a line-based text format. Each command is sent as a UTF-8 string ending with a newline character (\n). The server processes these lines individually and returns optional responses, also followed by newlines. Sources: src/api/ApiServer.cpp:115-133, tests/api_server_tests.cpp:106-107
Command Structure
A valid command consists of a name, followed by arguments enclosed in parentheses.
| Component | Description | Example |
|---|---|---|
| Name | The dot-notated method to call | world.setBlock |
| Arguments | Comma-separated strings within () | 1,2,3,1 |
| Delimiter | Newline character | \n or \r\n |
Sources: src/api/Command.cpp:22-54, tests/protocol_tests.cpp:23-44
Parsing Logic
The parser identifies the command name by locating the first open parenthesis ( and extracting the preceding string. Arguments are extracted by splitting the content between the first ( and the last ) by commas. Leading and trailing whitespace is trimmed from both the name and individual arguments. Sources: src/api/Command.cpp:22-54
Data Structures
The protocol implementation relies on specific internal structures to represent parsed commands and manage the server state.
Command Object
The Command struct stores the breakdown of a received network packet.
struct Command {
std::string name;
std::vector<std::string> arguments;
};
Sources: src/api/Command.hpp:11-14
Server Configuration
The ApiServer implementation uses an internal Impl struct to hide platform-specific socket details and manage concurrency.
| Field | Type | Description |
|---|---|---|
is_running | std::atomic<bool> | Thread-safe flag for server lifecycle |
handler | std::function | Callback for processing parsed commands |
worker | std::thread | The thread running the accept loop |
listener | NativeSocket | The base TCP listener socket |
Sources: src/api/ApiServer.cpp:94-138
Implementation Constraints
- Concurrency: The server handles one client session at a time within its worker thread, though it uses non-blocking concepts like
SO_RCVTIMEO(200ms timeout) to ensure it remains responsive tostop()signals even if no data is being received. Sources: src/api/ApiServer.cpp:46-59, src/api/ApiServer.cpp:108-114 - Robustness: Malformed input (e.g., missing parentheses, empty names, or trailing data after the closing parenthesis) results in the command being ignored. Sources: src/api/Command.cpp:27-37, tests/protocol_tests.cpp:46-48
- Buffer Management: The server uses a 4096-byte stack buffer for receiving raw TCP data, appending to a persistent string until a newline is encountered. Sources: src/api/ApiServer.cpp:109-122
The protocol implementation ensures that scripts written for the original Minecraft: Pi Edition can communicate with the recompiled version without modification, fulfilling the project's Phase 1 goal of API compatibility. Sources: README.md:9-16