Navigation: Documentation Home › Server Owner Guide › Script Intro Related: 自定义GUI.md · 配置文件.md · 物品源引用.md · Developer / 脚本API.md

📜 Script Intro (Server Owner Perspective)

This page teaches you how to extend QinhCoreLib (QCL) logic using JavaScript scripts. You don't need to know Java, and you don't need to build a plugin—just drop a .js file into a directory, and you can give a GUI custom conditions and actions like "block opening if level is too low" or "click to deduct money and give an item".

---

🤔 Why You Need Scripts

QCL's GUIs and sub-plugin hooks all support "conditions" and "actions". Plain YAML config covers most common needs (permissions, items, coins…), but it falls short for needs like these:

Need	Plain YAML	Script
"Only allow opening the shop at level ≥ 30"	❌ Not flexible enough	✅ canOpen returns a boolean
"Click to buy: deduct 100 coins first then give the item, reject if not enough money"	⚠️ Splits into multiple steps, hard to judge	✅ One function handles it
"Dynamically decide based on the player's PAPI variable"	❌	✅ qcl.placeholder(...)

Scripts are a "logic back door" opened for server owners: use a small snippet of JS to express "conditions" and "actions".

---

🧩 Engine Notes (Read This First)

QCL's script engine is GraalVM JavaScript (GraalJS).

