Previous: READMEใยทใNext: Installation
๐ Overview โ
๐งญ One-Sentence Positioning โ
QinhCoreLib (QCL for short) is the core foundation / platform library of the "Qinhuai Ecosystem". It does not implement any specific gameplay itself; instead, it provides a complete set of unified capabilities to upper-layer gameplay plugins and third-party plugins: item sources, economy, scripts, databases, PDC (persistent data), placeholders, GUIs, action contracts, bridge status, and diagnostics.
Main class: com.qinhuai.corelib.QinhCoreLibใยทใVersion: 1.2.0
๐ก One-sentence understanding: QCL is the "utilities (water/electricity/gas)", while QI/QS/QF/QSt are the "houses" built on top of it. Installing QCL alone adds no gameplay, but without it, not a single Qinhuai gameplay plugin can run.
๐๏ธ Its Place in the Ecosystem โ
QCL sits at the very bottom of the ecosystem. All Qinhuai gameplay plugins hard-depend on it, while third-party plugins are "pulled in" and used uniformly through the bridges it provides.
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ QI Items โ QS Skills โ QF Forge โ QSt Strengthen โ QCR โ โ Gameplay layer (hard-depends on QCL)
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ hard dependency
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ QinhCoreLib (QCL) โ โ Foundation layer
โ item source ยท economy ยท script ยท database ยท PDC ยท placeholder โ
โ GUI ยท action contract ยท bridge status ยท diagnostics โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ soft dependency (reflection bridge, auto-skipped if not installed)
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Vault ยท PlaceholderAPI ยท ModelEngine ยท ... โ โ Third-party layer
โ MMOItems ยท NeigeItems ยท ItemsAdder ยท Nexo... โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ๐ Relationship with Modules / Third Parties โ
| Relationship Type | Target | Description |
|---|---|---|
| Hard dependency (QCL required) | QinhItems(QI), QinhSkills(QS), QinhForge(QF), QinhStrengthen(QSt), QCR | These gameplay plugins cannot load without QCL |
| Soft dependency (bridged only if installed) | Vault, ExcellentEconomy, PlayerPoints, PlaceholderAPI, ModelEngine, CustomCrops, CustomFishing, MythicMobs, NeigeItems, MMOItems, CraftEngine, QinhItems, MagicGem, ItemsAdder, Nexo | All reflection bridges; auto-skipped if not installed, no errors |
| Collaboration contract | QI โ QS | QI's item actions hand skill casting over to QS via QCL's QISkillUseEvent / QinhActionHandler (handlerId qinhskills:cast) |
For each module's disk paths and division of responsibilities, see the ecosystem overview document. This series of docs only covers QCL itself.
โ What It Can Do (Typical Scenarios) โ
| Capability | Scenario Example | See |
|---|---|---|
| ๐ก๏ธ Native attribute system | A full attribute & damage system without any attribute plugin (attack / crit / defense / dodge / elements), with custom attributes (yml + JS scripts) | Attribute System |
| ๐ฏ Unified item source | Unifies items from 10 sources such as MythicMobs, MMOItems, ItemsAdder, Nexo, and QI into a single set of reference strings (e.g. mm-้พๅ, mi-SWORD-็็ฐๅ, qi:็ฅๅ), which any sub-plugin can copy and use directly | Item Source Reference |
| ๐ฐ Cross-plugin economy | One economy API simultaneously compatible with Vault / ExcellentEconomy / PlayerPoints, so sub-plugins don't each need their own adapters | Economy Actions |
| ๐ผ๏ธ Custom GUI | Draw interfaces with YAML in the guis/ directory, configure actions and conditions, no code needed | Custom GUI |
| ๐ Scripting capability | Built-in GraalJS / Groovy script engines for writing diagnostics, actions, and external item modules | Scripting Getting Started |
| ๐ฉบ Diagnostics & troubleshooting | A single /qcl status reveals the entire ecosystem's health status, bridge situation, and health codes | Diagnostics & Troubleshooting |
| ๐งฑ Custom blocks | A unified block abstraction, bridging ModelEngine / CraftEngine, etc. | Custom Blocks |
๐ซ What It Doesn't Do โ
QCL is a platform library, deliberately leaving "gameplay" to upper-layer plugins. The following are things it does not do at all:
| Doesn't Do | Who Does It |
|---|---|
| โ Doesn't design specific gameplay numbers (how much each item grants, how skills deal damage) | Decided by gameplay modules like QI / QS (QCL provides the attribute pipeline & native resolution; AttributePlus etc. are optional backends) |
| โ Doesn't define the item core (how an item's attributes, lore entries, and crafting are calculated) | QinhItems(QI) |
| โ Doesn't implement skill logic | QinhSkills(QS) |
| โ Doesn't implement forging / strengthening gameplay | QinhForge(QF) / QinhStrengthen(QSt) |
๐งฉ Design principle: QCL only provides "capability contracts" and "unified pipelines"; it doesn't make decisions for the gameplay. This ensures each gameplay plugin can evolve independently without being locked to the foundation.
๐บ๏ธ Which Chapter Should I Read? โ
| Who You Are / What You Want | Recommended Reading |
|---|---|
| ๐ Just got the jar, want to run it first | Installation โ Quick Start |
| ๐ง Want to understand its overall design | Core Concepts |
| ๐ ๏ธ Server owner: config / commands / item sources / GUI | The whole 02-Server Owner Guide chapter |
| ๐ Something broke, need to troubleshoot | Diagnostics & Troubleshooting, Diagnostic Codes |
| ๐ Want to integrate external plugins | 03-External Plugin Integration |
| ๐จโ๐ป Developer: call API / write scripts | The whole 04-Developers chapter |
| โ Don't understand a term / common questions | Glossary, FAQ |
๐ Continue Reading โ
- Next: Installation โ Environment requirements and installation steps
- Core Concepts โ Modules, bridges, item sources, diagnostics, API boundaries
- Quick Start โ The first thing to do after installation