Previous: Quick Start · Next: Configuration File
🧩 Core Concepts
Understanding QCL comes down to understanding its 5 core abstractions. Once you grasp these 5, every later chapter falls into place.
| # | Abstraction | In one sentence |
|---|---|---|
| ① | Module & ModuleManager | QCL is assembled from 22 modules, loaded by priority; one crashing doesn't take down the whole |
| ② | Bridge & soft dependency | Connects to third-party plugins via reflection; auto-skips if not installed, status is queryable |
| ③ | ItemSource | Unifies items from 10 sources into a single reference string |
| ④ | Diagnostics & health codes | See the whole ecosystem's health at a glance with /qcl status |
| ⑤ | API boundary | Public package vs internal package; apiJar draws the line on what developers can use |
① Module & ModuleManager
What it is
QCL itself is split into 22 core modules. Each module implements the Module interface and contains: name, priority, and the lifecycle methods load / enable / disable / unload. All modules are managed centrally by ModuleManager.
Why
- Decoupling: items, economy, scripts, GUI… each becomes its own module, none entangled with the others.
- Degrade, don't crash: if a single module throws during
load/enable, only that module is markedavailable=false/enabled=false, without affecting other modules. This is the "degrade rather than crash" design — one subsystem dies, the server keeps running. - Toggleable: the
modules:section ofconfig.yml(with keys likeconfig/database/gui/…) lets you enable/disable each one individually (alltrueby default).
How it shows up
- At startup,
CoreModules.registerAllregisters the 22 modules, andmoduleManager.loadAll()runsload()→enable()one by one in ascending priority order. - On shutdown,
moduleManager.unloadAll()runsdisable()→unload()in reverse. /qcl status detaillists the status of each module line by line.
📋 The 22 core modules and their priorities (loaded in ascending priority order)
| priority | Module | priority | Module |
|---|---|---|---|
| 0 | Config | 50 | Item |
| 5 | Database | 55 | Hologram |
| 8 | Reflection | 58 | Scheduler |
| 9 | ModelEngine | 60 | Condition |
| 10 | CustomCrops | 70 | Expression |
| 11 | CraftEngine | 75 | Script |
| 12 | MythicMobs | 80 | Economy |
| 13 | NeigeItems | 90 | CustomBlock |
| 14 | MMOItems | 100 | Assembly |
| 20 | Gui | ||
| 30 | Action | ||
| 40 | Pdc |
🔢 The smaller the priority, the earlier it loads. Infrastructure (Config / Database / Reflection) comes first, the assembly layer (Assembly) last. See Module System for details.
② Bridge & soft dependency
What it is
A Bridge is how QCL connects to third-party plugins: it calls the other plugin's API via reflection, feeding its capabilities into a unified pipeline. These third parties are all listed under softdepend (soft dependencies) in plugin.yml.
Why
- Soft dependencies only affect load order, they aren't mandatory: they ensure QCL loads after these plugins so it can bridge correctly.
- Auto-skip if not installed: install the corresponding plugin and the bridge lights up; without it, QCL auto-skips without error and the corresponding capability is silently disabled.
- This lets server owners "mix and match as needed" — install only the third-party plugins they actually use.
How it shows up
- Soft dependency list (all bridged via reflection):
Vault · ExcellentEconomy · PlayerPoints · PlaceholderAPI · ModelEngine CustomCrops · CustomFishing · MythicMobs · NeigeItems · MMOItems CraftEngine · QinhItems · MagicGem · ItemsAdder · Nexo /qcl statusdisplays the health codes of the economy bridge / PAPI / database / PDC, etc., as well as whether QI/QS/QF/QSt are available./qcl status detaillists the BridgeStatus of each bridge line by line.
🔌 For how each kind of third party is connected, see 03-External Plugin Integration.
③ ItemSource unified reference
What it is
ItemSource unifies items from 10 different sources into a single reference string, parsed by ItemSourceManager.
Why
- Different plugins obtain items in wildly different ways. QCL smooths over the differences with one unified syntax, ready for sub-plugins to copy and use directly.
- Any sub-plugin that goes through
ItemSourceManagerautomatically supports all sources, with no per-source adaptation needed.
How it shows up
Common reference forms:
| Form | Source |
|---|---|
vanilla:DIAMOND or DIAMOND | Vanilla |
mm-龙剑 | MythicMobs |
mi-SWORD-烈焰剑 | MMOItems |
qi:神剑 | QinhItems |
ia-包名_物品 | ItemsAdder |
nx-枪 | Nexo |
📖 For the full comparison table of all 10 sources and syntax details, see ItemSource Reference.
④ Diagnostics & health codes
What it is
QCL has a built-in diagnostics system that uses health codes and status text to express whether each subsystem is functioning, all exposed through /qcl status.
Why
- The ecosystem is assembled from many modules and bridges; when something breaks you need to pinpoint at a glance exactly which piece is down.
- Health codes make troubleshooting evidence-based (cross-reference Diagnostic Codes).
How it shows up
The /qcl status output covers:
- Platform status (OK / abnormal), overall health code
- Module health, script bridge / number of loaded scripts
- Economy bridge / PAPI / database / PDC health codes
- Whether QI / QS / QF / QSt are available
- Config diagnostics, API boundary, public API count, apiJar package count / internal package count
- Startup diagnostics, item reference diagnostics
/qcl status detail additionally lists module and bridge status line by line, and runs the script global:qcl_status.js:formatStatus to append custom diagnostic lines.
🩺 For the troubleshooting workflow, see Diagnostics & Troubleshooting.
⑤ API boundary (public package vs internal package)
What it is
QCL clearly distinguishes public API packages (depend-able by developers, stable) from internal packages (implementation details, no stability guarantee), and draws the boundary via apiJar.
Why
- A platform library is depended upon by many plugins, so it must commit to "which parts you can use, which you mustn't touch."
- The public API is stable while internal packages can be refactored freely, protecting upstream/downstream compatibility.
How it shows up
The API boundary section of /qcl status reports:
- Public API count
- apiJar package count
- Internal package count
👨💻 Developers should depend only on public packages. See API Overview for details.
⏱️ Startup lifecycle timeline (onEnable)
Stringing the above concepts together gives you QCL's startup flow:
| Order | Stage | Description |
|---|---|---|
| 1 | ServerCompat.validateServer | Validates Java≥25, MC≥1.21.11; disables the plugin if requirements aren't met |
| 2 | StartupReporter.reset | Resets the startup report |
| 3 | saveDefaultConfig | Writes out the default config.yml |
| 4 | EconomyBridge.init + QinhScriptBridge.init | Initializes the economy bridge and script bridge |
| 5 | Register the /qcl command | Created and registered with the Cloud command framework |
| 6 | CustomGuiManager.init | Loads all GUIs under guis/ |
| 7 | Module loading | CoreModules.registerAll registers the 22 modules, loadAll() runs load()→enable() in ascending priority order |
| 8 | Delay 1 tick | ItemSourceBootstrap.reportAvailable + ItemManagerBootstrap.reloadExternalModules (loads Groovy external item modules) + StartupReporter.printSummary (prints the startup summary) |
Shutdown (onDisable): moduleManager.unloadAll() runs disable()→unload() in reverse.
📚 Continue reading
- Next: Configuration File — config.yml and the modules section in detail
- Module System — the Module interface and development
- ItemSource Reference — full comparison of all 10 sources
- Diagnostics & Troubleshooting — reading health codes
- API Overview — public package vs internal package