scene import

---

navigation: title: Import Structure parent: index.md position: 162 categories:

• scenes

---

Import Structure

<ImportStructure> and <ImportStructureLib> expand external structure data into a <GameScene>.

StructureLib Preview

<ImportStructureLib controller="modid:name" /> loads the multiblock structure registered by a StructureLib controller:

Hover blocks in the StructureLib preview to inspect the extra structure text. Hold Shift to expand replacement candidates. If the imported structure exposes hatch or channel metadata, the preview also adds the hatch highlight button and the bottom sliders automatically.

Defaults can be written as child tags. Reset view restores these values after interactive slider changes, and GregTech controllers use the survival preview path so hatch-only positions are filled correctly:

facing, rotation, and flip use the same orientation vocabulary as StructureLib export. If a controller rejects the requested combination, GuideNH automatically falls back to the first valid alignment. GregTech controller previews also default to the opposite horizontal facing from the older preview orientation, rotating the visible front by 180 degrees around the Y axis.

Add formed={false} when a controller should remain unformed in preview even if the surrounding structure is otherwise valid. GregTech controllers are the main built-in example today.

Default unformed controller preview:

<GameScene width="384" height="256" zoom={4} interactive={true}>
  <ImportStructureLib controller="gregtech:gt.blockmachines:2741" />
</GameScene>

Explicit formed controller preview:

<GameScene width="384" height="256" zoom={4} interactive={true}>
  <ImportStructureLib controller="gregtech:gt.blockmachines:2741" formed={true} />
</GameScene>

StructureLib import with orientation and offsets:

<GameScene width="384" height="256" zoom={4} interactive={true}>
  <ImportStructureLib
    name="main"
    controller="gregtech:gt.blockmachines:2741"
    facing="north"
    rotation="clockwise_180"
    flip="none"
    offsetX="2"
    offsetY="1"
    offsetZ="-3"
  />
</GameScene>

Defaults can also be written as child tags. Reset view restores these values after interactive slider changes, and GregTech controllers use the survival preview path so hatch-only positions are filled correctly:

<GameScene width="384" height="256" zoom={4} interactive={true}>
  <ImportStructureLib controller="gregtech:gt.blockmachines:1000">
    <Tier value="4" />
    <Channel name="voltage" value="4" />
    <Facing value="north" />
    <GregTechActiveController />
    <GregTechPlaceHatches />
  </ImportStructureLib>
</GameScene>

Named StructureLib imports can drive conditional annotations and sounds:

This marker follows the selected `main` StructureLib state.

ImportStructure + RemoveBlocks

<ImportStructure src="..." /> expands an external SNBT/NBT file. <RemoveBlocks id="..." /> strips blocks by id after import:

ReplaceBlock

<ReplaceBlock from="..." to="..." /> replaces matching already-placed blocks with a new block. The search is global when no bounds are specified, or restricted to a box when any of x/y/z/dx/dy/dz are provided:

Add from_nbt to narrow the match to blocks whose TileEntity NBT contains specific keys, and to_nbt to supply tile entity data for the replacement block. If the replacement result includes a controller, formed={false} keeps that controller unformed.

PlaceBlock

<PlaceBlock id="..." /> fills an axis-aligned box unconditionally, overwriting whatever was already there. Use dx/dy/dz to fill multi-block regions:

If the filled region includes controllers, set formed={false} to keep every affected controller unformed in preview.

<GameScene width="384" height="256" zoom={4} interactive={true}>
  <PlaceBlock id="gregtech:gt.blockmachines:15411" dx="3" dz="3" formed={false} />
</GameScene>

SNBT File Format

<ImportStructure src="..." /> accepts SNBT (1.7.10's stock JsonToNBT: pos:[0,1,2] is recognized as IntArray automatically; the modern [I; ...] typed-array prefix is not supported and must be omitted). Gzipped or uncompressed binary NBT also work. Schema is {size, palette, blocks}; each block entry may carry meta and an optional nbt compound (the latter must include the vanilla TileEntity id field, e.g. "Chest"). Optional x/y/z attributes translate the whole structure.

This example references assets/example_structure.snbt: a 5×3×5 cobblestone platform with a glowstone center, four corner stairs in different facings (meta=2/3), two stone slabs (meta=0 bottom, meta=8 top), two upward-facing torches (meta=5), and a chest pre-filled with diamonds, iron, redstone and bread via TileEntity NBT.

**Loaded chest carries TileEntity NBT** with diamonds, iron, redstone and bread. The SNBT entry:

```
{pos:[2,1,2], state:4, meta:3, nbt:{id:"Chest", Items:[
  {Slot:0b, id:"minecraft:diamond",    Count:5b,  Damage:0s},
  {Slot:1b, id:"minecraft:iron_ingot", Count:32b, Damage:0s},
  ...
]}}
```

**Slab strip**: the two slabs use `meta=0` (bottom half) and `meta=8` (top half). **Torch line**: both torches use `meta=5` (standing on the floor).

The region wand uses one client-side global selection shared by all wand stacks. Left click sets Pos1, right click sets Pos2, and both clicks can target air at the cursor reach endpoint. Sneak + left click clears the current selection; sneak + right click exports with the wand's current mode. You can also use /guidenhc pos1 <x> <y> <z>, /guidenhc pos2 <x> <y> <z>, and /guidenhc clearselection; ~ coordinates are relative to the player. /guidenhc exportstructure [--mode snbt|snbt_e|blocks|blocks_e] exports the current selection, or accepts an explicit <x> <y> <z> <sizeX> <sizeY> <sizeZ>. Scene Editor reads the same client-side selection and, when the server also has GuideNH, first asks the server to export the selected blocks so TileEntity data comes from the authoritative world.