Installation

Previous: Overview　·　Next: Quick Start

This page walks you through installing QS, confirming it's actually running, and understanding what each soft dependency unlocks and what happens if it's missing.

---

🧱 Before installing: understand the dependencies

QS has one hard dependency and a string of soft dependencies. The distinction is crucial:

Dependency	Type	What happens if missing
QinhCoreLib (QCL)	Hard dependency	QS simply does not enable (the console will warn that QCL is missing)
QinhItems (QI)	Soft dependency	QS starts normally; it just loses the smoothest input — "item keypress triggers" — fall back to the /qs cast command bridge
MythicMobs (MM)	Soft dependency	QS starts normally and does all gating, but the skill "cast" degrades to a placeholder chat message with no real effects
AttributePlus (AP)	Soft dependency	Affects damage settlement on the MM side; QS itself does not read AP
PlaceholderAPI	Soft dependency	Placeholders (cooldown / charges / unlock / level…) become unavailable; everything else works

⚠️ Iron rule of order: install QCL first. QCL is the foundation of the entire Qinhuai ecosystem (item sources, attribute pipeline, action contracts, and script engine all live in it). If QCL isn't in place, QS won't enable.

---

📦 Installation steps

Step 1: Confirm the runtime environment

Item	Requirement
Server	Paper / Purpur / Spigot 1.21.11+
Java	25+

An insufficient Java version is the most common cause of "the plugin won't load." Run java -version first and take a look.

Step 2: Drop in the jars

Drop the following jars into plugins/:

1. QinhCoreLib-x.x.x.jar (required, drop in first)
2. QinhSkills-1.0.22.jar (this plugin)
3. As needed: QinhItems, MythicMobs, AttributePlus, PlaceholderAPI

Step 3: Start the server

On first startup, QS generates a full set of directories and example files under plugins/QinhSkills/ (see below). Once startup finishes with no red errors in the console and /qs responds, the installation succeeded.

---

🔌 Soft dependencies one by one: what each unlocks

QinhItems — item keypress triggers (the most common input)

With QI installed, you can write a qinhskills:cast action on an item so that "right-clicking this sword" directly triggers a QS skill. This is the smoothest, best-feeling way to wire things up.

No QI installed? Use the command bridge: any plugin that can run commands (NeigeItems, MMOItems, even command blocks) can trigger QS by running /qs cast <skill>. Functionality isn't reduced — it's just not as snappy as the native handler. See Integration Overview.

MythicMobs — the skill's "presentation execution backend"

This is the one you most need to understand. QS draws no particles and computes no damage; what the skill actually "looks like when cast" relies entirely on MM.

No MM installed? QS still starts and does all gating checks. It automatically creates a placeholder (stub) MM skill for each skill, and when you trigger it, a line pops up in chat:

[QinhSkills] fire_wave

Seeing this line proves the QS side is fully working — input, state, gating, plan, and bridge are all normal; only MM performing it is missing. Just add an MM skill of the same name to get real effects (see Quick Start).

🔑 QS never overrides an existing MM skill of the same name. The placeholder skill only exists when "you haven't written a skill of the same name"; once you write a real skill of the same name in plugins/MythicMobs/skills/, QS dutifully uses yours.

AttributePlus — damage values (on the MM side)

Neither QS nor QI has built-in damage. When an MM skill needs to deal damage, an attribute plugin like AttributePlus settles the actual values. QS itself doesn't read AP directly — it only casts the skill; damage is MM + AP's business.

PlaceholderAPI — placeholders

With PAPI installed, you can read placeholders like %qinhskills_<skill>_cooldown%, _charges, _unlocked, _level, _ready in your HUD / scoreboard / chat. Missing it doesn't affect the skills themselves.

---

📁 What gets generated on first startup

After startup, plugins/QinhSkills/ roughly looks like this:

plugins/QinhSkills/
├── config.yml              # Main config (runtime switches, bridge mode, unlock, resources, slots, actionbar, routing)
├── skills/                 # Skill definitions, foldered by five categories
│   ├── combat/             #   fire_wave / blade_slash / demo_slash / demo_slash_charged / retaliate
│   ├── movement/           #   dash
│   ├── utility/            #   shield
│   ├── combo/              #   fire_combo_finisher
│   └── boss/
├── graphs/                 # The execution graph for each skill
│   └── combat/ movement/ utility/ combo/ boss/
├── integrations/           # Integration examples (QI / command bridge / MM real presentation / class layer)
└── players/                # Player skill profiles (unlocks/levels/slots/cooldown persistence)

💡 The fastest way to get started: read the bundled examples directly. They all come with detailed comments; just copy and modify: combat/fire_wave (the most basic template, read it first) · combat/blade_slash (targeting + blood sacrifice + GCD + conditions + ready prompt + mutual exclusion) · combat/demo_slash (QI item trigger) · combat/demo_slash_charged (channel cast bar) · combat/retaliate (passive retaliation) · movement/dash (charges + ignores GCD) · utility/shield (toggle) · combo/fire_combo_finisher (combo right→right→left).

The integrations/ folder also has integration examples (QinhItems item keypresses, command bridge, real MM presentation, optional class layer) — likewise copy them as-is.

---

✅ Verify the installation

Two diagnostic commands tell you at a glance whether the install went well:

/qs protocol     # Check the runtime protocol/bridge status (protocol version, whether the bridge is ready, whether MM is available)
/qs bridge       # Check the MythicMobs bridge status (bridge mode, whether MM is present, whether registration succeeded)

• /qs protocol normal → the QS runtime (input→state→graph→plan→gate→execution→post-processing) is in place.
• /qs bridge normal →
  • With MM installed: shows the bridge connected and skills registerable to MM.
  • Without MM: shows the bridge in placeholder mode — this is also normal; triggering a skill goes to the placeholder message.

Now fire off an actual trigger to confirm the chain works:

/qs unlock fire_wave     # Unlock first (not everything is unlocked by default)
/qs cast fire_wave       # Cast via command

[QinhSkills] fire_wave appears in chat — congratulations, the entire QS chain works. The next page teaches you to swap it for real effects.

📌 Currently there are only 11 available commands (see the command table at the end of Quick Start). If you see /qs test, /qs gen, etc. in the docs, they are not currently exposed — don't treat them as available commands.

---

🔧 Troubleshooting quick reference

Symptom	Most likely because	What to do
/qs doesn't respond / console says QS isn't enabled	QCL not installed or failed to load	Install QinhCoreLib first, then restart
The plugin doesn't load at all	Java / server version too low	Confirm Java 25+ and 1.21.11+
The cast only shows a [QinhSkills] xxx chat prompt	No MM skill of the same name written (this is the normal placeholder)	Write a real skill of the same name in plugins/MythicMobs/skills/ + /mm reload
Pressing the item does nothing	The skill is not unlocked, or the item's handler isn't registered	/qs unlock <skill>; confirm QI is installed and /qi reload has been run
Changes to a skill yml don't take effect	Not reloaded	/qs reload
Placeholders don't show	PlaceholderAPI not installed	Install PAPI; nothing else is affected

---

Keep reading

• Build your first skill with real effects in 5 minutes → Quick Start
• Understand the architecture before configuring → Core Concepts
• Wire a skill to an item → Integration Overview