PlaceholderAPI Placeholders

In: Developer　·　Same group: QinhRuinsAPI · Data Storage Related: Guides & Codex · Realms & Keystones

QR exposes ruin / realm / guide / progress state via PlaceholderAPI, for scoreboards, Tab, BossBar, HUD, etc. The placeholder identifier is qinhruins, with the unified format:

%qinhruins_<placeholder>%

Implemented in RuinPlaceholders (identifier = "qinhruins"). All placeholders are based on the ruin the player is currently in / near (most take "the nearest / containing" one); offline players return an empty string.

---

1. Keystone

Placeholder	Meaning	Return value
%qinhruins_keystone_tier%	Current keystone tier	During reforging, returns the tier being built; otherwise reads the main hand / offhand keystone tier; if neither, returns an empty string

---

2. Realm (realm_*)

Reads the active realm near the player. When there's no active realm, returns the defaults in the table below.

Placeholder	Meaning	When no realm
%qinhruins_realm_active%	Whether there's an active realm nearby	false (true if there is)
%qinhruins_realm_tier%	Realm tier	0
%qinhruins_realm_name%	Display name of the realm's ruin (template display, or template id if none)	empty string
%qinhruins_realm_affixes%	Affix name list (space-separated)	empty string
%qinhruins_realm_affix_count%	Affix count	empty string
%qinhruins_realm_mobs%	Currently alive mob count	0
%qinhruins_realm_total%	Total spawn count for this realm	0
%qinhruins_realm_time%	Remaining time min:sec (e.g. 4:05); returns ∞ if untimed	0

---

3. Guide (guide_*)

Reads the player's currently active guide (after right-clicking a guide item, the compass points to the nearest ruin of the same kind). See Guides & Codex.

Placeholder	Meaning	When no guide
%qinhruins_guide_active%	Whether there's an active guide	false (true if there is)
%qinhruins_guide_ruin%	Target ruin name	empty string
%qinhruins_guide_distance%	Distance to the target (blocks)	0
%qinhruins_guide_direction%	Direction (text like N/E/S/W)	empty string
%qinhruins_guide_world%	The target's world	empty string

---

4. Final boss gate (boss_*)

The placeholders below read the "final boss gate" progress of the nearest ruin near the player (see Blueprints & Objectives · boss-gate). When no boss-gate ruin is nearby: boss_active / boss_unlocked return false, the counts return 0.

Placeholder	Meaning	Value
%qinhruins_boss_active%	Whether a ruin with a final boss gate is nearby	false (true if so)
%qinhruins_boss_unlocked%	Whether the final boss is unlocked (has appeared)	true / false
%qinhruins_boss_kills%	Cumulative counted-mob kills so far	integer
%qinhruins_boss_required%	Cumulative kill threshold to unlock	integer
%qinhruins_boss_remaining%	Kills left to unlock (floored at 0)	integer

HUD progress-bar example: &cFinal Boss &7%qinhruins_boss_kills%/%qinhruins_boss_required% (once unlocked, %qinhruins_boss_unlocked% becomes true, so you can switch the display to "The boss has awakened").

---

5. Ruin progress (based on the nearest ruin)

The placeholders below read the nearest ruin's progress near the player (ObjectiveTracker.nearestProgress). When there's no ruin progress nearby: stage and kills_* return 0, the rest return an empty string.

Placeholder	Meaning	Return value
%qinhruins_ruin%	Ruin display name	Template display (or template id if none)
%qinhruins_stage%	Current stage ordinal	Integer (0 when no ruin)
%qinhruins_max_stage%	Total stage count	Integer
%qinhruins_stage_name%	Current stage name	Stage name / empty string
%qinhruins_completed%	Whether cleared	true / false
%qinhruins_objective%	Current stage's objective text	Each kill item mobName killed/needed, joined by ·; when cleared shows the clear text
%qinhruins_progress%	Progress (the first objective's done/needed)	E.g. 2/5; 100% when cleared
%qinhruins_kills_<mobKey>%	Player's kill count for a mob	Integer (0 if none)

The <mobKey> in kills_<mobKey> is the mob key in the blueprint's spawn points (e.g. kills_zombie). It reads that player's personal kill count in the current ruin.

---

6. HUD / scoreboard use cases

Scoreboard (exploration progress bar)

# Illustrative config for some scoreboard plugin
lines:
  - "&6Ruin: &f%qinhruins_ruin%"
  - "&eStage: &f%qinhruins_stage%/%qinhruins_max_stage% &7(%qinhruins_stage_name%)"
  - "&aObjective: &f%qinhruins_objective%"
  - "&bProgress: &f%qinhruins_progress%"

Realm BossBar / Tab

&cRealm T%qinhruins_realm_tier% &7| Affixes %qinhruins_realm_affixes% &7| Remaining %qinhruins_realm_time% &7| Alive %qinhruins_realm_mobs%/%qinhruins_realm_total%

Guide HUD

&6Guiding &7→ &f%qinhruins_guide_ruin% &7(%qinhruins_guide_distance% blocks %qinhruins_guide_direction%)

For conditional display (e.g. "show the realm line only when %qinhruins_realm_active% is true"), use your scoreboard plugin's built-in conditional syntax with this placeholder.

---

Next

• Guides & Codex — the guide / codex gameplay
• Realms & Keystones — realm tier / affix sources