Integrating Other Item Plugins: The `qs cast` Command Bridge

Previous: Integrating MythicMobs　·　Next: Execution Flow & Events

Not every item plugin hooks into QS natively the way QinhItems does. NeigeItems, MMOItems, menu plugins, NPC plugins… how do you trigger a QS skill from those?

The answer is the command bridge: have the item (or menu, or NPC), when used, run a command as the player: qs cast <skill id>. As long as a plugin "can run a command on use," it can trigger a QS skill.

The iron rule still holds: the item is only responsible for "triggering"; the skill logic lives in QS, the visuals in MM, and the damage in the attribute plugin. The item's own attributes / lore use its own system; QS / QI play no part in the numbers.

🌉 1. What the command bridge is

The command-bridge pattern boils down to a single sentence:

Have the item / menu / NPC run qs cast <skill id> as the player.

Once this command reaches QS, it goes through the exact same runtime as the native QinhItems handler — passing through the full gating of unlock, cooldown, cost, targeting, and combos. The only difference is that "the entry point is a command" rather than "a native event."

🖼️ [Image placeholder] Command-bridge diagram: item use → run qs cast fire_wave → QS gating → MM visuals　·　suggested assets/command-bridge.png

📜 2. The QS command contract (stable across plugins — memorize it)

No matter which item plugin you use, the command contract on the QS side is fixed and unchanging. This is what makes the command bridge truly reliable:

Item	Content
Command format	`qs cast <skill id>`
Aliases	`/qskills` and `/qskill` work too
Permission	`qinhskills.cast` (granted to all players by default → item / NPC triggers need no extra authorization)
Identity	Must be run as a "player" (the command bridge requires "as player"). Console execution is rejected (skills must attach to a specific player)
Unlock	The skill must be one the player has already unlocked, otherwise QS blocks it and notifies them

To test unlocks: /qs unlock fire_wave, or set unlock.starter_skills / unlock.default_all: true in the QS config.yml.

⚠️ "Must run as a player" is the most common command-bridge pitfall: many plugins run commands as console by default, which gets rejected. Be sure to make it run "as the player" or "as player" (different plugins call this differently — see below).

📄 3. The full template: `neigeitems_skill_example.yml`

Below is the official template, copied verbatim, that QS drops into plugins/QinhSkills/integrations/neigeitems_skill_example.yml on first launch. It uses NeigeItems as the example.

Usage: copy this content into plugins/NeigeItems/Items/. ⚠ NeigeItems' action syntax follows the documentation for the NI version you use; what's truly stable and unchanging is the "QS command contract" at the end of the file.

yaml

#==============================================================================
#  【Integration Example 2/4】NeigeItems (or any item plugin) → trigger a QS skill (command bridge)
#
#  Not every item plugin hooks into QS natively the way QinhItems does. The general approach is the 【command bridge】:
#  simply have the item, when used, run this command as the player:   qs cast <skill id>
#  This approach works for NeigeItems, and any item/menu/NPC plugin that "can run a command on use."
#
#  This file uses NeigeItems as the example (place it under plugins/NeigeItems/Items/).
#  ⚠ NeigeItems' action syntax follows the documentation for the NI version you use; the form below is a common one,
#    but what's truly reliable and unchanging is the command contract on the QS side (see "QS command contract" at the end of the file).
#
#  Division of labor is the same as Example 1: the item only "triggers"; skill logic is in QS, visuals in MM, damage in the attribute plugin.
#  An NI item's own attributes/lore use NI's system; QS/QI play no part in the numbers.
#==============================================================================

# ---- NeigeItems item example (syntax follows the NI documentation) ----
炎符:
  material: PAPER
  name: '&b炎符'
  lore:
    - '&7右键:火焰波'
    - '&7潜行+右键:疾冲'
    - '&8技能由 QinhSkills 执行，伤害由属性插件结算'
  # NI actions: triggers right / left / shift_right / shift_left / all
  action:
    # Right-click → run  qs cast fire_wave  as the player
    right:
      - 'command: qs cast fire_wave'
    # Sneak + right-click → dash
    shift_right:
      - 'command: qs cast dash'

#------------------------------------------------------------------------------
# ★ QS command contract (this part is fixed and works across all plugins):
#   Command format: qs cast <skill id>          (aliases /qskills /qskill work too)
#   Permission:     qinhskills.cast             (granted to all players by default → item/NPC triggers need no extra authorization)
#   Identity:       must be run as a "player" (command bridge requires as player); console execution is rejected (skills must attach to a person).
#   Unlock:         the skill must be one the player has【already unlocked】, otherwise QS blocks it and notifies them.
#             Test: /qs unlock fire_wave, or unlock.starter_skills / unlock.default_all: true in QS config.yml.
#
# Difference from the QinhItems path:
#   · QinhItems goes through the handler qinhskills:cast → main event chain (see Example 1), which is more "native" and can carry payload/JSON.
#   · The command bridge goes through /qs cast → the same full gating (cooldown/cost/targeting/combos all apply), only the entry point is a command.
#   Both paths ultimately merge into the same QS runtime with identical results. Prefer the plugin's native method; use the command bridge if there isn't one.
#==============================================================================

Template highlights

Section	What it does
`炎符:` / `material` / `name` / `lore`	The NI item itself, using NI's own syntax
`action.right` → `'command: qs cast fire_wave'`	Right-click → run the command as the player to cast "Fire Wave"
`action.shift_right` → `'command: qs cast dash'`	Sneak + right-click → cast "Dash"

