Blueprint & Objectives (all blueprint.yml fields)

In: Server Admin Guide Overview　·　Previous: Structure Files　·　Next: Spawning & Clearing
Related: Core Concepts & Architecture · Mechanism System · Procedural Generation · Loot System

The structure file (.nbt) only decides the ruin's block body. The gameplay layer stacked on top of it—where and what to spawn, how many stages to clear, which chests unlock, where the keystone point is, how mechanisms fire—is all written in templates/<template-id>/blueprint.yml.

This page explains every top-level field of blueprint.yml, with complete examples you can copy verbatim. Mechanisms and sub-structure variants only get a signpost here; their full details live on their own pages.

🖼️ [Image placeholder] A top-down overlay of a ruin structure annotated with spawn points / loot chests / core / mechanisms layered on top　·　suggested assets/blueprint-overlay.png

1. The most important premise: all coordinates are "relative to the structure origin"

Every x / y / z in blueprint.yml is a block coordinate relative to the structure origin, not a world coordinate.

Structure origin = the structure's minimum corner = (0, 0, 0).
That is, the corner of the structure .nbt that is smallest on all three of the X/Y/Z axes within its own bounding box.
A spawn point written as { x: 5, y: 2, z: 5 } means "from the structure's minimum corner, go 5 blocks +X, 2 blocks up, and 5 blocks +Z."

The benefit of this design: the same blueprint can generate with the structure at any position and any rotation in the world, and the coordinates always line up. You don't have to care which world coordinate the ruin ends up generating at—just measure relative offsets against the structure itself.

Tip

Don't want to calculate coordinates by hand? Use /qr editor start <template-id> to enter the visual editor and click on blocks to place points; the editor writes the relative coordinates into blueprint.yml for you.

Caution

Effect of rotation: a ruin may be rotated when it generates (NONE / 90 / 180 / 270). Relative coordinates rotate together with the structure, so your points always stick to the structure body—no need to compensate for rotation.

2. blueprint.yml top-level field overview

Field	Purpose	See
`spawn-points`	Spawn points: where and what to spawn, how many, what level, which stage	§3 below
`loot-chests`	Unlockable reward chests: only open once you've cleared a given stage	§4 below
`cores`	Ruin core: right-click this point with a keystone to activate the realm	§5 below
`objectives`	Staged kill objectives (clear conditions)	§6 below
`mechanisms`	Programmable mechanisms (trigger → actions)	Mechanism System
`variants`	Random sub-structure variants (stamp a weighted-random template onto a slot)	Procedural Generation

All fields are optional: if you only want a pure spawn-point ruin, write only spawn-points; if you want a complete dungeon-style experience with stages, rewards, and mechanisms, configure them all.

Caution

Architecture red line: the blueprint is only responsible for "what to spawn, where, and at which stage." How strong a mob is is MythicMobs' job—you give a level, and MM scales the attributes itself. QR does not compute attributes / damage. See Core Concepts.

3. spawn-points

Declares, once the ruin is activated, which mobs to spawn at which points. Each spawn point is an entry in the list:

yaml

spawn-points:
  - { id: s1, x: 5, y: 2, z: 5, mob: ZOMBIE,          count: 3, level: 1, stage: 1 }
  - { id: s2, x: 8, y: 2, z: 5, mob: SKELETON,        count: 2, level: 1, stage: 1 }
  - { id: b1, x: 6, y: 2, z: 9, mob: mm-FireSkeleton, count: 1, level: 5, stage: 2 }

Field	Meaning	Default	Notes
`id`	Unique identifier of the spawn point	required	Don't duplicate within the same blueprint; the editor list and logs locate it by this
`x` / `y` / `z`	Coordinate relative to the structure origin	0	The mob is centered at +0.5 from this point and born at `y+1` (lands above the block, avoiding clipping into the ground)
`mob`	Mob identifier	required	See "How to write mob" below
`count`	How many to spawn at once	1	Capped at 64; the excess is auto-truncated
`level`	Mob level	1	Only takes effect for MythicMobs mobs (handed to MM to scale); vanilla mobs have no level concept
`stage`	Which stage it belongs to	1	Corresponds to the `stage` in `objectives.stages`; on activation stage 1 spawns first, and later-stage points only spawn after advancing

How to write mob

