Class ScriptEngines

java.lang.Object
scripting.ScriptEngines
public final class ScriptEngines extends Object
集中式腳本引擎工廠 —— Track B（Nashorn → GraalJS）遷移的「引擎接縫」。

兩處引擎建立點(AbstractScriptManager.getInvocable(String, MapleClient) 與 PortalScriptManager)都向本類別取引擎,使引擎建立集中於一處。

C8 收尾(2026-06-02):正式環境 GraalJS-only、Nashorn-free

C0–C7 的「雙引擎並存 + 逐類別 rollout(portal→reactor→npc→quest→event)+ 黃金參考 differ」 全數完成後,本里程碑(C8)把所有類別一次切到 GraalJS 並拔除 Nashorn:

  • fresh() / fresh(String) 一律建立 GraalJS 引擎 —— 不再有 backend 選擇、 不再有逐類別白名單(allowlist 機制已隨 C8 移除;回退方式為 git revert,非執行期開關)。
  • nashorn-core:15.7 已由 build.gradle 的 implementation 降為 testImplementation → src/ 不再 import 任何 Nashorn API 套件。黃金參考引擎的 建立點移入測試樹(test/scripting/GoldenReference),供 *RolloutDifferTest 續存比對。
  • map/ 與 special/ 兩類別在 C3–C7 期間始終留在 Nashorn(不在 rollout 白名單內),於 C8 首次切到 GraalJS;其執行緒模型與 npc/quest 相同(經 NPCScriptManager 的 per-client npc_mutex 序列化),correctness parity 由 MapSpecialRolloutDifferTest 把關。

安全性聲明(誠實)

newGraalEngine() 刻意關閉 GraalJS 沙箱(allowAllAccess),授予腳本對整個 JVM 的 無限制反射存取。這與 Nashorn 過去授予這 ~2,700 個「受信任的第一方伺服器內容」的信任等級 對等(非退步)。切勿用於執行不受信任的 JS。

  • Method Details

    • fresh

      public static ScriptEngine fresh()
      全新 GraalJS 引擎。

    • fresh

      public static ScriptEngine fresh(String path)
      全新 GraalJS 引擎。path 參數於 C8 後不再影響 backend 選擇(全域 GraalJS), 保留簽章供 AbstractScriptManager / PortalScriptManager 既有呼叫點。

    • serialized

      public static Invocable serialized(Invocable iv)
      把一個 event 引擎的 Invocable 包成「序列化進入」代理:per-engine 一把 ReentrantLock,橫跨整個 invokeFunction/put/… 持鎖,滿足 GraalJS 「Context 禁止並發、但允許序列換執行緒」的契約。

      只有 GraalJS 需要序列化:本方法只在底層引擎為 GraalJSScriptEngine 時裝代理; 否則原樣回傳 iv(C8 後正式環境引擎一律為 GraalJS,此分歧僅在 test/ 以 nashorn-core 黃金引擎 驗證代理契約時才走到)。回傳的代理同時實作 ScriptEngine 與 Invocable,故 EventScriptManager 的 (ScriptEngine) iv cast 與 EventManager 的 iv.invokeFunction(...) 皆可用。

      必須 ReentrantLock:排程方法體會同執行緒同步回呼另一 invoke (如 scheduledTimeout → dispose → playerExit),reentrant 才不自我死鎖。

    • trackStructuralLock

      public static Lock trackStructuralLock(Lock inner)
      把 EventInstanceManager 的結構鎖(wL/rL)包成「會登記持有狀態」的 Lock: 成功取得時 +1、釋放時 -1(per-thread 計數)。除此之外完全委派內層鎖,語意不變 (可重入、公平性、Condition 皆沿用內層 ReentrantReadWriteLock 的)。供 EventInstanceManager 的 rL/wL 欄位初始化使用。

    • factory

      public static ScriptEngineFactory factory()
      給將來可能需要 factory 形式的呼叫點(目前 PortalScriptManager 改用 fresh(String))。