Guide & Codex

In: Server Owner Guide　·　Related: Ruin Templates · Loot System · Placeholders · Command Reference

These two systems serve the player's exploration experience:

Guide — the player holds a "guide item" and right-clicks, and it leads them, compass-style, to the nearest ruin of the same kind;
Codex — ruins the player has discovered are recorded in a strategy card book, viewable with /qr codex for spawn, loot, and coordinate clues.

🖼️ [Image placeholder] A screen mid-guidance (title + directional particles pointing to a distant ruin)　·　suggested assets/guide-hud.png

1. Guide (Direction System)

1.1 The Full Flow of One Guidance

text

Player right-clicks the guide item
   │
   ▼
A "confirmation GUI" pops up (Yes / No)
   │ choose "Yes"
   ▼
Deduct 1 guide item → start guidance
   │
   ▼
Refresh every few ticks: the screen shows target name / distance / direction + directional particles
   │
   ├─ walk into discover-radius ─→ Arrived! Recorded in the codex, sound played, guidance ends (guide item permanently deducted)
   │
   └─ canceled midway (swap key/drop key/world change/disconnect) ─→ that 1 guide item is refunded

🔑 Design point: the item is permanently consumed only on arrival; ending midway for any reason returns the guide item to the player, never letting them lose it for nothing.

1.2 Where the Guide Item Comes From (QR Has No Built-in give)

The guide item is not dispensed by QR — it's an item carrying a special tag, whose tag ID is:

qinhruins:guide_<template id>

It's given to the player by an item source (any channel referencing this ID: QinhItems recipes/loot tables/shops//qi give etc.). For example, to let a ruin's guide item be bought from a shop or dispensed as a quest reward, reference qinhruins:guide_ancient_tower over there.

The guide item's appearance (material/name/Lore/custom model) is defined in the guide item config of the template's template.yml; on right-click QR reads the template tag on it to find the nearest instance of that template to guide to. Binding to a specific ruin instance (anchor) is also supported.

1.3 Config (the guide Section of config.yml)

yaml

guide:
  display: title              # title=upper-center screen title | actionbar=above the hotbar | none=show nothing (hand off to a HUD plugin)
  # built-in text templates (placeholders: {ruin} {distance} {direction} {world})
  title: "§e◈ {ruin}"                                   # main title for title mode
  subtitle: "§f{distance}m  §7{direction}"               # subtitle for title mode
  actionbar: "§e{ruin} §f{distance}m  §7{direction}"     # actionbar mode
  not-found: "§7Target ruin temporarily lost…"           # target temporarily unresolvable mid-guidance
  other-world: "§e{ruin} §7is in another world"          # target in a different world
  search-fail: "§cNo such ruin within {radius} blocks"   # no target in range when starting
  search-radius: 10000        # guidance search radius (blocks): too large lags the server on a big map; tune as needed
  discover-radius: 48         # entering this radius = arrival: permanently consume the item, end guidance
  refresh-ticks: 10           # distance/direction refresh interval in ticks (larger = lighter)
  exit-action: swap           # the in-game action to exit guidance: swap | drop | none
  confirm:                    # right-click confirmation GUI
    title: "Start guidance?"
    yes-name: "§a✔ Confirm"
    no-name: "§c✘ Cancel"
  particle:                   # directional particles (see §1.6)
    enabled: true
    type: SOUL_FIRE_FLAME
    points: 6
    size: 1.0
    min-distance: 2
    near-distance: 32
    near-color: GOLD
    far-color: AQUA

1.4 Display Mode `display`

Value	Effect
`title` (default)	Upper-center screen title + subtitle, using the `title` / `subtitle` templates
`actionbar`	A line above the hotbar, using the `actionbar` template
`none`	QR shows no built-in text — hands it off to your HUD plugin (BetterHud etc.) for free layout via placeholders

In the text templates you can use {ruin} (target name) {distance} (remaining blocks) {direction} (direction) {world} (target world).

1.5 Placeholders (for HUD Plugins)

Set display to none and use the following placeholders (require PlaceholderAPI) to lay out your own HUD:

Placeholder	Meaning
`%qinhruins_guide_active%`	Whether guidance is active (`true`/`false`) — the HUD shows/hides based on this
`%qinhruins_guide_ruin%`	Target ruin name
`%qinhruins_guide_distance%`	Remaining distance (blocks)
`%qinhruins_guide_direction%`	Direction (E/SW/…, 8 directions)
`%qinhruins_guide_world%`	The world the target is in

For the full placeholder set see Placeholders.

1.6 Directional Particles `particle`

