mBadges
带有收藏系统、排序装备槽位以及自动生成资源包的图形化玩家徽章。
功能介绍
- 为在线或离线玩家存储永久性和临时性徽章。
- 允许玩家在 GUI 中浏览、装备、移除、过滤和重新排序徽章。
- 从 PNG 文件生成确定性的字体资源包,并在重启后保留已分配的字符映射。
- 在玩家列表和可选的计分板名字标签中显示已装备的徽章。
- 支持 SQLite、MySQL 和 PostgreSQL,且数据库操作不会在主服务器线程上运行。
- 提供 PlaceholderAPI 占位符、带事件注册的 Java API、经过身份验证的 REST API,以及用于服务器网络的数据库轮询功能。
- 包含英文和俄文消息、自动迁移配置默认值、bStats 指标统计以及更新检查功能。
前置要求
- Java 25
- Paper、Purpur 或 Folia 26.3
- 当启用自动分发时,需要一种托管生成的资源包 ZIP 文件的方式
PlaceholderAPI、LuckPerms、Oraxen 和 ItemsAdder 为可选依赖。即使未安装这些插件,mBadges 也能正常运行。
安装
- 下载
mBadges-1.0.2.jar 并将其放入服务器的 plugins 目录。
- 启动并停止服务器一次,以创建
plugins/mBadges 文件夹。
- 按照下文描述添加徽章 PNG 文件和定义。
- 启动服务器并运行
/mbadge resourcepack rebuild。
- 托管生成的 ZIP 文件,如果希望玩家自动接收,请配置资源包分发。
请勿将 API JAR 作为服务器插件安装。它仅作为开发者的编译时工件使用。
添加徽章
将不超过 256×256 像素的 PNG 文件直接放入 plugins/mBadges/badges 目录,然后在 badges.yml 中添加其定义:
badges:
developer:
name: "<aqua>Developer"
description: "Server development team"
texture: developer.png
permission: mbadge.badge.developer
category: staff
priority: 100
hidden: false
enabled: true
temporary: true
徽章 ID 仅使用小写字母、数字、下划线 _ 或连字符 -。移除或重新排序定义不会重新分配现有的码位;稳定的映射关系保存在 generated/glyphs.yml 中。
资源包
默认的 INTERNAL 模式会写入 generated/mbadges-resource-pack.zip 和 generated/resource-pack.yml。将 ZIP 上传至直接的 HTTP(S) URL,并将生成的 SHA-1 值复制到 resourcepack.yml 中:
delivery:
send-on-join: true
url: "https://cdn.example.com/mbadges-resource-pack.zip"
required: true
sha1: "the-40-character-sha1-from-generated-resource-pack-yml"
当其他资源包管线负责字体文件时,请使用 EXTERNAL、ORAXEN 或 ITEMSADDER 模式。在这些模式下,mBadges 会保留字符映射,但不会编辑第三方配置或生成自己的资源包;你需要自行在该管线中添加匹配的位图提供程序。请参阅 资源包指南。
配置
| 文件 |
用途 |
config.yml |
语言、槽位、显示、过期时间、同步、REST、指标统计和更新设置 |
badges.yml |
徽章定义、权限、类别和优先级 |
database.yml |
SQLite、MySQL 或 PostgreSQL 连接配置 |
resourcepack.yml |
资源包生成、外部模式和分发设置 |
gui.yml |
物品栏大小、材质和导航槽位 |
lang/en_US.yml |
英文消息 |
lang/ru_RU.yml |
俄文消息 |
缺失的设置会在启动时自动添加。/mbadge reload 命令可重载消息、GUI 设置、安全的主配置项、徽章定义和内部资源包。数据库类型和连接设置需要完全重启服务器才能生效。
槽位限制起始于 equipment.default-slots。授予 mbadge.max.2、mbadge.max.3 等权限可将单个玩家的限制提升至 equipment.max-badges-hard-limit。
指令
| 指令 |
描述 |
/badge 或 /badge gui |
打开收藏 GUI |
/badge list |
列出拥有的徽章 |
/badge set <id> |
装备一个徽章 |
/badge remove <id> |
卸下徽章 |
/badge clear |
卸下所有徽章 |
/badge info <id> |
显示徽章详情 |
/mbadge give <player|uuid> <id> [--duration 1w2d] |
给予一个徽章 |
/mbadge take <player|uuid> <id> |
移除一个徽章 |
/mbadge equip <player|uuid> <id> |
强制装备徽章 |
/mbadge unequip <player|uuid> <id> |
卸下徽章 |
/mbadge clear <player|uuid> |
清除已装备的徽章 |
/mbadge list <player|uuid> |
显示收藏数量 |
/mbadge reload |
重载安全设置和定义 |
/mbadge resourcepack rebuild |
强制重建资源包 |
名称仅适用于服务器之前见过的玩家。UUID 无需玩家加入即可使用。
权限
| 权限 |
默认值 |
用途 |
mbadge.use |
everyone |
玩家命令 |
mbadge.gui |
everyone |
收集界面 GUI |
mbadge.badge.<id> |
unset |
使用已配置的徽章 |
mbadge.max.<number> |
unset |
增加装备槽位数量 |
mbadge.admin |
operators |
所有管理权限 |
mbadge.admin.give |
operators |
发放徽章 |
mbadge.admin.take |
operators |
移除徽章 |
mbadge.admin.equip |
operators |
为玩家装备或卸下徽章 |
mbadge.admin.clear |
operators |
清除已装备的徽章 |
mbadge.admin.list |
operators |
读取收集数量统计 |
mbadge.admin.reload |
operators |
重新加载配置 |
mbadge.admin.resourcepack |
operators |
重建资源包 |
PlaceholderAPI
%mbadge_equipped% — 渲染已装备的符号
%mbadge_count% — 已装备数量
%mbadge_owned_count% — 拥有数量
%mbadge_slots% — 可用槽位
%mbadge_slot_1%, %mbadge_slot_2%, ... — 特定槽位中的符号
空槽位将返回空字符串。占位符使用缓存数据,不会在服务端线程上查询数据库。
存储与网络
SQLite 是零配置的默认选项。对于服务器网络,请让所有服务器指向同一个 MySQL 或 PostgreSQL 数据库,并启用 sync.enabled。轮询机制用于刷新缓存的在线玩家;它不需要 Redis 或代理插件。每个服务器必须使用相同的 badges.yml 和符号映射表。
可选的 REST 服务默认绑定到 localhost,要求至少 24 个字符的令牌,检查 IP 白名单,并对调用者进行速率限制。请将其置于防火墙或反向代理之后。请参阅 API 和 REST 指南。
兼容性说明
- 玩家列表显示默认启用。
- 记分板名字标签默认禁用,因为记分板/队伍插件可能占用相同的展示层。
- 聊天格式化通过 PlaceholderAPI 和 Java 渲染器暴露;mBadges 不替换聊天插件。
- 不需要也不支持 Velocity,因为徽章在后端服务器和资源包中渲染。
遥测与更新
mBadges 使用 bStats 插件 ID 33353 进行匿名使用统计。可通过设置 metrics.enabled: false 禁用数据采集。更新检查器从 Modrinth 读取发布信息,并可独立通过设置 updates.enabled: false 禁用。
构建
./gradlew clean build
产物:
build/libs/mBadges-1.0.2.jar
api/build/libs/mBadges-API-1.0.2.jar
本项目采用 MIT 许可证授权。
mBadges
Graphical player badges with collections, ordered equipment slots, and a generated resource pack.
What it does
- Stores permanent and expiring badges for online or offline players.
- Lets players browse, equip, remove, filter, and reorder badges in a GUI.
- Generates a deterministic font resource pack from PNG files and preserves assigned glyphs across restarts.
- Displays equipped badges in the player list and, optionally, scoreboard nametags.
- Supports SQLite, MySQL, and PostgreSQL without running database work on the server thread.
- Provides PlaceholderAPI placeholders, a Java API with events, an authenticated REST API, and database polling for server networks.
- Includes English and Russian messages, automatic config-default migration, bStats metrics, and update checks.
Requirements
- Java 25
- Paper, Purpur, or Folia 26.3
- A way to host the generated resource-pack ZIP when automatic delivery is enabled
PlaceholderAPI, LuckPerms, Oraxen, and ItemsAdder are optional. mBadges also works when none of them are installed.
Install
- Download
mBadges-1.0.2.jar and place it in the server's plugins directory.
- Start and stop the server once to create
plugins/mBadges.
- Add badge PNG files and definitions as described below.
- Start the server and run
/mbadge resourcepack rebuild.
- Host the generated ZIP, then configure resource-pack delivery if players should receive it automatically.
Do not install the API JAR as a server plugin. It is only a compile-time artifact for developers.
Add a badge
Put a PNG no larger than 256×256 directly in plugins/mBadges/badges, then add its definition to badges.yml:
badges:
developer:
name: "<aqua>Developer"
description: "Server development team"
texture: developer.png
permission: mbadge.badge.developer
category: staff
priority: 100
hidden: false
enabled: true
temporary: true
Badge IDs use lowercase letters, numbers, _, or -. Removing or reordering definitions does not reassign existing code points; the stable map is kept in generated/glyphs.yml.
Resource pack
The default INTERNAL mode writes generated/mbadges-resource-pack.zip and generated/resource-pack.yml. Upload the ZIP to a direct HTTP(S) URL and copy the generated SHA-1 into resourcepack.yml:
delivery:
send-on-join: true
url: "https://cdn.example.com/mbadges-resource-pack.zip"
required: true
sha1: "the-40-character-sha1-from-generated-resource-pack-yml"
Use EXTERNAL, ORAXEN, or ITEMSADDER mode when another pack pipeline owns font files. In those modes mBadges keeps the glyph map but does not edit third-party configuration or generate its own pack; add the matching bitmap providers to that pipeline yourself. See the resource pack guide.
Configuration
| File |
Purpose |
config.yml |
language, slots, display, expiry, sync, REST, metrics, and updates |
badges.yml |
badge definitions, permissions, categories, and priorities |
database.yml |
SQLite, MySQL, or PostgreSQL connection |
resourcepack.yml |
pack generation, external mode, and delivery |
gui.yml |
inventory size, materials, and navigation slots |
lang/en_US.yml |
English messages |
lang/ru_RU.yml |
Russian messages |
Missing settings are added on startup. /mbadge reload reloads messages, GUI settings, safe main settings, badge definitions, and the internal pack. Database type and connection settings require a full restart.
Slot limits start at equipment.default-slots. Grant mbadge.max.2, mbadge.max.3, and so on to increase an individual player's limit up to equipment.max-badges-hard-limit.
Commands
| Command |
Description |
/badge or /badge gui |
Open the collection GUI |
/badge list |
List owned badges |
/badge set <id> |
Equip a badge |
/badge remove <id> |
Unequip a badge |
/badge clear |
Unequip every badge |
/badge info <id> |
Show badge details |
/mbadge give <player|uuid> <id> [--duration 1w2d] |
Give a badge |
/mbadge take <player|uuid> <id> |
Remove a badge |
/mbadge equip <player|uuid> <id> |
Force-equip a badge |
/mbadge unequip <player|uuid> <id> |
Unequip a badge |
/mbadge clear <player|uuid> |
Clear equipped badges |
/mbadge list <player|uuid> |
Show collection counts |
/mbadge reload |
Reload safe settings and definitions |
/mbadge resourcepack rebuild |
Force a pack rebuild |
Names work for players previously seen by the server. UUIDs work without requiring the player to have joined.
Permissions
| Permission |
Default |
Purpose |
mbadge.use |
everyone |
Player commands |
mbadge.gui |
everyone |
Collection GUI |
mbadge.badge.<id> |
unset |
Use a configured badge |
mbadge.max.<number> |
unset |
Increase equipped slots |
mbadge.admin |
operators |
Every administrative permission |
mbadge.admin.give |
operators |
Give badges |
mbadge.admin.take |
operators |
Remove badges |
mbadge.admin.equip |
operators |
Equip or unequip for players |
mbadge.admin.clear |
operators |
Clear equipped badges |
mbadge.admin.list |
operators |
Read collection counts |
mbadge.admin.reload |
operators |
Reload configuration |
mbadge.admin.resourcepack |
operators |
Rebuild the pack |
PlaceholderAPI
%mbadge_equipped% — rendered equipped glyphs
%mbadge_count% — equipped count
%mbadge_owned_count% — owned count
%mbadge_slots% — available slots
%mbadge_slot_1%, %mbadge_slot_2%, ... — glyph in a specific slot
Empty slots return an empty string. Placeholders use cached data and do not query the database on the server thread.
Storage and networks
SQLite is the zero-configuration default. For a network, point every server at the same MySQL or PostgreSQL database and enable sync.enabled. Polling refreshes cached online players; it does not require Redis or a proxy plugin. Each server must use the same badges.yml and glyph map.
The optional REST service binds to localhost by default, requires a token of at least 24 characters, checks an IP allowlist, and rate-limits callers. Keep it behind a firewall or reverse proxy. See the API and REST guide.
Compatibility notes
- The player-list display is enabled by default.
- Scoreboard nametags are disabled by default because scoreboard/team plugins may own the same presentation layer.
- Chat formatting is exposed through PlaceholderAPI and the Java renderer; mBadges does not replace a chat plugin.
- Velocity is not required or supported because badges render on the backend server and client resource pack.
Telemetry and updates
mBadges uses bStats plugin ID 33353 for anonymous usage statistics. Disable collection with metrics.enabled: false. The update checker reads releases from Modrinth and can be disabled independently with updates.enabled: false.
Build
./gradlew clean build
Artifacts:
build/libs/mBadges-1.0.2.jar
api/build/libs/mBadges-API-1.0.2.jar
The project is licensed under the MIT License.
评论 0
登录后参与评分
还没有评论,来抢沙发吧