Project Goals & Phase 1
Relevant source files
The following files were used as context for generating this wiki page:
The mcpi-recompiled project is a source-reconstruction and native-port initiative targeting Minecraft: Pi Edition 0.1.1 alpha. The primary purpose of the project is to reproduce the original game behavior and its associated programming API on modern systems, specifically Linux x86-64 and Windows x86-64, while strictly avoiding the redistribution of original game binaries or assets.
Phase 1 focuses on establishing a foundation of compatibility. This includes building a portable C++ build system, implementing a protocol-compatible API test harness, and reconstructing platform-independent game systems in testable increments. The objective is to reach functional parity with the original Pi Edition API before introducing any modern enhancements.
Sources: README.md:3-11, README.md:33-41, src/main.cpp:8-10
Core Objectives and Roadmap
The project adheres to a strict sequence of development phases to ensure accuracy during reconstruction.
Phase 1 Goals
- Native Compatibility: Support modern Linux and Windows x86-64 environments.
- Protocol Parity: Support the original MCPI protocol on TCP port
4711. - Incremental Reconstruction: Rebuild game behavior using documented observations and tests.
- Legal Integrity: Maintain a repository policy that excludes proprietary Mojang executables, textures, or leaked code.
Sources: README.md:13-21, README.md:43-45
Development Roadmap
The following flowchart illustrates the planned progression from bootstrapping to playable parity:
Sources: README.md:33-41
API Architecture and Protocol Handling
The project implements a network-based API server designed to be wire-compatible with the original Minecraft: Pi Edition. It uses a custom command parser to interpret TCP-based instructions.
Command Parsing Logic
The system processes text-based commands in the format method.name(arg1,arg2,...). The parser handles string trimming, parenthesis detection, and comma-separated argument splitting.
Network Server (ApiServer)
The ApiServer class manages the lifecycle of the TCP server. It utilizes a worker thread to handle client connections without blocking the main game loop.
| Feature | Description |
|---|---|
| Port | Defaults to 4711, or dynamically assigned if 0 is passed. |
| Threading | Uses std::thread and std::atomic<bool> for safe lifecycle management. |
| Socket Type | Standard TCP SOCK_STREAM using IPv4 (AF_INET). |
| Timeout | Configured with a 200ms receive timeout (SO_RCVTIMEO). |
Sources: src/api/ApiServer.cpp:45-56, src/api/ApiServer.cpp:106-118, src/api/ApiServer.hpp:16-18
API Interaction Sequence
The following sequence diagram represents the interaction between an external script (client) and the ApiServer:
Build System and Testing
The project uses CMake (minimum version 3.20) to manage the build process across different platforms.
CMake Configuration
The build is divided into a core library (mcpi_core) and the main executable.
- Language Standard: C++20.
- Platform Support: Specifically handles Windows via
ws2_32linkage for Winsock support. - Testing: Integrated via
ctest, building specific executables for protocol and server verification.
Sources: CMakeLists.txt:1-12, CMakeLists.txt:22-31
Verification Harness
The project emphasizes "documented observations" and "tests to track parity." Two primary test suites exist:
- Protocol Tests: Validates the parser against expected MCPI strings (e.g.,
chat.post,player.getPos). - API Server Tests: Conducts integration testing by spinning up a loopback server and validating real TCP communication.
Sources: tests/protocol_tests.cpp:21-43, tests/api_server_tests.cpp:94-110
Conclusion
Phase 1 of mcpi-recompiled serves as the critical bridge between modern hardware and the legacy Pi Edition protocol. By prioritizing a clean-room reconstruction of the API and protocol handling before graphics or game logic, the project ensures a stable foundation for the eventual goal of full playable parity.
Sources: README.md:6-11, src/main.cpp:8-12