🔬 Diagnostics & Protocol

Previous: Script API　·　Next: Data Storage

When a skill "won't cast" or "casts but does nothing," QS offers two diagnostic commands (/qs protocol, /qs bridge) and a set of debug trace logs, working together with the SkillRuntimeProtocol protocol layer to pinpoint the problem. This chapter spells out the QS ↔ MythicMobs protocol contract, how to read the diagnostic output, and what each trace stage means. This document targets QS 1.0.22.

QS has only one runtime pipeline. The trace reflects the stages of this single pipeline; there are no multiple chains.

1. The protocol layer: `SkillRuntimeProtocol`

The QS → MM forwarding sits behind a protocol layer that makes "identity / version / required fields / availability / failure reason" explicit:

Constant / Method	Value / Effect
`PROTOCOL_ID`	`"qinhskills:skill_cast_request"`
`PROTOCOL_VERSION`	`1`
`requiredFields()`	`{skillId, casterId}`
`isAvailable()`	Bridge id is non-empty and MythicMobs is available
`compatibility()`	`OK` / `BRIDGE_MISSING` / `MYTHIC_MISSING`
`validate(request)`	Validates the request, returns a `List<String>` of issues (empty list = valid)
`describe()`	Returns a `SkillRuntimeProtocolState` snapshot

Compatibility logic

Bridge unavailable               → BRIDGE_MISSING
Bridge available but MM not       → MYTHIC_MISSING
Both available                    → OK

Request: `SkillCastRequest`

kotlin

data class SkillCastRequest(
    val skillId: String,
    val casterId: UUID,
    val targetId: UUID?,
    val context: Map<String, Any>,
)

The three checks in validate:

skillId is not blank
casterId is not the zero UUID (UUID(0,0))
context is not empty

The single execution outlet

After protocol validation passes, there's only one outlet for actually "casting":

MythicExecutor.cast → MythicBukkit apiHelper.castSkill

QS itself does not draw particles or compute damage. SUCCESS only means QS successfully handed the request to MM; the actual outcome is determined by the MM skill. When MM isn't installed, it degrades to a placeholder message [QinhSkills] SkillName.

2. `/qs protocol`

Prints a snapshot of the protocol layer (describe()):

[QS] protocol=qinhskills:skill_cast_request@v1
[QS] required=[skillId, casterId]
[QS] bridge=<bridgeId>, bridgeAvailable=true, mythic=true, ready=true
[QS] compatibility=OK

Line-by-line reading:

Field	Meaning	When abnormal
`protocol`	Protocol id + version	—
`required`	Required fields	—
`bridge`	Bridge implementation id	empty string = bridge not registered properly
`bridgeAvailable`	Whether the bridge is available	`false` → `BRIDGE_MISSING`
`mythic`	Whether MM is available	`false` → `MYTHIC_MISSING`
`ready`	Overall readiness (bridge && MM)	`false` = skills won't produce real effects
`compatibility`	Combined compatibility code	see table above

Seeing compatibility=MYTHIC_MISSING: the QS side is fine — go install / troubleshoot MythicMobs. Seeing BRIDGE_MISSING: the bridge itself didn't come up — /qs reload first to re-sync the bridge.

3. `/qs bridge`

Prints the bridge's live status:

[QS] bridgeId=<id>
[QS] bridgeAvailable=true
[QS] lastRequest=fire_wave

Field	Meaning
`bridgeId`	The current bridge implementation identifier
`bridgeAvailable`	Whether the bridge is available
`lastRequest`	The skill id forwarded most recently (`null` if none)

lastRequest is very handy: a player presses a key and says nothing happened — check whether it refreshed to the corresponding skill id here. If it did = the request reached the bridge (the problem is on the MM side); if it didn't change = the request never reached the bridge (the problem is in gating/routing/triggering).

4. debug trace logs

Enable in config.yml:

yaml

debug: true

Once enabled, each cast prints a tagged trace by pipeline stage, making it easy to see "where it got stuck":

Tag	Stage
`[QI]`	QI-side entry (item trigger)
`[EVENT]`	`QISkillUseEvent` gateway fires the event
`[PARSE]`	Payload normalization, skill id resolution
`[ROUTE]`	Graph resolution, node selection (opener/continuation/combo)
`[GATE]`	Gate checks item by item (unlock/cooldown/charges/GCD/resource/blood-sacrifice/conflict/condition/cast_mode)
`[EXEC]`	Hand off to MythicExecutor for execution
`[POST]`	Post-processing (enter CD, spend cost, `post_js`)
`[FALLBACK]`	Took the `QiListener` backstop path
`[BYPASS]`	Always logged (unaffected by the debug switch); indicates the reason a stage was skipped

[BYPASS] is logged whether or not debug is on, specifically recording "why a stage didn't run." When troubleshooting "the skill mysteriously won't cast," look here first.

Typical troubleshooting paths

Symptom	Which trace to check
Keypress does nothing at all	Whether `[QI]` / `[EVENT]` appear
EVENT appears but no EXEC	`[GATE]` — which gate item blocked it
EXEC happened but no effect	`/qs bridge` `lastRequest` + the `mythic` field of `/qs protocol`
Combo won't chain	`[ROUTE]` — whether the node's `require_state` matches
Placeholder returns empty	Whether the skill's profile state exists (see Data Storage)

QS has 11 subcommands total (/qs, aliases /qskills /qskill); the diagnostics-related ones are:

Command	Permission	Notes
`/qs reload`	`qinhskills.admin`	Reload definitions/graph/routing + sync the MM bridge
`/qs protocol`	`qinhskills.use`	Protocol-layer snapshot
`/qs bridge`	`qinhskills.use`	Bridge status + `lastRequest`
`/qs info <skill>`	`qinhskills.use`	Skill definition details
`/qs list [player]`	`qinhskills.use`	List skills with unlock/level/cooldown

⚠️ There are no commands like /qs test or /qs gen. Capabilities marked "planned / internal" in the text are currently not exposed. Diagnostics rely solely on /qs protocol, /qs bridge, and the trace from debug: true.

🔬 Diagnostics & Protocol ​

1. The protocol layer: SkillRuntimeProtocol ​

Compatibility logic ​

Request: SkillCastRequest ​

The single execution outlet ​

2. /qs protocol ​

3. /qs bridge ​

4. debug trace logs ​

Typical troubleshooting paths ​

5. Command overview (diagnostics-related) ​

Further reading ​