Vanilla entities: write the Bukkit entity name directly (uppercase), e.g. ZOMBIE, SKELETON, WITHER_SKELETON, BLAZE. A misspelled name or a non-spawnable type is silently skipped.
MythicMobs mobs: write mm-<MythicMobs internal name>, e.g. mm-FireSkeleton. The mm- prefix is case-insensitive, but the MM name after it must exactly match the name in your MM config. Only takes effect if MythicMobs is installed; without it, this point doesn't spawn.

Tip

level only means something for mm- mobs. To make "mobs in the same ruin grow stronger with the realm tier," build the mob as a MythicMobs mob and give it a level; the realm raises the level so MM scales it itself.

The relationship between stages and spawning

When a ruin is activated by a player, only stage: 1 points spawn (provided objectives is configured; without objectives, all points spawn at once).
The player clears stage 1's kill objective → advances to stage 2 → only then do stage: 2 points spawn.
See Spawning & Clearing for detailed advance / respawn rules.

4. loot-chests (reward chests)

Blueprint-level unlockable reward chests: only allowed to open once you've cleared the specified stage. These can coexist with the loot.container-table in the template's template.yml (ordinary containers placed in the structure)—they serve different purposes:

loot.container-table: chests / barrels casually placed inside the structure, openable as soon as you enter the ruin (see Loot System).
loot-chests: "end-of-level treasure chests" at blueprint-specified coordinates, unlocked only after reaching a certain stage.

yaml

loot-chests:
  - { id: c1, x: 3, y: 2, z: 4, loot-table: vault, unlock-stage: 1, per-player-once: true, growth-scaled: true }

Field	Meaning	Default	Notes
`id`	Unique identifier of the reward chest	required	No duplicates within the same blueprint
`x` / `y` / `z`	Coordinate relative to the structure origin	0	Points at the block where the reward chest sits
`loot-table`	Loot table name	required	Corresponds to `loottables/<name>.yml`, e.g. `vault`
`unlock-stage`	Stage required to unlock	1	Can only be opened once clear progress reaches this stage; set to 0 = openable as soon as you enter the ruin
`per-player-once`	Whether it's once per player	true	true = each player rolls their own copy and opens once; false = a single real container shared server-wide, first-come-first-served
`growth-scaled`	Whether to scale by growth	true	true = loot quantity scales with the player's growth; false = fixed amount

Tip

per-player-once: true is the recommended "keep the mystery, everyone gets a share" play—each player sees their own independent copy and nobody steals from anyone. false suits the tension of "the whole team races for one real treasure chest."

5. cores (ruin cores)

The ruin's keystone activation point. A player holding a keystone right-clicks the block at these coordinates → this ruin is promoted to the corresponding tier realm.

yaml

cores:
  - { x: 6, y: 1, z: 6 }
  # You can configure multiple core points; right-clicking any one counts
  # - { x: 6, y: 1, z: 10 }

Field	Meaning	Default
`x` / `y` / `z`	Coordinate relative to the structure origin, pointing at the core block	0

A core has only coordinates, no id—it is simply "an interaction point that can be activated by a keystone."
Place the core on a conspicuous block in the structure (an altar, a beacon, a nether portal frame, etc.) so players know where to right-click.
See Keystone & Realm for the full keystone / realm tier / affix gameplay.

6. objectives (staged objectives)

The ruin's clear conditions, organized by stage. Each stage declares "which mobs to kill and how many of each"; satisfy them all to advance to the next stage; clearing the final stage = ruin cleared.

yaml

objectives:
  stages:
    - { stage: 1, name: "清剿前哨", kills: { ZOMBIE: 3, SKELETON: 2 } }
    - { stage: 2, name: "击败首领", kills: { mm-FireSkeleton: 1 } }

Field	Meaning	Notes
`stage`	Stage number	Increments from 1; corresponds to the `stage` in `spawn-points`
`name`	Stage name	Used for the on-screen text and bossbar when advancing / clearing (e.g. "清剿前哨")
`kills`	Kill mapping	`{ mob-key: count }`; can list multiple mobs

How the mob key in kills lines up

The mob key in kills must match how the mob's mob is written in spawn-points:

Vanilla mob: the key is the entity name, e.g. ZOMBIE: 3.
MythicMobs mob: the key carries the mm- prefix, e.g. mm-FireSkeleton: 1.

