Code Monkey home page Code Monkey logo

niels-ntg / gdmc_http_interface Goto Github PK

View Code? Open in Web Editor NEW
15.0 3.0 3.0 849 KB

Minecraft Forge Mod that implements an HTTP interface for reading and writing blocks (and more) with an external program or script. Intended for use in the GDMC competition.

Home Page: https://gendesignmc.wikidot.com

License: MIT License

Java 99.14% Shell 0.86%
generative-art generative-design level-editor minecraft minecraft-forge minecraft-mod procedural-generation gdmc-competition gdmc architecture

gdmc_http_interface's Introduction

GDMC HTTP Interface Mod

logo

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

Jump to: Installation | Usage | Acknowledgements

Installation

Automated installation (recommended)

Custom Minecraft launchers such as Modrinth App or Prism Launcher make it easy to create separate instances of the game and can automatically install the mods you want for you, including any dependencies these mods may require such as modding frameworks.

The following instructions are for the Modrinth App, but other custom launchers will follow similar steps.

  1. Download and install the free and open source Modrinth App. When starting it for the first time, you will be prompted to authenticate with your Microsoft/Minecraft account.
  2. Click the ๐Ÿ”Ž "Browse" button in the sidebar and search in the mods category for "GDMC HTTP Interface".
  3. Clicking "Install" will install the latest version, including the necessary dependencies. Alternatively you can pick a specific version from the "Versions" section on the mod's page. In the installation modal you can choose to add the mod to an existing compatible instance or create a new one.
  4. After the app has finished preparing the instance, you can click "Play" to launch your modded version of Minecraft.

Manual installation

  1. You need to own a copy of Minecraft Java Edition and have it installed on your machine.
  2. Get the Forge Mod Installer and navigate to your version of Minecraft that is supported by this mod (1.20.2, 1.19.2 or 1.16.5) and click "Installer" under the "Download Recommended" section to download.
  3. Open the downloaded file to install this version of Forge.
  4. Download this mod's jar file from here and move it in the mod folder:
    • On Windows: %APPDATA%/.minecraft/mods.
    • On macOS: ~/Library/Application\ Support/Minecraft/mods.
    • On Linux desktop: ~/.minecraft/mods
  5. Open the Minecraft launcher, go to the "Installations" tab and click "Play" on the Forge installation in the list.

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 using 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.

gdmc_http_interface's People

Contributors

avdstaaij avatar cmoyates avatar niels-ntg avatar nikigawlik avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar

gdmc_http_interface's Issues

Specific `/item` command does not work as expected with `POST /commands`

To reproduce:

  1. Open a world and place a container block (e.g. a chest) at (0,100,0)
  2. Send the following request:
    POST localhost:9000/commands
    
    item replace block 0 100 0 container.13 with minecraft:apple 1
    

Expected result:
An apple is placed in slot 13 of the chest.

Observed result:
No apple is placed. Response:

[
    {
        "status": 0,
        "message": "Target position 0, 100, 0 is not a container"
    }
]

The exact same command does work as expected when issued in-game, so this seems to be a problem with GDMC-HTTP.

A more complicated version of this command (involving /execute) is used in one of the GDPC examples.

Tested with:

  • GDMC-HTTP 1.4.4
  • Forge 48.1.0
  • Minecraft 1.20.2

This behavior was not there in GDMC-HTTP 1.1.1 / Forge 43.2.0 / Minecraft 1.19.2, but I don't know which version introduced it.

Improve documentation

The wiki page in this repo does an oke job documenting the workings of the endpoints, but can use some clarification. Also the code itself needs some more documentation for future maintainers (including my future self).

  • Restructure endpoints documentation
  • Add comments to the code aimed at future maintainers

1.18/1.19 compatibility

This may include:

  • Updating to Forge for MC 1.18 (Java 16)
  • Checking handling of sub-zero Y-coordinates
  • Checking handling of biomes stacked in Y-axis (3D biomes)

Block entity information does get placed when placing structure with rotation and/or pivot

When placing a structure using the POST /structure endpoint with the parameters rotate and the pivot parameters, block entity information gets "misaligned" and does not get applied to to the proper place.

To replicate:

  1. Create a structure NBT file of at least 2x1x2 blocks in size with a sign with written text on it.
  2. Place structure using the POST /structure endpoint with pivot coordinate that does not have the same x and z coordinate as the sign and pass a rotate=1, rotate=2 or rotate=3.
  3. Structure will appear in the world, including the sign itself. The sign's text is missing.

Structure endpoints

