Quick Start

Previous: Installation　·　Next: Core Concepts

In 5 minutes, turn the bundled fire_wave from a "placeholder chat prompt" into a skill with real flame effects that you can cast by right-clicking an item. Copy-paste the whole way.

The full path looks like this:

①/qs reload  →  ②understand fire_wave  →  ③unlock  →  ④/qs cast to test (see placeholder)  →  ⑤write the real MM skill  →  ⑥bind to item

---

① Reload, so QS releases the examples

/qs reload

/qs reload will: reload all skill definitions / graphs / routing, and sync the MM bridge. First startup actually already released the example files; this step ensures they're all loaded.

---

② Take a look at the bundled fire_wave (read it first)

Open plugins/QinhSkills/skills/combat/fire_wave.yml. It's the template for all skills — understand this one and every other example is just a variant of it. With comments stripped, the core is just this much:

id: fire_wave                   # Unique skill id, all lowercase; everywhere else references it by this id
display: "&c火焰波"             # Display name

# ↓ Upper half: ecosystem info (categorization + consistency validation on reload)
meta:
  category: combat              # One of the fixed five categories: combat/movement/utility/combo/boss
  type: active                  # active / passive
  rank: basic
trigger:
  primary: RIGHT_CLICK          # Primary trigger key, must appear in the graph entry node's triggers
state:
  required: IDLE                # State-machine state required to cast
graph:
  entry: fire_wave              # Which graph to use (found by graph_id)
execution:
  mythic_skill: fire_wave       # The MythicMobs skill name that actually executes

# ↓ Lower half: the fields actually read at runtime
type: active                    # The line that truly decides active/passive (the loader reads it)
max_level: 5

cooldown:
  base: 3000                    # Cooldown in milliseconds (3000 = 3 seconds)

resource:
  mana: 15                      # Cast cost (⚠ mana will move to QinhClass in the future; this is a temporary placeholder)

cast_mode: instant              # instant / channel / toggle

variables:
  element: fire                 # Variable passed through to MM, read in MM via <skill.var.element>

tags: [fire, aoe, combat]

💡 Why are there "two sets" of fields? The upper half meta/trigger/state/graph/execution is ecosystem info (categorization, reload validation, used by combos); the lower half type/cooldown/resource/... is the fields actually read at runtime. Both point to the same skill — just keep them consistent (see Core Concepts).

It also comes with a graph (graphs/combat/fire_wave.graph.yml); the simplest skill has just one entry node:

graph_id: fire_wave             # Must match the skill file's graph.entry
entry: fire_wave                # Entry node name
nodes:
  fire_wave:                    # Entry node (name = entry)
    skill_id: fire_wave
    mythic_skill: fire_wave     # = the skill file's execution.mythic_skill
    require_state: IDLE         # = the skill file's state.required
    triggers:                   # Hitting these keys takes this node
      - RIGHT_CLICK

---

③ Unlock it

By default QS does not unlock everything (config.yml has unlock.default_all: false). fire_wave is already in starter_skills, so new players get it automatically when joining; to manually unlock it for someone:

/qs unlock fire_wave
/qs unlock fire_wave Steve     # For a specific player

config.yml's unlock.starter_skills includes fire_wave / demo_slash / demo_slash_charged by default — new players auto-unlock these.

---

④ Test-cast via command, see the placeholder first

/qs cast fire_wave

If you haven't installed MM yet or haven't written a skill of the same name, this pops up in chat:

[QinhSkills] fire_wave

✅ This is exactly the intermediate state we want. It proves the entire QS pipeline (input→state→graph→plan→gate→execution→post-processing) works; only MM performing it is missing. The next step fills that in.

---

⑤ Write the real skill of the same name in MythicMobs

Create plugins/MythicMobs/skills/fire_wave.yml (the filename is arbitrary, but the skill key must be fire_wave, matching QS's execution.mythic_skill):

fire_wave:
  Skills:
  - particles{p=flame;amount=40;hSpread=1;vSpread=1} @Origin
  - sound{s=entity.blaze.shoot;v=1;p=1} @Self
  - damage{amount=6} @EntitiesInRadius{r=4}   # Damage values are ultimately settled by the attribute plugin

Then have MM load it:

/mm reload

🔑 QS won't override this file of yours. Once you write a fire_wave of the same name, QS immediately switches to your real skill and the placeholder message disappears. /qs cast fire_wave again — this time it's real flames.

🖼️ [Image placeholder] A screenshot of /qs cast fire_wave casting real flame particles　·　suggested assets/quickstart-fire-wave.png

---

⑥ Bind it to a QI item, right-click to cast

Finally, let a sword cast fire_wave on right-click. Add a qinhskills:cast handler to the QI item's actions (this is QI's handler, which hands the keypress to QS):

# The actions section of a sword in plugins/QinhItems/items/weapon.yml (excerpt)
  actions:
    triggers:
      right_click:                    # Right-click trigger
        trigger:
          atom: right_click
        refs:
          - handler: qinhskills:cast   # Hand off to QS
            payload: "fire_wave"       # Which skill to cast

Reload the item:

/qi reload
/qi give <your sword ID>

Right-click swing — QS decides whether it can cast (unlock / cooldown / cost…), and if it passes, hands off to MM to cast the flames.

For the full item-integration syntax (JSON payload, key combinations, shift triggers, etc.) see Integrating QinhItems.

---

🔁 Remember this change loop

Three files, three reload commands, each doing its own thing — don't mix them up:

You changed…	Use this reload	Example
QS skill / graph / routing	/qs reload	Change cooldown, change target, add a combo
MM skill presentation	/mm reload	Change particles, change damage, change movement
QI item / item actions	/qi reload	Change binding, change trigger key

⚠️ Reload whichever side you changed. For example, if you changed MM's flame effect but only ran /qs reload, of course it won't take effect — that's not QS's job.

---

📋 Commands you just used (11 available commands total)

Command	Permission	Description
/qs reload	qinhskills.admin	Reload definitions / graphs / routing + sync the MM bridge
/qs list [player]	qinhskills.use	List skills with unlock / level / cooldown status
/qs info <skill>	qinhskills.use	Skill definition details
/qs unlock <skill> [player]	qinhskills.admin	Unlock
/qs lock <skill> [player]	qinhskills.admin	Lock
/qs level <skill> <level> [player]	qinhskills.admin	Set level
/qs slot <slot> <skill|clear> [player]	qinhskills.admin	Set / clear a skill slot
/qs cast <skill>	qinhskills.cast	Cast via command (for testing)
/qs silence <seconds> [player]	qinhskills.admin	Block all skill casts for N seconds (0 = clear)
/qs protocol	qinhskills.use	Runtime diagnostics
/qs bridge	qinhskills.use	MM bridge diagnostics

Aliases: /qskills, /qskill. Permissions: qinhskills.admin (admin commands), qinhskills.use (basic / list / info / protocol / bridge), qinhskills.cast (cast), qinhskills.gui.

📌 /qs test, /qs gen, etc. are not currently exposed — do not use them.

---

Keep reading

• Want to really understand this pipeline and the state machine → Core Concepts
• Wire skills to various item plugins → Integration Overview
• Write more complex skills (combos / charge-up / passives) → Skill File Structure