Kill counting is tracked via a marker placed on the spawned mobs, so it only counts the mobs this ruin spawned itself—a wild zombie the player kills in passing inside the ruin doesn't count.

What happens if objectives is not configured

Omitting objectives: the ruin has no concept of "stages"; on activation it spawns all spawn-points at once (ignoring stage), never enters the CLEARED state, doesn't unlock stage-gated reward chests, and protection won't be lifted by "clearing."
Suitable for lightweight pure-exploration / pure-spawn ruins.
For the full "fight mobs → advance → clear → open chest → keystone drops" experience, configure objectives.

See Spawning & Clearing for runtime details of stage advancement, respawning, and protection lifting.

6B. boss-gate (final boss gate)

objectives staging requires you to list exactly which mobs each stage kills, and how many. If what you want is the more direct playstyle — "keep clearing mobs until a cumulative kill count is reached, then the final boss appears; defeat it to clear the ruin" — boss-gate is simpler. It is an alternative clear path to objectives: it unlocks a single final boss by cumulative kill count.

yaml

boss-gate:
  enabled: true
  required-kills: 30          # how many "counted mobs" must be killed (cumulative) to unlock the boss
  count-mobs: [ZOMBIE, SKELETON, mm-FireSkeleton]  # which mobs count; leave empty = any mob this ruin spawns
  announce: true             # broadcast a "final boss awakens" title to nearby players on unlock
  boss:                      # the final boss spawned on unlock (coordinates relative to the structure origin)
    id: final_boss
    x: 6
    y: 2
    z: 9
    mob: mm-AncientGuardian   # vanilla entity name, or mm-<MythicMobs name>
    count: 1
    level: 10

Field	Default	Meaning
`enabled`	`true`	Whether this ruin's final boss gate is active (set `false`, or omit the whole `boss-gate` section, to disable)
`required-kills`	`10`	Cumulative kill threshold: kill this many "counted mobs" in this ruin to unlock the boss
`count-mobs`	(empty)	Which mobs count: vanilla entity name (`ZOMBIE`) or `mm-<MM name>`, case-insensitive. Empty = any mob this ruin spawns counts
`announce`	`true`	Whether to show a "final boss awakens" title + sound to nearby players the moment it unlocks
`boss`	required	The final boss spawned on unlock; same fields as `spawn-points` (`id`/`x`/`y`/`z`/`mob`/`count`/`level`, coordinates relative to the structure origin; `mob` supports vanilla names or `mm-`)

How it runs:

