Selection & Saving (pos1 / pos2 / save / stage)

Previous: Structure Files (.nbt / .schem / marker blocks / terrain blending)　·　Next: Blueprint & Objectives (blueprint.yml)

Turning a build you've already constructed in the world into a QR ruin template relies on this set of commands: select → save template → preview-deploy → restore when needed. The whole process never touches YAML (basic fields are auto-generated; you flesh them out later with the Ruin Template).

All commands require the permission qinhruins.admin. The full command tree is in Command Reference.

---

1. Selecting: /qr pos1 and /qr pos2

Stand in the world, look at a block, and type the command to set it as one corner of the selection:

/qr pos1     ← the block you're looking at becomes the first corner
/qr pos2     ← the block you're looking at becomes the second corner

Key points:

• Pick corners with your crosshair: QR takes the block your line of sight hits (within ~100 blocks), not the block under your feet. Look at the target block, then type the command.
• If the crosshair isn't pointing at any block (pointing at sky), you'll be prompted "look at a block first."
• The two corners form a rectangular bounding box (inclusive of both end blocks); it doesn't matter which is front or back, higher or lower — QR auto-takes min/max.
• The selection is remembered per player; each admin has their own pos1/pos2, mutually independent.

🖼️ [Image placeholder] A diagram of standing outside a build, crosshair pointing at the two diagonal blocks to set pos1/pos2, with the selection highlighted · suggested assets/selection-corners.png

---

2. Saving: /qr save

After selecting, save it as a ruin template:

/qr save <ruin id>

QR will:

1. Scan the sign markers and marker blocks in the selection — found spawn points / reward chests / cores / command points are written into blueprint.yml, and the marker signs are swapped for the corresponding functional blocks (e.g. core sign → lodestone, reward-chest sign → chest, spawn sign → cleared);
2. Capture the selection into structure.nbt using the native Bukkit API;
3. Write structure.nbt + a default template.yml + blueprint.yml under templates/<ruin id>/ (won't overwrite if they already exist).
4. Report the selection size (width × height × depth) and the number of markers scanned.

Afterward:

• The default-generated template.yml has generation.enabled: false (no natural generation yet); configure it per the Ruin Template, turn on enabled, set weight etc., then /qr reload.
• <ruin id> has Tab-completion (lists existing template IDs, handy for overwrite-updating).

Tip

💡 Updating an existing ruin: re-select and /qr save <same id>; structure.nbt is overwritten by the new selection, but the existing template.yml / blueprint.yml are not overwritten (preserving the fields you configured by hand). To reset, delete those two files first.

---

3. Preview Staging: /qr stage

After saving a template, /qr stage lets you preview in place with ghost blocks how the structure will land — only you can see it, the world isn't actually changed; confirm to place it once satisfied. This is the killer tool for "trial placement" before deploying a ruin.

/qr stage start <template>     Start staging: lay out a ghost preview at the crosshair position
/qr stage here                 Move the staging origin to the block the crosshair points at
/qr stage move <dx> <dy> <dz>  Fine-tune position by offset
/qr stage rotate               Cycle rotation (NONE → 90 → 180 → 270)
/qr stage confirm              Confirm placement: actually generate this ruin anchor
/qr stage cancel               Cancel: clear the ghost preview, generate nothing

How it works:

Subcommand	Behavior
start <template>	Using the block your crosshair points at as the origin, send ghost blocks (visible only to you) drawing the structure body, and outline the bounding box with particles.
here	Move the origin to the current crosshair position and redraw the preview.
move <dx> <dy> <dz>	Fine-tune by XYZ offset from the current origin (e.g. move 0 1 0 raises it one block).
rotate	Cycle orientation through the four directions; the preview turns with it.
confirm	Actually generate the anchor at the preview position (landing, terrain blending, foundation, spawn points, etc. all take effect), clearing the ghost.
cancel	Abandon, clear the ghost, the world is entirely unchanged.

Key points:

• Ghost blocks are fake: the preview is only sent to your own client; the world's blocks don't move at all, and there's no trace after cancel.
• Preview block cap preview-cap (default 12000): if the structure's block count exceeds this, only the particle outline is drawn (sending too many fake blocks can lag the client). To preview larger structures, raise staging.preview-cap in config.yml.
• Marker blocks aren't drawn in the preview (barrier / bedrock); what you see is the actual look after placement.
• The preview only shows when you and the origin are in the same world.

🖼️ [Image placeholder] A comparison shot of translucent ghost blocks floating in front of the player + a green particle bounding box, with the orientation changing after rotate · suggested assets/stage-preview.png

Tip

💡 stage vs spawn: /qr spawn <template> deploys directly under your feet (no preview); /qr stage previews first, then confirms — ideal for carefully picking position and orientation. Both require qinhruins.admin.

---

4. Sign Markers

/qr save and /qr import scan signs in the selection as gameplay markers. The first line is the label; the following lines are parameters:

First-line label	Second line	Third line	Fourth line	Meaning
[mob] / [spawn]	mob ID	count*level (e.g. 3*5)	phase number	Normal spawn point
[mythicmob] / [mmob]	MM mob name	count*level	phase number	MythicMobs spawn point (auto-prefixed with mm-)
[chest] / [loot]	loot table name	unlock phase	—	Unlock-style reward chest
[core]	—	—	—	Realm core (keystone activation point)
[command] / [cmd]	command segment 1	segment 2	segment 3	Command point executed on generation

After saving, marker signs are swapped for the corresponding blocks (spawn / command point → cleared, reward chest → chest, core → lodestone).

The full blueprint fields (hand-writing blueprint.yml, phase objectives, variants) are in Blueprint & Objectives; to mark points with a GUI instead of placing signs, see Visual Ruin Building.

---

5. Removing & Restoring: /qr remove

Reclaim an already-generated anchor and restore the terrain to its pre-generation state as much as possible:

/qr remove <anchor id>

QR will: remove the anchor from the world registry, clear its spawn / mechanism / container-loot records / NPCs, then restore the original terrain from the snapshot, and finally report "restored" or "no snapshot (not restored)."

<anchor id> has Tab-completion. Companion lookup commands: /qr tp <anchor id> (teleport there), /qr markers <anchor id> (reverse-scan markers).

Snapshot Mechanism (decides whether remove can restore)

Controlled by the cleanup section of config.yml:

cleanup:
  snapshot-restore: true        # Snapshot the original terrain before generating, restore on /qr remove
  max-snapshot-volume: 500000   # Snapshot volume cap (block count)

Field	Default	Description
snapshot-restore	true	On: snapshot the original terrain to disk before generating a ruin, restore from it on remove / fade-and-regen. Off: saves disk, but blocks aren't restored after removal (leaving a crater).
max-snapshot-volume	500000	Snapshot volume cap (block count). Synchronously snapshotting a very large structure (e.g. millions) would freeze the main thread → watchdog kills the server, so anything over this value skips the snapshot (removal won't restore, but won't lag). 0 = unlimited (dangerous).

Caution

⚠️ To genuinely restore terrain after a ruin is removed / naturally fades, you must keep snapshot-restore: true. Turning it off, /qr remove only deregisters and doesn't restore blocks.

The "fade-and-regen" of cleared ruins over time also relies on snapshots — see director.regen-hours in Natural Generation & Pre-load.

---

6. Full Workflow Example: Turn a Tower into a Naturally Generating Ruin

1. Stand outside the tower, crosshair on one bottom corner of the tower   →  /qr pos1
2. Walk to the diagonal, crosshair on the opposite top corner             →  /qr pos2
3. (Optional) Place [mob]/[chest]/[core] sign markers inside the tower
4. Save as a template                                                     →  /qr save ancient_tower
5. Preview what it looks like placed elsewhere                            →  /qr stage start ancient_tower
   Fine-tune position / orientation                                       →  /qr stage move 0 1 0 / /qr stage rotate
   Place it down to try once satisfied                                    →  /qr stage confirm
6. Don't want this trial instance anymore                                 →  /qr remove <anchor id from the previous step>
7. Open templates/ancient_tower/template.yml,
   turn on generation.enabled, set weight/biomes/y etc. (see "Ruin Template"),
   save → /qr reload, and from now on it will generate naturally in the world

🖼️ [Image placeholder] A thumbnail flow of the six steps above (select → save → preview → confirm → restore → enable generation) · suggested assets/save-workflow.png

---

Next Step

• Flesh out template fields (generation / loot / foundation / guide item) → Ruin Template
• How a structure blends into terrain / marker blocks / import → Structure Files
• Configure the gameplay layer by hand or GUI → Blueprint & Objectives
• Look up all commands and permissions → Command Reference