Spawning & Clearing

In: Server Admin Guide Overview　·　Previous: Blueprint & Objectives　·　Next: Mechanism System

Related: Core Concepts & Architecture · Ruin Template · config.yml Full Configuration

---

Blueprint & Objectives covers "how to declare spawn points and stage objectives on disk." This page covers how they run at runtime: how a player's approach activates the ruin, how stages are tracked and advanced, how mobs respawn, when the ruin can't be damaged, and who is qualified to enter.

A single sentence runs through this whole page: QR does not instance, does not pull a separate world, and does not count down. The ruin grows right inside the main world and is activated by the player physically approaching—it is a "procedural Roguelike realm engine," not a dungeon plugin.

🖼️ [Image placeholder] A 4-state flow diagram of the anchor (DORMANT → ACTIVE → CLEARED → RECYCLED) with an activation-radius illustration　·　suggested assets/anchor-lifecycle.png

---

1. The anchor's 4 states

Every generated ruin instance is called an Anchor. All runtime gameplay hangs off the anchor. An anchor has 4 lifecycle states:

State	Meaning	Mobs / mechanisms	Protection
DORMANT	Generated, nobody nearby, dormant	Not spawned, not evaluated	Locked (if it has objectives)
ACTIVE	A player has entered the activation radius	Mobs spawned, objectives counting, mechanisms evaluating	Locked
CLEARED	Cleared / fully explored	Mobs cleared, chests unlocked	Lifted
RECYCLED	Recycled (faded & restored / /qr remove), slot freed	Cleaned up	—

Template vs anchor: one template can generate many anchors (the same ruin in various places in the world), just like one class news many objects. See Core Concepts.

State transitions:

  Generate → DORMANT
            │ Player enters activation-radius
            ▼
          ACTIVE ──── Clear the final stage's objective ────► CLEARED
            ▲                                                    │
            │ respawn (mobs cleared & cooldown passed)           │ After regen-hours with nobody nearby, snapshot restored
            └────────────────────────────────────────────────► RECYCLED

---

2. Anchor activation & spawning (approach-activated, not instanced)

QR does not pull players into a separate instance. It periodically scans, in the background, the anchors near all online players, and the moment a player physically walks into the activation radius that anchor is activated and starts spawning.

The relevant config is in the combat section of config.yml:

# Spawning (structure content, auto-activated by player proximity, non-instanced)
combat:
  activation-radius: 48     # Player entering this radius activates the anchor's spawning
  spawn-period-ticks: 40    # Activation detection interval in ticks (larger = cheaper, minimum 10)

Config	Meaning	Default
combat.activation-radius	Within how many blocks of the anchor center a player activates spawning	48
combat.spawn-period-ticks	Activation-scan interval in ticks (larger = cheaper CPU, slower response, floor 10)	40

Behavior on activation:

• First activation: if the blueprint configured objectives, only stage: 1 spawn points spawn; without objectives, all spawn points spawn at once.
• The spawned mobs are tagged with the anchor marker (recording which anchor, which spawn point, and which mob key they belong to) and set to "won't despawn automatically when the player walks away," so kill counting can track accurately.
• The first time a player approaches a ruin of a given template, it is recorded as a personal codex discovery and the player receives a "ruin discovered" prompt.
• Realm-state anchors have their spawning managed separately by the realm system and do not go through this ordinary spawning logic.

⚙️ The activation radius, the mechanism scan radius (mechanisms.scan-radius, default 48), and the session muster radius (session.enter-radius, default 48) are independent configs and can be tuned separately.

---

3. Staged objective tracking & advancement

As long as the blueprint configured objectives.stages, this ruin has stage-based clearing. At runtime it tracks as follows:

1. On activation the anchor starts from stage 1 and spawns the stage: 1 mobs.
2. The player kills mobs bearing this anchor's marker, accumulating the kill count for that stage by mob key (while also recording each player's individual contribution).
3. When all conditions in the current stage's kills are met → advance:
   • If there's a next stage: stage number +1, spawn that stage's mobs, full-screen on-screen text + sound announcing the new stage name (using the name in objectives), and fire that stage's STAGE mechanisms.
   • If it's already the final stage: the whole ruin is cleared, the anchor transitions to CLEARED, the clear title is announced, the post-clear mechanisms fire, and the purification slot-machine reward is dispensed.

Key points:

• Only counts mobs this anchor spawned. Wild mobs the player kills in passing within the ruin's range don't count (they have no anchor marker).
• The kill key must match how mob is written in spawn-points (vanilla name / mm- prefix), or the count won't line up. See Blueprint & Objectives §6.
• Stage advancement is anchor-shared progress (not per-player), suitable for multiplayer co-op clearing.

🧩 An alternative clear path: the final boss gate (boss-gate). Besides staging, you can use the playstyle of "kill a cumulative count of counted mobs → unlock and spawn a final boss → defeat it to clear," which is more straightforward to configure. It is mutually exclusive with the objectives staging. See Blueprints & Objectives · boss-gate.