After the ruin activates, players clear the mobs from spawn-points (only mobs this ruin itself spawned are counted; wild mobs don't count).
Each "counted mob" killed adds +1; once required-kills is reached → the final boss spawns at the boss coordinates automatically, and (if announce) a broadcast goes to nearby players.
Defeating the final boss = clearing the ruin (enters CLEARED, unlocks reward chests, grants clear loot / keystones) — equivalent to clearing via stages.

Caution

⚠️ boss-gate and objectives are mutually exclusive: both define "clearing." If you use boss-gate, don't also use objectives to define a final-boss stage, or one ruin will have two clear checks. Mobs are still configured via spawn-points.

💡 Let players reach the count: boss-gate doesn't spawn mobs by stage advancement — mobs respawn via the template's respawn. If required-kills is larger than one wave of mobs, set the template respawn to >0 (e.g. 30s), otherwise once the mobs are wiped the count can never be reached.

📊 Progress for your HUD (needs PlaceholderAPI): %qinhruins_boss_kills% (killed) / %qinhruins_boss_required% (needed) / %qinhruins_boss_remaining% (left) / %qinhruins_boss_unlocked% (unlocked?). See Placeholders.

🖼️ [Image placeholder] A cumulative-kill progress bar HUD + the moment the final boss awakens　·　suggested assets/boss-gate.png

7. mechanisms — signpost

mechanisms are the programmable mechanisms in the blueprint: "trigger → action" world interactions (open a door, spawn an ambush on a pressure plate, teleport-and-reward on stage completion, etc.)—purely world interaction, never touching attributes / damage.

It has many fields (6 triggers × 12 actions) and gets its own page:

➡️ For the full explanation, parameters, and YAML examples, see Mechanism System.

Here's a minimal preview (a redstone charge fills a door with air):

yaml

mechanisms:
  - id: open_door
    trigger: { type: REDSTONE, x: 4, y: 1, z: 0 }
    actions:
      - { type: FILL, from: { x: 3, y: 1, z: 0 }, to: { x: 5, y: 3, z: 0 }, material: AIR }
    once: false
    cooldown: 0
    require-stage: 0

8. variants (sub-structure variants) — signpost

variants let you stamp a sub-structure template onto a slot of the main structure by weight, creating procedural variation of "same body, different room / different spire" (on par with the sub-structure systems of BetterStructures / CS). Nestable, and can be placed on the surface.

It belongs to the "procedural generation" domain and gets its own page:

➡️ For the full explanation, the surface / y-min / y-max / options fields, and nesting rules, see Procedural Generation.

Minimal preview:

yaml

variants:
  - id: top
    x: 8
    y: 20
    z: 8
    options:
      - { template: spire_a, weight: 30 }
      - { template: spire_b, weight: 20 }

9. A complete blueprint.yml example

Put all the parts above together and you get a complete "two-stage, with an end-of-level treasure chest, a keystone core, and a redstone-opened door" ruin:

yaml

# All coordinates are relative to the structure origin (structure minimum corner = 0,0,0)

# —— Spawn points (mob: vanilla entity name, or mm-<MythicMobs name>) ——
spawn-points:
  - { id: s1, x: 5, y: 2, z: 5, mob: ZOMBIE,          count: 3, level: 1, stage: 1 }
  - { id: s2, x: 8, y: 2, z: 5, mob: SKELETON,        count: 2, level: 1, stage: 1 }
  - { id: b1, x: 6, y: 2, z: 9, mob: mm-FireSkeleton, count: 1, level: 5, stage: 2 }

# —— Unlockable reward chest ——
loot-chests:
  - { id: c1, x: 3, y: 2, z: 4, loot-table: vault, unlock-stage: 1, per-player-once: true, growth-scaled: true }

# —— Keystone activation point ——
cores:
  - { x: 6, y: 1, z: 6 }

# —— Staged kill objectives ——
objectives:
  stages:
    - { stage: 1, name: "清剿前哨", kills: { ZOMBIE: 3, SKELETON: 2 } }
    - { stage: 2, name: "击败首领", kills: { mm-FireSkeleton: 1 } }

# —— Mechanisms (see 机关系统.md) ——
mechanisms:
  - id: open_door
    trigger: { type: REDSTONE, x: 4, y: 1, z: 0 }
    actions:
      - { type: FILL, from: { x: 3, y: 1, z: 0 }, to: { x: 5, y: 3, z: 0 }, material: AIR }
    once: false
    cooldown: 0
    require-stage: 0

Tip

This example can be found as a prototype in templates/_example/blueprint.yml (templates starting with _ are not loaded as real ruins—purpose-built for copying).

Next steps

How ruin activation, stage advancement, protection, and entry thresholds run → Spawning & Clearing
Add mechanisms to a ruin → Mechanism System
Add random variants to a ruin → Procedural Generation
Configure loot tables → Loot System
All template-body fields (structure / generation / entry threshold) → Ruin Template

Blueprint & Objectives (all blueprint.yml fields) ​

1. The most important premise: all coordinates are "relative to the structure origin" ​

2. blueprint.yml top-level field overview ​

3. spawn-points ​

How to write mob ​

The relationship between stages and spawning ​

4. loot-chests (reward chests) ​

5. cores (ruin cores) ​

6. objectives (staged objectives) ​

How the mob key in kills lines up ​

What happens if objectives is not configured ​

6B. boss-gate (final boss gate) ​

7. mechanisms — signpost ​

8. variants (sub-structure variants) — signpost ​

9. A complete blueprint.yml example ​

Next steps ​

Blueprint & Objectives (all blueprint.yml fields)

1. The most important premise: all coordinates are "relative to the structure origin"

2. blueprint.yml top-level field overview

3. spawn-points

How to write mob

The relationship between stages and spawning

4. loot-chests (reward chests)

5. cores (ruin cores)

6. objectives (staged objectives)

How the mob key in kills lines up

What happens if objectives is not configured

6B. boss-gate (final boss gate)

7. mechanisms — signpost

8. variants (sub-structure variants) — signpost

9. A complete blueprint.yml example

Next steps