Previous: Overview　·　Next: Quick Start

🚀 Installation

QCL is the foundation of the entire Qinhuai ecosystem, and should be installed first. It has no hard dependencies. Once it is installed, gameplay plugins such as QI/QS/QF/QSt can load correctly.

---

🧰 Environment Requirements

Item	Requirement	Notes
Server	Paper / Purpur / Spigot 1.21.11+	⚠️ Paper / Purpur strongly recommended — see below for the reason
Java	25+	Purpur 26.1 requires JDK25
MC version	1.21.11+	Below this version, startup will be disabled
Kotlin (runtime)	2.3.0	Pulled automatically by the libraries section — no manual install needed

✅ QCL has no hard dependencies and can be dropped straight into plugins/ to start.

---

⚠️ Why must you use Paper / Purpur? (the libraries mechanism)

At runtime, QCL needs libraries such as Kotlin, GraalJS, and Groovy4. These libraries are not bundled into the jar. Instead, they are declared in the libraries section of plugin.yml, and the server automatically downloads them from Maven at startup and caches them into the server's libraries/ directory.

• ✅ Paper / Purpur natively support the libraries auto-pull mechanism → everything works.
• ❌ Pure Spigot does not support this mechanism → Kotlin / GraalJS may fail to load, and the plugin will not work properly.

💡 Conclusion: if you can use Paper / Purpur, don't use pure Spigot. This isn't a preference — QCL's runtime libraries depend on this mechanism.

Startup validation is handled by ServerCompat.validateServer(): at startup it checks for Java ≥ 25 and MC ≥ 1.21.11, and if these aren't met it logs a severe message and disables the plugin.

---

📦 Installation Steps

1️⃣ Drop in the jar

Place QinhCoreLib-1.2.0.jar into the server's plugins/ directory.

server root/
├─ plugins/
│  └─ QinhCoreLib-1.2.0.jar   ← put it here
├─ libraries/                  ← runtime libraries are cached here automatically (Paper/Purpur)
└─ ...

2️⃣ Start the server

On the first startup, the server will:

1. Automatically download Kotlin / GraalJS / Groovy4 from Maven into libraries/ (requires internet; slightly slow the first time);
2. Run ServerCompat.validateServer() to validate the Java and MC versions;
3. Automatically generate QCL's configuration and directories.

3️⃣ Auto-generated directory structure

After a successful startup, the following will be generated under plugins/QinhCoreLib/:

plugins/QinhCoreLib/
├─ config.yml      # main config (includes the modules: section)
├─ guis/           # custom GUIs (YAML)
├─ scripts/        # scripts (GraalJS / Groovy)
└─ data/           # database / persistent data

📁 Throughout this documentation series, YAML and file paths are relative to plugins/QinhCoreLib/ by default.

4️⃣ Verify install

After joining the server, run:

/qcl status

If you see an ecosystem status summary (platform status, health code, module health, etc.), the install succeeded. For a detailed walkthrough, see Quick Start.

---

🪵 What logs will you see on first startup?

QCL's onEnable runs in the following order, and under normal conditions the logs will reflect these stages:

Order	Stage	What it does
1	ServerCompat.validateServer	Validate Java≥25, MC≥1.21.11
2	StartupReporter.reset	Reset the startup report
3	saveDefaultConfig	Emit the default config.yml
4	Bridge initialization	EconomyBridge.init + QinhScriptBridge.init
5	Register commands	Register /qcl using the Cloud framework
6	CustomGuiManager.init	Load all GUIs under guis/
7	Module loading	Register the 22 core modules, calling load()→enable() one by one in ascending priority order
8	Delay 1 tick	Report item source availability + load Groovy external item modules + print the startup summary

🧾 At the very end of startup, StartupReporter.printSummary prints a startup summary. This is the key log for confirming that everything is fine — it's worth a glance on every restart.

---

☕ Java 25 installation tips

QCL requires Java 25+ (Purpur 26.1 needs JDK25). If your server is still on Java 17 / 21:

1. Download and install JDK 25 (e.g. Temurin / Oracle JDK 25);
2. Edit the server startup script so that java points to the JDK25 executable, for example:

   "C:\path\to\jdk-25\bin\java.exe" -jar paper.jar nogui

3. Use java -version to confirm that the output shows 25.

⚠️ If you start with an older Java version, QCL will log a severe error and disable itself, paralyzing the entire ecosystem.

---

🔌 Where do soft dependencies go?

QCL's soft dependencies (see the softdepend section of plugin.yml) only affect load order — they are not mandatory. Just drop them into plugins/ like any other plugin:

Vault · ExcellentEconomy · PlayerPoints · PlaceholderAPI · ModelEngine
CustomCrops · CustomFishing · MythicMobs · NeigeItems · MMOItems
CraftEngine · QinhItems · MagicGem · ItemsAdder · Nexo

• ✅ Installed → QCL automatically bridges via reflection, and the corresponding capability lights up.
• ❌ Not installed → automatically skipped, no error, and the corresponding capability is silently disabled.

Soft dependencies only decide "who loads first", ensuring QCL can bridge correctly after them. For specific integrations, see 03 - External Plugin Integration.

---

🆘 Common installation failures

Symptom / log	Cause	Fix
Kotlin / GraalJS fail to load, classes not found	Using pure Spigot, which doesn't support the libraries auto-pull mechanism	Switch to Paper / Purpur
Severe log says Java version too low, plugin disabled	Java < 25	Install JDK25 and update the startup script
Severe log says MC version too low, plugin disabled	MC < 1.21.11	Upgrade the server to 1.21.11+
First startup stuck downloading libraries	The server cannot reach Maven	Check the network / configure a Maven mirror

🩺 For more troubleshooting, see Diagnostics & Troubleshooting and Diagnostic Codes.

---

📚 Continue reading

• Next: Quick Start — the first thing to do after installing
• Core Concepts — understanding modules, bridges, and item sources
• Configuration File — config.yml in detail