Overview: What QS Is, and Why You Need It
Previous: Home · Next: Installation
One-sentence positioning
QinhSkills (QS) is a state-driven "skill brain": when the player presses a key, whether a skill can be cast at all, which skill it is, and what gates it must clear first — unlock, cooldown, charges, cost, target acquisition, combos, channel cast bars, passive triggers — are all decided inside QS.
But QS deliberately draws no particles, computes no damage, and performs no movement. Once the checks pass, what the skill actually "looks like when cast" is handed to MythicMobs (MM) to execute, and damage values are settled by an attribute plugin such as AttributePlus (AP).
Remember the division of labor in one line: the item handles "the press," QS handles "can it cast," MythicMobs handles "what it looks like," and the attribute plugin handles "how much damage."
🖼️ [Image placeholder] A sequence of frames from keypress to flame effect (keypress → QS gating → MM presentation) · suggested assets/overview-pipeline-frames.png
The four-way division of labor — who handles what
A lot of people, seeing QS for the first time, ask: "Isn't casting skills just MythicMobs' job? Why do I need QS too?" The answer is: casting a skill is actually split into four non-overlapping responsibilities, and each plugin only does the part it does best.
| Role | Who does it | Handles | Firmly does not do |
|---|---|---|---|
| The press | Item plugin (QinhItems / NeigeItems…) | Turns "the player right-clicked this sword" into a standard trigger signal | Doesn't decide which skill to cast, doesn't manage cooldowns |
| Can it cast | QinhSkills (this plugin) | Unlock / cooldown / charges / cost / target / combo / channeling / passives — all the "gates" | Draws no particles, computes no damage, performs no movement |
| What it looks like | MythicMobs | Particles, movement, knockback, presentation, the mechanic itself | Doesn't manage the state machine, combos, or trigger parsing |
| How much damage | Attribute plugins like AttributePlus | Damage value settlement (on the MM side) | Doesn't manage skill flow |
🔑 Core iron rule: Neither QS nor QI has built-in attributes / damage. You can never write "deal 30 damage" inside QS — damage values are settled by AttributePlus on the MM side. QS only decides "whether this swing can be thrown at all."
These four layers work like an assembly line: the item passes the signal to QS, QS clears all the checkpoints, then hands MM an execution plan — "cast fire_wave, target that zombie, power parameter power=1.2" — MM performs it, and AP computes how much that hit dealt.
If you've used MythicMobs
The most easily confused point: QS is not a replacement for MythicMobs — it's the "brain" that drives MM. They are upstream and downstream, not competitors.
| What you want to do | MythicMobs alone | With QS added |
|---|---|---|
| A skill's particles, damage, movement | ✅ MM's core job, QS doesn't touch it | Still MM's job |
| Right-click to cast a skill | You must wire up the Skill trigger and parse input yourself | QS uniformly takes over input |
| Unlock / level / cooldown / charges | MM has cooldown, but unlock, charge layers, and cooldown groups must be cobbled together | QS has a full gating suite built in |
| Auto-lock the nearest mob as the target | You must write a targeter + various filters | QS does it in one line: target: NEAREST |
| Right→right→left combo into a finisher | You must write state tracking and sequence matching yourself | QS state machine + native combo support |
| 2-second charge-up cast bar, movement interrupts | You must cobble together a bossbar and interrupt logic | QS does it with one cast_mode: channel |
| Auto-retaliate when hit | You must write an onDamaged trigger + rate limiting | QS passive trigger + built-in rate limiting |
You can think of it this way:
| MythicMobs concept | QS equivalent | Note |
|---|---|---|
| Skill (the skill itself) | Still an MM Skill | QS doesn't replace it, only calls it |
Trigger (~onAttack etc.) | QS's input normalization + passive triggers | QS funnels them in and dispatches |
Targeter (@NearestPlayer…) | target: NEAREST / LOOK … | QS picks the target and passes it to MM as @Target |
| Cooldown | QS's gating cooldown / charges / cooldown group / GCD | Finer-grained than MM's native one |
| Conditions | QS's conditions: declarative conditions | Validated before the cast is allowed |
💡 In short: MM is the "hand," QS is the "brain." You still write the skill's visuals and mechanics in MM; QS stands between the item and MM, deciding when, at whom, and in what state this hand strikes.
QS's three design philosophies
Understand these three and you understand why QS looks the way it does — and you'll dodge a lot of pitfalls.
1) QS only manages "logic," not "presentation" or "values"
QS itself draws not a single particle, drops not a single point of health, moves not a single block. What it outputs is an execution plan: which MM skill to cast, who the target is, and which variable parameters to carry. Presentation goes to MM, damage goes to the attribute plugin.
- "How much this swing hits for" is decided by AttributePlus (settled on the MM side).
- QS only handles: deciding whether it can cast → picking the target → passing parameters through to MM.
- No MM installed? QS still performs all gate checks; the skill "cast" just degrades to a placeholder message
[QinhSkills] <skill name>— seeing it means the QS side is working.
This boundary follows the same line of thinking as QI's "doesn't manage how values are computed, only that values hang on the item": single responsibility, everyone does their own job.
2) All triggers funnel into the same runtime pipeline
Whether a skill is triggered by an item keypress, by the command /qs cast, by the API, or by a passive event (taking damage / killing / sneaking…), they all enter the same pipeline:
Input → State machine (State) → Graph resolution (Graph) + combo (Combo) → Execution plan (Plan) → Gate → Execution (MM) → Post-processing (Post)The benefit: rules like cooldown, charges, combos, and targets are written only once and apply equally to all trigger sources. You don't maintain two sets of logic for "cast via command" and "cast via item." See Core Concepts.
3) Skill graphs + a state machine make combos and follow-ups orchestratable
Beyond its "skill definition," each skill also has a graph (execution graph) that answers: "in a given state, when a given key is pressed, which node do we take and which MM skill do we cast?"
Paired with a 6-state state machine (idle / casting / combo window / recovery / locked / interrupted), QS can orchestrate time-sequenced gameplay like "right-click opener → another right-click within the combo window for a follow-up → right-right-left triggers a finisher" in declarative YAML, instead of you hand-writing a pile of state checks. See Core Concepts and Graphs and Combos.
What it can do — typical scenarios
These are all gameplay patterns QS can orchestrate out of the box (you fill in the presentation part in MM):
- Left-click to auto-lock the nearest mob and cast a blade slash —
target: NEAREST+filter: MONSTERS, QS picks the target for you. - 2-second charge-up cast bar for an ultimate —
cast_mode: channel, with bossbar progress and movement / damage interruption. - Sneak right-click blink — a movement skill that ignores the global cooldown (
gcd.ignore: true), responsive and snappy. - Auto-retaliate when hit — an
ON_DAMAGEDpassive trigger with built-in rate limiting to prevent spam. - Right→right→left combo into a fire-burst finisher — write
inputs: [RIGHT_CLICK, RIGHT_CLICK, LEFT_CLICK]in the graph; pressing the sequence within the combo window triggersfinalize_skill.
🖼️ [Image placeholder] Four-panel illustration: targeted blade slash / charge-up cast bar / sneak blink / combo finisher · suggested assets/overview-scenarios.png
Behind every scenario is the same sentence: QS decides "can it cast, which one, and what gates it clears," MM decides "what it looks like."
Its place in the Qinhuai ecosystem
QS is the "skill foundation" of the Qinhuai RPG ecosystem. The sibling modules it works with:
| Module | Role | Relationship to QS |
|---|---|---|
| QinhCoreLib (QCL) | Unified base library | QS hard-depends on it; without QCL, QS does not enable |
| QinhItems (QI) | Custom item engine | The qinhskills:cast in an item action hands the keypress to QS (soft dependency) |
| QinhSkills (QS) | Skill engine (this plugin) | Decides whether it can cast, which one, and what gates it clears |
| MythicMobs (MM) | Skill execution backend | QS hands it the execution plan to perform (soft dependency) |
| AttributePlus (AP) | Attributes / damage settlement | Computes damage on the MM side (soft dependency) |
🖼️ [Image placeholder] Qinhuai ecosystem module relationship diagram (QCL base, QI items, QS skills, MM execution, AP values) · suggested
assets/ecosystem-diagram.png
Note the difference between "hard dependency" and "soft dependency": QCL must be installed first, or QS simply won't enable; the rest (QI / MM / AP / PlaceholderAPI) are soft dependencies — it'll still start without them, the corresponding capabilities just degrade. See the degradation table on the next page, Installation.
Keep reading
- Ready to install the plugin → Installation
- In a hurry to build your first castable skill → Quick Start
- Want to fully grasp the architecture first → Core Concepts