Integration Overview: Wiring Skills to Items / NPCs / MythicMobs
Previous: Home · Next: Integrating QinhItems
QS listens to no keypress on its own, and draws not a single particle. It is the "skill brain" sandwiched in the middle. So this chapter on "integration" essentially answers two questions:
- How do you trigger it — how does a player keypress / item use / NPC click turn into "cast a particular QS skill"? (Integrating item plugins)
- How do you make it visible — once a skill fires, how does it get particles, movement, and damage? (Integrating MythicMobs)
By the end of this page you'll know: the iron rule of the four-way division of labor, which integration example files QS drops on first startup, the three ways to wire a skill onto an item, and "which page should I read for item plugin X."
🖼️ [Image placeholder] Four-way division-of-labor flowchart (item keypress → QS gating → MM presentation → attribute plugin settles damage) · suggested
assets/integration-overview.png
🧱 1. First, memorize this iron rule: the four-way division of labor
The entire QinhSkills ecosystem splits the act of "casting a skill" across four plugins, each owning one segment, none stealing another's authority. This is the prerequisite for understanding every later page, so be sure to commit it to memory first:
| Role | Who does it | Owns | Never touches |
|---|---|---|---|
| 🎮 Trigger | QinhItems / NeigeItems / MMOItems / NPC… | Turning "keypress / item use / click" into "cast a particular skill id" | Skill logic, cooldown, damage |
| 🧠 Gating | QinhSkills (QS) | Unlock / cooldown / cooldown groups / charges / GCD / resources / blood sacrifice / target acquisition / combo state / cast progress / passive conditions / gating | Particles, movement, sound, presentation, damage numbers |
| 🎆 Presentation | MythicMobs (MM) | Particles / movement / sound / firing damage events / everything about "what it looks like" | Cooldown, unlock, combos, trigger parsing |
| ⚔️ Numbers | AttributePlus (AP) and other attribute plugins | Settling final damage numbers from the attacker's item attributes | How and when the skill is cast |
In one sentence: the item handles "the press," QS handles "whether it can fire," MythicMobs handles "what it looks like when it fires," and the attribute plugin handles "how much damage it deals."
Why split it this way? (the WHY first)
The most intuitive approach is "let the item call MythicMobs directly to cast the skill" — so why does QinhSkills insist on inserting a QS layer in the middle? Because if items call MM directly, three unsolvable problems appear:
- Nobody manages cooldown centrally — the item configures one cooldown, MM configures another, and players hit either "double cooldown" or "cooldown bypass."
- Resources get double-charged — the item deducts mana once, then the skill deducts mana again.
- Logic scatters across three places — unlock checks in the item, combos in the item, damage in MM… changing one skill means digging through three plugins.
By inserting QS in the middle, "state / logic" and "presentation" are cleanly separated: QS is the single source of truth (cooldown, resources, unlocks all live there), and MM is a replaceable execution backend. The full argument for "why not call MM directly" is the opening focus of Integrating MythicMobs, and is strongly recommended reading.
📂 2. The 4 integration example files dropped on first startup
The first time QS starts, it drops 4 integration examples into the plugins/QinhSkills/integrations/ directory. They are "copy-and-go" templates, each corresponding to a page in this chapter:
| File dropped | Purpose | Matching doc page |
|---|---|---|
integrations/qinhitems_action_example.yml | QinhItems item → trigger a QS skill (native handler) | Integrating QinhItems |
integrations/neigeitems_skill_example.yml | NeigeItems / any plugin → trigger a QS skill (command bridge) | Integrating other item plugins |
integrations/mythic/QinhSkillsEcosystem.yml | MythicMobs skills ← invoked by QS for execution (presentation layer) | Integrating MythicMobs |
integrations/QinhClass_MMOCore.md | Notes on cooperating with class plugins (QinhClass / MMOCore) | (class-system docs) |
📌 These files are examples only; QS does not auto-load and execute them.
qinhitems_action_example.ymlmust be copied toplugins/QinhItems/items/, andQinhSkillsEcosystem.ymlmust be copied toplugins/MythicMobs/skills/to take effect. The header of each file spells out "where to copy it and what command to run after editing."
🔌 3. Three ways to wire a skill onto an item
There are three paths to "let a player cast a skill with a keypress." They all ultimately funnel into the same QS runtime (passing the same unlock / cooldown / cost / target / combo gating); only the "entry point" differs:
| Approach | Entry point | Use when | Capability | See |
|---|---|---|---|---|
| ① QI native handler | Write handler: qinhskills:cast in the item action | You use QinhItems | Most "native"; can carry a JSON payload and access item / itemId context | Integrating QinhItems |
| ② Command bridge | Item / NPC runs the command qs cast <skill id> "on use" | You use NeigeItems / MMOItems / any plugin that can run commands | Universal and stable; payload is a plain string only | Integrating other item plugins |
| ③ MM execution backend | Not a trigger entry; it's the "presentation" end | Everyone must configure it | Gives the skill particles / damage / movement | Integrating MythicMobs |
⚠️ ① and ② are mutually exclusive trigger methods; ③ is the presentation layer everyone needs. In other words: whether you trigger via QI or NI, you must ultimately write a same-named skill in MythicMobs for the skill to have real presentation. Otherwise the skill "firing" is just a placeholder message
[QinhSkills] skill name.
How to choose ① vs ②?
- Using QinhItems → always prefer ① the native handler (most full-featured).
- The item plugin has no native QS integration → use ② the command bridge (as long as it can run a command on use).
- Prefer the plugin's native method; fall back to the command bridge only when there isn't one.
🧭 4. Decision table: I use item plugin X → which page should I read?
| Your item / trigger comes from… | Which approach | Main read | Also configure |
|---|---|---|---|
| QinhItems | ① native handler | Integrating QinhItems | Integrating MythicMobs |
| NeigeItems | ② command bridge | Integrating other item plugins | Integrating MythicMobs |
| MMOItems | ② command bridge (ability/command runs qs cast) | Integrating other item plugins | Integrating MythicMobs |
| Citizens / any NPC plugin | ② command bridge (click NPC runs a command) | Integrating other item plugins | Integrating MythicMobs |
| Menu / GUI plugins (DeluxeMenus etc.) | ② command bridge (click a slot runs a command) | Integrating other item plugins | Integrating MythicMobs |
| Want to write your own triggering plugin | API / listen to QISkillUseEvent | Execution chain and events | Integrating MythicMobs |
💡 No matter which row, the "Integrating MythicMobs" column is unavoidable — it's the presentation layer, and everyone needs it.
🪜 5. Dependency degradation table: what happens if a plugin is missing
QS's dependency relationships (declared in plugin.yml):
depend: [QinhCoreLib] # hard dependency; QS won't enable without it
softdepend: [QinhItems, MythicMobs, AttributePlus, PlaceholderAPI] # soft dependencies, can be absent| Missing | Consequence | Still usable? |
|---|---|---|
| QinhCoreLib | ❌ QS simply won't enable (this is a hard dependency) | No |
| QinhItems | The qinhskills:cast handler isn't registered | ✅ Command bridge /qs cast still works; if QI loads late, registration is auto-patched |
| MythicMobs | Skill execution (EXEC) fails | ✅ Gating still runs; the skill "firing" gets only a placeholder message or a failure |
| AttributePlus | Doesn't affect QS operation; damage just isn't settled by an attribute plugin | ✅ Skills still cast; damage goes through MM itself / vanilla |
| PlaceholderAPI | %qinhskills_*% placeholders aren't registered | ✅ Everything else works normally |
📌 Key point: only QinhCoreLib is "broken if absent." The other three can be missing and things still run, just with one capability degraded. This lets you "first get QS + QI running to see the placeholder messages," then gradually fill in the MM presentation.
🎯 Suggested reading order
If you're completely new, this order reads most smoothly:
- First understand why insert a QS layer → the opening "why not call MM directly" of Integrating MythicMobs.
- Then pick a trigger approach based on your item plugin → Integrating QinhItems or Integrating other item plugins.
- Want to understand what actually happens between "keypress and skill firing," and how to diagnose problems → Execution chain and events.
Keep reading
- Using QinhItems? → Integrating QinhItems
- Want to understand "why not call MM directly" + configure MM presentation → Integrating MythicMobs
- Using NeigeItems / MMOItems / NPC? → Integrating other item plugins
- Want the full chain / to write your own triggering plugin → Execution chain and events