Skip to content

macchie/minecraft-bedrock-server-bridge

Repository files navigation

Docker Pulls GitHub Issues

Minecraft Bedrock Server Bridge

RCON replacement for Minecraft Bedrock Dedicated Servers.

Currently allows you to bridge your server console to a Telegram Bot.

Setup

Create a Telegram Bot and obtain the Token

Extend your itzg/docker-minecraft-bedrock-server docker-compose.yml file to produce something similar:

version: '3.4'

services:
  bds:
    image: itzg/minecraft-bedrock-server
    environment:
      EULA: "TRUE"
      GAMEMODE: creative
      SERVER_NAME: Your Server Name
    ports:
      - 19132:19132/udp
#      - 39133:39133/udp
    volumes:
      - /path/to/your/data:/data
    labels:
      minecraft_bedrock_server: "true"
    stdin_open: true
    tty: true
    sysctls:
      net.ipv4.ip_local_port_range: 39132 39133
  
  bds_bridge:
    image: macchie/minecraft-bedrock-server-bridge
    environment:
      - TELEGRAM_BOT_TOKEN=12345
      - TELEGRAM_BOT_ADMINS=username1,username2
    volume:
      - /var/run/docker.sock:/var/run/docker.sock

Make sure you set your Server with:

stdin_open: true
tty: true
labels:
  minecraft_bedrock_server: "true"

Remeber to set stdin_open and tty, these two properties allows you attach to the Docker container to run commands through the console.

Add a minecraft_bedrock_server label under the labels list (value is not important) to flag this container so that the bridge can succesfully discover it.

Also, add a new bds_bridge service and set TELEGRAM_BOT_TOKEN and TELEGRAM_BOT_ADMINS:

bds_bridge:
  image: macchie/minecraft-bedrock-server-bridge
  environment:
    - TELEGRAM_BOT_TOKEN=12345
    - TELEGRAM_BOT_ADMINS=username1,username2
  volume:
    - /var/run/docker.sock:/var/run/docker.sock

Configuration

Configuration is achieved via environment variables on your bridge container, here is a list of available env variables:

  • BDS_CONTAINER_LABEL - used to change the Docker container label (optional, default: minecraft_bedrock_server)
  • TELEGRAM_BOT_TOKEN - your Telegram BOT token, if set enables Telegram BOT (default: null)
  • TELEGRAM_BOT_ADMINS - a comma separated list of Telegram usernames that will be able to communicate with the BOT (optional, default: null)
  • ENABLE_API - enables experimental HTTP API support (optional, default: false)
  • API_TOKEN - if set the token will be checked to authenticate the request (optional, default: null)
  • API_PORT - used to change the HTTP API port (optional, default: 17394)

How To Use

Using Telegram BOT

Open Telegram and send a message to your bot, every message is passed to the Server console.

For example, to say something to all players you can text (you can send you messages with or without the / character):

  • say Hello World!

or execute any other command:

  • /give username diamond_block
  • daylock

The command response will be texted back to you by the BOT, if the command generates no output a confirmation of execution is sent back.

Using HTTP API

First you need to expose the port, to do this edit your docker-compose.yml file and add the HTTP API port:

bds_bridge:
  image: macchie/minecraft-bedrock-server-bridge
  environment:
    - TELEGRAM_BOT_TOKEN=12345
    - TELEGRAM_BOT_ADMINS=username1,username2
  # add the ports entry
  ports:
    - 17394:17394
  volume:
    - /var/run/docker.sock:/var/run/docker.sock

The HTTP API exposes a single /execute endpoint, the request is made in standard JSON format, here is an example via CURL (any HTTP client is valid):

$ curl -L -X POST 'http://<your-server-address>:17394/execute' \
    -H 'Content-Type: application/json' \
    --data-raw '{ "command": "say Hello World!" }'
$ curl -L -X POST 'http://<your-server-address>:17394/execute' \
    -H 'Content-Type: application/json' \
    --data-raw '{ "command": "/give username diamond_block" }'

The HTTP API response is also in standard JSON format and looks like this:

{
  "status":200,
  "response":"There are 0/10 players online:"
}

minegen.js example script

After enabling your HTTP API you can send commands to your server with simple HTTP requests, this allows you to script command execution. Inside the examples/ folder you will find a simple JavaScript file that creates auto-generated fill commands from a .json input source.

Here is an example of what you can achieve:

To test this structure on your server use this syntax:

# 
./minegen.js INPUT_FILE [START_X, optional] [START_Y, optional] [START_Z, optional]

# example (defaults on server 127.0.0.1:17394)
./minegen.js test.json 0 64 0

# example (defaults on server 127.0.0.1:17394)
SERVER_IP=localhost SERVER_PORT=17394 ./minegen.js test.json 0 64 0

Notes

To-Do

  • add minegen.js json format info
  • Add Web Panel ?