Submission

This page intends to give an overview of the requirements a submission might fulfill to be considered, as well as possible technologies and frameworks that might be used in a submission. We prefer for 2023 that all submissions are made in either the Amulet format or as a client that runs with the HTTP framework. If you want to provide a submission in another format, please contact the organizers.

Submission Information

Requirements of your Generator

The requirements for entry in the Settlement Generation Challenge 2023 are that your generator…

• …works on Minecraft Java Edition 1.19.2
• …accepts a map generated in Minecraft Java Edition 1.19.2 (Vanilla)
• …accepts a 3D bounding box (the build area within the map)
• …should not run "substantially longer" than 10 minutes
• …does not exceed 2 GB of working memory per map

We think the best way to assure this is to work with one of the two suggested frameworks below. In the past, we have allowed for other submission types, but due to organizational concerns, we try to limit submissions to these two types now.

Who can participate?

Regarding who can participate:

• Anyone can join in!
• Working in teams in encouraged!
• Only one submission per person / team
• If you are an academic supervisor with several teams, we are willing to make an exception, but please contact us beforehand.

Our goal is to run your submissions on our machines.

But the organizers might require your help with running your framework, we suggest you use an email for submission where we can contact you in the two weeks after submission, and monitor that email. We might send you the competition maps and instructions to apply your own code to the maps in that timeframe.

Any submitted works, unless explicitly requested otherwise, will be publicly available after the evaluation period. You retain all rights to your work (though we recommend including a license and adding author information to your source code).
If you have any questions, feel free to ask on our Discord server in the '#competition-rules' channel.

Submission Material

Your actual submission should be done on our official website. You will have to set up an account, and we might contact you via the email address you register there for follow-up queries. You then should submit a .zip file, that contains the following items:

*your code that allows us to run the generator. If you use the HTTP Interface mod framework, then you do not need to send us code for the interface mod, just for your client.
*a short write up on how your generator works. This can be an attached pdf, or a text file. Feel free to add images, if you like.
*one, or several, example images of what your output should look like. We might use them to check if your generator runs as intended.
*[optional] a license statement.

We will ask you at the time of submission if you are fine with us sharing your code. If you do not object, we will share your code. We also recommend including an online repository link in your readme, so people can download a current version from you. We will also publish the generator explanation after the competition, but we will not provide this to the judges. We believe the generators should speak for themselves. We assume that we are allowed to share all the material you include on our site, including the images and text you submitted. If you add your real names to the text you attach, we might also share your names.

Frameworks

Although you can attempt to start your work from scratch, we highly recommend building up on the past work of others!

One way of speeding up and facilitating development is by using one of our community-developed frameworks, a couple of which are listed below sorted by their method of interacting with the world.
If you decide to use a method that is either not listed or not recommended, please make certain to provide a 'README' file in your submission. We recommend you contact the organizers on the discord to discuss your alternative option beforehand.
If you have any questions regarding frameworks or are having difficulty with using a framework, feel free to ask on our Discord server in the '#frameworks' and '#framework-support' channels respectively, and if you decide to create your own framework ping @Moderator to get access to a special channel!

HTTP Interface

Main article: Submission Method: HTTP Interface

The HTTP Interface Mod is a Forge mod for Minecraft Java Edition 1.19.2 based on a previous (now outdated) version made by Nils Gawlik. It creates a REST API in a running Minecraft client to allow for easy and flexible access to various in-world information. The generator runs in real-time making it potentially slower but allowing for users to observe the generator in action.

While you can create your own HTTP client to interface with the API of HTTP Interface mod, there are a couple of options already out there for some popular programming languages. If you choose this submission route your job is basically to write a client that communicates with the HTTP Interface Mod. There are existing clients to get you started, and you can use them as a basis to develop your own submission.
If you decide to use an HTTP-based solution, ping @Moderator on our Discord server to gain a special role!

GDPC (Python)

GDPC (Generative Design Python Client) is a Python 3 framework for the HTTP interface. It is one of the most widely used frameworks in the competition, and it comes with many helpful tools for writing generators.

It can easily be imported to your Python project after pip-installing 'gdpc'. There are also various code tutorials available.

Sample code:

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"))

HTTP Wrapper (C#)

The GDMC-HTTP-wrapper is a barebones framework written in C#.
Sample code:

Connection connection = new Connection();
Vec3Int point = new Vec3Int(20, 64, 15);
// Get 3x3 chunk area starting from the chunk containing 20, 64, 15
Chunk[] chunks = connection.GetChunksSync(point, 3, 3);
 
// Get an individual block
Block block = connection.GetBlockSync(point);
 
// Send commands to the server
string[] returns = connection.SendCommandsSync(new string[]
        {
            "say hello!",
            "data get entity @p Pos"
        });
 
// Set a block on the server
Block goldBlock = new Block(new Vec3Int(0, 70, 0), BlockName.gold_block);
bool blockChanged = SetBlockSync(Block block)
 
// Create some blocks and then push them to the server
List<Block> blocks = new List<Block>(30);
for (int x = 0; x < 10; x++)
{
    for (int z = 0; z < 3; z++)
    {
        blocks.Add(new Block(new Vec3Int(x, 70, z), BlockName.gold_block));
    }
}
connection.SetBlocksSync(blocks.ToArray());
 
// Get build area set on the server
Vec3Int[] buildArea = connection.GetBuildArea();

Amulet (Python)

Main article: Submission Method: Amulet

Amulet is the spiritual successor to MCEdit. It supports all versions from Minecraft Java Edition 1.12 and Bedrock Edition 1.7 onwards and is based on Python 3, allowing for flexible integration into your solution.

Amulet is an interface able to read Minecraft saves files, and rewrite them if needed. Based on the data in the save file, Amulet will render the loaded world. Any modification made to the rendered world will be saved in the Minecraft saves. Therefore, you are then able to reopen the same save with the game later on and see your changes in the game.

You can find support on how to get started with this approach here.

If you want to submit via this method, your submission should contain the python script you wrote for amulet which should include a single operation that should be named like your generator.

Unsupported Submission Options

The following are all options that allow you in principle to interact with a Minecraft map. We discourage submission in these formats, for various reasons, but have supported some in the past.

MCEdit (Python)

Creating Python filters for MCEdit is the oldest method used for creating generators for GDPC. Currently, MCEdit is no longer in development and only supports Minecraft Java Edition 1.12. We have used the method in the past, but since it does not support the version 1.19.2 of Minecraft, we no longer accept submission in MCEdit. You can still see our instructions below, as they were used for many past submissions: MCEdit for more information.

MineRL (Python)

MineRL is a Python package designed for player emulation using reinforced learning. While a fascinating project, it is neither recommended nor supported for use in this competition due to the gargantuan amount of training data that would be required to train the agent to build a settlement.

Custom Mod (Java)

With a custom mod, you can do whatever you like! Although using the Forge mod loader is recommended, Fabric is a popular alternative.

Notable Examples

For brevity, 'Settlement Generator' and similar titles have been replaced with 'SG'.

Score	Year	Team	Generator	Comment
5.50	2019	Filip	Incremental bottom-up SG (MCEdit)	2019 Winner
5.37	2021	Tsukuba Team	IRMSG (GDPC)	2021 Winner
4.42	2020	David Mason	MyVeryKewlSG (MCEdit)	2020 Silver Medal
3.17	2018	Filip	Incremental bottom-up (MCEdit)	2018 Winner

Submitting

To submit your entry, go to the GDMC homepage, create an account or log in and follow the instructions!
Of course, we are always happy if you show off your submission on our Discord server in the 'share-your-progress' channel!