Previous: Installation · Next: Commands & Permissions
⚙️ Configuration File config.yml Explained
QinhCoreLib (hereafter QCL) has only one main configuration file: plugins/QinhCoreLib/config.yml. It auto-generates default content on first startup. This page walks through every key section by section and item by item, explaining each key's default value, allowed values, purpose, and whether a /qcl reload is enough after editing or a server restart is required.
📌 General rule: any change involving a database connection method switch or a module toggle is best applied with a server restart to be safe; pure numeric/toggle changes (such as debug, the economy default provider, javascript debug) mostly take effect with
/qcl reload. The exact behavior is noted under each item below.
🗂️ Full config.yml Source
Below is the complete content generated by default in QCL 1.2.0, which you can copy directly as a template:
database:
type: sqlite # sqlite or mysql
sqlite:
data-folder: data # data folder relative to the plugin directory
mysql:
host: localhost
port: 3306
database: qinhcorelib
username: root
password: ""
debug:
enabled: false
prefix: "[QinhCoreLib-Debug]"
economy:
default-provider: auto # auto|vault|excellenteconomy|ee|playerpoints|pp. auto: prefer EE when a currency is set, otherwise Vault>EE>PlayerPoints
default-currency: money # EE currency id (money/silver/gold...), ignored by Vault/PlayerPoints
javascript:
enabled: true
default-function: main # the default function called when a script reference omits the function name
debug:
print-stacktrace: false
attribute: # attribute backend (the whole ecosystem reads it from here)
backend: native # native (built-in native attributes, no plugin needed) | attributeplus | auto
modules: # disable modules you don't need (all true by default)
config: true
database: true
reflection: true
modelengine: true
customcrops: true
craftengine: true
mythicmobs: true
neigeitems: true
mmoitems: true
gui: true
action: true
pdc: true
item: true
hologram: true
scheduler: true
condition: true
expression: true
script: true
economy: true
customblock: true
assembly: true🗡️ attribute — Attribute Backend
| Key | Default | Allowed | Purpose |
|---|---|---|---|
attribute.backend | native | native / attributeplus / auto | native = QCL's built-in native attributes, no attribute plugin required; attributeplus = hand to AttributePlus; auto = prefer third-party if present, else fall back to native |
The whole ecosystem (QI/QS/QC/QSt/QF) reads the backend from here. How attributes work and how to make your own → Attribute System.
🛢️ database — Data Storage
QCL provides unified data storage for the entire Qinhuai ecosystem.
| Key | Default | Allowed Values | Purpose |
|---|---|---|---|
database.type | sqlite | sqlite, mysql | Choose the storage backend |
database.sqlite.data-folder | data | Any directory name | SQLite data folder (relative to the plugin directory) |
database.mysql.host | localhost | Host/IP | MySQL address |
database.mysql.port | 3306 | Port number | MySQL port |
database.mysql.database | qinhcorelib | Database name | MySQL database name |
database.mysql.username | root | Username | MySQL account |
database.mysql.password | "" (empty) | Password string | MySQL password |
🧭 When to Use Which?
| Scenario | Recommended |
|---|---|
| Single server, few players, want simplicity | sqlite (zero config, works out of the box) |
| Cross-server / large server / need external data access | mysql |
📁 SQLite Data Directory Structure
When type: sqlite, data is stored in plugins/QinhCoreLib/data/ (i.e. the directory specified by data-folder):
plugins/QinhCoreLib/data/
├── global.db # global database (shared, cross-player data)
├── {uuid}.db # one separate database per player, filename is the player UUID
├── {uuid}.db
└── ...💡
global.dbstores global data, and each player has a separate database file named after their UUID. To back up, simply archive the entiredata/directory.
⚠️ Things to Know After Editing
- Switching
type(sqlite ⇄ mysql) or changing the MySQL connection parameters: a server restart is required. The database connection is established at startup, and/qcl reloadwill not reconnect. - After switching, data is not migrated automatically — the two backends are independent.
🐛 debug — Debug Output
| Key | Default | Allowed Values | Purpose |
|---|---|---|---|
debug.enabled | false | true/false | Whether to print debug logs |
debug.prefix | [QinhCoreLib-Debug] | Any string | Debug log prefix |
When troubleshooting, set enabled to true and the console will output more detailed internal logs, each line carrying the prefix to make filtering easier.
⚠️ Things to Know After Editing
/qcl reloadis enough (reload refreshes the config).
💰 economy — Economy Integration
QCL wraps multiple economy plugins in a unified way, so sub-plugins don't need to care which economy is used underneath.
| Key | Default | Allowed Values | Purpose |
|---|---|---|---|
economy.default-provider | auto | auto, vault, excellenteconomy/ee, playerpoints/pp | Default economy provider |
economy.default-currency | money | EE currency id (e.g. money/silver/gold) | Default currency id |
🔄 The auto Logic of default-provider
When set to auto, QCL picks automatically according to these rules:
- When a currency (currency id) is specified → prefer ExcellentEconomy (EE) (since only EE supports multiple currencies).
- When no currency is specified → priority order is Vault > EE > PlayerPoints, using whichever is available.
If you want to lock to a single economy plugin, just set default-provider directly to vault / ee / pp.
💵 When Does default-currency Matter?
| Provider | Uses default-currency? |
|---|---|
| ExcellentEconomy (EE) | ✅ Yes, must be a valid EE currency id |
| Vault | ❌ Ignored (Vault is single-currency) |
| PlayerPoints | ❌ Ignored |
In other words, default-currency only matters when using EE, determining which currency is operated on by default.
🔗 When writing economy actions in places like GUIs, you can override the default with a more precise format, e.g.
excellenteconomy:gold:50. See Commands & Permissions and the developer docs Economy API.
⚠️ Things to Know After Editing
/qcl reloadis enough (reload reloads the economy).
📜 javascript — Script Engine
QCL has a built-in JavaScript script engine for sub-plugins to hook in logic (such as QI's crafting validation).
| Key | Default | Allowed Values | Purpose |
|---|---|---|---|
javascript.enabled | true | true/false | Whether to enable the script engine |
javascript.default-function | main | Any function name | The default function called when a reference omits the function name |
javascript.debug.print-stacktrace | false | true/false | Whether to print the full stack trace when a script errors |
🧩 Script Path Format
The script reference format is: namespace:relative-path.js[:functionName]
qinhitems:hooks/craft.js:check # calls the check function of hooks/craft.js under the qinhitems namespace
qinhitems:hooks/craft.js # no function name → calls default-function (default main)default-function: when a reference omits the function name, this is the default function called (defaultmain).print-stacktrace: set totrueduring development/troubleshooting; when a script throws an exception, the full Java stack trace is printed for easier diagnosis.
⚠️ Things to Know After Editing
/qcl reloadreloads scripts, and most changes can be hot-reloaded; if you turnenabledoff/on, a restart is recommended to ensure it is fully applied.
🔗 For script development, see Script API.
🧱 modules — Module Toggles
QCL is modular. The modules section lets you disable individual modules you don't need, all true by default.
Capabilities of Each Module
| Module Name | Capability |
|---|---|
config | Config loading (foundational, recommended to keep enabled) |
database | Data storage (SQLite/MySQL) |
reflection | Reflection utilities |
modelengine | ModelEngine integration (model entities) |
customcrops | CustomCrops integration (crops) |
craftengine | CraftEngine integration (custom blocks/items) |
mythicmobs | MythicMobs integration |
neigeitems | NeigeItems integration |
mmoitems | MMOItems integration |
gui | Custom GUI system |
action | Action system |
pdc | PersistentDataContainer data storage |
item | Item system (including unified item source references) |
hologram | Hologram text |
scheduler | Scheduler |
condition | Condition system |
expression | Expression evaluation |
script | Script system |
economy | Economy integration |
customblock | Custom blocks |
assembly | Assembly/composition |
🔧 How to Disable a Module
Just change the corresponding key to false. For example, if you don't need MythicMobs integration:
modules:
mythicmobs: false⚠️ Side-Effect Warning When Disabling
- Features that depend on a disabled module will stop working. For example, after disabling
item, unified item source references, GUI item references, and sub-plugins' item APIs will all be affected. - Sub-plugins (QI/QS/QF/QSt, etc.) may depend on certain modules. Unless you are sure they are unused, do not casually disable core modules such as
config,database,item,action,script,economy. - Only when you are sure the server does not have the corresponding external plugin installed is it safe and resource-saving to turn off the matching integration module (such as
modelengine,mythicmobs). - After disabling a module, it will show as "not enabled" in
/qcl status detail.
⚠️ Things to Know After Editing
- Module toggles affect the initialization flow, so a server restart is recommended to load/unload modules completely cleanly.
📋 Quick Reference: How Changes Take Effect
| Config Section | Is reload enough? | Notes |
|---|---|---|
database (connection/type) | ❌ Restart | Connection is established at startup |
debug | ✅ reload | — |
economy | ✅ reload | reload reloads the economy |
javascript | ✅ reload (mostly) | Restart recommended for the enabled toggle |
modules | ❌ Restart | Affects module loading |
📖 Continue Reading
- ➡️ Next: Commands & Permissions — what exactly
/qcl reloadreloads - 🧩 Item Source References — core functionality depending on the
itemmodule - 🩺 Diagnostics & Troubleshooting — use
/qcl statusto check each module's status - 📚 Glossary · FAQ