5-Minute Quick Start

Previous: Installation　·　Next: Core Concepts

This page walks you through building your first ruin from scratch — one that generates naturally, can be explored, and can be cleared. There are two routes: A, using the GUI editor (recommended for newcomers) and B, hand-writing YAML (faster once you understand structures). Let's start with A.

Prerequisite: you've installed QCL + QR per Installation and have OP permissions in-game.

Route A: Visual editor (recommended)

Step 1 · Build a structure

Build a small structure anywhere in the world — a stone room or a tower will do. Remember its extent.

Step 2 · Select a region and save it as a template

Stand at one corner of the building, look at the lowest corner block, and type:

/qr pos1          # running the command while looking at a block = set the first corner

Walk to the opposite corner and look at the highest corner block:

/qr pos2
/qr save my_ruin  # save the selected structure as the template my_ruin

This step generates templates/my_ruin/, containing the structure file and a default template.yml.

Step 3 · Enter the editor and mark points

/qr editor start my_ruin     # enter the visual editor for this ruin

Once inside you'll get editing tools. Following the prompts:

/qr editor mode spawn → stand somewhere and mark it as a spawn point, then /qr editor set mob ZOMBIE, set count 3, set stage 1.
/qr editor mode chest → mark a reward chest, set loot vault, set unlock 1 (unlocks only when stage 1 is cleared).
/qr editor mode core → mark the ruin core (used by keystones to activate a realm).
/qr editor save → save, which automatically writes blueprint.yml.

For the full editor workflow, see Building Ruins Visually.

Step 4 · Make it generate naturally

Open templates/my_ruin/template.yml and confirm:

yaml

generation:
  profile: surface_overworld   # use the built-in "surface · Overworld" placement profile
  enabled: true                # participate in natural generation
  weight: 20                   # lottery weight

Run /qr reload. Now it will emerge naturally on the surface of the Overworld.

Step 5 · Find it, verify it

Don't want to wait for natural generation? Drop it manually or debug it directly:

/qr spawn my_ruin     # immediately generate one at your feet
/qr gentest           # force-generate one nearby (bypasses probability, for debugging)
/qr near 500          # list ruins within 500 blocks nearby
/qr tp <anchor id>    # teleport to a ruin

Walk up to it — monsters activate, chests can be opened, and kill objectives start counting. Clear all objectives → completion, rewards unlocked. 🎉

Route B: Hand-write YAML (faster once you understand structures)

If you already have a .schem schematic (from WorldEdit / downloaded):

# 1. Drop xxx.schem into plugins/QinhRuins/schematics/
/qr import xxx my_ruin    # convert to templates/my_ruin/, native .nbt + template skeleton

Then hand-write templates/my_ruin/blueprint.yml (all coordinates are relative to the structure origin 0,0,0):

yaml

spawn-points:
  - { id: s1, x: 5, y: 2, z: 5, mob: ZOMBIE, count: 3, level: 1, stage: 1 }
loot-chests:
  - { id: c1, x: 3, y: 2, z: 4, loot-table: vault, unlock-stage: 1, per-player-once: true }
objectives:
  stages:
    - { stage: 1, name: "Clear out", kills: { ZOMBIE: 3 } }

Then just run /qr reload. For all template fields, see Ruin Templates; for all blueprint fields, see Blueprints and Objectives.

The debugging trio (essential when a ruin won't generate)

Command	What it does
`/qr why <template>`	Stand somewhere and ask "why does / doesn't this ruin generate here," listing each site check one by one (✔/✘)
`/qr gentest`	Force-generate one nearby (bypassing probability) to verify the structure / blueprint itself is fine
`/qr spawn <template>`	Precisely drop one at your feet

For systematically troubleshooting a ruin that "just won't appear," see Diagnostics and Troubleshooting.

What you can already do

Build a ruin template with the GUI or YAML
Mark spawn points / reward chests / cores / kill objectives
Make it generate naturally, and use commands to manually drop, teleport, and troubleshoot it

Go deeper next

Understand exactly what each term means → Core Concepts
Tune generation to feel more natural (density / spacing / terrain blending) → Natural Generation and Pre-generation
Add mechanisms, stages, and realms → Server Guide Overview

5-Minute Quick Start ​

Route A: Visual editor (recommended) ​

Step 1 · Build a structure ​

Step 2 · Select a region and save it as a template ​

Step 3 · Enter the editor and mark points ​

Step 4 · Make it generate naturally ​

Step 5 · Find it, verify it ​

Route B: Hand-write YAML (faster once you understand structures) ​

The debugging trio (essential when a ruin won't generate) ​

What you can already do ​

Go deeper next ​