HuHoBot-Penguin_Spigot v1.15.0

HuHoBot-Penguin_Spigot v1.15.0

下载

文件	用途	大小
HuHoBot-Penguin_Spigot-1.15.0.jar	主插件，必需。放进 plugins/	22.6 MB
HuHoBot-Engine-GraalJs-1.15.0.jar	可选。仅当你要写 .js 脚本时需要，放进 plugins/HuHoBotPenguin/engines/	34.1 MB
HuHoBot-Engine-GraalPy-1.15.0.jar	可选。仅当你要写 .py 脚本时需要，放进 plugins/HuHoBotPenguin/engines/	124.6 MB

只想用现成附属插件的话，只下载主插件即可，两个引擎包不必装。

.lua 脚本不需要任何引擎——LuaJ 已经打进主 jar。不放引擎包插件照常启动，只是对应语言的脚本加载失败，其它语言不受影响。

引擎包需与主插件同一次构建产出（文件名版本号要一致，对不上时启动会给出告警）。

脚本扩展系统（新增，仅 Spigot / Paper）

不用编译就能扩展插件，用 JavaScript / Lua / Python 写脚本即可。

目录式脚本插件——plugins/HuHoBotPenguin/addons/<名字>/ 下放一个目录就是一个插件：

plugins/HuHoBotPenguin/addons/hello/
├── metadata.yaml          name / version / author / description / entry
├── _conf_schema.json      配置声明（可选），默认值写回 addons/config/hello.json
├── requirements.txt       Python 依赖声明（可选，仅预检提示）
└── main.js                或 main.lua / main.py

根目录上直接放 .js / .lua / .py 不再加载（会有一条提示告诉你挪到哪）。

Bird 桥——三种语言注入同一组对象，能力完全对等：

能力	说明
Bird.onEvent	监听任意 Bukkit 事件，可指定优先级
Bird.onCommand	注册游戏内命令，不需要改 plugin.yml，支持 Tab 补全
Bird.runTask*	同步 / 异步定时任务，重载时自动取消
Bird.fetch	异步 HTTP，回调切回主线程
Bird.on / Bird.emit	跨脚本事件总线
Bird.registerBotCommand	往 QQ 群里加自定义命令
config / kv / setData	用户可改配置、键值存储、脚本私有持久化
玩家 / 世界 / 方块 / 物品 / 音效 / 粒子	常用 Bukkit 操作的封装

引擎按需安装：

入口	引擎	放在哪	体积
main.lua	LuaJ 3.0.1	已在主 jar 内	—
main.js	GraalJS 24.1.2	plugins/HuHoBotPenguin/engines/HuHoBot-Engine-GraalJs-<版本>.jar	约 34 MB
main.py	GraalPy 24.1.2（Python 3）	plugins/HuHoBotPenguin/engines/HuHoBot-Engine-GraalPy-<版本>.jar	约 125 MB

重载

/huhobot scripts reload              卸载全部再加载全部
/huhobot scripts reload hello        只重载 addons/hello/，目录名大小写不敏感

重载和加载失败都会撤销该脚本登记的全部内容——Bukkit 事件、动态命令、定时任务、QQ 群命令、addon 元数据，不会留下幽灵条目。_enabled: false 记为「跳过」而不是「失败」。

兼容性

• 仅 Spigot / Paper 平台（其它平台未适配）
• 主插件保持 Java 8 字节码，可运行在 1.16.5 及以上服务端
• 引擎包由 Java 17 构建，但只是被加载的库，不影响服务端自身的 Java 要求

三语言写法差异

同一种返回值，三种语言拿到的形态不同，这是最容易踩的地方：

	命令参数	列表	字典
JavaScript	args[0]	.length、arr[0]	obj.key
Lua	args[1]	#t、t[1]、ipairs(t)	t.key、pairs(t)
Python	args[0]	len(x)、for v in x	x["key"]

Lua 侧是 1 起。LuaJ 会把 Java 的 List / Map 变成 userdata，在 Lua 里既不能取长度也不能 pairs，所以插件的 Lua 绑定层会把容器返回值转成真正的 table。另外 Lua 调用 Bird 的方法必须用冒号（Bird:broadcast(...)），点号会丢掉 self 导致参数错位。

Bird.tell 支持玩家、任意 CommandSender 和玩家名三种重载，所以从控制台执行脚本命令也能正常回应；giveItem / sendActionBar 这些只接受 Player，从控制台调用前先 Bird.getPlayer(...) 并判空。

已知边界

• Bird.fetch 走 JVM 默认信任库。目标站点证书链不被信任时会失败（例如本机装了流量代理时 GitHub 会被拦截），需要访问这类站点时把根证书导入服务端 JVM 的 cacerts。
• Python 的 requirements.txt 只做 import 预检并打警告，不会自动安装任何第三方库。
• .py 首次加载需要解压 GraalPy 标准库，约 10 秒，之后有缓存会快很多。
• 脚本回调在主线程执行，回调里不要做长时间阻塞操作。

文档

完整说明见仓库 docs/spigot-script-addons.md，含全部 Bird API 清单、三语言完整示例和常见报错速查。

致谢

脚本扩展系统（Bird 桥与脚本加载、生命周期设计）借鉴并移植自 birdlibraryapi（Apache-2.0，原作者 prach1121），并按 Spigot 1.16+ 与 HuHoBot 附属插件注册做了适配。