Realm & Keystone (Realm × Keystone)
In: Server Owner Guide Overview · Upstream: Core Concepts & Architecture · Related: Affix System · Loot System
A Realm is QR's endgame: it injects a "tier + affix" combo into an already-generated, activatable ruin, making its mobs respawn, its rules rewritten, and its output upgraded — to be run over and over. A Keystone is the key that activates a realm. This page lays out the whole loop and breaks down the realm: section of config.yml item by item.
🔑 Architectural red line: QR does not compute attributes / damage. The way a realm makes "mobs stronger" = attaching a level to the mob when it spawns, and MythicMobs scales the stats itself; player attributes are delegated to the attribute plugin; QR only orchestrates quantity / environment / rules / loot.
1. The Loop in One Breath
Clear a ruin → drops a keystone (carries a ladder; chance to drop a higher tier)
→ (optional) /qr reroll spends currency to recast affixes, until satisfied
→ hold the keystone, right-click a ruin "core" to activate the realm (inject tier+affix)
→ clear every mob = Cleanse
→ privately deliver exclusive loot + currency + (by chance) same-tier / higher-tier keystone
→ take the new keystone, return to step one, climb the tiers ever higherThe higher-tier keystone dropped on cleanse is the ladder engine: players keep climbing tiers — the higher, the fatter and the more dangerous.
🖼️ [Image placeholder] Diagram of the realm loop (clear → keystone → reroll → activate → cleanse → higher-tier keystone) · suggested assets/realm-loop.png
2. Where Keystones Come From, and How to Use Them
2.1 Obtaining a Keystone
| Channel | Description |
|---|---|
| Clear drop | On clearing a normal ruin, or after a realm is cleansed, drops by keystone-chance / next-tier-chance probability (straight into the inventory) |
| Admin grant | /qr keystone give <tier> [player] (permission qinhruins.admin); tier is auto-clamped to 1..max; omit player to give to yourself |
| Item source / shop / loot | A keystone is essentially an item carrying a keystone_tier NBT, and can be dispensed through any loot table or shop |
2.2 Activating a Realm
A player holds a keystone and right-clicks a ruin core (the interaction block defined in the blueprint's cores section) to activate it.
- The vanilla Ender Eye fly-away and similar right-click behavior is suppressed (even though the default material is an Ender Eye, it won't be thrown).
- Right-clicking air does nothing; you must right-click the core block.
- A successful activation consumes 1 keystone, injecting the tier recorded on that keystone and (if already rerolled) its affixes; if the keystone has no pre-stored affixes, a blind-box roll happens the instant it activates.
You can also activate with the /qr activate command: it first searches the ruin the player is standing in, then the nearest activatable ruin within the activate-radius. If none is found, it reports the distance to the nearest ruin. See Command Reference for details.
A ruin that is already a realm, already cleared (
CLEARED), or whose blueprint has no spawn points cannot be activated, and the corresponding hint is shown.
2.3 Keystone Appearance (realm.keystone)
realm:
keystone:
# material supports any item source (vanilla by default):
# vanilla: material name / minecraft:xxx / vanilla:xxx
# other plugins (soft-depend): craftengine:xxx | itemsadder:xxx(ia-xxx) | nexo:xxx(nx-xxx)
# qinhitems:xxx(qi-xxx) | mmoitems:type:id(mi-) | neigeitems:xxx(ni-) | mythicmobs:xxx(mm-xxx)
material: minecraft:ender_eye
# name/lore only take effect for [vanilla materials]; when material points to another item source,
# the item's own name/lore are kept entirely, not overridden.
name: "&dRealm Keystone &7T{tier}" # {tier}=tier; leave "" empty and even a vanilla material won't be renamed
lore:
- "&7Right-click a ruin core to activate a &dT{tier} &7realm"
model-data: 0 # custom model data (for vanilla materials)Key rules:
- The
{tier}placeholder is replaced with that keystone's tier (only thename/loreof vanilla materials get the replacement). - To show the tier on a keystone made from a custom item (mi/ni/qi/ia/ce/mm…), write the placeholder
%qinhruins_keystone_tier%in that item's own name/lore (requires PlaceholderAPI). For the full placeholder set see Placeholders. - If affixes were rerolled before activation, an
— Affixes —list (&7• affix name) is automatically appended to the end of the keystone's Lore.
🖼️ [Image placeholder] Item tooltip of an Ender Eye keystone (with the T tier and the Affixes list) · suggested assets/keystone-tooltip.png
3. Tier Curve (realm.tiers)
The tier is the realm's strength dial. The four expressions take tier (the current tier) as their variable and are evaluated by CoreLib's expression engine.
realm:
tiers:
max: 16 # highest tier (keystone/ladder caps here)
affix-count: "1 + tier / 3" # number of affixes per tier (rounded)
mob-level: "tier * 5" # spawn base level (plus affix level bonuses; handed to MM to scale)
loot-bonus: "1 + tier * 0.1" # cleanse-loot "roll count" multiplier, scaling with tier
danger-budget: "40 + tier * 10" # danger budget cap (sum of affix dangers caps here)| Key | Meaning | Default-effect example |
|---|---|---|
max | Keystone tier cap; the ladder caps here (at least 1) | 16 |
affix-count | How many affixes are injected at this tier (result rounded, clamped to 0–32) | T3 → 1+3/3=2 |
mob-level | Spawn base level (plus the bonus from "level"-type affixes); handed to MM to scale mob stats | T5 → level 25 |
loot-bonus | The quantity multiplier for cleanse drops, multiplied with the "greed" affix multiplier. Write "1" to disable per-tier scaling | T1→1.1×, T16→2.6× |
danger-budget | The affix danger budget cap; see below and Affix System | T1 → 50 |
mob-levelplus "level"-type affixes (Veteran +2 / Overlord +5) are summed and passed to MythicMobs as the spawn level; QR never changes any value directly.
4. Affix Injection & Danger Budget
On activation QR rolls affix-count affixes by tier (or uses the pre-stored batch if the keystone was rerolled). Two constraints guard the experience:
- Danger budget (danger-budget): the sum of all affixes'
dangermust not exceed that tier's budget, preventing low-tier hell stacking (e.g. T1 can never assemble "No Heal + Time Limit + Horde"). The first affix is always guaranteed (ignoring the budget), ensuring every realm has at least one affix. Only high tiers, with high budgets, can assemble heavy combos. - Same-group exclusion (group): affixes in the same
group(e.g. Elite Swarm / Horde in themob-countgroup) appear only one at a time.
For the full affix table, effect types, and the 13 built-in affixes, see Affix System.
5. Cleanse Reward (realm.reward)
Clearing every mob in the realm is the "Cleanse". Cleansing privately delivers exclusive loot and currency to each participant (not ground drops — settled per person).
realm:
reward:
loot-table: realm # exclusive loot table name (loottables/<name>.yml)
per-tier-table: false # when true, prefers realm_t{tier}, falling back to loot-table if absent
growth-scaled: true # personal drop count scales by "growth"
currency-base: "tier * 100" # base currency per participant (expression, variable tier; 0=disabled)
currency-provider: "" # economy backend: empty=auto | vault | excellenteconomy(ee) | playerpoints
currency-id: "" # currency ID (required for ExcellentEconomy, e.g. money/silver; leave empty for Vault/PP)| Key | Meaning |
|---|---|
loot-table | The exclusive loot table dispensed on cleanse, corresponding to loottables/<name>.yml (default realm) |
per-tier-table | When enabled, prefers the realm_t<tier> table (e.g. realm_t12), falling back to loot-table if not found. Good for configuring a fatter table for high tiers separately |
growth-scaled | Personal drop count scales by player growth (QinhClass/MMOCore level, or vanilla substitute) |
currency-base | Base currency amount per participant (expression), then multiplied with the "Golden Touch" affix multiplier. Requires an economy plugin, otherwise skipped |
currency-provider | Economy backend selection. Empty auto-detects; vault/ee/playerpoints specify explicitly |
currency-id | ExcellentEconomy's currency ID (required for EE); leave empty for Vault / PlayerPoints |
For how to write the loot table
loottables/realm.yml(itemparsed from any source via CoreLib,weight/amount/min-growth/unique), see Loot System. Entries withunique: trueare weighted by the "Hidden Trove" affix.
/qr reward (cleanse slot machine reward): after cleansing, the player opens the nearest slot machine interface with /qr reward to collect the output (an animated draw UI). For slot machine mechanics see Loot System.
🖼️ [Image placeholder] Cleanse slot machine draw interface · suggested assets/reward-slotmachine.png
6. Reroll Gambling (realm.reroll)
Not happy with the affixes rolled on a keystone? Spend currency to re-roll, then go activate once satisfied.
realm:
reroll:
enabled: true # when off, /qr reroll is unavailable and affixes only blind-box roll the instant of activation
cost-base: "tier * 50" # cost per reroll (expression, variable tier; requires an economy plugin)
currency-provider: "" # same as reward: empty=auto | vault | ee | playerpoints
currency-id: "" # currency ID (required for ExcellentEconomy)A player holding a keystone (main or off hand) runs /qr reroll:
- The cost is computed from
cost-base; - If the cost > 0 and no economy plugin is installed, it reports unavailable; insufficient balance reports the cost / balance and prompts to top up;
- After a successful charge, affixes are re-rolled by the keystone's tier and written straight back onto the keystone in hand (updating the Affixes list in its Lore);
- The new affixes are reported back to the player one by one.
Reroll pre-stores the affixes into the keystone, adopted directly on activation, no more blind box. When
enabled: false, the player can only accept the random result at the instant of activation.
7. Failure, Abandon & Time Limit
realm:
failure:
consume-keystone: false # whether failure consumes the keystone (recommend true at high tiers for thrill; the keystone is already consumed on activation, so this affects whether it's refunded on failure)
activate-radius: 48 # radius within which /qr activate searches for nearby ruins
abandon-seconds: 120 # how long with no players near a realm before it's deemed abandoned (clears mobs, resets; prevents persistent mob pile-up)
time-limit: "0" # global realm time limit, 0=no limit (more like a world structure than a dungeon countdown)| Key | Meaning |
|---|---|
failure.consume-keystone | Default false: after a realm fails (time-out / abandoned), a same-tier keystone is dropped back on the spot for the player to retry; set true and failure gives no refund — the keystone is wasted, raising the climb's thrill |
activate-radius | The radius within which the /qr activate command searches for activatable ruins |
abandon-seconds | If the realm range has no players continuously for this many seconds, it's deemed abandoned: spawned mobs are cleared, state returns to DORMANT, preventing wild mob pile-up |
time-limit | The realm's global time limit (supports 5m/300 etc.), 0 = no limit. Note: time-limit affixes like "Sands of Time" take the shorter limit nearby, with priority over this setting |
Failure (a non-clear end) only branches the outcome: only a clear gives rewards; abandon / timeout decides whether the keystone is refunded by
consume-keystone.
8. Ladder Probability (realm.keystone-chance / realm.next-tier-chance)
After a cleanse, a die is rolled for each participant to decide whether a keystone drops — this is the ladder engine of the whole endgame.
realm:
keystone-chance: 0.5 # chance of dropping a "same-tier" keystone after cleanse (straight into the inventory, 0~1)
next-tier-chance: 0.2 # additional chance of dropping a "one tier higher" keystone after cleanse (the climb engine, capped at max)| Key | Meaning |
|---|---|
keystone-chance | The chance of dropping a same-tier keystone after cleanse (0=never, 1=always). Keeps a keystone in the player's hands to keep the loop going |
next-tier-chance | The additional chance of dropping a one-tier-higher keystone; once the tier reaches tiers.max it no longer rises. This is the core driver of climbing tiers |
The two are judged independently: a single cleanse may drop both a same-tier and a higher-tier keystone. Drops go straight into the inventory; if it's full, they drop at the player's feet.
9. Bossbar & Appearance
realm:
bossbar-color: PURPLE # PINK/BLUE/RED/GREEN/YELLOW/PURPLE/WHITE
bossbar-style: SEGMENTED_10 # SOLID/SEGMENTED_6/10/12/20While a realm is active, players in range see a Bossbar above their head; the title includes the tier, the ruin name and the affix list, and the progress bar = remaining mobs / total mobs.
10. Related Placeholders
Requires PlaceholderAPI (see Placeholders):
| Placeholder | Meaning |
|---|---|
%qinhruins_realm_active% | Whether the player is inside a realm |
%qinhruins_realm_tier% | Current realm tier |
%qinhruins_realm_name% | Realm ruin name |
%qinhruins_realm_affixes% | Current realm's affix list |
%qinhruins_realm_affix_count% | Affix count |
%qinhruins_realm_mobs% / %qinhruins_realm_total% | Remaining / total mob count |
%qinhruins_realm_time% | Remaining time limit |
%qinhruins_keystone_tier% | The tier of the keystone in the player's hand (for custom keystone appearances) |
Next Steps
- Configure affixes, understand the 11 effects and the danger budget → Affix System
- Configure the cleanse loot table and the slot machine → Loot System
- Look up
/qrcommands → Command Reference