Spray a trail of particles toward the target in the player's line of sight, as an "arrow":

Key	Description
`enabled`	Master switch
`type`	Particle type: `SOUL_FIRE_FLAME` / `FLAME` / `END_ROD` / `HAPPY_VILLAGER` / `DUST` (uses the colors below) / …any vanilla particle name
`points`	Number of directional particle points (fewer = lighter)
`size`	Particle size (only takes effect for `DUST`)
`min-distance`	Below this distance, directional particles are no longer drawn (already very close)
`near-distance`	Below this distance use `near-color` (only `DUST`)
`near-color` / `far-color`	Particle color when near / far (only `DUST`): `GOLD` `AQUA` `RED` `GREEN` `BLUE` `YELLOW` `ORANGE` `PURPLE` `LIME` `WHITE`

For a "more gold the closer, more blue the farther" gradient hint, set type to DUST and configure near-color / far-color.

1.7 Cancel Guidance `exit-action`

The way to actively exit guidance in-game:

Value	Corresponding key
`swap` (default)	Swap key (default F)
`drop`	Drop key (default Q)
`none`	Binds no gesture key

To cancel with any key (e.g. K): bind that key in your client keybindings / HUD plugin to the command /qr guide cancel — this command works under any exit-action.

In addition, these situations automatically cancel and refund the guide item: world change, disconnect/reconnect. When the target instance is temporarily not found mid-guidance (recycled/unloaded), the not-found text is shown, and it resumes once the target becomes reachable again.

Command	Permission	Effect
`/qr guide cancel`	`qinhruins.use`	Player cancels their own current guidance (refunds the guide item)
`/qr guide clear <player>`	`qinhruins.admin`	Admin force-clears a player's guidance (refunds the guide item if online)

Note

QR has no dispense command like /qr guide give — the guide item is always given by an item source referencing qinhruins:guide_<template id> (see §1.2).

2. Codex

2.1 What It Is

Ruins the player has discovered are automatically recorded into a codex. /qr codex opens a 54-slot card book: discovered ruins show a strategy card, undiscovered ones show "❓ Unknown Ruin".

The trigger of "discovery": when a player is guided and arrives at a ruin, that template and that instance are automatically recorded into the codex (see the arrival step in §1.1).

2.2 What's on a Strategy Card

Each discovered card (hover with the mouse to see the Lore) summarizes that ruin's key intel:

Location clues: dimension (Overworld/Nether/End, or the specific world) + spawn layer (surface/underground/sky/sea level/seabed/fixed Y);
Spawn intel: total spawn count, refresh cooldown, plus the possible mobs and their probabilities, marked with rarity by share (Common ≥35% / Rare ≥20% / Elite for the rest);
Loot strategy: split into three columns "Container / Reward Chest / Clear", each listing the top few outputs (taken from the loot tables that template references).

🖼️ [Image placeholder] Codex GUI (discovered cards + unknown-ruin slots + the progress book at the bottom)　·　suggested assets/codex-gui.png

The "Ruin Codex" book at the bottom center shows the total collection progress Discovered X / Total Y. When there are more than 45 templates, only the first 45 are shown (GUI capacity limit).

Single-machine/single-server: codex discovery records are stored in local YAML, usable with zero config.
Networked servers (BungeeCord/Velocity) wanting a shared codex across servers: set config.yml's storage.type to database, and point each backend's QinhCoreLib at the same MySQL, so players' codex discoveries are naturally shared across sub-servers.

Note

Only codex discoveries (per player) go into the database; data bound to specific server-world coordinates — anchors, chest collection records, slot machine eligibility, etc. — stay in each server's local YAML (as they should). See Data Storage for details.

Command	Permission	Effect
`/qr codex`	`qinhruins.use`	Open your own ruin codex

Next Steps

Ruin Templates: configure the guide item appearance, the spawn layer (which decides the location clue in the codex)
Loot System: the loot on a strategy card comes from here
Party & Session: entry hints, party-shared progress
Placeholders: all guide / exploration placeholders

Guide & Codex ​

1. Guide (Direction System) ​

1.1 The Full Flow of One Guidance ​

1.2 Where the Guide Item Comes From (QR Has No Built-in give) ​

1.3 Config (the guide Section of config.yml) ​

1.4 Display Mode display ​

1.5 Placeholders (for HUD Plugins) ​

1.6 Directional Particles particle ​

1.7 Cancel Guidance exit-action ​

1.8 Related Commands ​

2. Codex ​

2.1 What It Is ​

2.2 What's on a Strategy Card ​

2.3 Cross-Server Sharing ​

2.4 Related Commands ​

Next Steps ​