QinhRuins

What is QinhRuins?
QinhRuins (QR) makes structures naturally appear in your world — players exploring stumble onto an ancient tower, a sunken tomb, a floating sky island. Walk close: mobs activate, mechanisms run, chests roll loot per-player. Clear it, and you can slot in a Keystone to inject affixes and turn it into a tiered Realm endgame.

QR is not a dungeon plugin. It does not pull players into a separate world and does not run a countdown. The ruin lives in your main world, is part of it, and after clearing it fades over time to free a slot for a new one — a living, breathing world.



✨ Core Features

• Procedural natural generation — ruins spawn by weighted draw in new chunks or already-explored worlds, bounded by global density, minimum spacing, flatness, and biome / dimension / world filters.
• Generation Director — one scheduler runs weighted competition across all ruins, living-world periodic refresh, and post-clear terrain fade & regen.
• ️ Terrain-fusion placement — mask pasting (blend into terrain, no bulldozing), foundation fill + edge blending, marker blocks (barrier → carve-out / bedrock → terrain show-through), frame-spread placement to avoid lag spikes.
• Blueprint gameplay layer — lay spawn points, staged kill objectives, unlock chests, a ruin core, and programmable mechanisms over the same structure.
• ⚙️ Programmable mechanisms — 6 trigger types (redstone / interact / region / timer / stage / break) × 12 actions (fill / spawn / teleport / give / loot / NPC…).
• ️ Final Boss Gate — kill a cumulative count of designated mobs (vanilla and MythicMobs) to unlock and spawn the final boss; an alternative, simpler clear path to staged objectives.
• Realm endgame — right-click a ruin core with a Keystone to inject tier + affixes; higher tiers = deadlier and richer; with reroll gambling, purification rewards, and a keystone ladder.
• Affix system — five categories (quantity / level / environment / rule / loot), bounded by a danger budget, mutually-exclusive groups, customizable via command / JS script.
• Loot system — container loot (per-player roll or server-shared), unlock chests, purification slot-machine, growth scaling, conditional groups, stacks on vanilla loot tables.
• Guides & Codex — a guide item right-clicks to point a compass at the nearest ruin of the same kind (HUD / particles / title); discovering a ruin records a codex card.
• Sub-structure variants & tile assembly — stamp weighted-random variant templates into slots (same body, different rooms / spires), and a Tile Palette assembles many small structures into one big ruin.
• ️ In-game visual editor — stand in the world, box-select, mark spawn points / chests / cores, wire mechanisms, save as a template — never touch YAML.
• Stable API + events + scripting — QinhRuinsAPI, lifecycle events, JS affix scripts, provider bridges, PlaceholderAPI.

️ How It Works: Recipe → Instance → Endgame
QR cleanly separates "the recipe" from "the instance it generates."

• Template (templates/<id>/) — a ruin's ID card: which structure, where to generate, what loot, entry thresholds.
• Placement Profile (generators/*.yml) — a reusable "where to generate" rule pack (dimension / biome / layer / spacing / probability). 17 built-in.
• Blueprint (blueprint.yml) — the gameplay layer stamped on the structure (spawns / objectives / chests / cores / mechanisms).
• Anchor — a real ruin instance generated from a template at a world coordinate, with lifecycle states DORMANT → ACTIVE → CLEARED → RECYCLED.

️ Final Boss Gate
A straightforward "kill counter → boss unlock" clear path. Set a cumulative kill threshold over a set of mobs (vanilla and MythicMobs mix freely); when reached, the final boss spawns automatically, and defeating it clears the ruin.
Live HUD via PlaceholderAPI: %qinhruins_boss_kills% / %qinhruins_boss_required% / %qinhruins_boss_remaining% / %qinhruins_boss_unlocked%.


Keystone Realm Endgame
Clearing a ruin is just the beginning. Hold a Keystone and right-click the ruin core → that very ruin is re-empowered into a Realm: mobs respawn stronger, rules rewrite, output upgrades — not a new world, the same ruin in place. Higher tiers stack more affixes (within a danger budget) for deadlier, richer runs, and keystones can drop with a tier ladder or be rerolled.



️ In-Game Visual Editor
No YAML required. Stand inside any build, box-select with /qr pos1 / pos2, mark spawn points / chests / cores, wire mechanisms with a wand, and save it all as a template in one command. Already have a build or a .schem? Import it with /qr import (auto-converts to Bukkit native .nbt — no FAWE needed).



Seven Languages
Interface, commands and messages are fully translatable, with auto-fallback to English. One line in config.yml:
English　 简体中文　 繁體中文　 Русский　 Français　 Tiếng Việt　 Español — edit lang/<language>/*.yml, no recompile.


Quick Start

1. Install QinhCoreLib first (hard dependency), then drop QinhRuins into plugins/
2. Start the server (requires Paper / Purpur / Spigot 1.21.11+, Java 25+)
3. Use the in-game editor or the bundled _example template to create your first ruin
4. /qr scatter to pre-generate, or just let players explore and find ruins naturally
5. /qr why / /qr gentest if something doesn't generate

Common Commands

Command	Function
/qr pos1 / pos2 / save	Box-select & save a build as a structure / template
/qr import	Convert & import a .schem to native .nbt
/qr scatter	Pre-generate ruins across an area
/qr keystone give	Give a realm keystone
/qr codex	Open the ruin codex / discovery album
/qr why / gentest	Diagnose why a ruin isn't generating
/qr reload	Reload configuration