[SPIGOT-2903] Structure API Created: 08/Dec/16  Updated: 05/Oct/21  Resolved: 05/Oct/21

Status: Resolved
Project: Spigot
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: New Feature Priority: Minor
Reporter: Martin | MiniDigger Assignee: Unassigned
Resolution: Fixed Votes: 17
Labels: API, Bukkit, Structures


 Description   

Introduce a api that uses minecraft internal DefinedStructureManager (spigot name) or TemplateManager (mcp name) to be able to load and save structures.
structures are similar so schematics, they are nbt files that save blocks and entities, but it is the official format for doing so.
A api for bukkit/spigot would wrap the nms classes (DefinedStructureManager, DefinedStructure, EnumBlockMirror, EnumBlockRotation etc) and provide all necessary methods so load and save structures with all available options. (saveing with and without entities, the author and a name, loading with or without entities, rotated or mirrored and potentially others that I have missed)
I threw together a quick implementation of this here (https://www.spigotmc.org/threads/structure-util-nms-schematics.199250 and https://gist.github.com/MiniDigger/ce2b0b0446d53d3bb94f24f1c708c657)

if this feature will be accepted I am willing to write a api proposal and a PR.



 Comments   
Comment by Martin | MiniDigger [ 27/Jul/18 ]

Even if it will not be an replacement for schematics I still think that a structure API could be useful as it allows to do simple operations without world edit and allows interaction with what most make makers currently use.

Comment by Black Hole [ 27/Jul/18 ]

Structure blocks are of very limited use as they can only cover an area of 32*32*32.

A WorldEdit contributor is already working on implementing a draft version of the Sponge schematics format that fully covers 1.13 block features, but no entities.

Comment by Senmori [ 27/Jul/18 ]

The PR was accepted back in February. I'm sure if we knew what Mojang wanted to do then we would have done something about it.

Comment by R4zorax [ 27/Jul/18 ]

I'm not saying it is m8, just saying that a ticket about providing an API for structures isn't solved by adding the structureblock with block-data to the list of blocks.
Not unless a way to interact with that block in a meaningful way is also added, and I fail to see that in the commit above.

I have utter respect for the huge task, and the amount of dedication and skill all the Spigot contributor's employ.

But in my Humble opinion, this ticket still encompass a work to be done, and one that should be done.

Comment by Senmori [ 26/Jul/18 ]

Unfortunately it's much more than just slapping in a method to load and save a structure. Do we have a class that represents a structure? Do we fire events when loading them? Can server owners disable all custom structures from being loaded? As well, I'm fairly sure someone else is going to have to implement this because my focus is currently on datapacks.

Comment by R4zorax [ 26/Jul/18 ]

For my usage, an API that allows me to do what the structure block does on load and save, would be sufficient. Your concerns would be addressed exactly like what would happen if an OP player activated the block while the server did any of those things. Structures seems to be prepared to support crossing Minecraft versions, and would as such be the closest we have, to a "Mojang endorsed" schematic format.

Comment by Senmori [ 26/Jul/18 ]

I definitely think it'd be nice for some sort of API concerning all the new world features. Structures, Loot tables, etc all need an API that developers can use. However, there hasn't been any talk about how to do this in a way that is maintainable and allows server owners to control what gets loaded and what doesn't. As well, how much control do you give plugin authors to override default minecraft behavior. 

Currently there is talk of implementing plugins as datapacks. However, I'm finding it slow going because I have to crawl through the code. My point is, while this would be nice. I believe we'd have to have a discussion about how to implement it.

I know that recipes are purged when a world is loaded that doesn't contain the appropriate datapack. Does that happen with structures? What happens if a world is stopped in the middle of generating a structure? I don't say this to discourage the structure API. I say this so we can know what to handle when implementing it.

Comment by R4zorax [ 26/Jul/18 ]

I respectfully disagree - the above commit only exposes the structure-block, not an API for accessing the structures.

With 1.13 totally blowing away the MCEdit style support for schematics - an API for the Structures would be hugely beneficial, the alternative feels like a lot of plugins are going to use NMS code to obtain what is needed instead (or waiting for WorldEdit to decide how to do their future schematic-support). Exposing some sort of version of the DefinedStructureManager would enable a lot of plugins to do more, in a more performant way.

Comment by Senmori [ 12/Feb/18 ]

This can be closed now. c03d8909d98

Comment by Senmori [ 10/Apr/17 ]

I just submitted a PR that handles this somewhat. The PR deals with Structure Blocks, not the Structures themselves. If the PR is approved I can start work on an API to load/save structures outside of Structure Blocks, similar to how the Loot Tables PR handles it.

Generated at Sat Dec 13 15:23:12 UTC 2025 using Jira 10.3.13#10030013-sha1:56dd970ae30ebfeda3a697d25be1f6388b68a422.