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. |