Submission Method: HTTP Interface

The GDMC HTTP Interface is a HTTP API that allows you to interact with a live Minecraft world using standard web requests. It allows you to read and place blocks, run commands, download chunk data, and more. The main implementation of the interface is the Minecraft Forge mod GDMC-HTTP, which is graciously developed and maintained by Niels-NTG (previously Niki Gawlik and Blinkenlights), all members of the GDMC community. The mod's repository also contains the full API specification. The community has also created libraries for the HTTP interface in a few programming languages. The most widely-used of these is GDPC (Generative Design Python Client), a Python 3 framework developed and maintained by avdstaaij (previously Niki Gawlik and Blinkenlights). For real-time troubleshooting or questions, go to the Discord and utilize the #i-http-support channel.

Quick Info

Why we do like it?

Using HTTP requests to modify the Minecraft world allows for a new level of interaction not available with other tools like MCEdit and Amulet. You can edit the world while logged into your world and see the changes occur in front of you. This allows you to iterate on your generator algorithm much more quickly.

In addition to that, the GDMC HTTP interface acts as a well-documented and stable standard for modifying the world, which comes with various advantages. For one, its implementations can easily be updated for new versions of Minecraft, which makes programs written with the HTTP interface quite future-proof. While MCEdit is frozen in Minecraft 1.12, the GDMC-HTTP mod currently supports Minecraft 1.20.2. Another advantage is that you could in principle write a different "backend" that provides the GDMC HTTP interface, and all programs written for it will automatically be compatible.

Before you submit

In order to let your generator know where to build a settlement, we make use of the interface's *build area* feature. You can retrieve the build area bounds using ‘GET /buildarea`. We will provide an example in the `How it works’ section.

How to submit with this method?

There are detailed instructions on how to submit on our submission page. In general:

1. Login to the submission website
2. Go to the submission page
3. In the file section, add a ZIP file that contains the script that will send requests to the HTTP interface and any other required files (see submission page), and files necessary for your code (data files, etc). There is no need to include the GDMC-HTTP mod itself in your submission, since we will already have it installed. We also allow for submission of a link to a repository, such as GitHub, to download the code.
4. If you have other requirements, please document them and include them with your submission. We strongly recommend using something like a setup.py file or including your libraries as part of your submission to streamline the process, or we may have to contact you for instructions.

Getting Started

To get started go over here and follow the installation instructions.

After you are done you should have a working installation of the mod. Make sure to open a Minecraft world, or else the HTTP server will not be running and therefore won't be able to do request with your Minecraft world.

If you are already familiar with HTTP requests it's probably best to take a look at the different endpoints over here or to jump straight to the python example further down.

The basics

The GDMC-HTTP implements a REST API, which means that interacting with Minecraft world is entirely based around requests HTTP requests: You make a request to the server for some data, and the you get a response back which contains that data (or an error message). The benefit of using HTTP as a communication protocol is that it is widely supported. Many programming languages and frameworks have libraries to facilitate this.

To test if everything works we can just open a web browser and visit the following url http://localhost:9000/blocks?x=0&y=-64&z=0. In this example localhost:9000 is the IP and port of the server, blocks is the endpoint for accessing blocks and ?x=0&y=-64&z=0 are the query parameters further specifying the request.

You should see a webpage containing the text minecraft:bedrock. This is the block at position (0, -64, 0).

While this works for simple stuff, to be able to properly play around with the interface I would recommend using an application such as Insomnia or Postman, which allow you to use the manually use the features of GDMC-HTTP without having to write your own code.

In Insomnia a request for a block would look like this.

If you switch the request method from GET to PUT, you can easily place blocks in the world. You specify which block to set in the request body using the "namespaced id" of the block, for example: minecraft:red_concrete.

There are many ways to find out the id of a block. Pressing F3+H in Minecraft will toggle a setting that shows the block id when hovering over an item in your inventory. You can also press F3 to show the debug overlay, if you look at a block the block's id will also be displayed along with it's block state on the right-hand side of the screen in the section "Targeted Block".

Using GDPC

While you can use any programming language to access the HTTP interface, we recommend using the community-developed Python 3 library GDPC. The library is available on PyPI, which means all you need to do to get started is pip-installing gdpc.

On Linux/MacOS:	python3 -m pip install gdpc
On Windows:	py -m pip install gdpc

There are various code examples and tutorials available to familiarize you with GDPC. We recommend that you start with the step-by-step tutorials.

Here's a brief code sample of the library:

from gdpc import Editor, Block, Transform, geometry
 
editor = Editor(buffering=True)
 
# Get a block
block = editor.getBlock((0,48,0))
 
# Place a block
editor.placeBlock((0,80,0), Block("stone"))
 
# Build a cube
geometry.placeCuboid(editor, (0,80,2), (2,82,4), Block("oak_planks"))
 
# Get the build area
buildArea = editor.getBuildArea()
 
# Place a more complex block (there are also helpers available!)
data = '{Items: [{Slot: 13b, id: "apple", Count: 1b}]}'
block = Block("chest", {"facing": "east"}, data)
editor.placeBlock((0,80,0), block)
 
# Use local coordinates
with editor.pushTransform(buildArea.offset):
    editor.placeBlock((10,10,10), Block("stone"))
 
    t = Transform(translation=(1,2,3), rotation=1, flip=(True, False, False))
    with editor.pushTransform(t):
        editor.placeBlock((10,10,10), Block("stone"))

Restrictions and Pitfalls

It's important to remember that the GDMC-HTTP mod will never be as fast as submission methods that modify a world file directly, like Amulet. The networking and string parsing as well as placing the blocks into the minecraft world has a significant overhead. Don't be afraid to send bulk block placement requests, even up to bigger numbers such as a 1000 blocks. Generally Minecraft will handle them fine.

Since this submission method uses a network interface, it may be wise to program somewhat defensively: things can always go wrong. For example, requests can sometimes time out if Minecraft saves the world at an inopportune moment. The GDPC library already performs a few retries for all sent requests automatically, which should take care of any minor connections hiccups.

If you have the minecraft world open, your block placements will interact with the world in real-time: water and lava will flow, sand will fall, etc. This can slow down the game, as well as mess up your generation. Blocks can also sometimes be overridden by outstanding block updates, such as new water sources spawning. So be careful around water.