API Command Structure

Relevant source files

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

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

The API Command Structure defines the communication protocol used by mcpi-recompiled to maintain compatibility with Minecraft: Pi Edition 0.1.1. It facilitates a text-based interface over TCP port 4711, allowing external programs to interact with the game world, player, and chat systems. The system is designed to parse incoming string-based messages into structured command objects and route them to appropriate handlers.

Sources: README.md:10-12, src/main.cpp:8-10, src/api/ApiServer.hpp:16

Command Representation and Data Models

Commands are encapsulated within the mcpi::api::Command structure. This structure separates the call identifier from its parameters, providing a clean interface for the server's command handler.

The Command Structure

The primary data container for a parsed request consists of:

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

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

The diagram above represents the basic structure of a command as defined in the API header.
Sources: src/api/Command.hpp:12-15

Command Parsing Logic

The parsing process transforms raw TCP byte streams into Command objects. The parser is implemented in mcpi::api::parse_command and follows a strict syntax: command.name(arg1,arg2,...).

Parsing Workflow

1. Trimming: The input line is trimmed of leading and trailing whitespace.
2. Validation: The parser ensures the string contains balanced parentheses and that the closing parenthesis is at the end of the line.
3. Name Extraction: The substring before the opening parenthesis is extracted as the command name.
4. Argument Splitting: The content within the parentheses is split by commas to populate the argument vector.

Sources: src/api/Command.cpp:24-60

This flowchart illustrates the logic applied in parse_command to validate and decompose a raw string.
Sources: src/api/Command.cpp:24-60

Parser Behavior Examples

Input String	Parsed Name	Arguments	Notes
world.setBlock(1,2,3,57)	world.setBlock	["1", "2", "3", "57"]	Standard multi-arg command.
player.getPos()	player.getPos	[]	Zero-argument command.
chat.post(Hello Pi)	chat.post	["Hello Pi"]	Text payloads are preserved.
not-a-command	N/A	N/A	Fails: missing parentheses.

Sources: tests/protocol_tests.cpp:20-44

API Server Integration

The ApiServer utilizes the command structure to process network requests. It operates as a multi-threaded TCP server that listens for incoming connections and executes a provided Handler.

Data Flow within ApiServer

1. Connection: The server accepts a client connection and configures a receive timeout (200ms).
2. Buffering: Data is read into a 4096-byte buffer and appended to a pending string.
3. Line Processing: The server searches for newline characters (\n) to identify complete command lines.
4. Execution: Validated commands are passed to the Handler. If the handler returns a string, it is sent back to the client followed by a newline.

Sources: src/api/ApiServer.cpp:103-157

The sequence diagram demonstrates the lifecycle of a single command interaction between a client and the server implementation.
Sources: tests/api_server_tests.cpp:113-118, src/api/ApiServer.cpp:138-154

Summary

The API Command Structure is the foundational communication layer for mcpi-recompiled. By utilizing a structured Command object and a dedicated parse_command utility, the system ensures that string-based TCP messages are accurately converted into actionable data for the game engine. The integration with ApiServer allows for reliable, synchronous request-response cycles, maintaining parity with the original Minecraft: Pi Edition protocol.