🖼️ [Image placeholder] Stage-advance on-screen text + bossbar progress illustration　·　suggested assets/stage-advance.png

---

4. respawn (spawning reset)

An activated ruin doesn't stay empty forever. Whether it respawns is controlled by the template template.yml's respawn (not in the blueprint). It only respawns another wave once all conditions are met:

1. This anchor has spawned before (has been activated);
2. The template respawn seconds is > 0 (set to 0 = never respawn, spawns once and stays empty);
3. The mobs this anchor previously spawned are all dead (won't respawn while there are still live mobs, to avoid pileup);
4. More than respawn seconds have passed since the last spawn (cooldown elapsed).

Once met, it respawns a wave per the current activation logic (from stage 1 if objectives are configured). This makes the ruin behave like a "world structure that recovers naturally," rather than a one-shot dungeon.

Tip

To make a ruin "empty out once cleared, never revive," set the template's respawn to 0. To make it recover every few minutes, set the corresponding seconds. respawn is a template field; see Ruin Template.

In addition, when the QR plugin stops / reloads, it proactively removes all the still-alive tagged mobs it spawned, to avoid leftover mob pileup.

---

5. Protection system (no breaking / placing during exploration / activation)

To keep a ruin intact while it's "being attempted," QR has built-in protection: a ruin in the locked state cannot be broken or have blocks placed.

Configured in the protection section of config.yml:

# Ruin protection: no breaking/placing during exploration/activation, unlocked after clearing
protection:
  enabled: true   # Master switch

When does it count as "locked"

An anchor is locked (no breaking / placing) if it meets any of these conditions:

• It is in realm state (Realm active); or
• It has kill objectives and is not yet cleared (configured objectives and hasn't reached CLEARED).

Conversely: a pure-exploration ruin with no objectives is not locked by default; a ruin with objectives is automatically unlocked after clearing, and players can freely remodel the cleared ruin.

Exceptions (still breakable / placeable while locked)

Exception	Notes
Admins	Players with the qinhruins.admin permission are not subject to protection limits (convenient for debugging / fixing structures)
Mechanism trigger blocks	The block used as a trigger by a BLOCK_BREAK mechanism is allowed to be mined—otherwise the "dig through a wall to trigger a mechanism" play would be impossible

Caution

Protection is judged by whether a block falls within the anchor structure's bounding box. If a sub-structure variant is stamped outside the main structure's bounding box, the overflowing part is unprotected, and the /qr remove snapshot can't restore it either; when configuring variants, take care to keep them within the main structure's range (see Procedural Generation).

---

6. Entry threshold (soft threshold, non-instanced)

entry is the soft threshold for "whether you're qualified to operate in this ruin," written in the template template.yml (not in the blueprint).

Caution

Key understanding: QR does not instance, does not open a separate world. So entry is not a "dungeon entrance gate"—it's a set of "soft conditions / hints" expressing "how many people, what class, and what growth this ruin expects." It won't bar unqualified people at a portal like a dungeon plugin, because there is no portal at all.

# —— Entry threshold (QR doesn't instance; this is the "qualified to operate here" soft threshold) ——
entry:
  min-players: 1
  max-players: 10
  # required-classes: [warrior]  # Classes required to be present (QinhClass)
  min-growth: 0.0                # Minimum growth
  # cost: "100"                  # Entry cost (economy)
  cooldown: 0s

Field	Meaning	Default / example
min-players	Expected minimum players present	1
max-players	Expected maximum players present	10
required-classes	Classes required to be present (integrates with the QinhClass class system)	Omitted = unrestricted, e.g. [warrior]
min-growth	Minimum growth threshold	0.0
cost	Entry cost (integrates with an economy plugin)	Omitted = free, e.g. "100"
cooldown	Entry cooldown	0s (e.g. 30s / 5m / 1h)

Tip

Growth is QR's unified concept that bridges the QinhClass / MMOCore level systems or built-in progression, and is also used to scale loot by growth. min-growth makes "a high-difficulty ruin only friendly to strong enough players."

---

7. Common combinations cheat sheet

Play you want	How to configure
Pure-exploration ruin (no spawning, no clearing)	Don't write spawn-points / objectives in the blueprint; protection unlocked by default
One-shot spawn points (empty once cleared)	Write spawn-points, not objectives; template respawn: 0
A recovering spawn camp	Write spawn-points, template respawn: 600 (respawn every 10 minutes)
Multi-stage dungeon-style ruin	Write spawn-points (tagged with stage) + objectives.stages; clearing unlocks loot-chests
High-difficulty restricted ruin	Set thresholds via the template's entry.min-growth / required-classes

---

Next steps

• Add mechanisms to a ruin (open door / pressure-plate ambush / stage teleport) → Mechanism System
• Review of blueprint fields → Blueprint & Objectives
• The template's respawn / entry / loot / reward fields → Ruin Template
• The keystone and realm after clearing → Keystone & Realm