TCP Port 4711 Implementation

Relevant source files

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

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

The TCP Port 4711 implementation provides a protocol-compatible API for the mcpi-recompiled project, aiming to reconstruct the original Minecraft: Pi Edition 0.1.1 alpha programming interface. Its primary purpose is to allow external scripts and programs to interact with the game world and player state via a networked socket, preserving compatibility with existing MCPI tools and libraries.

Sources: README.md:1-12, src/main.cpp:8-10

Architecture and Components

The API system is built around a multi-threaded server architecture that handles socket lifecycle, connection management, and command parsing.

ApiServer Class

The ApiServer class acts as the primary interface for managing the TCP listener. It uses a Pimpl (Pointer to Implementation) pattern via struct Impl to encapsulate platform-specific socket logic for both Windows (Winsock2) and Linux (POSIX).

Sources: src/api/ApiServer.hpp:14-36, src/api/ApiServer.cpp:78-124

Data structures

The implementation uses a simple Command structure to represent parsed requests.

Field	Type	Description
name	std::string	The identifier of the command (e.g., world.setBlock).
arguments	std::vector<std::string>	A list of string arguments passed within the parentheses.

Sources: src/api/Command.hpp:11-14

Class Relationship

The following diagram illustrates the relationship between the public ApiServer interface and its internal execution logic.

Connection Handling and Data Flow

The server operates on a dedicated worker thread to avoid blocking the main game loop. It listens for incoming connections, processes command strings delimited by newlines, and dispatches them to a registered Handler.

Lifecycle of a Command

1. Accept: The server accepts a new TCP connection on port 4711 (or a user-specified port).
2. Receive: Data is read into a buffer until a newline character (\n) is encountered.
3. Parse: The parse_command function extracts the command name and arguments.
4. Execute: The registered Handler callback processes the Command object and returns an optional response.
5. Respond: If a response is provided, it is sent back to the client followed by a newline.

Protocol Parsing Logic

The protocol parser is designed to handle the specific text-based format used by Minecraft: Pi Edition. It expects commands in the format command.name(arg1,arg2,...).

Parsing Rules

• Trimming: Leading and trailing whitespace is removed from the input line.
• Delimiters: Commands must contain parentheses ( and ). Arguments are separated by commas.
• Empty Arguments: If commas are present without text between them, empty strings are added to the argument vector.
• Validation: Input without parentheses or with trailing data after the closing parenthesis is rejected.

Sources: src/api/Command.cpp:24-60, tests/protocol_tests.cpp:20-43

Configuration and Defaults

The implementation defaults to standard MCPI settings but allows for flexibility during testing.

Setting	Default Value	Source
Port	4711	src/api/ApiServer.cpp:115
Backlog	4	src/api/ApiServer.cpp:177
Receive Timeout	200ms	src/api/ApiServer.cpp:45
Buffer Size	4096 bytes	src/api/ApiServer.cpp:99

Sources: src/api/ApiServer.cpp:45, 99, 115, 177

Platform Specifics

The implementation provides cross-platform support by abstracting socket operations.

Socket Abstraction

// src/api/ApiServer.cpp:20-33
#ifdef _WIN32
using NativeSocket = SOCKET;
constexpr NativeSocket kInvalidSocket = INVALID_SOCKET;
#else
using NativeSocket = int;
constexpr NativeSocket kInvalidSocket = -1;
#endif

Sources: src/api/ApiServer.cpp:20-33

Windows Initialization

On Windows, the ApiServer::start method automatically initializes Winsock using WSAStartup and performs cleanup via WSACleanup during stop().

Sources: src/api/ApiServer.cpp:142-148, 222-227

Summary

The TCP Port 4711 implementation in mcpi-recompiled successfully establishes a foundation for API compatibility. By utilizing a multi-threaded server and a strict text-based parser, it replicates the original Minecraft: Pi Edition communication interface, enabling interoperability with modern C++ environments and existing third-party scripts.

Sources: README.md:14-22, src/main.cpp:5-15