GDMC HTTP Interface Mod

Forge Mod for Minecraft (Java Edition) that implements an HTTP interface for reading and writing blocks (and more).

With this interface you can use other applications and scripts running on the same machine to read and modify a Minecraft world.

This is designed as a tool for the Generative Design in Minecraft Competition (GDMC), an annual competition for generative AI systems in Minecraft, where the challenge is to write an algorithm that creates a settlement while adapting to pre-existing terrain. Feel free to join our community Discord server!

Minecraft version	GDMC-HTTP version	Docs	GDMC competition year
1.20.2	📦 GDMC-HTTP 1.4.6	📒 API Docs	2024
1.19.2	📦 GDMC-HTTP 1.4.6	📒 API Docs	2023
1.16.5	📦 GDMC-HTTP 0.4.2	📒 API Docs	2021, 2022

Usage

When you open a Minecraft world, you will see a chat message that the mod has opened an HTTP connection at the address localhost:9000. This means that you can now send HTTP requests from an external program to Minecraft while the world is open.

For testing and experimentation we recommend an API testing tool such as Insomnia or Postman or a command line tool such as cURL or wget.

When you want to build your own settlement generator or some other application, we recommend the GDPC Python library, which is purpose-built by the GDMC community to work with this mod. But any programming or scripting language that supports communication over HTTP (which includes most of them, be it either built-in or via an easy-to-use library) will work.

HTTP Endpoints

When the HTTP interface is active, you have access to the following HTTP endpoints:

HTTP method	URL	Description	Docs
POST	/commands	Send Minecraft console commands	📒 API Docs
GET	/blocks	Get information on blocks in a given area	📒 API Docs
PUT	/blocks	Place blocks	📒 API Docs
GET	/biomes	Get information on biomes in a given area	📒 API Docs
GET	/chunks	Get raw chunk data in a given area	📒 API Docs
GET	/structure	Create an NBT structure file from a given area	📒 API Docs
POST	/structure	Place an NBT structure file into the world	📒 API Docs
GET	/entities	Get information on entities in a given area	📒 API Docs
PUT	/entities	Summon entities into the world	📒 API Docs
PATCH	/entities	Edit entities that already exist in the world	📒 API Docs
DELETE	/entities	Remove entities from the world	📒 API Docs
GET	/players	Get information on players in a given area	📒 API Docs
GET	/buildarea	Get information on the current build area	📒 API Docs
GET	/heightmap	Get heightmap information of the build area	📒 API Docs
OPTIONS	/	Get current Minecraft and mod version	📒 API Docs

Detailed documentation of the endpoints can be found at docs/Endpoints.

Commands

This mod adds the following custom console commands to the game:

Command	Description
/setbuildarea <fromX> <fromY> <fromZ> <toX> <toY> <toZ>	Sets virtual "build area" to a certain area of the world. GET endpoints use this as their default area. Endpoints that edit the world can use the withinBuildArea flag to constrain actions to this area. For the command arguments you can mix and match absolute, local or relative coordinates.
/setbuildarea (no arguments)	Unset build area
/sethttpport <number>	Changes port number of the HTTP interface. Useful for when the default port (9000) conflicts with some other application on your machine. You need to reload your world for this setting to take effect.
/sethttpport (no arguments)	Reset port number of the HTTP interface back to the default 9000
/gethttpport	Show current port number of the HTTP interface

Acknowledgements

GDMC-HTTP has been actively developed with the help of the GDMC community. Of special note here is Niki Gawlik, who created the original version of this mod for Minecraft 1.16.5. This repo is a continuation of their work.