Datapack TCP

Datapack TCP is a mod that connects Minecraft to external programs. It opens a TCP socket that streams game information such as scoreboards and chat messages outwards and commands inwards, allowing internal datapacks and external programs to work together.

Usage

The mod runs a TCP server alongside your Minecraft server (default is localhost: 127.0.0.1, default port: 25566).

Communication is handled via JSON Lines. Every payload sent to or from the server must be a single-line, valid JSON object, terminated by a newline character (\n). Any number of clients (such as Python scripts) can connect to receive/send payloads.

---

Client -> Server Protocol

command

Executes a Minecraft command as the server console.

• type (String): "command".
• command (String): The Minecraft command to run (no leading slash required).
• id (String, Optional): A unique identifier (like a UUID) to track the result of this specific command.
• tick (Long, Optional): The target tick to execute the command on. If absent or tick has already occured, command executes immediately.

Example:

{"type": "command", "command": "summon zombie ~ ~ ~", "id": "spawn_zombie_1", "tick": 2333}

---

Server -> Client Protocol

command_result

When a client sends a command, the server executes it and sends the result back to the client that requested it.

• type (String): "command_result"
• command (String): The command that was run.
• success (Boolean): Whether the command could be run.
• result (Int, Optional): The return value of the command if it was run.
• error (String, Optional): The syntax error of the command if it could not be run.
• id (String, Optional): The unique identifier of this command if present.
• tick (Long): The server tick when the command was run.

Example (success):

{"type": "command_result", "command": "summon zombie ~ ~ ~", "success": true, "result": 1, "id": "spawn_zombie_1", "tick": 2333}

Example (failure):

{"type": "command_result", "command": "summon zombi ~ ~ ~", "success": false, "error": "Can't find element 'minecraft:zombi' of type 'minecraft:entity_type' at position 12: ...mmon zombi<--[HERE]", "id": "spawn_zombie_1", "tick": 2333}

scoreboard

Sent when a client first connects, providing the current state of all scoreboards.

• type (String): "scoreboard"
• tick (Long): The server tick of the scoreboard state.
• scoreboard (Json): The key-value map of objective to player scores.

Example:

{"type": "scoreboard", "tick": 24000, "scoreboard": {"kills": {"Player1": 5,"Player2": 12}, "round": {"#current": 3}}}

scoreboard_change

Sent when one or more scores are changed, and contains only those changes.

• type (String): "scoreboard_change"
• tick (Long): The server tick that the scoreboard changed.
• scoreboard (Json): The key-value map of objective to player scores.

Example (after Player1 gets a kill):

{"type": "scoreboard_change", "tick": 24025, "scoreboard": {"kills": {"Player1": 6}}}

chat_message

Sent when a player sends a normal chat message.

• type (String): "chat_message"
• tick (Long): The server tick when the message occurred.
• sender (String): The username of the player.
• message (String): The raw text of the message.

Example:

{"type": "chat_message", "tick": 24050, "sender": "Player1", "message": "Hello world!"}

command_message

Sent when a command broadcasts a message to chat (e.g., /me, /say).

• type (String): "command_message"
• tick (Long): The server tick when the message occurred.
• source (String): The entity, block, or console that ran the command.
• message (String): The raw text of the message.

Example:

{"type": "command_message", "tick": 24055, "source": "Server", "message": "Server restarting in 5 minutes"}

game_message

Sent when the game posts a message, such as player join/leave events or death messages.

• type (String): "game_message"
• tick (Long): The server tick when the message occurred.
• overlay (Boolean): true if the message appeared as an overlay, false if in the chat.
• message (String): The raw text of the message.

Example:

{"type": "game_message", "tick": 24060, "overlay": false, "message": "Player2 fell from a high place"}

---

Configuration

Option	Default	Description
port	25566	The TCP port to use.
host	"127.0.0.1"	The IP address to use. Default is localhost.
streamScoreboard	true	Enables sending the scoreboard.
scoreboardChanges	true	Enables sending only scoreboard changes. Otherwise send full scoreboard every tick.
streamChatMessages	true	Enables sending player chat messages.
streamCommandMessages	true	Enables sending command message events (e.g., /me, /say).
streamGameMessages	true	Enables sending game message events (e.g., join/leave, death messages).
acceptCommands	true	Allows clients to send commands for the server to run.
returnCommandResults	true	Enables sending command results back to clients.