FFAUtils: Paper FFA 插件
FFAUtils 是一款面向 Paper 1.21.4 的开源 Minecraft PvP 和自由对战 (FFA) 插件。它提供可配置的套装、竞技场和出生点、战斗踢出检测、玩家统计、基于等级的 PvP 访问控制,以及十胜制决斗 (/fto10),适用于竞技类 Minecraft 服务器。
功能
- 套装 — 通过游戏内的库存编辑器创建、编辑和删除套装。每个套装单独存储在一个 JSON 文件中。
- 多个出生点 — 将任意位置命名为出生点,并可选择限制在该位置可用的套装。
- 等级门禁出生点 — 要求达到最低 PvP 等级(例如 HT3 或更高)才能进入某个出生点,支持从 MCTiers、PvPTiers 或 EliteStorm 解析等级。详见 等级门禁出生点。
- 战斗日志 — 处于战斗状态的玩家在退出时会被击杀,且在标记期间无法运行已配置的命令。
- Fto10 决斗 — 邀请另一位玩家使用相同的套装和出生点进行十胜制系列赛,包含回合比分、外部伤害保护以及自动判负胜利。
- 大厅物品 — 为在大厅中的玩家配置快捷栏,并为加载了套装后死亡的玩家提供重生道具。
- 统计信息 — 击杀数、死亡数和 K/D 比存储在 SQLite 中,并通过 PlaceholderAPI 暴露。
- 死亡消息 — 一组可配置的广播消息池,包含连杀播报。
依赖
这两个可选依赖均为软依赖——即使没有它们,插件也能正常加载;当缺少 PlaceholderAPI 时,插件会跳过注册占位符。
安装
- 从 发布页 下载
FFAUtils-<version>.jar。
- 将其放入
plugins/ 文件夹。
- 启动服务器一次以生成配置文件,然后编辑它们并运行
/ffautils reload。
命令
所有权限默认仅限操作员。
玩家
| 命令 |
权限 |
描述 |
/loadme <kit> <spawn> |
无 |
加载套装并进入指定出生点。此处应用套装限制和等级门禁。 |
/spawn |
ffautils.commands.spawn |
传送回大厅,恢复生命值并重新获得大厅物品。 |
/dead |
无 |
自杀。 |
/kit <name> |
ffautils.commands.kit |
装备一个套装。 |
/kit list |
ffautils.commands.kit |
列出可用套装。 |
/fto10 invite <player> |
无 |
邀请玩家进行十胜制决斗,使用你当前的套装和出生点。 |
/fto10 accept <player> |
无 |
接受来自某玩家的 Fto10 邀请。 |
/fto10 deny <player> |
无 |
拒绝 Fto10 邀请。 |
/fto10 leave <player> |
无 |
离开决斗并将胜利判给对手。 |
管理
| 命令 |
权限 |
描述 |
/kit create|edit|delete <name> |
ffautils.commands.kit |
管理套装。create 和 edit 会打开库存编辑器。 |
/ffakiteditor |
ffautils.commands.ffakiteditor |
打开套装编辑器菜单。仅限玩家。 |
/setspawn create <name> |
ffautils.commands.setspawn |
将当前位置保存为出生点。 |
/setspawn delete <spawn> |
ffautils.commands.setspawn |
删除一个出生点。 |
/setspawn allowkit <spawn> <kit> |
ffautils.commands.setspawn |
限制某个出生点仅允许特定套装。若出生点未设置允许套装,则允许所有套装。 |
/setspawn removekit <spawn> <kit> |
ffautils.commands.setspawn |
从出生点的允许套装列表中移除一个套装。 |
/ffautils reload |
ffautils.commands.ffautils |
重载消息、套装、出生点和死亡消息。仅限玩家。 |
/tiers … |
ffautils.commands.tiers |
管理等级门禁 —— 见下文。 |
其他权限
| 权限 |
效果 |
ffautils.bypass-combat-block |
在处于战斗状态时运行被阻止的命令。 |
ffautils.tiers.bypass |
无视等级限制进入受保护的出生点。 |
名为 lobby 的出生点是特殊的:玩家加入服务器或被 /spawn 命令召唤时会传送到这里。如果该出生点不存在,则使用第一个世界的出生点。
配置
| 文件 |
用途 |
config.yml |
主要设置,包括整个等级门禁系统。 |
messages.yml |
所有面向玩家显示的字符串,采用 MiniMessage 格式。 |
death-messages.yml |
死亡广播消息池。 |
blocked-commands.yml |
玩家在战斗状态下无法运行的命令标签列表。 |
spawn-lobby-items.yml |
大厅快捷栏物品和重生道具。 |
spawns/<name>.json |
每个出生点对应一个文件(包含位置和允许的套装)。 |
kits/<name>.json |
每个套装对应一个文件。 |
stats.db |
存储击杀和死亡数据的 SQLite 数据库。 |
messages.yml 在更新时永远不会被覆盖。新版本新增的字符串会自动初始化,因此该文件在升级过程中始终保持有效。
主 config.yml 键值
disable-lobby-items: false # 完全跳过给予大厅物品
stats-database-name: stats.db # 插件文件夹内的 SQLite 文件名
combatlog.timeout-ticks: 300 # 战斗标记持续的时间,单位为刻
战斗日志持续时间也可以设置为 duration-combat-log(单位为秒),其值会乘以 20 转换为刻。如果两个键都不存在,默认值为 15 秒。
等级门禁出生点
进入出生点需要满足最低 PvP 等级要求。排名遵循三个平台通用的约定:等级 1–5(数字越小越好),加上 位置 — 0 表示高组,1 表示低组。因此 tier: 3, pos: 0 表示 HT3 或更好,允许 HT3 进入而阻挡 LT3。
门禁默认关闭,直到你启用它:
/tiers # 查看状态、提供商和受限出生点
/tiers on | off | toggle # 启用或禁用,设置持久化到 config.yml
/tiers reload # 重新读取 tiers 配置部分
/tiers cache clear # 清除所有缓存的等级
/tiers check <player> [provider]
配置
tiers:
enabled: false
provider: "mctiers" # mctiers | pvptiers | elitestorm | any
gamemode: "vanilla" # 或设置为 "best" 以使用玩家最强的游戏模式
tier: 3 # 1-5,数值越低限制越严格
pos: 0 # 0 = 高级, 1 = 初级
restricted-spawns:
tryhard: # 每个出生点均可覆盖 tier、pos、gamemode 和 provider
tier: 3
pos: 0
provider: "mctiers"
use-peak-when-retired: true # 对退役玩家按其巅峰等级进行判定
allow-on-error: true # 若 API 不可达:true 允许玩家进入,false 阻止进入
cache-minutes: 30 # 按 UUID 和 provider 缓存等级数据
prefetch-on-join: true # 这样在 /loadme 时检查无需发起请求
bypass-permission: "ffautils.tiers.bypass"
未列在 restricted-spawns 下的出生点永远不会受到限制。
提供商 (Providers)
每次查询都会针对每个 UUID 和每个提供商进行缓存,并在玩家加入时预取,且在重连期间保持有效,因此通常无需任何网络请求即可解决门控判断。
|
MCTiers |
PvPTiers |
EliteStorm |
| 端点 (Endpoint) |
mctiers.com/api/v2 |
pvptiers.com/api |
api.elitestorm.es/v2 |
| 查询依据 |
带连字符的 UUID with dashes |
不带连字符的 UUID without dashes |
昵称 (或无连字符的 UUID) |
| 游戏模式 |
vanilla sword axe pot nethop uhc smp mace |
sword axe pot neth_pot uhc smp mace crystal |
vanilla sword axe pot nethop uhc smp mace |
不同网站间的等效游戏模式标识符会自动转换,例如 nethop 对应 PvPTiers 的 neth_pot。仅存在于单一网站的游戏模式(MCTiers 和 EliteStorm 上的 vanilla,PvPTiers 上的 crystal)在其他站点不会返回排名,并且该提供商会拒绝此类玩家。
provider: any 会检查所有网站,如果 任意 一个网站允许则放行玩家——这很有用,因为各网站对同一玩家的评级可能确实存在分歧。实际有响应的网站优先级高于无法访问的网站,因此 allow-on-error 仅在没有任何提供商响应时才生效。
EliteStorm 与离线模式服务器。 EliteStorm 默认通过昵称查询,这使得门控能在离线模式服务器上正常工作:在这些服务器上,Bukkit 生成的 UUID 是本地生成的,永远与其他网站基于 Mojang UUID 进行的查询不匹配。设置 providers.elitestorm.lookup-by: uuid 可改用 UUID 进行查询。其游戏模式 ID 绑定于特定的 Discord 公会,如果你使用的是其他公会,请设置 providers.elitestorm.guild-id —— 插件会在启动时从 API 读取词汇表。
线程
每次查询都在专用的线程池上运行;HTTP 相关操作绝不涉及主线程,包括启动和重载阶段。如果一个网站缓慢或宕机,服务器仍可正常运转。
PlaceholderAPI
| 占位符 (Placeholder) |
值 (Value) |
%ffa_kills% |
玩家的击杀数 |
%ffa_deaths% |
玩家的死亡数 |
%ffa_kdr% |
击杀/死亡比 |
%ffa_kit_<name>_players% |
当前使用该套装的 FFA 玩家数量 |
构建
./gradlew shadowJar # 生成包含依赖的 JAR 文件至 build/libs/
./gradlew test # 运行测试套件
./gradlew runServer # 部署插件的 Paper 1.21.4 测试服务器
Gradle 已启用配置缓存。如果你修改了 build.gradle.kts,请添加 --no-configuration-cache 参数运行,或删除 .gradle/configuration-cache/ 目录。
有关项目布局、架构说明以及每个等级提供商依赖的细节,请参阅 AGENTS.md。
已知问题
- 默认
config.yml 中的 time-combat-log 未被任何逻辑读取。战斗日志持续时间来源于 combatlog.timeout-ticks 或 duration-combat-log —— 详见 Main config.yml keys。
FFAUtils: Paper FFA Plugin
FFAUtils is an open-source Minecraft PvP and free-for-all (FFA) plugin for Paper 1.21.4. It provides configurable kits, arenas and spawns, combat logging, player statistics, tier-gated PvP access, and first-to-ten (/fto10) duels for competitive Minecraft servers.
Features
- Kits — create, edit and delete kits from an in-game inventory editor. Kits are stored one JSON file each.
- Multiple spawns — name any location as a spawn, and optionally restrict which kits may be used there.
- Tier-gated spawns — require a minimum PvP tier (for example HT3 or better) to enter a spawn, resolved from MCTiers, PvPTiers or EliteStorm. See Tier-gated spawns.
- Combat log — players tagged in combat are killed on quit and cannot run configured commands while tagged.
- Fto10 duels — challenge another player to a first-to-ten series using the same kit and spawn, with round scores, external damage protection, and automatic forfeit wins.
- Lobby items — a configurable hotbar for players in the lobby, plus a respawn item for players who died with a kit loaded.
- Stats — kills, deaths and K/D stored in SQLite, exposed through PlaceholderAPI.
- Death messages — a configurable pool of broadcast messages, with killstreak announcements.
Requirements
Both optional dependencies are soft — the plugin loads fine without them, and simply skips registering placeholders when PlaceholderAPI is absent.
Installation
- Download
FFAUtils-<version>.jar from the releases.
- Drop it into
plugins/.
- Start the server once to generate the config files, then edit them and run
/ffautils reload.
Commands
Every permission defaults to operators.
Players
| Command |
Permission |
Description |
/loadme <kit> <spawn> |
none |
Load a kit and enter a spawn. This is where kit restrictions and the tier gate apply. |
/spawn |
ffautils.commands.spawn |
Teleport back to the lobby, healed and with lobby items restored. |
/dead |
none |
Kill yourself. |
/kit <name> |
ffautils.commands.kit |
Apply a kit. |
/kit list |
ffautils.commands.kit |
List available kits. |
/fto10 invite <player> |
none |
Invite a player to a first-to-ten duel using your current kit and spawn. |
/fto10 accept <player> |
none |
Accept a Fto10 invitation from a player. |
/fto10 deny <player> |
none |
Reject a Fto10 invitation. |
/fto10 leave <player> |
none |
Leave a duel and award the win to the other player. |
Administration
| Command |
Permission |
Description |
/kit create|edit|delete <name> |
ffautils.commands.kit |
Manage kits. create and edit open the inventory editor. |
/ffakiteditor |
ffautils.commands.ffakiteditor |
Open the kit editor menu. Player only. |
/setspawn create <name> |
ffautils.commands.setspawn |
Save your current location as a spawn. |
/setspawn delete <spawn> |
ffautils.commands.setspawn |
Delete a spawn. |
/setspawn allowkit <spawn> <kit> |
ffautils.commands.setspawn |
Restrict a spawn to a kit. A spawn with no allowed kits permits all of them. |
/setspawn removekit <spawn> <kit> |
ffautils.commands.setspawn |
Remove a kit from a spawn's allowed list. |
/ffautils reload |
ffautils.commands.ffautils |
Reload messages, kits, spawns and death messages. Player only. |
/tiers … |
ffautils.commands.tiers |
Manage the tier gate — see below. |
Other permissions
| Permission |
Effect |
ffautils.bypass-combat-block |
Run blocked commands while tagged in combat. |
ffautils.tiers.bypass |
Enter tier-restricted spawns regardless of rank. |
The spawn named lobby is special: it is where players are sent on join and by /spawn. If it does not exist, the first world's spawn point is used.
Configuration
| File |
Purpose |
config.yml |
Main settings, including the whole tier gate. |
messages.yml |
All player-facing strings, in MiniMessage format. |
death-messages.yml |
Pool of death broadcast messages. |
blocked-commands.yml |
Command labels players cannot run while in combat. |
spawn-lobby-items.yml |
Lobby hotbar items and the respawn item. |
spawns/<name>.json |
One file per spawn (location plus allowed kits). |
kits/<name>.json |
One file per kit. |
stats.db |
SQLite database of kills and deaths. |
messages.yml is never overwritten on update. Strings added by a newer version are seeded automatically, so the file stays valid across upgrades.
Main config.yml keys
disable-lobby-items: false # skip giving lobby items entirely
stats-database-name: stats.db # SQLite file inside the plugin folder
combatlog.timeout-ticks: 300 # how long a combat tag lasts, in ticks
Combat log duration may also be given in seconds as duration-combat-log, which is multiplied by 20. If neither key is present the default is 15 seconds.
Tier-gated spawns
Requires a minimum PvP tier to enter a spawn. Ranks follow the convention all three sites share: tier 1–5 where lower is better, plus a position — 0 for high, 1 for low. So tier: 3, pos: 0 means HT3 or better, which lets HT3 in and turns LT3 away.
The gate is off until you turn it on:
/tiers # state, providers and restricted spawns
/tiers on | off | toggle # enable or disable, persisted to config.yml
/tiers reload # re-read the tiers config section
/tiers cache clear # drop every cached tier
/tiers check <player> [provider]
Configuration
tiers:
enabled: false
provider: "mctiers" # mctiers | pvptiers | elitestorm | any
gamemode: "vanilla" # or "best" to use the player's strongest gamemode
tier: 3 # 1-5, lower is stricter
pos: 0 # 0 = high, 1 = low
restricted-spawns:
tryhard: # each spawn may override tier, pos, gamemode, provider
tier: 3
pos: 0
provider: "mctiers"
use-peak-when-retired: true # judge retired players on their peak tier
allow-on-error: true # unreachable API: true lets players in, false blocks
cache-minutes: 30 # tiers are cached per UUID, per provider
prefetch-on-join: true # so the check at /loadme costs no request
bypass-permission: "ffautils.tiers.bypass"
Spawns not listed under restricted-spawns are never gated.
Providers
Every lookup is cached per UUID per provider, prefetched when the player joins, and kept across reconnects, so the gate normally resolves without any request at all.
|
MCTiers |
PvPTiers |
EliteStorm |
| Endpoint |
mctiers.com/api/v2 |
pvptiers.com/api |
api.elitestorm.es/v2 |
| Looked up by |
UUID with dashes |
UUID without dashes |
nickname (or UUID without dashes) |
| Gamemodes |
vanilla sword axe pot nethop uhc smp mace |
sword axe pot neth_pot uhc smp mace crystal |
vanilla sword axe pot nethop uhc smp mace |
Equivalent gamemode slugs are translated automatically between sites, so nethop matches PvPTiers' neth_pot. A gamemode that only exists on one site (vanilla on MCTiers and EliteStorm, crystal on PvPTiers) simply yields no ranking elsewhere, and the player is turned away by that provider.
provider: any checks every site and lets the player in if any of them allows it — useful because the sites genuinely disagree about the same player. A site that actually answered always outranks one that could not be reached, so allow-on-error only applies when no provider answered at all.
EliteStorm and offline-mode servers. EliteStorm is looked up by nickname by default, which is what makes the gate work on offline-mode servers: there the UUID Bukkit hands out is generated locally and never matches the Mojang UUID the other sites are keyed by. Set providers.elitestorm.lookup-by: uuid to use the UUID instead. Its gamemode ids are scoped to a Discord guild, so set providers.elitestorm.guild-id if you use a different one — the plugin reads the vocabulary from the API at startup.
Threading
Every lookup runs on a dedicated thread pool; nothing HTTP-related touches the main thread, including startup and reload. If a site is slow or down, the server keeps ticking.
PlaceholderAPI
| Placeholder |
Value |
%ffa_kills% |
Player's kills |
%ffa_deaths% |
Player's deaths |
%ffa_kdr% |
Kill/death ratio |
%ffa_kit_<name>_players% |
Players currently in FFA using that kit |
Building
./gradlew shadowJar # fat JAR into build/libs/
./gradlew test # run the test suite
./gradlew runServer # Paper 1.21.4 test server with the plugin deployed
Gradle's configuration cache is enabled. If you change build.gradle.kts, run with --no-configuration-cache or clear .gradle/configuration-cache/.
See AGENTS.md for the project layout, architecture notes and the details each tier provider depends on.
Known issues
time-combat-log in the default config.yml is not read by anything. Combat log duration comes from combatlog.timeout-ticks or duration-combat-log — see Main config.yml keys.
评论 0
登录后参与评分
还没有评论,来抢沙发吧