To allow for easy use and exchange of structure files. May include:

  • Endpoints for getting and setting in-world structure files (in NBT format, as if saving with a structure block)
  • Endpoint for placing a structure file in an NBT format (as if loading a structure file in-world)
  • Endpoint for placing an in-world structure file at x y z with rotation, deterioration etc. (as if activating a structure block)

Overwriting a container drops its contents even with `spawnDrops=false`

Overwriting a container block (e.g. a chest) with a different block will cause its contents to be dropped, even when spawnDrops is set to the default value false. Based on the documentation of spawnDrops, this seems like unintended behavior.

Example request that produces this effect (sending two requests works too):

PUT localhost:9000/blocks

[
    {
        "x": 0,
        "y": 100,
        "z": 0,
        "id": "minecraft:chest",
        "data": "{Items: [{Slot: 13b, id: 'apple', Count: 1b}]}"
    },
    {
        "x": 0,
        "y": 100,
        "z": 0,
        "id": "minecraft:stone"
    }
]

Tested with:

  • GDMC-HTTP 1.4.4
  • Forge 48.1.0
  • Minecraft 1.20.2

This behavior was not there in GDMC-HTTP 1.1.1, but I don't know which version introduced it (and I didn't feel like doing a binary search :P). I would guess it's 1.2.3 (which touched overwriting blocks with NBT data) or 1.4.0 (which optimized everything).

Internal server error (500) when sending specific malformed sign SNBT data

Calling PUT /blocks with a sign block with SNBT data in which one of the elements of front_text.messages or back_text.messages is an empty string causes an internal server error. The sign will however still be placed.

Example request that produces the error:

PUT localhost:9000/blocks

[
    {
        "x": 0,
        "y": 100,
        "z": 0,
        "id": "minecraft:oak_sign",
        "data": "{front_text:{messages:['']}}"
    }
]

Response:

{
    "status": 500,
    "message": "java.lang.NullPointerException\n\tat [email protected]/com.google.common.base.Preconditions.checkNotNull(Preconditions.java:903)\n\tat [email protected]/com.google.common.collect.ImmutableList$Builder.add(ImmutableList.java:815)\n\tat MC-BOOTSTRAP/[email protected]/com.mojang.serialization.codecs.ListCodec.lambda$decode$1(ListCodec.java:49)\n\tat MC-BOOTSTRAP/[email protected]/com.mojang.serialization.DataResult$Instance.ap2(DataResult.java:318)\n\tat MC-BOOTSTRAP/[email protected]/com.mojang.serialization.DataResult.apply2stable(DataResult.java:179)\n\tat MC-BOOTSTRAP/[email protected]/com.mojang.serialization.codecs.ListCodec.lambda$decode$2(ListCodec.java:48)\n\tat java.base/java.lang.Iterable.forEach(Iterable.java:75)\n\tat MC-BOOTSTRAP/[email protected]/com.mojang.serialization.codecs.ListCodec.lambda$decode$4(ListCodec.java:45)\n\tat MC-BOOTSTRAP/[email protected]/com.mojang.serialization.DataResult.lambda$flatMap$11(DataResult.java:139)\n\tat MC-BOOTSTRAP/[email protected]/com.mojang.datafixers.util.Either$Left.map(Either.java:38)\n\tat MC-BOOTSTRAP/[email protected]/com.mojang.serialization.DataResult.flatMap(DataResult.java:137)\n\tat MC-BOOTSTRAP/[email protected]/com.mojang.serialization.codecs.ListCodec.decode(ListCodec.java:39)\n\tat MC-BOOTSTRAP/[email protected]/com.mojang.serialization.Decoder$1.decode(Decoder.java:49)\n\tat MC-BOOTSTRAP/[email protected]/com.mojang.serialization.Codec$2.decode(Codec.java:71)\n\tat MC-BOOTSTRAP/[email protected]/com.mojang.serialization.Decoder.parse(Decoder.java:18)\n\tat MC-BOOTSTRAP/[email protected]/com.mojang.serialization.codecs.FieldDecoder.decode(FieldDecoder.java:29)\n\tat MC-BOOTSTRAP/[email protected]/com.mojang.serialization.MapCodec$1.decode(MapCodec.java:34)\n\tat MC-BOOTSTRAP/[email protected]/com.mojang.serialization.codecs.RecordCodecBuilder$Instance$7.decode(RecordCodecBuilder.java:406)\n\tat MC-BOOTSTRAP/[email protected]/com.mojang.serialization.codecs.RecordCodecBuilder$2.decode(RecordCodecBuilder.java:107)\n\tat MC-BOOTSTRAP/[email protected]/com.mojang.serialization.MapDecoder.lambda$compressedDecode$1(MapDecoder.java:52)\n\tat MC-BOOTSTRAP/[email protected]/com.mojang.serialization.DataResult.lambda$flatMap$11(DataResult.java:139)\n\tat MC-BOOTSTRAP/[email protected]/com.mojang.datafixers.util.Either$Left.map(Either.java:38)\n\tat MC-BOOTSTRAP/[email protected]/com.mojang.serialization.DataResult.flatMap(DataResult.java:137)\n\tat MC-BOOTSTRAP/[email protected]/com.mojang.serialization.MapDecoder.compressedDecode(MapDecoder.java:52)\n\tat MC-BOOTSTRAP/[email protected]/com.mojang.serialization.MapCodec$MapCodecCodec.decode(MapCodec.java:91)\n\tat MC-BOOTSTRAP/[email protected]/com.mojang.serialization.Decoder.parse(Decoder.java:18)\n\tat TRANSFORMER/[email protected]/net.minecraft.world.level.block.entity.SignBlockEntity.m_142466_(SignBlockEntity.java:106)\n\tat TRANSFORMER/[email protected]/net.minecraftforge.common.extensions.IForgeBlockEntity.deserializeNBT(IForgeBlockEntity.java:35)\n\tat TRANSFORMER/[email protected]/nl.nielspoldervaart.gdmc.handlers.BlocksHandler.setBlockNBT(BlocksHandler.java:516)\n\tat TRANSFORMER/[email protected]/nl.nielspoldervaart.gdmc.handlers.BlocksHandler.lambda$putBlocksHandler$4(BlocksHandler.java:247)\n\tat java.base/java.util.stream.Streams$RangeIntSpliterator.forEachRemaining(Streams.java:104)\n\tat java.base/java.util.stream.IntPipeline$Head.forEach(IntPipeline.java:617)\n\tat TRANSFORMER/[email protected]/nl.nielspoldervaart.gdmc.handlers.BlocksHandler.putBlocksHandler(BlocksHandler.java:229)\n\tat TRANSFORMER/[email protected]/nl.nielspoldervaart.gdmc.handlers.BlocksHandler.internalHandle(BlocksHandler.java:118)\n\tat TRANSFORMER/[email protected]/nl.nielspoldervaart.gdmc.handlers.HandlerBase.handle(HandlerBase.java:61)\n\tat jdk.httpserver/com.sun.net.httpserver.Filter$Chain.doFilter(Filter.java:95)\n\tat jdk.httpserver/sun.net.httpserver.AuthFilter.doFilter(AuthFilter.java:82)\n\tat jdk.httpserver/com.sun.net.httpserver.Filter$Chain.doFilter(Filter.java:98)\n\tat jdk.httpserver/sun.net.httpserver.ServerImpl$Exchange$LinkHandler.handle(ServerImpl.java:851)\n\tat jdk.httpserver/com.sun.net.httpserver.Filter$Chain.doFilter(Filter.java:95)\n\tat jdk.httpserver/sun.net.httpserver.ServerImpl$Exchange.run(ServerImpl.java:818)\n\tat jdk.httpserver/sun.net.httpserver.ServerImpl$DefaultExecutor.execute(ServerImpl.java:201)\n\tat jdk.httpserver/sun.net.httpserver.ServerImpl$Dispatcher.handle(ServerImpl.java:561)\n\tat jdk.httpserver/sun.net.httpserver.ServerImpl$Dispatcher.run(ServerImpl.java:527)\n\tat java.base/java.lang.Thread.run(Thread.java:833)\n"
}

Tested with:

  • GDMC-HTTP 1.4.4
  • Forge 48.1.0
  • Minecraft 1.20.2

Timeout on big /get_blocks request

Could a timeout parameter be added to /get_blocks? It times out at around a minute, which doesn't work for big requests (n>1 million)

Player interaction endpoints

Certain interactions cannot currently be replicated through the interface. Some interactions can be replicated, but are comparatively tedious (requesting, interpreting, modifying player-accessible data).
These interactions may include:

  • (can be replicated) 'Right click' on block / entity (attack/mine)
  • (can be replicated) 'Middle-click' on block / entity (return block / entity)
  • (can be replicated) Empty-handed 'left click' on block / entity (remove item from armour stand / item frame)
  • 'Left-click' with item in air or on block / entity (use item) which may include:
    • Applying bonemeal to blocks
    • Forcing a block update
    • Tethering animals to fences
      Some interactions may require a player-like entity to take effect. Such actions are unlikely to have an effect on the generation and may be ignored.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.