Full config.yml Reference
In: Reference · Related: Natural Generation & Preloading · Realms & Keystones · Guide & Codex · Back: Home
A quick reference to every field in plugins/QinhRuins/config.yml. Changes take effect with /qr reload. This page is a field reference; in-depth gameplay explanations link to the matching server guide. Verified field by field against the source's built-in config.yml.
All YAML paths are relative to
plugins/QinhRuins/by default. Player-facing text is not in this file — it lives inlang/<language>/*.yml.
Top level
| Field | Default | Description |
|---|---|---|
config-version | 1 | Config version baseline; do not edit by hand (used for automatic migration on future structural upgrades) |
language | zh_cn | Language folder name; one of the 7 built-ins or your own. Missing keys fall back to en_US. See Bundled Content List |
storage — storage backend
yaml
storage:
type: yaml # yaml | database| Value | Meaning |
|---|---|
yaml (default) | Enough for single-server use, zero configuration |
database | Reuse QinhCoreLib's database (SQLite / MySQL is configured in QCL's config.yml; QR does not configure a database separately). The legacy values sqlite/mysql are also treated as database |
Only player codex discoveries go to the database (point a group of servers at the same MySQL and it is shared cross-server); world-coordinate-bound data such as anchors / chest claims / slot machines always stays in local YAML. See Data Storage.
guide — guidance system
Right-click guide item → confirm GUI → consume 1 and start compass guidance. For gameplay details see Guide & Codex.
| Field | Default | Description |
|---|---|---|
display | title | Display mode: title (title at upper-center of screen) / actionbar (above the hotbar) / none (handed off to a HUD plugin, paired with placeholders) |
title | §e◈ {ruin} | Main title in title mode (placeholders {ruin} {distance} {direction} {world}) |
subtitle | §f{distance}m §7{direction} | Subtitle in title mode |
actionbar | §e{ruin} §f{distance}m §7{direction} | Text in actionbar mode |
not-found | — | Hint shown when the target can't be temporarily resolved en route |
other-world | — | Hint shown when the target is in another world |
search-fail | — | Hint shown when there is no target in range when guidance starts |
search-radius | 10000 | Guidance search radius (blocks). Too large lags the server during map search; tune as needed |
discover-radius | 48 | Entering this radius = arrival: permanently consume the guide item, end guidance |
refresh-ticks | 10 | Distance / direction refresh interval in ticks (larger is cheaper) |
exit-action | swap | In-game action to exit guidance: swap (swap hands, F) / drop (drop, Q) / none. To use any key: bind that key on the client to /qr guide cancel |
guide.confirm — right-click confirm GUI
| Field | Default | Description |
|---|---|---|
title | Start guidance? | Confirm GUI title (can use an ItemsAdder :xxx: / CraftEngine <image:xxx> overlay) |
yes-name | §a✔ Confirm | Confirm button name |
no-name | §c✘ Cancel | Cancel button name |
guide.particle — direction particles
| Field | Default | Description |
|---|---|---|
enabled | true | Whether to draw direction particles |
type | SOUL_FIRE_FLAME | Particle type (any vanilla particle name; DUST uses the colors below) |
points | 6 | Number of direction particle points (fewer is cheaper) |
size | 1.0 | Particle size (DUST only) |
min-distance | 2 | Below this distance, stop drawing |
near-distance | 32 | Below this distance, use near-color (DUST only) |
near-color | GOLD | Color when close (DUST only) |
far-color | AQUA | Color when far (DUST only) |
HUD placeholders (require PlaceholderAPI):
%qinhruins_guide_active%/_ruin/_distance/_direction/_world. See Placeholders.
realm — realms (affix × tier endgame)
For gameplay details see Realms & Keystones · Affix System.
realm.tiers — tier curves (expression variable tier)
| Field | Default | Description |
|---|---|---|
max | 16 | Maximum tier |
affix-count | 1 + tier / 3 | Number of affixes per tier (expression) |
mob-level | tier * 5 | Mob level curve |
loot-bonus | 1 + tier * 0.1 | Cleanse loot quantity multiplier (scales by tier, multiplies with greed; write 1 to disable per-tier bonus) |
danger-budget | 40 + tier * 10 | Danger budget cap (caps the sum of affix danger, preventing low-tier hellstacks; ≤0=unlimited. The first affix is always guaranteed) |
realm.keystone — keystone appearance
Right-click a keystone = activate a realm (vanilla behaviors like ender-eye flight are suppressed).
| Field | Default | Description |
|---|---|---|
material | minecraft:ender_eye | Keystone material; supports any item source (craftengine:/itemsadder:/nexo:/qinhitems:/mmoitems:type:id/neigeitems:/mythicmobs:) |
name | &dRealm Keystone &7T{tier} | Name ({tier}=tier; applies only to vanilla materials; for other item sources the source's own name/lore is kept; leave empty "" to leave even vanilla materials unrenamed) |
lore | (one line) | Lore (same rules as name) |
model-data | 0 | CustomModelData |
For a custom-item keystone to show its tier: write
%qinhruins_keystone_tier%in its own name/lore (requires PlaceholderAPI).
realm.reward — cleanse reward
Exclusive loot outside the keystone ladder, handed out privately per participant.
| Field | Default | Description |
|---|---|---|
loot-table | realm | Exclusive loot table name (loottables/<name>.yml) |
per-tier-table | false | When true, prefer realm_t{tier}, falling back to loot-table if missing |
growth-scaled | true | Personal drop quantity scales by growth |
currency-base | tier * 100 | Base currency per participant (expression, 0=disabled, requires an economy plugin) |
currency-provider | "" | Economy backend: empty=auto / vault / excellenteconomy (ee) / playerpoints |
currency-id | "" | Currency ID (required for ExcellentEconomy, e.g. money/silver/gold; leave empty for Vault/PP) |
realm.reroll — keystone reroll / gambling
Spend currency to re-roll keystone affixes, then activate once satisfied.
| Field | Default | Description |
|---|---|---|
enabled | true | When off, /qr reroll is unavailable and affixes are blind-box rolled only at the moment of activation |
cost-base | tier * 50 | Cost per reroll (expression, requires an economy plugin) |
currency-provider | "" | Same as reward |
currency-id | "" | Same as reward |
realm — others
| Field | Default | Description |
|---|---|---|
failure.consume-keystone | false | Whether failure consumes the keystone (can be overridden per tier; true recommended for high tiers) |
activate-radius | 48 | Radius /qr activate searches for nearby ruins |
abandon-seconds | 120 | How long with no players around a realm before it's deemed abandoned (clears mobs and resets, preventing persistent-mob buildup) |
time-limit | "0" | Realm time limit (seconds); 0=unlimited (more like a world structure) |
keystone-chance | 0.5 | Chance to drop a same-tier keystone after cleansing (goes straight into the inventory, 0~1) |
next-tier-chance | 0.2 | Extra chance to drop a one-tier-higher keystone after cleansing (the ladder engine) |
bossbar-color | PURPLE | Realm bossbar color |
bossbar-style | SEGMENTED_10 | Realm bossbar style |
mechanisms — programmable mechanisms
Pure world interactions of trigger→action inside a blueprint. For gameplay see Mechanism System.
| Field | Default | Description |
|---|---|---|
enabled | true | Master switch |
scan-radius | 48 | Scan radius for area / timer triggers (evaluated only when a player is within this range) |
period-ticks | 10 | Evaluation interval in ticks for area / timer triggers |
max-fill-volume | 20000 | Maximum blocks per fill action (prevents server lag) |
vessel — container loot
Place a vanilla container in the structure and it works automatically, rolling rewards independently per player. For gameplay see Loot System.
| Field | Default | Description |
|---|---|---|
enabled | true | Master switch |
refresh-mode | per-player-once | per-player-once (once per person) / timed (can re-open and re-roll after a cooldown) |
refresh-cooldown | 30m | Cooldown in timed mode (30m/1h/…) |
rows | 3 | Number of rows in the container interface (1-6) |
Container ownership is determined automatically by the structure's footprint (no radius needed); which table to use is specified by the template's
loot.container-table.
protection — ruin protection
| Field | Default | Description |
|---|---|---|
enabled | true | While exploring / activating, placed blocks cannot be broken; unlocked after clearing. Admins (qinhruins.admin) and "dig-through" mechanism trigger blocks are exempt |
See Spawning & Clearing.
cleanup — removal / cleanup
| Field | Default | Description |
|---|---|---|
snapshot-restore | true | Snapshot the original terrain before generating a structure, restored on /qr remove / regen (disabling saves disk but means removal won't restore blocks) |
max-snapshot-volume | 500000 | Snapshot volume cap (block count): above this, skip the snapshot (removal won't restore but won't lag). 0=unlimited (dangerous) |
staging — preview staging
/qr stage previews with ghost blocks before placing.
| Field | Default | Description |
|---|---|---|
preview-cap | 12000 | Ghost-block preview cap: above this, only a particle border is drawn. Raise it to preview larger structures |
generation — world generation
For gameplay details see Natural Generation & Preloading.
| Field | Default | Description |
|---|---|---|
enabled | true | Master switch for natural generation (when off, ruins can only be placed manually with /qr spawn) |
grid-bucket-size | 512 | Spatial index bucket size |
max-per-tick | 4 | Maximum candidate chunks processed per pass (throttle) |
max-millis-per-tick | 3 | Millisecond budget per pass: yield the tick once this is exceeded (handles load, smooths spikes) |
period-ticks | 5 | Interval in ticks between candidate-processing tasks |
spread-place-threshold | 30000 | If a structure exceeds this block count and has NONE orientation → place across frames in the background (no server freeze). Small structures still place in one shot natively |
paste-millis-per-tick | 8 | Per-tick millisecond budget for frame-sliced placement / marker cleanup: yields the tick once pasting exceeds it (wall-clock time slicing, adaptive to load, more resilient than a fixed block count). At least 1024 blocks/tick are guaranteed |
marker-blocks | true | Automatic schematic marker-block handling: barrier → cleared to air on placement; bedrock → keep original terrain, no overwrite (terrain shows through the marker). false=place as-is |
generation.director — director
| Field | Default | Description |
|---|---|---|
enabled | true | When on, the director takes over: all ruins compete in a weighted draw and are constrained by global density. When off, falls back to the old behavior of "each template rolls independently by probability" |
notify-admins | true | Privately message online admins the coordinates (with /qr tp) whenever any ruin generates naturally. A debug godsend for finding ruins |
chunk-chance | 80 | The denominator of the chance a new chunk attempts generation (1/N per chunk; 0=exploration spawns nothing actively, relying purely on live) |
generation.director.live — living world
New ruins emerge over time even in already-explored worlds.
| Field | Default | Description |
|---|---|---|
enabled | true | Living world switch |
interval | 10m | How often it attempts around online players (the refresh interval; 1m/30s for debugging) |
chance | 0.25 | Chance per player per attempt |
min-radius | 80 | Inner radius of the placement ring (keeps away from underfoot) |
max-radius | 220 | Outer radius of the placement ring (slightly beyond view distance) |
generation.director.density — global density
| Field | Default | Description |
|---|---|---|
region-size | 512 | Side length of the density-counting square |
max-per-region | 3 | Maximum ruins per square (0=unlimited) |
min-spacing | 48 | Minimum spacing between any two ruins (0=unlimited) |
generation.director — others
| Field | Default | Description |
|---|---|---|
regen-hours | 24 | How many hours after a ruin is cleared before it regens (snapshot-restored and slot-freed when no one is nearby; 0=never regen; true regen requires cleanup.snapshot-restore on) |
weights | [] | Ruin weighted-draw table (- { template: id, weight: 30 }); empty=auto-derive from each template's probability |
combat — spawning
Structure contents activate automatically when a player approaches (not instanced). See Spawning & Clearing.
| Field | Default | Description |
|---|---|---|
activation-radius | 48 | A player entering this radius activates the anchor's spawning |
spawn-period-ticks | 40 | Activation-check interval in ticks |
session — session
Enter / exit / bossbar. See Party & Session.
| Field | Default | Description |
|---|---|---|
enter-radius | 48 | Radius for searching nearby anchors; teammates must also be within this range to count as rallied |
bossbar | true | Whether to show the session bossbar |
bossbar-color | PURPLE | PINK/BLUE/RED/GREEN/YELLOW/PURPLE/WHITE |
bossbar-style | SOLID | SOLID/SEGMENTED_6/SEGMENTED_10/SEGMENTED_12/SEGMENTED_20 |
Other runtime data files
Beyond config.yml, QR also loads content from these files — see Resource Files Overview:
| Path | Content |
|---|---|
generators/*.yml | Placement profiles (17 built-in) |
templates/<id>/ | Ruin templates + blueprints + structure files |
palettes/*.yml | Procedural assembly palettes |
loottables/*.yml | Loot tables (default / vault / realm) |
affixes.yml | Affix library (13 built-in enabled) |
scripts/*.js | Affix JS scripts |
lang/<language>/*.yml | Multilingual text (7 built-in) |
schematics/*.schem | WorldEdit files awaiting /qr import |
anchors.yml | Anchor instance data (generated at runtime, do not edit by hand) |