Glossary
Navigation: Docs Home · Contents · Core Concepts · Module System · FAQ · Diagnostic Codes
This page collects the common terms used across QinhCoreLib (QCL) and the Qinhuai RPG ecosystem. Each entry gives a one-sentence explanation and points to a detailed page. Roughly grouped by topic.
🧩 Platform & Ecosystem
QCL (QinhCoreLib) — The core foundation / platform library of the Qinhuai ecosystem. It implements no gameplay; it provides a unified item source, economy, scripting, database, PDC, placeholders, GUI, action contracts, bridges, and diagnostics. Main class com.qinhuai.corelib.QinhCoreLib. See Overview.
QI — QinhItems, the item system plugin. Responsible for item definition/assembly/display; it does not directly manage combat values or crafting. Hard-depends on QCL.
QS — QinhSkills, the casting/skill engine. Provides variable channels, passives, cooldowns, casting (channeling), etc.; QI's item actions hand off the release to it via QISkillUseEvent (handlerId qinhskills:cast).
QF — QinhForge, the forging gameplay plugin.
QSt — QinhStrengthen, the strengthening gameplay plugin.
QCR — One of the ecosystem member plugins (collaborating by responsibility split).
QI / QS / QF / QSt / QCR together form the Qinhuai RPG ecosystem, all hard-depending on QCL; QCL provides them with a unified item source, attribute pipeline, toolkit, and bridges.
🏗️ Architecture Concepts
Module — A functional unit in QCL that can be independently load/enable/disable/unload-ed, managed by ModuleManager in ascending priority order. QCL ships 22 built-in core modules. See Module System, Core Concepts.
ModuleManager — The module registration and lifecycle manager; loadAll() loads by priority, and an exception in a single module only degrades that module without affecting the whole.
CoreModules — The entry point that registers all 22 core modules (registerAll).
AbstractModule — The default empty base implementation of the Module interface; custom modules can extend it and override only the lifecycle methods they need.
Bridge — The adapter layer connecting QCL to a specific external plugin (CraftEngine block bridge, ModelEngine model bridge, various item source bridges, economy bridge, etc.). Reflection-based; when a soft dependency is not installed it is skipped and marked NO_HOOK. See External Plugin Integration.
Soft dependency (softdepend) — An optional dependency declared in plugin.yml: if installed, the corresponding bridge is enabled; if not, it is skipped without error, affecting only load order. See FAQ.
Degrade — A fault-tolerance strategy where, when a single module/bridge errors or a soft dependency is missing, only that item is marked unavailable while the core keeps running normally; corresponds to health code DEGRADED.
Enabled / Available — Two layers of state: enabled (whether the switch is on + whether loading succeeded) and available (whether it can actually work at runtime). See Diagnostic Codes · Two-Layer State.
API boundary / apiJar / public packages / internal packages — The stable API artifact (apiJar) that QCL publishes externally exposes only the public packages; the internal packages are implementation details and sub-plugins should not depend on them. See API Overview.
📦 Item Sources
Item source (ItemSource) — QCL's unified item-origin abstraction, covering 10 types: vanilla, CraftEngine, MMOItems, NeigeItems, QinhItems, MythicMobs, CustomFishing, MagicGem, ItemsAdder, Nexo. See Item Source References.
ItemSourceManager — The item source registry; parseItemReference parses a reference string into (source, item ID, optional JSON params) and builds an ItemStack.
ItemSourceType — Enumerates all item source types and their aliases (e.g. mi/mmoitems, ia/itemsadder).
Reference — A string identifier pointing to an item, in the form source:itemId or source-itemId; with no prefix it defaults to vanilla. See Item Source References.
Alias — Multiple shorthands for the same item source, e.g. vanilla's vanilla/minecraft/mc/v.
JSON params (::) — JSON appended after :: in a reference string, passed to the item source as build parameters, e.g. ni-blade::{"品质":"传说"}.
ResolveResult — The structured return of ItemManagerAPI.resolve(...) (success/item/code/message/source/suggestion/traceId). For error codes see Diagnostic Codes.
ItemModule — The external item module interface (build/buildWithParams); a Groovy script can implement it to register a new item source under item-modules/. See Item API.
ItemMetadata / TypeManager — Convenience wrappers for reading and writing metadata and type markers on an item's PDC.
⚙️ Actions / Conditions / Expressions
Handler (QinhActionHandler) — An action handler: the callback entry point that handles a category of actions (handlerId/isAvailable/dispatch). The QI→QS contract layer. See Action & Skill Bridge.
QinhActionContext — The context dispatched to a Handler (trigger/player/item/itemId/handlerId/payload/triggerType/rawContext…).
ActionDispatchResult — The dispatch result enum: HANDLED / NOT_HANDLED / HANDLER_UNAVAILABLE.
Payload — Opaque payload data carried with an action; QI passes it through unchanged and the Handler interprets it itself.
TriggerType — A unified trigger type enum (right-click/left-click/sneak/double-click/long-press/command/passive, etc.), shielding Bukkit event details.
QISkillUseEvent — The skill trigger event shared by QI/QS (Cancellable), carrying flags such as skillHandled/castResult.
QISkillBridge — The bridge that dispatches actions to QS via the event bus, HANDLER_ID = qinhskills:cast.
ActionContext / ActionPipeline / ActionRegistry — The context, pipeline (chained or DSL), and registry of action execution.
Condition / ConditionPipeline / CompositeCondition — The condition-evaluation interface, pipeline (AND/OR), and composite condition (LogicOperator). Operators include eq/neq/exists/notnull/contains/var_eq. See Conditions & Expressions.
ExpressionEngine — An exp4j-based math expression evaluator, including random functions such as randomDouble/randomInt/randomGaussian/randomExponential.
💰 Economy
EconomyBridge — The unified economy bridge, automatically selecting a source among Vault / ExcellentEconomy / PlayerPoints (economy.default-provider). See Economy API.
EconomyProvider — The implementation of a given economy backend (id/isAvailable/getBalance/deposit/withdraw/setBalance).
EconomyTransactionResult — The return of an economy operation (success/message/code/provider).
Provider — A generic term for an implementor of some category of service; in the economy context, the EconomyProvider above.
Currency — ExcellentEconomy's multi-currency concept (money/silver/gold…); Vault/PlayerPoints are single-currency and ignore this parameter.
auto (automatic source selection) — The selection strategy when default-provider: auto: a specified currency prefers ExcellentEconomy, otherwise Vault > ExcellentEconomy > PlayerPoints.
📜 Scripts / Data / Display
GraalJS / GraalVM — The JavaScript runtime embedded in QCL; requires Paper/Purpur to pull the runtime library. See Scripting Getting Started.
Namespace — The prefix distinguishing the origin in script and item references, e.g. script qinhitems:hooks/craft.js, item itemsadder:namespace:id.
ScriptContext / qcl / ctx — The script execution context, plus the API object (qcl) and context object (ctx) injected into the script.
ScriptExecutionResult — The return of a script execution (success/value/code/message); for error codes see Diagnostic Codes.
PDC (PersistentDataContainer) — The Bukkit persistent data container; QCL's PdcService wraps reads/writes by namespace (keys in the form qinhcorelib:namespace_keyName). See Data Storage & Placeholders.
Placeholder — A marker in text that can be dynamically replaced. QCL provides PapiBridge (a PlaceholderAPI bridge that degrades safely when not installed) and the GUI's built-in {xxx} placeholders.
QinhPlaceholderProvider — The interface for registering custom %identifier_param% placeholders.
Assembly / DisplayLayer — The dynamic item display layering system: it splits display (name, lore, etc.) into stackable DisplayLayers, which apply to ItemMeta in ascending priority order. See Toolkit.
Semantic spec (SemanticSpec) — A semantic-layer spec description of objects such as items/skills/forging, used for unified expression across sources (ItemSpec/SkillSpec…).
🧰 Services & Tools
TaskScheduler — A synchronous/asynchronous task scheduling wrapper (using Runnable/Supplier to avoid cross-plugin LinkageError), compatible with Folia. Comes with CooldownManager (cooldown) and ThrottledExecutor (throttling). See Toolkit.
HologramManager — ArmorStand-based hologram management.
ServerCompat — Server platform/version detection and compatibility utilities (validateServer, multi-name fallback resolution of sounds/particles/materials, etc.).
Folia — Paper's multithreaded regionized fork; QCL scheduling goes through the Bukkit scheduler to stay compatible.
CustomBlock / CustomBlockProvider — The custom block abstraction and its backend provider (built-in CraftEngineBlockProvider). See Custom Blocks.
MiniMessage — Adventure's rich-text tag format (<red>, <bold>, etc.); QCL's TextUtil.toComponent supports both it and the legacy &/§ color codes.
❤️ Diagnostics
Health code (HealthReport) — Status codes: OK (normal), NO_HOOK (no soft dependency), DEGRADED (degraded but recoverable). See Diagnostic Codes.
Diagnostic (DiagnosticResult) — A unified diagnostic result container (success/value/code/message/suggestion/traceId), constructed with ok()/fail().
BridgeStatus — The status object of a single bridge (available/enabled/source/recoverable/message).
EcosystemStartupProbe / StartupReporter — The startup probe and startup summary printer, summarizing available item sources, economy, and hooked plugins.
Continue Reading
- Core Concepts — Conceptual basics and the startup lifecycle
- Module System — The module and diagnostic model
- Diagnostic Codes — Code tables for each subsystem
- FAQ — Frequently asked questions
- Docs Home · Contents