NI's action triggers: right / left / shift_right / shift_left / all. These correspond to player actions, but the syntax follows your NI version's documentation — QS doesn't care how the item plugin triggers, only about that final qs cast command.

🆚 4. Command bridge vs. QinhItems native handler

Both paths ultimately merge into the same runtime, with full gating and identical results. The only difference is in entry-point capabilities:

Dimension	QI native handler (`qinhskills:cast`)	Command bridge (`qs cast`)
Entry point	A handler inside the item's action	Player runs `/qs cast`
Payload capability	Supports plain id / `id:mode` / JSON	Plain skill-id string only
Item context	Yes (`item` / `itemId`, etc.)	No (the command carries no item info)
Gating (unlock/cooldown/cost/target/combo)	✅ Full	✅ Full
Final runtime / result	Same, identical	Same, identical

How to choose? Prefer the plugin's native method (QI uses a handler); use the command bridge if there's no native integration. All the command bridge sacrifices is "JSON payload" and "item context" — gating and visuals are fully preserved.

🔧 5. How to integrate other common plugins

The command bridge works for any plugin that can run a command on use. Just write that command as qs cast <skill id> and make sure it runs "as the player."

MMOItems

Both MMOItems' Ability and command-type use can run commands. In the item's ability / command config, have it run as the player:

text

qs cast fire_wave

MMOItems' various "Command Ability" types usually come with an "as player" toggle — just confirm it's set to player identity rather than console.

Menu slots run commands on click. Set the click command to the "player command" type:

text

[player] qs cast fire_wave

Different menu plugins mark player commands differently ([player], as player, etc.) — check the corresponding plugin's documentation.

NPC plugins (Citizens, etc.)

NPCs run commands when clicked / interacted with; again choose "as the player":

text

qs cast fire_wave

🧩 Universal recipe (one template to rule them all)

For any plugin, as long as you can answer "what command to run on use, and as whom," just fill it in:

What you fill in	What to put
The command to run	`qs cast <skill id>`
Execution identity	Player (not console)
Skill prerequisite	The player has already unlocked this skill

🔁 6. The command-bridge flow (one diagram)

text

Player uses item / clicks menu / clicks NPC
  → that plugin runs  qs cast fire_wave  as the player
  → QS command handler catches it (validates: player identity? unlocked?)
  → enters QS's full gating (unlock/cooldown/cooldown group/charges/GCD/resources/blood-sacrifice/targeting/combos)
  → passes → calls MythicMobs to produce the visuals
  → damage is settled by AttributePlus based on item attributes

See — from "entering the gating" onward, it's exactly the same as the QinhItems native path. The command bridge just enters the same building through a different door.

📌 7. A one-line clarification about "the item itself being referenced"

You may have heard that MMOItems / NeigeItems items themselves can be referenced through QinhCoreLib's (QCL) unified item source (written as references like mi-type-id, ni-id).

⚠️ That's a QCL / QI "item source" topic (letting the Qinhuai ecosystem reference other plugins' items as drops or crafting materials), and it's unrelated to this page. This page focuses on one thing only: how to make another plugin's item trigger a QS skill — and the answer is the command bridge, qs cast.

🩺 8. Troubleshooting checklist

Symptom	Possible cause	Fix
Command says "no permission / can't be used from console"	The item runs the command as console	Change it to run "as the player / as player"
"Skill not unlocked" notice	The player hasn't unlocked that skill	`/qs unlock fire_wave`; or set `unlock.starter_skills` / `unlock.default_all`
Command typed but nothing happens	Skill id misspelled / wrong case	Double-check the skill id (QS lowercases it); `/qs list` to view available skills
Cast only shows placeholder text	MM has no skill of the same name	Go to Integrating MythicMobs to add the visuals
I want JSON / item context	The command bridge doesn't support it	Switch to the QI native handler (Integrating QinhItems)

Keep reading

Want to understand the full flow after a command enters QS + diagnostics → Execution Flow & Events
Configure a skill's MM visuals → Integrating MythicMobs
Want native / JSON capability with QinhItems → Integrating QinhItems

Integrating Other Item Plugins: The qs cast Command Bridge ​

🌉 1. What the command bridge is ​

📜 2. The QS command contract (stable across plugins — memorize it) ​

📄 3. The full template: neigeitems_skill_example.yml ​

Template highlights ​

🆚 4. Command bridge vs. QinhItems native handler ​

🔧 5. How to integrate other common plugins ​

MMOItems ​

Menu / GUI plugins (DeluxeMenus, etc.) ​

NPC plugins (Citizens, etc.) ​

🧩 Universal recipe (one template to rule them all) ​

🔁 6. The command-bridge flow (one diagram) ​

📌 7. A one-line clarification about "the item itself being referenced" ​

🩺 8. Troubleshooting checklist ​

Keep reading ​

Integrating Other Item Plugins: The `qs cast` Command Bridge

🌉 1. What the command bridge is

📜 2. The QS command contract (stable across plugins — memorize it)

📄 3. The full template: `neigeitems_skill_example.yml`

Template highlights

🆚 4. Command bridge vs. QinhItems native handler

🔧 5. How to integrate other common plugins

MMOItems

Menu / GUI plugins (DeluxeMenus, etc.)

NPC plugins (Citizens, etc.)

🧩 Universal recipe (one template to rule them all)

🔁 6. The command-bridge flow (one diagram)

📌 7. A one-line clarification about "the item itself being referenced"

🩺 8. Troubleshooting checklist

Keep reading