• The server (Paper / Purpur) needs to be able to load the GraalJS runtime library.
• If the runtime library is unavailable, script calls return the failure code SCRIPT_UNAVAILABLE directly (it won't crash the server, but all script logic stops working).
• After startup, watch the console to confirm the script system loaded correctly.

---

📁 Where Scripts Go

Namespace	Disk Directory	Whose
global	plugins/QinhCoreLib/scripts/global/	Server owner's shared scripts
qinhitems	plugins/QinhItems/scripts/	Namespace registered by the sub-plugin QinhItems
Others	Registered by each sub-plugin itself	Sub-plugins

💡 A namespace is a mapping from a name to a directory. When a server owner writes their own scripts, just drop them into scripts/global/, and the namespace when referencing them is global (which can also be omitted, see below). Sub-plugins can register their own namespace and point its script directory at their own plugin folder.

---

🔗 Reference Syntax Explained

A script reference is a string in three parts:

namespace:relative-path.js:functionName

Part	Description	Omission Rule
namespace	Decides which directory to look in	Omitted → defaults to global
relative-path.js	File path relative to the namespace directory	.js can be omitted, appended automatically
functionName	Which function in the file to call	Omitted → uses config's javascript.default-function (default main)

Example Comparison

Form	Equivalent Meaning
qinhitems:hooks/craft.js:check	qinhitems namespace → hooks/craft.js → call check
global:example.js	global → example.js → call main (default function name)
example.js:onClick	global (namespace omitted) → example.js → call onClick
example	global → example.js (.js appended automatically) → call main

✅ All three parts can be omitted; the shortest form is just scriptName, which calls main in scripts/global/scriptName.js.

---

⚙️ Config Options (config.yml)

Three script-related options, located in the main config:

Key	Default	Description
javascript.enabled	true	Master switch; turning it off disables all script calls
javascript.default-function	main	Default function called when the reference omits the function name
javascript.debug.print-stacktrace	false	When enabled, prints the full stack trace to the console on script errors (a troubleshooting lifesaver)

javascript:
  enabled: true
  default-function: main        # Called when the function name is omitted
  debug:
    print-stacktrace: false     # Change to true when troubleshooting

🔄 After changing config or adding new scripts, run /qcl reload to rescan the scripts directory.

---

✍️ Write Your First Script (Step by Step)

Step 1: Create the File

Create a new hello.js under plugins/QinhCoreLib/scripts/global/:

// hello.js —— Note: use English for key names/function names, Chinese only for comments
function main(ctx) {
    // ctx.player() may be null (when not triggered by a player)
    var p = ctx.player();
    qcl.logInfo("hello.js was called, player=" + (p ? p.getName() : "null"));
    return true;   // Returning true means success
}

Step 2: Reload

/qcl reload

Step 3: Reference global:hello.js (or the shorthand hello) somewhere to trigger it.

Inside a script you can always get two injected objects: qcl (API) and ctx (context). When called by a GUI, the function signature is fixed as function name(ctx){ ... }.

---

📦 ctx —— The Context Object

ctx represents "the scene of this call" (who triggered it, what data it carried).

Method	Returns	Description
ctx.player()	Player or null	The triggering player; null when not triggered by a player—always null-check
ctx.pluginName()	String	The name of the plugin that triggered it
ctx.get(key)	Value	Read data carried by the context
ctx.set(key, value)	—	Write context data (for use by later steps)
ctx.vars()	Variable collection	Get all context variables

---

🛠️ qcl —— The API Object

qcl is the toolbox QCL exports for scripts to use.

Category	Method	Description
Logging	qcl.logInfo(msg) / logWarn(msg) / logError(msg)	Print a log to the console (common for debugging)
Bridging	qcl.bridgeStatusNames()	List of currently connected external plugin bridge names
Placeholder	qcl.placeholder(text)	Parse text using PlaceholderAPI (including %...%)
Economy · Query	qcl.economyHas(amount, provider?, currency?)	Whether the player has enough money, returns a boolean
Economy · Withdraw	qcl.economyWithdraw(amount, provider?, currency?)	Deduct money, returns a boolean
Economy · Deposit	qcl.economyDeposit(amount, provider?, currency?)	Give money, returns a boolean
Item · Parse	qcl.itemParse(ref)	Parse an item source reference into an item
Item · Give	qcl.itemGive(ref, amount)	Give an item to the player, returns a boolean
Scheduling · Sync	qcl.runSync(task)	Throw a task back to the main thread to execute
Scheduling · Delayed	qcl.runSyncLater(ticks, task)	Execute on the main thread after N ticks of delay
Scheduling · Wait	qcl.runSyncAndWait(task)	Execute on the main thread and wait for the result

💰 The economy methods' provider / currency are optional parameters; if not provided, the default economy is used. The item ref is the unified item source reference (see 物品源引用.md).

---

🔁 Return Value Rules (Very Important)

What a script function "returns" determines whether QCL considers it a success or failure:

Return Value	Verdict	Notes
null / undefined / true	✅ Success	Returning nothing also counts as success
false	❌ Failure	The failure message is "script returned false"
String / Number	✅ Success with value	Carries the value back along with it
{ success: ..., message: ... }	Judged by success	You can customize the failure message

function check(ctx) {
    var p = ctx.player();
    if (!p) return false;
    if (p.getLevel() < 30) {
        return { success: false, message: "&cYour level is below 30!" };
    }
    return true;
}

---

🖼️ Attaching Conditions and Actions in a GUI

The most common use for scripts is to wire logic into a GUI's open condition and click action.

Usage 1: Open Condition (view-requirement)

view-requirement:
  type: javascript
  value: global:example.js:canOpen   # Returns false → don't allow opening

Usage 2: Click Action (click-actions)

click-actions:
  - type: javascript        # or run_script
    value: global:example.js:onClick

---

🧪 Complete Example A: Level Gate for Opening a GUI

scripts/global/shop_gate.js

function canOpen(ctx) {
    var p = ctx.player();
    if (!p) return false;
    if (p.getLevel() < 30) {
        return { success: false, message: "&cYou need level 30 to enter the shop" };
    }
    return true;
}

GUI Config (excerpt)

view-requirement:
  type: javascript
  value: global:shop_gate.js:canOpen

---

🧪 Complete Example B: Click to Buy (Deduct Money, Give Item)

scripts/global/buy_sword.js

function buy(ctx) {
    var p = ctx.player();
    if (!p) return { success: false, message: "&cOnly players can buy" };

    // 1) Check whether there's enough money first
    if (!qcl.economyHas(100)) {
        return { success: false, message: "&cNot enough coins, need 100" };
    }
    // 2) Deduct money
    if (!qcl.economyWithdraw(100)) {
        return { success: false, message: "&cWithdrawal failed" };
    }
    // 3) Give the item (item source reference, 1 of it)
    qcl.itemGive("qinhitems-fire_sword", 1);

    return { success: true, message: "&aPurchase successful!" };
}

GUI Config (excerpt)

click-actions:
  - type: javascript
    value: global:buy_sword.js:buy

Order is critical: check first → then deduct → then give. If any step fails, return a failure object to avoid "money deducted but no item given".

---

📖 Built-in Example Scripts Explained Function by Function

QCL ships with two example scripts that you can copy and modify directly:

scripts/global/example.js

function main(ctx) {
    qcl.logInfo("example.js main() was called, player=" + (ctx.player() ? ctx.player().getName() : "null"));
    return true;
}
function canOpen(ctx) {
    var player = ctx.player();
    if (!player) return false;
    return player.getLevel() >= 0;     // An always-true example condition
}
function onClick(ctx) {
    var player = ctx.player();
    if (!player) return false;
    qcl.logInfo("onClick: " + player.getName());
    return true;
}

Function	Purpose	How to Reference It in a GUI
main	Default entry point; logs then returns success	Called when the function name is omitted
canOpen	Open condition example (null-check + level check)	value: global:example.js:canOpen
onClick	Click action example (logging)	value: global:example.js:onClick

scripts/global/qcl_status.js

Contains the formatStatus function, which appends output lines to the /qcl status detail command. This is a demonstration of "sub-plugin / system-level" usage; server owners generally don't need to touch it.

---

🔒 Sandbox Restrictions

Scripts run in a restricted sandbox. The allowed and forbidden lists:

✅ Allowed	❌ Forbidden
Calling the exported qcl API	Creating threads
Operating on Bukkit's Player object	File read/write (IO)
Plain JS logic	Reflecting arbitrary Java classes
	Network access

Want to do something outside the sandbox (like reading an external file)? That's beyond the scope of server owner scripts; you should switch to a sub-plugin or dedicated development capabilities, see 脚本API.md.

---

🚑 Error Codes and Troubleshooting

When a script call fails, QCL gives an error code:

Error Code	Meaning	How to Fix
SCRIPT_UNAVAILABLE	GraalJS runtime library unavailable	Switch to Paper/Purpur, confirm GraalJS is loaded
SCRIPT_PARSE_FAILED	The reference format is written wrong	Check the spelling of namespace:path:functionName
SCRIPT_NOT_FOUND	The file doesn't exist	Confirm the .js file is in the right directory and that you ran /qcl reload
SCRIPT_FUNCTION_MISSING	The function name doesn't exist	Confirm the file has this function with matching case
SCRIPT_FAILED	The script threw an exception during execution	Enable print-stacktrace to see the stack trace

---

🐛 Debugging Tips

1. Enable the stack trace: change javascript.debug.print-stacktrace to true, and the console will print the full stack trace when a script errors, so you can tell which line blew up at a glance.
2. Add logging: insert qcl.logInfo("got here: " + variable) at key steps to observe the execution path.
3. Null-check first: almost all bugs come from ctx.player() being null and not being handled—develop the habit of if (!p) return ....
4. Always reload after changes: only /qcl reload rescans scripts; otherwise your changes won't take effect.
5. Case-sensitive: namespaces, file names, and function names are all case-sensitive; copy them exactly and don't casually change the case.

---

➡️ Continue Reading

• 自定义GUI.md —— Wiring scripts into a GUI's conditions and actions
• 物品源引用.md —— The reference format used by qcl.itemGive / itemParse
• 配置文件.md —— Full explanation of the three javascript.* config options
• Developer / 脚本API.md —— Deeper script capabilities and API details