MkJS (KubeJS HTTP)

一个基于 Forge 的 Minecraft 1.20.1 模组，为 KubeJS 增加网络能力：

• HTTP 请求（GET / POST）
• WebSocket 连接、收发与回调

前置需求

• Minecraft 1.20.1
• Forge 47.x（当前项目为 47.4.0）
• Java 17
• KubeJS（mods.toml 中声明为必需）

安装方法

玩家 / 整合包安装

1. 准备好 Forge 1.20.1 运行环境。
2. 安装 KubeJS（以及其要求的依赖）。
3. 将本模组 JAR 放入 .minecraft/mods（或服务器 mods）目录。
4. 启动后在模组列表确认 KubeJS HTTP (mkjs) 已加载。

从源码构建

在项目根目录执行：

.\gradlew build

构建产物位于：

build/libs/

使用说明

本模组向 KubeJS 脚本暴露两个绑定对象：

• HttpPlugin
• WSPlugin

建议在 kubejs/server_scripts/*.js 中使用。

HttpPlugin 用法

可用方法：

• HttpPlugin.get(url)
• HttpPlugin.get(url, headersMap)
• HttpPlugin.post(url, jsonString)
• HttpPlugin.post(url, headersMap, jsonString)

示例：

ServerEvents.loaded(event => {
  const getResult = HttpPlugin.get("https://httpbin.org/get");
  console.log("GET result: " + getResult);

  const headers = new java.util.HashMap();
  headers.put("Authorization", "Bearer your-token");
  headers.put("Content-Type", "application/json");

  const body = JSON.stringify({ msg: "hello from KubeJS" });
  const postResult = HttpPlugin.post("https://httpbin.org/post", headers, body);
  console.log("POST result: " + postResult);
});

WSPlugin 用法

可用方法：

• WSPlugin.connect(url, onMessage, onOpen, onClose, onError)
• WSPlugin.connect(url, onMessage, onOpen, onClose, onError, autoReconnect, maxRetries, reconnectDelayMs)
• WSPlugin.send(connectionId, message)
• WSPlugin.close(connectionId)
• WSPlugin.isConnected(connectionId)

示例：

let wsId = null;

ServerEvents.loaded(event => {
  wsId = WSPlugin.connect(
    "wss://echo.websocket.events",
    (message, url) => console.log("[WS message] " + message + " from " + url),
    (url) => console.log("[WS open] " + url),
    (reason, code, url) => console.log("[WS close] " + code + " " + reason + " " + url),
    (error, url) => console.log("[WS error] " + error + " " + url)
  );

  if (wsId && WSPlugin.isConnected(wsId)) {
    WSPlugin.send(wsId, "hello websocket");
  }
});

ServerEvents.unloaded(event => {
  if (wsId) WSPlugin.close(wsId);
});

GitHub Workflow 发布（CI/CD）

仓库已集成工作流：.github/workflows/release.yml。

1. 正式版本发布

当你推送符合格式 v[a].[b].[c] 的标签（如 v1.2.3）时，会自动：

1. 使用 Java 17 构建项目。
2. 打包 build/libs/*.jar。
3. 创建或更新同名 GitHub Release，并上传 JAR。

常用命令：

git tag v1.2.3
git push origin v1.2.3

2. Preview 预览版本发布

当你向 main 或 master 推送代码时，会自动构建并发布 preview 版本。

规则：

• 每次发布前会删除旧的 preview release/tag。
• 因此仓库中始终只保留一个 preview 版本。

注意事项

• HTTP 请求为同步调用，避免在高频事件中直接大量请求。
• 建议网络调用都使用 try/catch。
• WebSocket 回调应尽量保持轻量逻辑。