Interface Endpoints - nikigawlik/gdmc_http_interface GitHub Wiki

POST http://localhost:9000/command

request body:

<command>
<command>
...

The request body contains one or multiple commands on separate lines without the slashes, for example:

say start
tp @p 0 70 0
setblock 0 69 0 stone
fill -8 68 -8 8 68 8 oak_planks replace
say end

These commands are then executed line by line. The response body of the request contains the return values for each command in separate lines. A return value can either be an integer or an error message. For example the request above might return:

1
1
1
289
1

And on a subsequent call, two of the commands will fail, so the return text will be:

1
1
Could not set the block
No blocks were filled
1

For commands and their return values consult the Minecraft commands documentation.

GET http://localhost:9000/blocks?x=<int>&y=<int>&z=<int>

This returns the namespaced id of the block at position x, y, z.

for example

GET http://localhost:9000/blocks?x=-354&y=48&z=1023

could return:

minecraft:stone

if you set the includeState query parameter to true, like this

GET http://localhost:9000/blocks?x=-354&y=48&z=1023&includeState=true

you will get block state information, which could for example look like this:

minecraft:furnace[facing=east,lit=false]

You can also set the 'Accept' header of your http request to application/json. This will return the data in JSON format, which many languages handle well out of the box.

The above example return value would look like this in JSON:

{
    "id": "minecraft:furnace",
    "state": {
        "facing": "east",
        "lit": "false"
    }
}

PUT http://localhost:9000/blocks?x=<int>&y=<int>&z=<int>

request body:

<block>

for example

PUT http://localhost:9000/blocks?x=-354&y=67&z=1023

request body: minecraft:stone

Sets a block in the Minecraft world, similar to the /setblock command.

The x, y, z parameters specify the block location. The request body specifies the block using Minecraft's argument syntax, it also supports block states:

minecraft:furnace[facing=north]

Specifying additional nbt data (like inventory contents) is not supported at the moment. For now, you can use the /command endpoint with Minecraft's /setblock or /data command instead.

More info on the block state syntax can be found on the Minecraft wiki

PUT http://localhost:9000/blocks?x=<int>&y=<int>&z=<int>

request body:

<x> <y> <z> <block>
<x> <y> <z> <block>
<x> <y> <z> <block>
...

for example

PUT http://localhost:9000/blocks?x=-354&y=67&z=1023

request body:

~0 ~0 ~1 minecraft:stone
~0 ~0 ~2 minecraft:stone
~0 ~0 ~3 minecraft:stone
~0 ~0 ~3 minecraft:stone
~1 ~0 ~3 minecraft:stone
~2 ~0 ~3 minecraft:stone

The /blocks endpoint can also contain multiple lines, with each line corresponding to setting one block. The x, y, and z coordinates can be specified in tilde notation (~1 ~2 ~3). In that case they are relative to the position specified in the x, y and z query parameters.

It is completely feasible to send hundreds of blocks at once with this endpoint. Minecraft will then place them as quickly as possible and return the request once it has placed all the blocks.

In Minecraft destroying or placing a block will cause a 'block update'. A block update tells neighboring blocks to react to the change. An example would be for water to flow in to the newly created space, a torch to pop off after the block it was on has been destroyed or a fence to connect to a newly placed fence post.

If for performance or stability reasons you want to avoid block updates you can set the query parameter doBlockUpdates to false.

PUT http://localhost:9000/blocks?x=<int>&y=<int>&z=<int>&doBlockUpdates=false

But be warned, this can cause cosmetic issues such as fences not connecting automatically!

By default blocks placed through the interface will not cause any items to be dropped. In the example of the torch, if a block is detroyed, and attached torch will be destroyed too, but not drop as an item.

If for some reason you do want items to drop you can set the spawnDrops query parameter to true.

PUT http://localhost:9000/blocks?x=<int>&y=<int>&z=<int>&spawnDrops=true

Both of these qury parameters set certain 'block update flags' internally.

If you know what you are doing you can also set the block update behavior manually. But be careful, because this can cause glitchy behavior!

You can set the block update flags with the query parameter customFlags. It is a bit string consisting of 7 bits and it will override the behavior set by doBlockUpdates and spawnDrops.

PUT http://localhost:9000/blocks?x=<int>&y=<int>&z=<int>&customFlags=0000010

The flags are as follows:

You can combine these flags as you wish, for example 0100011 will cause a block update and send the change to clients and prevent neighbor reactions. You should always have the 0000010 flag active, otherwise you will get invisible block glitches.

The following list shows which block update flags doBlockUpdates and spawnDrops get evaluated to internally:

doBlockUpdates=False, spawnDrops=False -> 0110010
doBlockUpdates=False, spawnDrops=True  -> 0110010
doBlockUpdates=True,  spawnDrops=False -> 0100011    (default behavior)
doBlockUpdates=True,  spawnDrops=True  -> 0000011

GET http://localhost:9000/chunks?x=<int>&z=<int>&dx=<int>&dz=<int>

for example

GET http://localhost:9000/chunks?x=0&z=0&dx=2&dz=2

This returns the chunks as an NBT data structure. The NBT format is the save format Minecraft uses for most things. There are open source NBT parsers available for different languages including Python and C#.

The query parameters x and z specify the position of the chuck in 'chunk coordinates'. To get a chunk coordinate from a normal world coordinate, simply divide by 16 and round down to the nearest integer.

The query parameters dx and dz specify how many chunks to get. So dx=3 and dz=4 would get you a 3 by 4 area of chunks, so 12 chunks in total.

The chunks within the returned nbt structure are arranged in z, x order, so the chunk at position (x, z) is in the array at position (x + z * dx).

If you set the 'Accept' header of your request to "application/octet-stream" you will get raw binary data. This is what you probably want if you are using an NBT parsing library.

If the Accept header is anything else, you will get a human readable representation, which looks like this:

{Chunks:[{Level:{Status:"full",zPos:0,LastUpdate:6560L,Biomes:[I;3,3,3,3,7,7 ...

This human readable representation of NBT is defined by Minecraft and used in different places, for example when using NBT data in commands.

The layout of the chunk save data is not completely trivial to process. An example on how to read this data and extract block and heightmap information you can take a look at this python script.

GET http://localhost:9000/buildarea

This returns the current specified build area. The build area can be set inside Minecraft using the setbuildarea command. This is just a convenience command to specify the area, it has no implications to where blocks can be placed or read on the map.

The syntax for the setbuildarea Minecraft command is /setbuildarea xFrom yFrom zFrom xTo yTo zTo.

The return value will be in json format, and contain the coordinates for two positions ("from" and "to") for example:

{"xFrom":0,"yFrom":0,"zFrom":0,"xTo":256,"yTo":256,"zTo":256}

The area will not be saved when you close the world. If no area was specified since the world was loaded, the request will return a 404 error.