uxmEssentials REST 附加组件
为无法作为插件运行的程序(如 Web 面板、Discord 机器人、商店 Webhook、仪表盘或脚本)提供对 uxmEssentials 的 HTTP 和 WebSocket 访问。
Paper 26.2 · Java 25 · 支持 Folia · uxmEssentials 伴侣插件 · 开源 (GPL-3.0)
功能说明
uxmEssentials 发布了一个开发者 API,服务器上的任何插件都可以对其进行编译。此附加组件将该 API 的能力扩展到了网络套接字层面,使得使用任意编程语言编写的程序都能调用它。
- 读取:余额、家园、传送点、玩家自定义传送点、套装、保险箱、制裁与惩罚记录、在线时长、AFK 及隐身状态、传送请求、世界、投票、邮件和忽略列表。
- 写入:存款、取款和转账;家园和传送点;套装发放与领取;封禁、静音、踢出、警告和监禁;上帝模式、飞行、游戏模式、速度、治疗与喂食;传送;世界加载与卸载;投票和队伍进度;消息和邮件。
- 订阅:通过 WebSocket 接收实时事件流,涵盖 uxmEssentials 发布的七十四种全部事件类型,无需轮询即可获取所有信息。
本插件完全基于已公开的 API 构建,不依赖其他内容。每个端点都对应一个插件自身可以调用的表面接口,这一原则确保了两者行为的一致性,防止出现偏差。
令牌管理(在游戏中操作)
/uxmapi token create <label> [scopes] 创建令牌(仅显示一次)
/uxmapi token list 列出所有令牌(不含密钥)
/uxmapi token revoke <label> 使指定令牌失效
/uxmapi status 查看监听状态及当前连接者
密钥仅在创建时打印一次并支持一键复制,之后不再显示;服务器端仅保存密钥的哈希值。配置文件中不存在粘贴密钥的位置,因为将密钥放入配置文件会导致其泄露到剪贴板、备份文件或技术支持工单中。
每个令牌可授予三种作用域:read 用于所有 GET 请求,write 用于所有 POST 请求,events 用于事件流。同时支持 Authorization: Bearer 和 HTTP Basic 认证方式。
安装设置
-
将
uxmEssentials-rest-0.8.0.jar放入plugins/目录,与主 uxmEssentials 插件 jar 文件放在一起,然后重启服务器。 -
默认情况下不会启动监听。附加组件会生成
plugins/uxmEssentials-rest/config/rest.conf配置文件,并在日志中提示开关位置,保持静默状态,因为一个因安装而自动开始监听的 jar 包属于事故而非功能特性。enabled = false # 监听地址。默认为回环地址,这也是推荐的位置。 bind = "127.0.0.1" port = 8123 # 每个令牌每分钟允许发起的请求数量。 requests-per-minute = 120 # 跨所有令牌同时打开的事件流连接最大数量。 max-subscribers = 8 -
将
enabled = true,重启服务器,并使用/uxmapi token create panel创建一个令牌。
curl -H "Authorization: Bearer uxm_..." \
http://127.0.0.1:8123/api/v1/players/$UUID/balance
{ "ok": true, "data": { "currency": "coins", "amount": 1250.50 } }
如果服务器理解该操作但拒绝执行,并不会返回 HTTP 错误码,而是返回 ok:false 以及 Java API 返回的相同失败代码,因此消费者可以在 HTTP 层面对同一字符串进行分支判断,与进程内处理保持一致。
系统要求
- 服务器: 运行 uxmEssentials 0.8.0 的 Paper 26.2。
- 必须安装主插件:此附加组件无法独立运行。
- 不支持 TLS:监听器使用纯 HTTP 协议,默认绑定到回环地址。如果需要外部访问,请在其前端部署反向代理。
备注
开源协议 (GPL-3.0)。完整的端点、请求体字段和事件参考文档见:docs.uxplima.com。
uxmEssentials REST add-on
HTTP and WebSocket access to uxmEssentials for the programs that are not plugins: a web panel, a Discord bot, a store webhook, a dashboard, a script.
Paper 26.2 · Java 25 · Folia-ready · Companion to uxmEssentials · Open source (GPL-3.0)
What it does
uxmEssentials publishes a developer API that any plugin on the server can compile against. This add-on puts that same reach on a socket, so a program written in anything can use it.
- Read balances, homes, warps, player-warps, kits, vaults, sanctions and punishment history, playtime, AFK and vanish state, teleport requests, worlds, votes, mail and ignores.
- Write deposits, withdrawals and transfers; homes and warps; kit grants and claims; bans, mutes, kicks, warns and jails; god, flight, game mode, speed, heal and feed; teleports; world load and unload; votes and party progress; messages and mail.
- Subscribe to a live event stream over WebSocket, carrying every one of the seventy-four things uxmEssentials announces, so nothing has to be found out by polling.
It is built on the published API and nothing else. Every endpoint is one call to a surface a plugin could make itself, which is the rule that keeps the two from drifting apart.
Tokens, made in game
/uxmapi token create <label> [scopes] issue one, shown once
/uxmapi token list what exists, without the secrets
/uxmapi token revoke <label> stop one working
/uxmapi status whether it is listening, and who is connected
The secret is printed once, click-to-copy, and never again; what the server keeps is a hash. There is nowhere to paste a secret into a config file, because a secret in a config file ends up in a paste bin, a backup, and a support ticket.
Three scopes, granted per token: read for every GET, write for every POST, events for the stream. Both Authorization: Bearer and HTTP Basic work.
Setup
-
Drop
uxmEssentials-rest-0.8.0.jarintoplugins/alongside the main uxmEssentials jar and restart. -
Nothing opens. The add-on writes
plugins/uxmEssentials-rest/config/rest.conf, says in the log where the switch is, and stays dormant, because a jar that starts listening because it was installed is an incident rather than a feature.enabled = false # Where to listen. The default is the loopback address, which is where this belongs. bind = "127.0.0.1" port = 8123 # How many requests one token may make per minute. requests-per-minute = 120 # How many event-stream connections may be open at once, across every token. max-subscribers = 8 -
Set
enabled = true, restart, and issue a token with/uxmapi token create panel.
curl -H "Authorization: Bearer uxm_..." \
http://127.0.0.1:8123/api/v1/players/$UUID/balance
{ "ok": true, "data": { "currency": "coins", "amount": 1250.50 } }
An operation the server understood and declined is not an HTTP error: it comes back with ok:false and the same failure code the Java API returns, so a consumer branches on the same string over HTTP as in process.
Requirements
- Server: Paper 26.2 running uxmEssentials 0.8.0.
- Main jar required this add-on does nothing on its own.
- No TLS. The listener speaks plain HTTP and defaults to the loopback address. Put a reverse proxy in front of it if the outside world needs to reach it.
Notes
Open source (GPL-3.0). Full endpoint, body-field and event reference: docs.uxplima.com.
下载 uxmEssentials REST
下载 uxmEssentials REST
下载 uxmEssentials REST
下载 uxmEssentials REST
下载 uxmEssentials REST
下载 uxmEssentials REST
下载 uxmEssentials REST
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 uxmEssentials REST
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
从 0.10.0 升级
替换 jar 文件并重启即可。无需手动编辑任何内容。
- 您的数据保留在原位。 数据库中的表保持其当前名称,已应用的迁移会被识别且不会重复执行。
- 您的文件得以保留。 您修改过的设置或消息行不会被改动。新的设置和新的消息行会添加到您的文件中。从未修改过的消息行会更新为新的措辞。
- 存储块拥有新名称
type和pool-size,与该插件系列的其他部分共享。仍然写入backend和read-pool-size的文件将继续按原样工作。 - 一个未指定数据库的存储配置项会阻止新安装,从而防止网络服务器悄悄地在独立的文件上启动。已在该配置项下基于 SQLite 文件运行的服务器将继续正常运行,并在控制台中输出相关信息。
- 没有命令、权限节点或公共 API 被移除或重命名。
修复
/lay、/bellyflop和/spin可能导致玩家永久隐身:在旁观者模式下开始姿势、饮用隐形药水后,以及在姿势进行中重载或重启时发生此问题。现在,每次退出姿势以及崩溃后下次加入时,都会恢复身体模型。/poses reveal <player>(权限uxmessentials.poses.reveal,默认对管理员和控制台可用)可让旧版本遗留的隐身状态恢复身体模型。- 仅当账号确实拥有该名称时,才会将玩家名称填入管理员命令、点击动作、套装动作、投票奖励、NPC 命令和占位符货币中。关闭 Paper 名称检查的服务器可能允许包含空格或括号的名称进入,这会导致向命令添加参数或更改消息。此类行现在会被跳过,并在控制台中提示。
- 聊天消息保留其他插件为其设置的颜色。
- 当没有任何内容锁定世界时,世界的昼夜和天气周期保持不变。
- 即使 Floodgate 在此插件之后启用,也能被正确检测到。
新增
storage.table-prefix用于新安装;storage.local-only用于网络中保留自身行的单一服务器;storage.copy-from-file用于首次启动时将 SQLite 文件移动到网络数据库中。- 全息图使用数据包为每位观看者单独绘制,使用其各自的语言,并在执行
/uxmess reload时重新绘制。默认情况下,点击距离全息图可达 12 格。 - 名字标签、标签页名称和聊天前缀为每位读者单独绘制,关系占位符和等级以目录行的形式显示在读者的语言中。
- NPC 在其观看者走开时会转回放置时的朝向。
%uxmessentials_player_language%,即玩家阅读所使用的语言。- 以
<center>开头的聊天行会居中显示,公告可以设置centered = true。 /uxmess reload会重新读取自定义菜单。- 管理员命令会以管理员自身的语言进行回复。
性能优化
- 计分板和标签页将其工作分散到刷新间隔内,并且每行只解析一次。
- NPC 为每位观看者发送单个数据包,且仅在朝向发生变化时发送。
- PlaceholderAPI 仅在被询问包含占位符的文段时才进行查询。
关于这个资源的讨论、问题反馈与使用心得
还没有讨论,来发第一帖吧
你是这个资源的作者?登录后可认领此资源。
相似资源
插件
PacketEvents 是一款专为 Minecraft Java 版打造的协议库,旨在简化数据包的处理与传输。
插件
ExyliaPlugins 的库。
插件
通过对话框或铁砧界面帮助你的 Anthme
插件
重新定义服务器上的生物运输方式。使用高度可定制的口袋道具,安全地捕获、存储和释放任何实体。
插件
为基于 Spigot/Paper/Folia 的服务器添加对 Vivecraft 的支持
插件
用于绘制游戏内地图或在浏览器中随探索实时进行地图绘制的实时地图。
评论 0
登录后参与评分
还没有评论,来抢沙发吧