# GDPC
GDPC (Generative Design Python Client) is a Python framework for use in conjunction with the [GDMC-HTTP](https://github.com/Niels-NTG/gdmc_http_interface) mod for Minecraft Java edition.
It is designed for the [Generative Design in Minecraft Competition (GDMC)](https://gendesignmc.engineering.nyu.edu).
You need to be playing in a Minecraft world with the mod installed to use the framework.
The latest version of GDPC is compatible with GDMC-HTTP versions **>=1.0.0, <2.0.0** and Minecraft **1.20.2** (see [note](#note-on-supported-minecraft-version)).
## Quick example
```python
from gdpc import Editor, Block, 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"))
```
## What's the difference between GDMC, GDMC-HTTP and GDPC?
These abbreviations are all very similar, but refer to different things.
**GDMC:** Short for the [Generative Design in Minecraft Competition](https://gendesignmc.engineering.nyu.edu), a yearly competition for generative AI systems in Minecraft.
The challenge is to write an algorithm that creates a settlement while adapting to the pre-existing terrain. The competition also has a [Discord server](https://discord.gg/YwpPCRQWND).
**GDMC-HTTP:** A [Minecraft Forge mod](https://github.com/Niels-NTG/gdmc_http_interface) that provides a HTTP interface to edit the world.
It allows you to modify the world live, while you're playing in it. This makes it possible to iterate quickly on generator algorithms.
The mod is an official submission method for the competition.
**GDPC:** This repository (notice the "P"). A Python framework for interacting with the GDMC-HTTP interface.
It provides many high-level tools that make working with the interface much simpler.
## Installation
GDPC requires Python 3.7 or above. It is available on PyPI; to install, run:
```
python3 -m pip install gdpc
```
To update, run:
```
python3 -m pip install --upgrade gdpc
```
On Windows, you may need to replace `python3` with `py`.
If you would like to install the latest cutting-edge development version directly from GitHub, replace `gdpc` with\
`git+https://github.com/avdstaaij/gdpc`\
For more information on installing from GitHub (such as getting old versions), see the [pip documentation](https://pip.pypa.io/en/stable/topics/vcs-support/).
## Tutorials and examples
There are various tutorial scripts that will help to get you started:
| Tutorial | Description |
|------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------|
| [Hello block](https://github.com/avdstaaij/gdpc/blob/latest-release/examples/tutorials/1_hello_block.py) | Place and retrieve a single block in the world. |
| [Vectors](https://github.com/avdstaaij/gdpc/blob/latest-release/examples/tutorials/2_vectors.py) | Use vector math and some of GDPC's various vector utilities. |
| [Build area](https://github.com/avdstaaij/gdpc/blob/latest-release/examples/tutorials/3_build_area.py) | Get the specified build area and use it to place a block inside the bounds. |
| [World slice](https://github.com/avdstaaij/gdpc/blob/latest-release/examples/tutorials/4_world_slice.py) | Load and use a world slice for faster read access. |
| [Geometry](https://github.com/avdstaaij/gdpc/blob/latest-release/examples/tutorials/5_geometry.py) | Use the geometry module to place geometrical regions of blocks. |
| [Advanced blocks](https://github.com/avdstaaij/gdpc/blob/latest-release/examples/tutorials/6_advanced_blocks.py) | Place blocks with block states and block entity data, and use block palettes. |
| [Editor performance](https://github.com/avdstaaij/gdpc/blob/latest-release/examples/tutorials/7_editor_performance.py) | Use the Editor class's various optional performance features. |
| [Transformation](https://github.com/avdstaaij/gdpc/blob/latest-release/examples/tutorials/8_transformation.py) | Use GDPC's powerful transformation system. |
Some practical examples are also available, though they're slightly older and may not reflect the latest features:
| Example | Description |
|--------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------|
| [Visualize map](https://github.com/avdstaaij/gdpc/blob/latest-release/examples/visualize_map.py) | Displays a map of the Minecraft world using OpenCV. |
| [Emerald city](https://github.com/avdstaaij/gdpc/blob/latest-release/examples/emerald_city.py) | Demonstrates basic GDPC functionality by building a simple model of the Emerald City. |
**Note:** the links above always point to tutorials/examples for the latest release of GDPC. To view the examples for an older version, switch to the tag for that version (using the dropdown box at the top left of the file list, where it probably says "master"), and manually navigate to the examples.
## Note on supported Minecraft version
We list a specific compatible version of Minecraft, but most of GDPC actually supports a wide range of Minecraft versions.
In particular, basic block getting and setting should work with any Minecraft version for which there is a compatible version of GDMC-HTTP.
The parts of GDPC that may not be compatible with Minecraft versions other than the listed one are those that interact with "Minecraft data". These include:
- Rotation and flipping of individual blocks.
- Utility functions from the `minecraft_tools` and `editor_tools` modules that generate Minecraft data, such as `bookData` and `placeSign`.
- The `WorldSlice` class and associated functions like `Editor.loadWorldSlice()`.
We are working on fully supporting multiple versions of Minecraft simultaneously ([#99](https://github.com/avdstaaij/gdpc/issues/99)), but this probably won't be done soon.
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for information about how to contribute.
## Acknowledgements
GDPC was progressively developed with the help of various members of the GDMC community. Of special note are [Niki Gawlik](https://github.com/nikigawlik), who started both GDMC-HTTP and GDPC, and [Blinkenlights](https://github.com/flashing-blinkenlights), who previously maintained the project.
Raw data
{
"_id": null,
"home_page": "https://github.com/avdstaaij/gdpc",
"name": "gdpc",
"maintainer": "Arthur van der Staaij",
"docs_url": null,
"requires_python": "<4,>=3.7",
"maintainer_email": "arthurvanderstaaij@gmail.com",
"keywords": "GDMC, generative design, Minecraft, HTTP, development",
"author": "Arthur van der Staaij, Blinkenlights, Nils Gawlik",
"author_email": "arthurvanderstaaij@gmail.com, blinkenlights@pm.me, nilsgawlik@gmx.de",
"download_url": "https://files.pythonhosted.org/packages/99/eb/5770d1f76817a350049bfe766ebb1acc1122ad7e47bd21075c93e8b3fbbd/gdpc-7.1.0.tar.gz",
"platform": null,
"description": "# GDPC\n\nGDPC (Generative Design Python Client) is a Python framework for use in conjunction with the [GDMC-HTTP](https://github.com/Niels-NTG/gdmc_http_interface) mod for Minecraft Java edition.\nIt is designed for the [Generative Design in Minecraft Competition (GDMC)](https://gendesignmc.engineering.nyu.edu).\n\nYou need to be playing in a Minecraft world with the mod installed to use the framework.\n\nThe latest version of GDPC is compatible with GDMC-HTTP versions **>=1.0.0, <2.0.0** and Minecraft **1.20.2** (see [note](#note-on-supported-minecraft-version)).\n\n\n## Quick example\n\n```python\nfrom gdpc import Editor, Block, geometry\n\neditor = Editor(buffering=True)\n\n# Get a block\nblock = editor.getBlock((0,48,0))\n\n# Place a block\neditor.placeBlock((0,80,0), Block(\"stone\"))\n\n# Build a cube\ngeometry.placeCuboid(editor, (0,80,2), (2,82,4), Block(\"oak_planks\"))\n```\n\n## What's the difference between GDMC, GDMC-HTTP and GDPC?\n\nThese abbreviations are all very similar, but refer to different things.\n\n**GDMC:** Short for the [Generative Design in Minecraft Competition](https://gendesignmc.engineering.nyu.edu), a yearly competition for generative AI systems in Minecraft.\nThe challenge is to write an algorithm that creates a settlement while adapting to the pre-existing terrain. The competition also has a [Discord server](https://discord.gg/YwpPCRQWND).\n\n**GDMC-HTTP:** A [Minecraft Forge mod](https://github.com/Niels-NTG/gdmc_http_interface) that provides a HTTP interface to edit the world.\nIt allows you to modify the world live, while you're playing in it. This makes it possible to iterate quickly on generator algorithms.\nThe mod is an official submission method for the competition.\n\n**GDPC:** This repository (notice the \"P\"). A Python framework for interacting with the GDMC-HTTP interface.\nIt provides many high-level tools that make working with the interface much simpler.\n\n\n## Installation\n\nGDPC requires Python 3.7 or above. It is available on PyPI; to install, run:\n```\npython3 -m pip install gdpc\n```\nTo update, run:\n```\npython3 -m pip install --upgrade gdpc\n```\nOn Windows, you may need to replace `python3` with `py`.\n\nIf you would like to install the latest cutting-edge development version directly from GitHub, replace `gdpc` with\\\n`git+https://github.com/avdstaaij/gdpc`\\\nFor more information on installing from GitHub (such as getting old versions), see the [pip documentation](https://pip.pypa.io/en/stable/topics/vcs-support/).\n\n\n## Tutorials and examples\n\nThere are various tutorial scripts that will help to get you started:\n| Tutorial | Description |\n|------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------|\n| [Hello block](https://github.com/avdstaaij/gdpc/blob/latest-release/examples/tutorials/1_hello_block.py) | Place and retrieve a single block in the world. |\n| [Vectors](https://github.com/avdstaaij/gdpc/blob/latest-release/examples/tutorials/2_vectors.py) | Use vector math and some of GDPC's various vector utilities. |\n| [Build area](https://github.com/avdstaaij/gdpc/blob/latest-release/examples/tutorials/3_build_area.py) | Get the specified build area and use it to place a block inside the bounds. |\n| [World slice](https://github.com/avdstaaij/gdpc/blob/latest-release/examples/tutorials/4_world_slice.py) | Load and use a world slice for faster read access. |\n| [Geometry](https://github.com/avdstaaij/gdpc/blob/latest-release/examples/tutorials/5_geometry.py) | Use the geometry module to place geometrical regions of blocks. |\n| [Advanced blocks](https://github.com/avdstaaij/gdpc/blob/latest-release/examples/tutorials/6_advanced_blocks.py) | Place blocks with block states and block entity data, and use block palettes. |\n| [Editor performance](https://github.com/avdstaaij/gdpc/blob/latest-release/examples/tutorials/7_editor_performance.py) | Use the Editor class's various optional performance features. |\n| [Transformation](https://github.com/avdstaaij/gdpc/blob/latest-release/examples/tutorials/8_transformation.py) | Use GDPC's powerful transformation system. |\n\nSome practical examples are also available, though they're slightly older and may not reflect the latest features:\n\n| Example | Description |\n|--------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------|\n| [Visualize map](https://github.com/avdstaaij/gdpc/blob/latest-release/examples/visualize_map.py) | Displays a map of the Minecraft world using OpenCV. |\n| [Emerald city](https://github.com/avdstaaij/gdpc/blob/latest-release/examples/emerald_city.py) | Demonstrates basic GDPC functionality by building a simple model of the Emerald City. |\n\n**Note:** the links above always point to tutorials/examples for the latest release of GDPC. To view the examples for an older version, switch to the tag for that version (using the dropdown box at the top left of the file list, where it probably says \"master\"), and manually navigate to the examples.\n\n\n## Note on supported Minecraft version\n\nWe list a specific compatible version of Minecraft, but most of GDPC actually supports a wide range of Minecraft versions.\nIn particular, basic block getting and setting should work with any Minecraft version for which there is a compatible version of GDMC-HTTP.\nThe parts of GDPC that may not be compatible with Minecraft versions other than the listed one are those that interact with \"Minecraft data\". These include:\n- Rotation and flipping of individual blocks.\n- Utility functions from the `minecraft_tools` and `editor_tools` modules that generate Minecraft data, such as `bookData` and `placeSign`.\n- The `WorldSlice` class and associated functions like `Editor.loadWorldSlice()`.\n\nWe are working on fully supporting multiple versions of Minecraft simultaneously ([#99](https://github.com/avdstaaij/gdpc/issues/99)), but this probably won't be done soon.\n\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for information about how to contribute.\n\n\n## Acknowledgements\n\nGDPC was progressively developed with the help of various members of the GDMC community. Of special note are [Niki Gawlik](https://github.com/nikigawlik), who started both GDMC-HTTP and GDPC, and [Blinkenlights](https://github.com/flashing-blinkenlights), who previously maintained the project.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "The Generative Design Python Client (GDPC) is a Python-based interface for the Minecraft GDMC HTTP Interface mod.\\nIt was created for use in the Generative Design in Minecraft Competition (GDMC).",
"version": "7.1.0",
"project_urls": {
"Bug Reports": "https://github.com/avdstaaij/gdpc/issues",
"Changelog": "https://github.com/avdstaaij/gdpc/blob/master/CHANGELOG.md",
"Chat about it on Discord": "https://discord.gg/YwpPCRQWND",
"Homepage": "https://github.com/avdstaaij/gdpc",
"Official Competition Website": "https://gendesignmc.engineering.nyu.edu",
"Source": "https://github.com/avdstaaij/gdpc"
},
"split_keywords": [
"gdmc",
" generative design",
" minecraft",
" http",
" development"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9775bf904debbe7d689f040dcab99f60947117c7c2c5e59bcc0a4a12efc9ac59",
"md5": "9bd6807db13303388a975030b28f6aef",
"sha256": "48d109416be82bb9c0afaaa650090bb7ef5b673b02b12ae7eb83d52b08f1e207"
},
"downloads": -1,
"filename": "gdpc-7.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9bd6807db13303388a975030b28f6aef",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.7",
"size": 66083,
"upload_time": "2024-04-19T20:49:03",
"upload_time_iso_8601": "2024-04-19T20:49:03.014493Z",
"url": "https://files.pythonhosted.org/packages/97/75/bf904debbe7d689f040dcab99f60947117c7c2c5e59bcc0a4a12efc9ac59/gdpc-7.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "99eb5770d1f76817a350049bfe766ebb1acc1122ad7e47bd21075c93e8b3fbbd",
"md5": "fdb65c9785c3ba6a01b56aad3bd1cdf5",
"sha256": "0a09ae90899cac05de4bd6c6f6280ccdfe61b33a9eeee1ad49ce803451e8c1e3"
},
"downloads": -1,
"filename": "gdpc-7.1.0.tar.gz",
"has_sig": false,
"md5_digest": "fdb65c9785c3ba6a01b56aad3bd1cdf5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.7",
"size": 64963,
"upload_time": "2024-04-19T20:49:05",
"upload_time_iso_8601": "2024-04-19T20:49:05.075141Z",
"url": "https://files.pythonhosted.org/packages/99/eb/5770d1f76817a350049bfe766ebb1acc1122ad7e47bd21075c93e8b3fbbd/gdpc-7.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-19 20:49:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "avdstaaij",
"github_project": "gdpc",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "gdpc"
}
JSON
