Core Concepts and Architecture

Previous: Quick Start　·　Back: Home

This page explains every term in QR clearly and shows how they thread into a single pipeline. Once you finish this page, all the later server / developer docs will make instant sense.

The whole picture in one diagram

text

              ┌─────────── The "recipe" you provide (YAML + structure files on disk) ───────────┐
              │                                                                                 │
  Structure ──→ Template ──refers──→ Placement Profile        Blueprint                         │
  .nbt          template.yml         generators/*.yml         blueprint.yml                     │
              │                          │                      │                               │
              └──────────────────────────┼──────────────────────┘                               │
                                         ▼                                                       ▼
                       The Generation Director runs the lottery, picks a site,
                          pastes the structure, and blends the terrain
                                         │
                                         ▼
                              Anchor  ← a real ruin instance that exists in the world
                                         │
                          ┌──────────────┼───────────────┐
                          ▼              ▼               ▼
                 Monster activation/    Mechanism        Loot
                 objectives
                          │
                          ▼  after clearing, can be infused by a Keystone
                              Realm = Anchor + Tier + Affix

Threading it together in one line: "Template + Placement Profile + Blueprint" is the recipe (on disk), an "Anchor" is the finished instance generated in the world from the recipe, and a "Realm" is the repeatable-farming gameplay that stacks buffs onto the finished product.

The recipe layer (definitions on disk, reusable)

Template — `template.yml`

A ruin's ID card. It answers: "what ruin is this, which structure file it uses, what it looks like, where it generates, what loot it drops, and what its entry requirements are." Each template is a templates/<id>/ folder containing:

template.yml — the template definition itself
the structure file (default structure.nbt) — the block body of the ruin
blueprint.yml — the gameplay layer (spawn points / objectives / mechanisms / cores)

Folders starting with _ (such as _example) are ignored and not loaded as real ruins. For all template fields, see Ruin Templates.

Structure

The block body of a ruin. QR uses Bukkit native .nbt; WorldEdit's .schem is converted to .nbt via /qr import. Placement supports mask blending, foundation fill, marker blocks, and frame-by-frame anti-lag. See Structure Files.

Placement Profile — `generators/*.yml`

A reusable rule pack for "where to generate": dimension / world filters, generation layers (surface / underground / sky / sea surface / seabed), flatness, minimum spacing, probability… Multiple templates can share the same profile (generation.profile: surface_overworld), and a template can also locally override any field. 17 are built in. See Placement Profiles.

Blueprint — `blueprint.yml`

The gameplay layer stacked on top of the structure. All coordinates are block coordinates relative to the structure origin (the structure's minimum corner = 0,0,0):

Spawn points (spawn-points) — where to spawn what mobs, how many, what level, which stage they belong to
Kill objectives (objectives) — staged clear conditions
Reward chests (loot-chests) — unlockable chests
Cores (cores) — the interaction point where a keystone activates a realm
Mechanisms (mechanisms) — trigger → action
Sub-structure variants (variants) — weighted-random templates pasted into slots

See Blueprints and Objectives.

The instance layer (things that really exist in the world)

Anchor

A real ruin generated from a template at some coordinate in the world — the "instance." An anchor records: which template it uses, where, its facing, its size (width / height / depth), and its current state. All runtime gameplay (activation spawning, objective counting, mechanisms, protection, loot ownership) hangs on the anchor.

An anchor has 4 lifecycle states:

State	Meaning
`DORMANT`	Generated but no one nearby; monsters / mechanisms are asleep
`ACTIVE`	A player has entered the activation radius; monsters are active, objectives are counting
`CLEARED`	Cleared / fully explored; chests have been opened, protection lifted
`RECYCLED`	Recycled (faded-restored or `/qr remove`); the slot has been freed

Template vs. anchor: one template can generate many anchors (the same ruin in various places across the world), just as one class can new many objects.

Generation Director

The scheduling brain that turns recipes into anchors: all generatable ruins compete in a weighted lottery, constrained by global density (per-region cap, minimum spacing); it can also refresh on a timer around players in already-explored worlds (a living world), and let cleared ruins fade and regenerate over time. Turning off the Generation Director reverts to the old behavior of "each template rolls independently by its own probability." See Natural Generation and Pre-generation.

The endgame layer (stacking buffs onto the finished product for repeat farming)

Realm

The empowered state of a cleared ruin after infusing it with "tier + affix." The higher the tier, the stronger the mobs, the more affixes, and the richer the loot. A realm is not a new world — it's still that ruin in place — only the mobs respawn, the rules are rewritten, and the output is upgraded. See Realms and Keystones.

Keystone

The key that activates a realm. A player right-clicks a ruin core with a keystone → that ruin ascends into a realm of the corresponding tier. Keystones can drop on clearing (with a ladder: a chance to drop one tier higher), or be reforged (spend currency to re-roll the affixes).

Affix

The empowering modifiers of a realm, in five categories: count (spawn ×N), level (mob level +N, scaled by the monster plugin), environment / rules (no healing / time limit / darkness), player state (slowness / weakness), and loot (greedy / gilded / treasured). Constrained by a danger budget to prevent hellish stacking, with mutually exclusive groups.

🔑 Architecture red line: QR computes no attributes / damage. Making "monsters stronger" via affixes is delegated to MythicMobs by raising the level (MM scales the stats itself), not QR changing the numbers. This follows the same line of thinking as QI / QS "not touching values."

See Affix System.

Cross-cutting systems (running through every layer)

System	In one line	See
Mechanism	The blueprint's "trigger → action," pure world interaction (open a door / spawn an ambush / teleport), not attributes	Mechanism System
Loot	Container loot (independent per person / shared server-wide) + unlockable reward chests + a purge slot machine, with growth scaling	Loot System
Guide	Right-click a guide item → a compass points to the nearest ruin of that kind	Guides and Codex
Codex	A collection album of "strategy cards" recorded after a player discovers a ruin	Guides and Codex
Session / Party	Enter / exit prompts, bossbar, party-shared progress	Parties and Sessions
Protection	A ruin being explored / active can't be broken or built on; unlocked after clearing	Spawning and Clearing
Snapshot / Regen	Snapshot the original terrain before generating, restore it on removal / fading	Natural Generation and Pre-generation

How data is stored

Recipes (templates / blueprints / profiles / loot tables / affixes) = YAML + structure files on disk; the server owner edits them and /qr reload applies them.
Instances and runtime state (anchors, chest claim records, slot machine, mechanism trigger records) = local YAML (anchors.yml, etc.), tied to specific world coordinates, which should be local.
Player codex discoveries = optionally in the database (shared across servers); everything else stays local.

See Data Storage.

A complete example threading all the concepts together

You wrote the template ancient_tower (Template), which refers to the placement profile surface_overworld (Profile) and is configured with a blueprint.yml (Blueprint) where stage 1 spawns 3 zombies and stage 2 spawns 1 boss.
As players explore, the Generation Director wins the lottery for it in some valley, pastes the structure in and blends the terrain, giving birth to an Anchor (state DORMANT). A player approaches → ACTIVE, monsters activate; stepping on a redstone plate triggers a Mechanism to open a door; clearing both stage objectives → CLEARED, the reward chest unlocks and hands out Loot, and a T3 Keystone drops.
The player right-clicks the ruin core → infusing three Affixes ("overlord + greedy + no healing"), and this anchor ascends into a T3 Realm; after purging, they get exclusive loot and a higher-tier keystone. A day later, with no one nearby, this cleared ruin is snapshot-restored, its state turns to RECYCLED, and the world frees a slot to grow a new ruin.

Every bolded word can be found defined on this page — you've now mastered all of QR's core concepts.

Next step

Configure ruins systematically → Server Guide Overview
Look up commands / config → Reference

Core Concepts and Architecture ​

The whole picture in one diagram ​

The recipe layer (definitions on disk, reusable) ​

Template — template.yml ​

Structure ​

Placement Profile — generators/*.yml ​

Blueprint — blueprint.yml ​

The instance layer (things that really exist in the world) ​

Anchor ​

Generation Director ​

The endgame layer (stacking buffs onto the finished product for repeat farming) ​

Realm ​

Keystone ​

Affix ​

Cross-cutting systems (running through every layer) ​

How data is stored ​

A complete example threading all the concepts together ​

Next step ​