Reverse-Engineering Methodology

Relevant source files

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

• README.md
• src/api/ApiServer.cpp
• src/api/Command.cpp
• tests/protocol_tests.cpp
• tests/api_server_tests.cpp
• src/api/ApiServer.hpp
• src/api/Command.hpp

The reverse-engineering methodology of the mcpi-recompiled project is a structured approach to reconstructing the source code and native functionality of Minecraft: Pi Edition 0.1.1 alpha. The process focuses on incremental reconstruction through documented observations, protocol compatibility, and a strict separation between new code and original proprietary assets. The primary goal is to achieve playable parity on modern Linux and Windows x86-64 systems while maintaining 100% compatibility with the original TCP-based programming API.

Sources: README.md:3-13, README.md:27-35

Phase-Based Reconstruction Strategy

The project employs a multi-phase roadmap to ensure technical accuracy and legal compliance. The methodology prioritizes the creation of a portable build system and a protocol-compatible API harness before attempting to reconstruct complex game systems like rendering or physics.

Phase	Focus Area	Description
Bootstrap	Infrastructure	Establishment of C++20 build system (CMake) and CI environment.
Protocol	API Compatibility	Implementing a test harness for the MCPI protocol on TCP port 4711.
Documentation	Research	Recording factual observations of original executable and platform assumptions.
Systems	Logic Reconstruction	Incremental, testable implementation of platform-independent game logic.
Platform	Integration	Implementing rendering, input, and windowing for modern OS targets.
Parity	Validation	Reaching full functional parity with Pi Edition 0.1.1.

Sources: README.md:37-46, CMakeLists.txt:1-20

Protocol Reverse-Engineering

A core component of the methodology is the reconstruction of the Minecraft Pi API protocol. This is achieved by analyzing the communication patterns of the original game and implementing a parser capable of handling the specific string-based command format used over TCP.

Command Parsing Logic

The protocol relies on a text-based format where commands are structured as name(arg1,arg2,...). The reconstruction process uses a specialized parser to decompose these strings into a Command structure.

The parser specifically handles:

• Command Names: Extracted by finding the substring before the first parenthesis.
• Arguments: Comma-separated values within the parentheses, which are trimmed and stored in a vector.
• Edge Cases: Empty inputs, malformed structures (missing parentheses), or trailing data are explicitly rejected to ensure parity.

Sources: src/api/Command.cpp:18-53, tests/protocol_tests.cpp:24-52

API Server Reconstruction

The reconstruction of the API server involves implementing a multi-threaded TCP server that mimics the behavior of the original game's listener on port 4711.

Socket Management Architecture

The methodology utilizes a platform-agnostic socket wrapper to support both Windows (Winsock) and Linux (POSIX sockets). This ensures the reconstructed API can be tested and run across different environments.

Key Server Components

• ApiServer::Impl: A Pimpl-patterned structure managing the listener socket and worker thread.
• receive_timed_out: A platform-specific check for EAGAIN/EWOULDBLOCK to allow the server to remain responsive during shutdown.
• send_all: A robust utility to ensure complete transmission of responses over TCP.

Sources: src/api/ApiServer.cpp:68-150, src/api/ApiServer.hpp:16-35

Parity Validation through Testing

To verify the accuracy of the reverse-engineered components, the project uses a test-driven approach. Two primary test suites validate different layers of the reconstruction:

1. Protocol Tests: Validate the string parser against known command formats like world.setBlock, player.getPos, and chat.post.
2. API Server Integration Tests: Spin up a live TCP server, connect a loopback client, and verify that the request-response cycle matches the original game's behavior.

// Example of a parity test for the getPos command
const auto command = parse_command("player.getPos()\r\n");
expect(command.has_value(), "zero-argument command should parse");
expect(command->name == "player.getPos", "player.getPos name should match");

Sources: tests/protocol_tests.cpp:33-37, tests/api_server_tests.cpp:95-115

Ethical and Legal Boundaries

A critical aspect of the project's methodology is the strict avoidance of proprietary data. The repository policy prohibits the inclusion of:

• Original Mojang executables or binaries.
• Game assets such as textures, sounds, or data files.
• Leaked or proprietary source code.

Instead, the project relies on documented observations and factual reverse-engineering notes to guide the reconstruction of game systems in a "clean-room" style implementation.

Sources: README.md:8-13, README.md:48-50

Conclusion

The mcpi-recompiled methodology is defined by its focus on incremental, test-backed reconstruction of the Minecraft: Pi Edition protocol and game systems. By prioritizing API compatibility and platform independence through C++20 and cross-platform socket abstractions, the project provides a foundation for modernizing the game while respecting the original's technical constraints and legal boundaries.