# Structure Placer API
\nThis 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!
\n## Setup
\nInclude this library into your `build.gradle` as a dependency
\n“`gradle
\nrepositories {
\n maven {
\n name = “Modrinth”
\n url = “https:\/\/api.modrinth.com\/maven”
\n content {
\n includeGroup “maven.modrinth”
\n }
\n }
\n}<\/p>\n
dependencies { dependencies { <\/p>\n ## How to use it ### Where to put the file I got? ### Creating a new placer object ### Placing the structure #### Restoring the old terrein after some time You can also add an animation for the blocks reappearing by using: ### Selecting which blocks should be replaced (from 2.0.0 onwards) \/** Weather or not this structure should replace the barrier block *\/ \/** Sets weather or not this structure should only replace blocks with the provided tag, for example only replace air blocks *\/ \/** Allows to specify blocks which won’t be replaced if they have the provided tag*\/ ### Performing an action when a certain block is placed with the structure, or replaced by it (2.0.0+) For example, if you want a random fox to spawn when placing a structure containing berry bushes you can use: \/\/Example: The other thing you can do is execute something when a block that is *already in the world gets replaced* by the structure. \/\/Example: ### Example “`java ### Warning! “`java ## Support me  ## License An API made for fabric mod developers to spawn NBT structures <\/p>\n","protected":false},"featured_media":82640,"template":"","meta":{"_minecraft_slug":"structureplacerapi","_minecraft_project_id":"sSdng0L4","_minecraft_author":"Emafire003","_minecraft_license":"CC0-1.0","_minecraft_downloads":5467,"_minecraft_follows":11,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"structureplacerapi.zip","_minecraft_size_bytes":11560461,"_minecraft_version_count":89,"_minecraft_updated_at":"2026-05-17T01:27:30.975704Z","_minecraft_date_created":"2022-07-14T14:06:28.055979Z","_minecraft_date_modified":"2026-04-12T17:29:48.719936Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/structureplacerapi","_minecraft_icon_attachment_id":82640,"_minecraft_imported_at":"2026-06-09T00:03:14+00:00","_minecraft_import_hash":"083c0858777d43b96f402f3c3cc0fd87","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[97,104,873,158,98,92],"mod_loader":[99,106,160,100],"minecraft_version":[54,55,56,59,36,60,93,94,101,102,62,37,40,41,73,74,38,78,79,80,81,82,83,167,163],"class_list":["post-149610","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-fabric","mod_category-forge","mod_category-library","mod_category-neoforge","mod_category-quilt","mod_category-utility","mod_loader-fabric","mod_loader-forge","mod_loader-neoforge","mod_loader-quilt","minecraft_version-1-19","minecraft_version-1-19-1","minecraft_version-1-19-2","minecraft_version-1-20","minecraft_version-1-20-1","minecraft_version-1-20-2","minecraft_version-1-20-3","minecraft_version-1-20-4","minecraft_version-1-20-5","minecraft_version-1-20-6","minecraft_version-1-21","minecraft_version-1-21-1","minecraft_version-1-21-10","minecraft_version-1-21-11","minecraft_version-1-21-2","minecraft_version-1-21-3","minecraft_version-1-21-4","minecraft_version-1-21-5","minecraft_version-1-21-6","minecraft_version-1-21-7","minecraft_version-1-21-8","minecraft_version-1-21-9","minecraft_version-26-1","minecraft_version-26-1-1","minecraft_version-26-1-2"],"yoast_head":"\n
\n modImplementation “maven.modrinth:structureplacerapi:
\n}
\n“`
\nIf you want you can `include` the API in your jar file by adding only the `include` string:
\n“`gradle
\nrepositories {
\n maven {
\n name = “Modrinth”
\n url = “https:\/\/api.modrinth.com\/maven”
\n content {
\n includeGroup “maven.modrinth”
\n }
\n }
\n}<\/p>\n
\n modImplementation “maven.modrinth:structureplacerapi:
\n include “maven.modrinth:structureplacerapi:
\n}
\n“`
\nIt’s less than 25 kb!<\/p>\n
\n### How to create the structure?
\nYou have to create an NBT structure using minecraft’s StructureBlocks, as demonstrated in this video: https:\/\/www.youtube.com\/watch?v=umhuRXinD3o<\/p>\n
\nYou will need to place the *structure.nbt* file insde your mod’s data folder, like this: `data\/yourmodid\/structures`<\/p>\n
\nIn 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:
\n“`java
\nStructurePlacerAPI(ServerWorld world, Identifier templateName, BlockPos blockPos, BlockMirror mirror, BlockRotation rotation, boolean ignoreEntities, float integrity, BlockPos offset)
\n“`
\n### The parameters
\n– 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.
\n– The second parameter **`templateName`** is an Identifier made up by the MOD_ID of your mod and the structure’s name
\n– 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
\n– 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
\n– 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
\n– 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
\n– 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
\n– Finally, the **`offset`** parameter is another BlockPos that could be useful to reposition the structure under an entity’s feet or something.<\/p>\n
\nYou have just created a `StructurePlacerAPI placer = new StructurePlacerAPI(things up there)`, and to spawn it you will have to do this:
\n“`java
\nplacer.loadStructure();
\n“`
\nYeah 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.<\/p>\n
\nStarting from version `1.1.0` you can also use:
\n“`java
\nplacer.loadAndRestoreStructure(int restore_ticks);
\n“`
\nto supply an amount of ticks ( 1 seconds = 20 ticks ) after which the old terrain will be restored.
\n**NOTICE**: It could lead to performance issues, especially if the structure is really big! (It needs to save every block inside the structure!)<\/p>\n
\n“`java
\nplacer.loadAndRestoreStructureAnimated(int restore_ticks, int blocks_per_tick, boolean random);
\n“`
\n– `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.
\n– `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.<\/p>\n
\nYou can now specify if the structure that gets placed can replace bedrock and barriers or blocks with a certain tag, or if it can ONLY replace blocks with a certain tag.
\nAfter you have created you StructurePlacerAPI placer object, ou can use these methods:
\n“`java
\n\/** Sets weather or not this structure should replace the bedrock *\/
\nplacer.setReplaceBedrock(boolean replaceBedrock)<\/p>\n
\nplacer.setReplaceBarrier(boolean replaceBarrier)<\/p>\n
\nplacer.setOnlyReplaceTaggedBlocks(boolean onlyReplaceTaggedBlocks, TagKey
\nplacer.setPreventReplacementOfTaggedBlocks(boolean preventReplacementOfTaggedBlocks, TagKey
\n“`<\/p>\n
\nNow you have the option to execute a function when a block inside a structure gets placed in the world or when a block
\nis replaced while placing the structure. <\/p>\n
\n“`java
\nplacer.actionOnBlocksPlacedByStructure(ActionOnBlockFind action, TagKey
\nplacer.actionOnBlocksPlacedByStructure((info, world) -> {world.spawnEntity(EntityType.FoxEntity, …)}, BlockTags.BUSHES);
\n“`
\nThe action is a lambda function that provides you with the `StructureBlockInfo` and `ServerWorldAccess` (or `ServerLevelAccess` or whatever it is with mojmaps). You have to specify a tag for the kind of block you want to replace. If it’s only a single block type create a Tag for that block.<\/p>\n
\nLike spawning snow particles when an ice block is replaced:
\n“`java
\nplacer.actionOnBlocksReplacedByStructure(ActionOnBlockFind action, TagKey
\nplacer.actionOnBlocksReplacedByStructure((info, world) -> {world.spawnParticles(ParticleType.SNOW, …)}, BlockTags.ICE);
\n“`<\/p>\n
\nAn example of this could be the one you find insde the LightWithin mod(whihc btw, you should check out):
\n“`java
\nStructurePlacer placer = new StructurePlacer((ServerWorld) caster.getWorld(), new Identifier(MOD_ID, “frost_light”), caster.getBlockPos(), BlockMirror.NONE, BlockRotation.CLOCKWISE_90, true, 1.0f, new BlockPos(-4, -3, -3));
\nplacer.loadStructure();
\n“`
\nTo have a permanent structure<\/p>\n
\nStructurePlacer placer = new StructurePlacer((ServerWorld) caster.getWorld(), new Identifier(MOD_ID, “frost_light”), caster.getBlockPos(), BlockMirror.NONE, BlockRotation.CLOCKWISE_90, true, 1.0f, new BlockPos(-4, -3, -3));
\nplacer.loadAndRestoreStructureAnimated(200, 2, true);
\n“`
\nTo make the old terrain regenerate by replacing two blocks per tick, in a random order. <\/p>\n
\nIMPORTANT! MAKE SURE YOU ARE ON THE SERVER THREAD!<\/p>\n
\nif(!world.isClient){
\n\/\/run stuff
\n}
\n“`<\/p>\n
\nIf you would like to offer me a coffee, here you go.<\/p>\n
\nAlternativly, you can support me by supporting you using a 25% off on a server for you and your friend using this code down here<\/p>\n
\nThis API is available under the CC0 license. Feel free to learn from it and incorporate it in<\/p>\n","protected":false},"excerpt":{"rendered":"