StructurePlacerAPI

# Structure Placer API This simple API provides a simple way to spawn a structure in your world one-time, instead of putting it in the world generation. It could be useful for an item that creates a portal, or some other kind of structure. Or to create LuckyBlocks, who knows! ## Setup Include this library into your `build.gradle` as a dependency ```gradle repositories { maven { name = "Modrinth" url = "https://api.modrinth.com/maven" content { includeGroup "maven.modrinth" } } } dependencies { modImplementation "maven.modrinth:structureplacerapi:<version>" } ``` If you want you can `include` the API in your jar file by adding only the `include` string: ```gradle repositories { maven { name = "Modrinth" url = "https://api.modrinth.com/maven" content { includeGroup "maven.modrinth" } } } dependencies { modImplementation "maven.modrinth:structureplacerapi:<version>" include "maven.modrinth:structureplacerapi:<version>" } ``` It's less than 25 kb! (https://github.com/user-attachments/assets/66b45404-d8c6-497b-8cc8-ac08adfae0de)](https://nodecraft.com/r/emalightdev) ## How to use it ### How to create the structure? You have to create an NBT structure using minecraft's StructureBlocks, as demonstrated in this video: https://www.youtube.com/watch?v=umhuRXinD3o ### Where to put the file I got? You will need to place the *structure.nbt* file insde your mod's data folder, like this: `data/yourmodid/structures` ### Creating a new placer object In order to place the structure, you will need to create a placer object first, this is done simply by creating a new `StructurePlacerAPI` object. It has quite a few parameters to play with: ```java StructurePlacerAPI(ServerWorld world, Identifier templateName, BlockPos blockPos, BlockMirror mirror, BlockRotation rotation, boolean ignoreEntities, float integrity, BlockPos offset) ``` ### The parameters - The first parameter **`world`** is the wolrd in which we are going to place a structure. You could get it from an entity, or whatever. - The second parameter **`templateName`** is an Identifier made up by the MOD_ID of your mod and the structure's name - The third parameter **`blockPos`** is the block position where your structure is going to spawn. You can get it from an entity coordinates for example - The fourth, **`mirror`** is the first of the optional parameters. With this you can mirror your structure using the `BlockMirror` class. No need to create another object just type BlockMirror.#stuff - The fifth, **`rotation`** is like the previuous one, and you will be able to rotate your structure using the `BlockRotation` class. No need to create another object just type BlockMirror.#stuff - The **`ignoreEntities`** parameter if set to true won't spawn entities included inside the structure file. If set to false, it will instead spawn them - The **`integrity`** parameter is pretty intresting, since it is a float value between 0f and 1f which will deteremine how much the structure will be run-down. If set to a value below 1f some of the blocks will be removed upon generation - Finally, the **`offset`** parameter is another BlockPos that could be useful to reposition the structure under an entity's feet or something. ### Placing the structure You have just created a `StructurePlacerAPI placer = new StructurePlacerAPI(things up there)`, and to spawn it you will have to do this: ```java placer.loadStructure(); ``` Yeah ok it's not that difficult. You just have to run that tho, not the `.place` method directly, since the load will also check for the existance of said structure before spawning it. #### Restoring the old terrein after some time Starting from version `1.1.0` you can also use: ```java placer.loadAndRestoreStructure(int restore_ticks); ``` to supply an amount of ticks ( 1 seconds = 20 ticks ) after which the old terrain will be restored. **NOTICE**: It could lead to performance issues, especially if the structure is really big! (It needs to save every block inside the structure!) You can also add an animation for the blocks reappearing by using: ```java placer.loadAndRestoreStructureAnimated(int restore_ticks, int blocks_per_tick, boolean random); ``` - `blocks_per_ticks` is the amaount of blocks that will be replaced each tick, so if your structure is made by 200 blocks, and the blocks_per_ticks is set to 1, it will take 1 second to place 20 blocks, and 20 seconds to finish the terrain restoration. - `random` refers to order in which the blocks will be replaced. Setting to true, each time the regenerated block will be a random one, otherwise it will go from one angle of the structure to the other one. In my opinion, random = true is cooler. ### Selecting which blocks should be replaced (from 2.0.0 onwards) You can now specify if the structure that gets placed can replace bedrock and barriers or blocks with a certain tag, or if i