{"id":15175137,"url":"https://github.com/shynixn/structureblocklib","last_synced_at":"2026-02-03T03:10:23.423Z","repository":{"id":10787064,"uuid":"66574317","full_name":"Shynixn/StructureBlockLib","owner":"Shynixn","description":"StructureBlockLib is a bukkit implementation for handling structures on spigot server.","archived":true,"fork":false,"pushed_at":"2024-05-14T19:13:47.000Z","size":2742,"stargazers_count":59,"open_issues_count":0,"forks_count":5,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-09-27T12:03:32.444Z","etag":null,"topics":["api","bukkit","hacktoberfest","spigot","structure"],"latest_commit_sha":null,"homepage":"https://shynixn.github.io/StructureBlockLib/apidocs/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Shynixn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2016-08-25T16:19:47.000Z","updated_at":"2024-07-24T14:06:56.000Z","dependencies_parsed_at":"2023-12-15T16:50:23.008Z","dependency_job_id":null,"html_url":"https://github.com/Shynixn/StructureBlockLib","commit_stats":null,"previous_names":[],"tags_count":30,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shynixn%2FStructureBlockLib","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shynixn%2FStructureBlockLib/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shynixn%2FStructureBlockLib/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shynixn%2FStructureBlockLib/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Shynixn","download_url":"https://codeload.github.com/Shynixn/StructureBlockLib/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219875424,"owners_count":16554677,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","bukkit","hacktoberfest","spigot","structure"],"created_at":"2024-09-27T12:03:39.613Z","updated_at":"2025-10-01T12:31:01.684Z","avatar_url":"https://github.com/Shynixn.png","language":"Java","readme":"\u003e [!IMPORTANT]  \n\u003e **Final Notes:**\n\u003e The NBT format has been reworked in Minecraft 1.20.5 and this library will not updated any further because it was not intended for that.\n\u003e The final version support range is Minecraft 1.9.0 - 1.20.4 and can still be used for that. The binaries stay available in [Maven Central](https://central.sonatype.com/artifact/com.github.shynixn.structureblocklib/structureblocklib-api).\n\u003e Thank you for supporting StructureBlockLib all those years ♥️ .\n\n# StructureBlockLib  [![Build Status](https://maven-badges.herokuapp.com/maven-central/com.github.shynixn.structureblocklib/structureblocklib-bukkit-api/badge.svg?style=flat-square)](https://maven-badges.herokuapp.com/maven-central/com.github.shynixn.structureblocklib/structureblocklib-bukkit-api) [![GitHub license](http://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](https://raw.githubusercontent.com/Shynixn/StructureBlockLib/master/LICENSE)\n\n| branch        | status        | version | download |\n| ------------- | ------------- | -------- | --------| \n| master        | [![Build Status](https://github.com/Shynixn/StructureBlockLib/workflows/CI/badge.svg?branch=master)](https://github.com/Shynixn/StructureBlockLib/actions) |![GitHub license](https://img.shields.io/nexus/r/https/oss.sonatype.org/com.github.shynixn.structureblocklib/structureblocklib-bukkit-plugin.svg?style=flat-square)  |[Download latest release](https://github.com/Shynixn/StructureBlockLib/releases)|\n| development  | [![Build Status](https://github.com/Shynixn/StructureBlockLib/workflows/CI/badge.svg?branch=development)](https://github.com/Shynixn/StructureBlockLib/actions)|![GitHub license](https://img.shields.io/nexus/s/https/oss.sonatype.org/com.github.shynixn.structureblocklib/structureblocklib-bukkit-plugin.svg?style=flat-square) |  [Download snapshots](https://oss.sonatype.org/content/repositories/snapshots/com/github/shynixn/structureblocklib/structureblocklib-bukkit-plugin/) |\n\nJavaDocs: https://shynixn.github.io/StructureBlockLib/apidocs/\n\n## Description\n\nStructureBlockLib is a bukkit API and implementation for handling structures on spigot server.\n\n## Features\n\n* Bukkit API for the StructureBlock.\n* API to save or load structures without an actual structure block. \n* Asynchronous implementation and API.\n* Fluent API.\n* Version support 1.9.R1 - 1.20.R3\n* Java support 8 - Latest\n\n## Installation\n\n1. Include the dependency to StructureBlockLib\n\n**Maven**\n```xml\n\u003cdependency\u003e\n     \u003cgroupId\u003ecom.github.shynixn.structureblocklib\u003c/groupId\u003e\n     \u003cartifactId\u003estructureblocklib-bukkit-api\u003c/artifactId\u003e\n     \u003cversion\u003e2.13.0\u003c/version\u003e\n     \u003cscope\u003eprovided\u003c/scope\u003e\n\u003c/dependency\u003e\n```\n**Gradle**\n\n```xml\ndependencies {\n    compileOnly(\"com.github.shynixn.structureblocklib:structureblocklib-bukkit-api:2.13.0\")\n}\n```\n\n**Jar File**\n\n[StructureBlockLibBukkitApi.jar](http://repository.sonatype.org/service/local/artifact/maven/redirect?r=central-proxy\u0026g=com.github.shynixn.structureblocklib\u0026a=structureblocklib-bukkit-api\u0026v=LATEST)\n\n## Code Examples\n\n* If you need more information, check out the sample implementation of a plugin using StructureBlockLib in the `structureblocklib-bukkit-sample` folder.\n* All calls are not blocking and complete in the future.\n\n##### Store a structure on your server to a target file \n```java\n// Minimal configuration\nPlugin plugin;\nPath path = plugin.getDataFolder().toPath().resolve(\"mystructure.nbt\");\n\nStructureBlockLibApi.INSTANCE\n    .saveStructure(plugin)\n    .at(new Location(Bukkit.getWorld(\"world\"), 100, 100, 100))\n    .sizeX(32)\n    .sizeY(5)\n    .sizeZ(32)\n    .saveToPath(path)\n    .onException(e -\u003e plugin.getLogger().log(Level.SEVERE, \"Failed to save structure.\", e))\n    .onResult(e -\u003e plugin.getLogger().log(Level.INFO, ChatColor.GREEN + \"Saved structure 'mystructure'.\"));\n```\n```java\n// Maximal configuration\nPlugin plugin;\nPath path = plugin.getDataFolder().toPath().resolve(\"mystructure.nbt\");\n\nStructureBlockLibApi.INSTANCE\n    .saveStructure(plugin)\n    .at(new Location(Bukkit.getWorld(\"world\"), 100, 100, 100))\n    .sizeX(32)\n    .sizeY(5)\n    .sizeZ(32)\n    .includeEntities(false) // See JavaDoc for default values.\n    .restriction(StructureRestriction.UNLIMITED)  // See JavaDoc for default values.\n    .author(\"me\")\n    .saveToPath(path)\n    .onProgress(c -\u003e plugin.getLogger().log(Level.INFO, String.format(\"Percentage %.2f\", c)))\n    .onException(e -\u003e plugin.getLogger().log(Level.SEVERE, \"Failed to save structure.\", e))\n    .onResult(e -\u003e plugin.getLogger().log(Level.INFO, ChatColor.GREEN + \"Saved structure 'mystructure'.\"));\n```\n\n##### Store a structure on your server to the default structure storage, so it can be used by ordinary StructureBlocks\n```java\n// Minimal configuration\nPlugin plugin;\n\nStructureBlockLibApi.INSTANCE\n    .saveStructure(plugin)\n    .at(new Location(Bukkit.getWorld(\"world\"), 100, 100, 100))\n    .sizeX(32)\n    .sizeY(5)\n    .sizeZ(32)\n    .saveToWorld(\"world\", \"me\", \"mystructure\")\n    .onException(e -\u003e plugin.getLogger().log(Level.SEVERE, \"Failed to save structure.\", e))\n    .onResult(e -\u003e plugin.getLogger().log(Level.INFO, ChatColor.GREEN + \"Saved structure 'mystructure'.\"));\n```\n\n##### Load a structure on your server from a source file \n```java\n// Minimal configuration\nPlugin plugin;\nPath path = plugin.getDataFolder().toPath().resolve(\"mystructure.nbt\");\n\nStructureBlockLibApi.INSTANCE\n    .loadStructure(plugin)\n    .at(new Location(Bukkit.getWorld(\"world\"), 100, 100, 100))\n    .loadFromPath(path)\n    .onException(e -\u003e plugin.getLogger().log(Level.SEVERE, \"Failed to load structure.\", e))\n    .onResult(e -\u003e plugin.getLogger().log(Level.INFO, ChatColor.GREEN + \"Loaded structure 'mystructure'.\"));\n```\n\n```java\n// Maximal configuration\nPlugin plugin;\nPath path = plugin.getDataFolder().toPath().resolve(\"mystructure.nbt\");\n\nStructureBlockLibApi.INSTANCE\n    .loadStructure(plugin)\n    .at(new Location(Bukkit.getWorld(\"world\"), 100, 100, 100))\n    .includeEntities(true) // See JavaDoc for default values.\n    .seed(50L) // See JavaDoc for default values.\n    .integrity(0.2F) // See JavaDoc for default values.\n    .mirror(StructureMirror.FRONT_BACK) // See JavaDoc for default values.\n    .rotation(StructureRotation.ROTATION_90) // See JavaDoc for default values.\n    .loadFromPath(path)\n    .onException(e -\u003e plugin.getLogger().log(Level.SEVERE, \"Failed to load structure.\", e))\n    .onResult(e -\u003e plugin.getLogger().log(Level.INFO, ChatColor.GREEN + \"Loaded structure 'mystructure'.\"));\n```\n       \n##### Load a structure on your server from the default structure storage, so you can use structures from ordinary StructureBlocks\n\n```java\n// Minimal configuration\nPlugin plugin;\n\nStructureBlockLibApi.INSTANCE\n    .loadStructure(plugin)\n    .at(new Location(Bukkit.getWorld(\"world\"), 100, 100, 100))\n    .loadFromWorld(\"world\", \"me\", \"mystructure\")\n    .onException(e -\u003e plugin.getLogger().log(Level.SEVERE, \"Failed to load structure.\", e))\n    .onResult(e -\u003e plugin.getLogger().log(Level.INFO, ChatColor.GREEN + \"Loaded structure 'mystructure'.\"));\n```\n\n##### Load a structure on your server and manipulate the blocks\n\n```java\n// Minimal configuration\nPlugin plugin;\n\nStructureBlockLibApi.INSTANCE\n    .loadStructure(plugin)\n    .at(new Location(Bukkit.getWorld(\"world\"), 100, 100, 100))\n    .onProcessBlock(part -\u003e {\n      // onProcessBlock is called for every block before it is placed.  \n      if (part.getSourceBlock().getBlockData().getMaterial() == Material.AIR) {\n        // When the block in the structure file equals AIR, we do not want to place it -\u003e return false.  \n        return false;\n      }\n  \n      // When the block in the structure file is something else, we do want to place it -\u003e return true.\n      return true;\n    })\n    .loadFromWorld(\"world\", \"me\", \"mystructure\")\n    .onException(e -\u003e plugin.getLogger().log(Level.SEVERE, \"Failed to load structure.\", e))\n    .onResult(e -\u003e plugin.getLogger().log(Level.INFO, ChatColor.GREEN + \"Loaded structure 'mystructure'.\"));\n```\n\n##### Load a structure on your server and manipulate the entities\n\n```java\n// Minimal configuration\nPlugin plugin;\n\nStructureBlockLibApi.INSTANCE\n    .loadStructure(plugin)\n    .at(new Location(Bukkit.getWorld(\"world\"), 100, 100, 100))\n    .includeEntities(true)\n    .onProcessEntity(part -\u003e {\n      // onProcessEntity is called for every entity before it is placed.\n      if (part.getEntity().isPresent()) {\n        if (part.getEntity().get().getType() == EntityType.COW) {\n          // When the entity in the structure file equals COW, we do not want to place it -\u003e return false.\n          return false;\n        }\n      }\n  \n      // When the entity in the structure file is something else, we do want to place it -\u003e return true.\n      return true;\n    })\n    .loadFromWorld(\"world\", \"me\", \"mystructure\")\n    .onException(e -\u003e plugin.getLogger().log(Level.SEVERE, \"Failed to load structure.\", e))\n    .onResult(e -\u003e plugin.getLogger().log(Level.INFO, ChatColor.GREEN + \"Loaded structure 'mystructure'.\"));\n```\n\n##### Load entities in memory and iterate them\n\n```java\nList\u003cStructureEntity\u003cEntity, Location\u003e\u003e entities = new ArrayList\u003c\u003e();\nStructureBlockLibApi.INSTANCE\n  .loadStructure(plugin)\n  .at(player.getLocation()) // We do need an existing world.\n  .includeEntities(false) // Do not place entities.\n  .includeBlocks(false)  // Do not place blocks.\n  .onProcessEntity(entity -\u003e {\n      entities.add(entity);\n      return false;\n  })\n  .loadFromWorld(\"world\", \"me\", \"mystructure\")\n  .onException(c -\u003e c.printStackTrace())\n  .onResult(e -\u003e {\n      for (StructureEntity\u003cEntity, Location\u003e structureEntity : entities) {\n          // Do something with the entities\n          structureEntity.spawnEntity(player.getLocation().add(-3, 0, 0));\n      }\n  });\n```\n\n##### Load blocks in memory and iterate them\n\n```java\nList\u003cStructurePlacePart\u003cBlock, World\u003e\u003e blocks = new ArrayList\u003c\u003e();\nStructureBlockLibApi.INSTANCE\n  .loadStructure(plugin)\n  .at(player.getLocation()) // We do need an existing world.\n  .includeEntities(false) // Do not place entities.\n  .includeBlocks(false)  // Do not place blocks.\n  .onProcessBlock(part -\u003e {\n    blocks.add(part);\n    return false;\n  })\n  .loadFromWorld(\"world\", \"me\", \"mystructure\")\n  .onException(c -\u003e c.printStackTrace())\n  .onResult(e -\u003e {\n    for (StructurePlacePart\u003cBlock, World\u003e structureBlock : blocks) {\n      // Do something with the blocks\n      System.out.println(structureBlock.getSourceBlock().getType());\n    }\n  });\n```\n\n##### Modify and use an existing structure block\n```java\nPlugin plugin;\nLocation location = new Location(Bukkit.getWorld(\"world\"), 100, 100, 100);\nlocation.getBlock().setType(Material.STRUCTURE_BLOCK);\n\nStructureBlockSave structureBlock = StructureBlockLibApi.INSTANCE.getStructureBlockAt(location, plugin);\nstructureBlock.setStructureMode(StructureMode.SAVE);\nstructureBlock.setSaveName(\"sample_save\");\nstructureBlock.setSizeX(31);\nstructureBlock.setSizeY(15);\nstructureBlock.setSizeZ(12);\nstructureBlock.update();\n```\n\n## Shipping and Running\n\n* In order to use the StructureBlockLib Api on your server, you need to put the implementation of the Api on your server.\n\n### For version \u003e= 1.17\n\n* Add the dependencies to the libraries tag\n\n**plugin.yml**\n```yaml\nlibraries:\n  - com.github.shynixn.structureblocklib:structureblocklib-bukkit-api:2.13.0\n  - com.github.shynixn.structureblocklib:structureblocklib-bukkit-core:2.13.0\n```\n\n### For version \u003c 1.17\n\n#### Installing the StructureBlockLib.jar\n\n* Just go to the [releases page](https://github.com/Shynixn/StructureBlockLib/releases) and download the plugin.\n \n#### Shipping the implementation with your plugin\n\n* Include both dependencies and shade them in your plugin jar file. If you do not know how to do that, you should\ngo with the option above instead. There are several tutorials on spigotmc.org. \n\n**Maven**\n```xml\n\u003cdependency\u003e\n     \u003cgroupId\u003ecom.github.shynixn.structureblocklib\u003c/groupId\u003e\n     \u003cartifactId\u003estructureblocklib-bukkit-api\u003c/artifactId\u003e\n     \u003cversion\u003e2.13.0\u003c/version\u003e\n     \u003cscope\u003ecompile\u003c/scope\u003e\n\u003c/dependency\u003e\n\u003cdependency\u003e\n     \u003cgroupId\u003ecom.github.shynixn.structureblocklib\u003c/groupId\u003e\n     \u003cartifactId\u003estructureblocklib-bukkit-core\u003c/artifactId\u003e\n     \u003cversion\u003e2.13.0\u003c/version\u003e\n     \u003cscope\u003ecompile\u003c/scope\u003e\n\u003c/dependency\u003e\n```\n**Gradle**\n\n```xml\ndependencies {\n    implementation(\"com.github.shynixn.structureblocklib:structureblocklib-bukkit-api:2.13.0\")\n    implementation(\"com.github.shynixn.structureblocklib:structureblocklib-bukkit-core:2.13.0\")\n}\n```\n \n## Contributing\n\n### Setting up development environment\n\n* Install Java 17 or higher\n* Fork the StructureBlockLib project on github and clone it to your local environment.\n* StructureBlockLib requires spigot server implementations from 1.9.4 to 1.20.2 to be correctly installed in your local Maven cache. \n  As this requires multiple java version to build different versions, a Dockerfile is provided to build these dependencies in a docker container\n  and then copy it to your local Maven cache.\n  \nNote: If using Windows, execute the commands using Git Bash.\n````sh\nmkdir -p ~/.m2/repository/org/spigotmc/\ndocker build --target dependencies-jdk8 -t structureblocklib-dependencies-jdk8 .\ndocker create --name structureblocklib-dependencies-jdk8 structureblocklib-dependencies-jdk8 bash\ndocker cp structureblocklib-dependencies-jdk8:/root/.m2/repository/org/spigotmc ~/.m2/repository/org/\ndocker rm -f structureblocklib-dependencies-jdk8\ndocker build --target dependencies-jdk17 -t structureblocklib-dependencies-jdk17 .\ndocker create --name structureblocklib-dependencies-jdk17 structureblocklib-dependencies-jdk17 bash\ndocker cp structureblocklib-dependencies-jdk17:/root/.m2/repository/org/spigotmc ~/.m2/repository/org/\ndocker rm -f structureblocklib-dependencies-jdk17\n````\n\n* Open the project with an IDE, gradle sync for dependencies.\n\n### Testing\n\n#### Option 1\n\n* Setup your own minecraft server\n* Change ``// val destinationDir = File(\"C:/temp/plugins\")`` to your plugins folder in the ``structureblocklib-bukkit-sample/build.gradle.kts`` file.\n* Run the ``pluginJar`` task to generate a plugin.jar file.\n* Run your minecraft server\n\n#### Option 2 :whale: \n\n* Run the provided docker file. \n* The source code is copied to a new docker container and built to a plugin.\n* This plugin is installed on a new minecraft server which is accessible on the host machine on the default port on ``localhost``.\n\n````sh\ndocker build -t structureblocklib .\ndocker run --name=structureblocklib -p 25565:25565 -p 5005:5005 structureblocklib\n````\n\n## Licence\n\nThe source code is licensed under the MIT license. \n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshynixn%2Fstructureblocklib","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshynixn%2Fstructureblocklib","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshynixn%2Fstructureblocklib/lists"}