Placing a structure template
From Sunrise's modding bookead8a1e
host.place_template puts a structure template into the level through the game's own placement, the one /place template and a structure block's Load take. Blocks, block-entity data and the template's own entities arrive as vanilla places them: states are mirrored then turned, a block that carries a block entity keeps its data, loot tables get the seed a placement gives them, and the template's entities are spawned where the turn puts them.
let placed = host.place_template(
&StructureTemplateSource::id("mymod:hut"),
[120, 64, -40], // at
[120, 64, -40], // pivot: what /place template uses
StructureRotation::None,
StructureMirror::None,
);
if let Err(reason) = placed {
// Nothing was placed; `reason` says why.
}Side: server. The call acts on the level the server is ticking, as edit_blocks and native_set_block do, and refuses a client.
Where the template comes from
StructureTemplateSource is one of two things:
StructureTemplateSource::id("mymod:hut"): a template of the game's, found asStructureTemplateManager.getfinds it, the waystructure_templatefinds it: the world's saved structures first, then the game's and the mods' own.StructureTemplateSource::nbt(bytes): vanilla structure NBT the mod carries, the bytes of astructures/<namespace>/<path>.nbtfile, gzipped as the game saves one or plain. The game's own loader reads it, within vanilla's limits for a template file (astructure/*.nbtread underNbtAccounter.unlimitedHeap, the byte cap as the only guard).
What the placement does
atis the template's corner,rotationandmirrorturn it, andpivotis the level position the turn and the mirroring go around./place templatepassesattwice, which turns the template about its own origin; that is the placement to copy when the mod has no opinion.- The palette is the one the placement picks at
at, as/place templatepicks it. - No processor runs, there is no
integrityand nostrict: everything in the palette places, and the neighbours of a replaced block are not told. Loot seeds come from the clock, as/place templateruns without aseedargument. - The chunks the turned template covers all have to be loaded. The call checks the box first and places nothing at all rather than half a structure.
structure_template is the read side of the same thing: it answers the transformed blocks for a preview, and place_template places them. A mod that wants to place blocks its own way, one at a time or through edit_blocks, keeps using structure_template; a mod that wants vanilla's block entities and entities uses this call.
Refusals
Err(String) says why nothing was placed, and nothing of the template reaches the level:
| Reason | What was wrong |
|---|---|
| not a template id | the id doesn't parse, or has a . or .. part |
| the game has no structure template | nothing of that id is the world's, the game's or the mods' |
| the structure NBT does not decompress / does not read | the bytes are not a gzipped or plain structure file, or they are past vanilla's limits |
| the template places nothing | it has no palette, or a side of its size is below 1 |
| a client of a server places nothing | the call ran on a client |
| chunk (x, z) of the template's box is not loaded | the footprint reaches a chunk the level has not loaded |
| the game placed nothing | the game has no structure resources, or the palette holds no block and there is no entity |
Nothing here panics on what a mod supplies: an unreadable file, a rotation this build does not know and an id with a .. in it all come back as a reason.
Placing a feature
level.place_feature(host, "minecraft:oak", pos) places a minecraft:worldgen/feature by id, as /place feature does: Feature.place with the level's random and chunk generator, after the command's check that the 3x3 chunks around pos are loaded. The blocks it sets reach players as any block change does. The answer is the feature's own report: Ok(false) means it reported failure, and blocks it set before that are kept, as the command keeps them.
match level.place_feature(host, "mymod:ender_tree", pos) {
Ok(true) => { /* placed */ }
Ok(false) => { /* it reported failure: a tree with no room */ }
Err(refusal) => { /* nothing changed; `refusal` names why */ }
}Side: server, on the level being ticked. Each refusal changes nothing: PlaceFeatureRefusal::Stale, Client, NotInPlace (another level than the one in place), NotLoaded (a chunk of the ring is not loaded, or pos is out of height) and UnknownFeature (the id has no namespace or names no feature). Each is checked before the feature runs.
Edit this page on GitHub · Spotted something wrong? Open an issue or ask on Discord.



