SyPVP v2.0
适用于 Minecraft 1.21.x Purpur / Paper / Spigot 的多功能 PVP 插件
作者:Shiyuan
环境:Java 21 + Spigot API(兼容 Paper / Purpur)
概述
SyPVP 提供四种核心 PVP 玩法模式:
| # |
功能 |
描述 |
| 1 |
个人 PVP 开关 |
玩家可随时开启/关闭自己的 PVP 状态;关闭时免疫其他玩家的伤害 |
| 2 |
排位赛季模式 |
通过 GUI 发起全服 PVP 邀请;结算时调整排名积分 |
| 3 |
娱乐 PVP 模式 |
流程与排位模式相同,但不计算积分——仅供娱乐 |
| 4 |
OP 活动模式 |
管理员使用木棍选择固定的对战区域;可配置是否计算排名积分 |
1. 个人 PVP 开关
- 命令:
/pvp 或 /sypvp toggle
- 当 PVP 禁用时,玩家免疫来自其他玩家的伤害
- 当一名 PVP 已启用 的玩家攻击一名 PVP 已禁用 的玩家时:
- 不会造成伤害
- 攻击者会收到一条包含可点击的 “邀请开启 PVP” 按钮的聊天消息
- 点击该按钮后,目标玩家会收到一条包含可点击的 “点击开启 PVP” 按钮的消息
- 目标玩家可以点击该按钮来开启自己的 PVP
PVP 状态会持久化保存到 pvp_states.yml,并在服务器重启后保留。
2. 排位赛季模式
流程
- 玩家运行
/sypvp ranked 打开 GUI 面板
- 选择参与者总数(2 ~ 8,上限可在配置中设置)
- 点击“开始邀请”按钮,向全服广播可点击的邀请链接
- 其他玩家在聊天中点击 “点击加入” 按钮以加入比赛
- 邀请有效期为 2 分钟(可配置);若超时未满员则取消
- 满员时:
- 所有参与者被传送至主世界的随机位置(环形分布,范围可配置)
- 双方均看到标题倒计时:
3 → 2 → 1 → Start!
- 倒计时期间自动启用 PVP;比赛正式开始
胜负判定
- 首先死亡的玩家失败
- 或 首先执行
/sypvp surrender 的玩家失败
- 击杀者(或比赛中另一方参与者)获胜
积分结算
| 结果 |
积分变化(默认) |
| 胜利 |
+25 分 |
| 失败 |
-15 分 |
积分会持久化保存到 ranking.yml,可通过 /sypvp top 查看。
3. 娱乐 PVP 模式
- 命令:
/sypvp fun
- 整个流程与排位赛季模式完全相同(GUI 发起、倒计时、随机传送、死亡/投降判定)
- 区别:结算时不调整排名积分——仅供娱乐
4. OP 活动模式(仅限管理员)
1. 获取选区木棍
/sypvp opactivity wand
获得一根名为 “SyPVP Region Selection Stick” 的木棍。
2. 选择对战区域
- 左击空气/方块:设置点 1
- 右击空气/方块:设置点 2
这两个点定义了一个长方体区域,作为本次活动的固定对战竞技场。
3. 启动活动
/sypvp opactivity start <ranked:true|false> [maxPlayers]
ranked:是否计算排名积分(true / false)
maxPlayers:最大参与者数量(默认 2,受配置限制)
启动后,参与者会被传送到选定区域内的随机位置进行 PVP。流程与排位模式相同。
命令参考
| 命令 |
权限 |
描述 |
/pvp |
sypvp.use |
切换自己的 PVP 状态 |
/sypvp toggle |
sypvp.use |
同 /pvp |
/sypvp ranked |
sypvp.use |
打开排位模式 GUI |
/sypvp fun |
sypvp.use |
打开娱乐模式 GUI |
/sypvp surrender |
sypvp.use |
投降当前比赛 |
/sypvp top [n] |
sypvp.use |
查看前 n 名排名排行榜(默认 10) |
/sypvp join <id> |
sypvp.use |
加入指定 ID 的比赛(通常由按钮点击触发) |
/sypvp invite <player> |
sypvp.use |
邀请某玩家开启 PVP |
/sypvp accept |
sypvp.use |
接受邀请并开启自己的 PVP |
/sypvp opactivity wand |
sypvp.admin |
获取选区木棍 |
/sypvp opactivity start <ranked> [max] |
sypvp.admin |
在选定区域启动活动 |
/sypvp reload |
sypvp.admin |
重载配置文件 |
sypvp.admin 权限默认由 OP 拥有。
权限节点
| 权限 |
默认分配 |
描述 |
sypvp.use |
所有玩家 |
基本 PVP 功能使用 |
sypvp.admin |
OP |
OP 活动模式和重载权限 |
安装
- 确保服务器为 Minecraft 1.21.x,核心为 Purpur / Paper / Spigot
- 确保服务器运行在 Java 21 上
- 将
target/SyPVP-2.0.jar(或发布页面上的 jar 文件)放入服务器的 plugins/ 目录
- 重启服务器
- 首次启动时会生成默认的
plugins/SyPVP/config.yml;按需修改后运行 /sypvp reload
构建说明
要求
构建命令
mvn clean package
构建产物位于 target/SyPVP-2.0.jar。
配置
config.yml
settings:
ranking:
win-points: 25 # 每次胜利获得的积分
loss-points: 15 # 每次失败损失的积分
starting-points: 1000 # 初始排名积分
random-teleport:
min-range: 1000 # 最小随机传送半径(方块)
max-range: 5000 # 最大随机传送半径(方块)
invitation-duration: 120 # 邀请有效期(秒)
countdown-duration: 3 # 倒计时秒数
max-participants: 16 # 最大参与者数量
invite-cooldown: 5000 # 邀请按钮冷却时间(毫秒)
messages:
prefix: "&8[&cSyPVP&8]&r "
... 其他消息文本可自定义,支持 & 颜色代码和 {占位符}
所有消息均支持 `&` 颜色代码和占位符替换(例如 `{player}`、`{count}`)。
### 持久化数据文件
| 文件 | 用途 |
|------|---------|
| `plugins/SyPVP/pvp_states.yml` | 玩家的个人 PVP 开关状态 |
| `plugins/SyPVP/ranking.yml` | 全服排名积分数据 |
---
## 项目结构
SyPVP 2/
├── pom.xml
├── README.md
└── src/main/
├── java/com/shiyuan/sypvp/
│ ├── SyPVP.java # 主类
│ ├── commands/
│ │ ├── PVPCommand.java # /pvp 命令
│ │ └── SyPVPCommand.java # /sypvp 主命令
│ ├── gui/
│ │ ├── MatchGUI.java # 比赛选择面板
│ │ └── MatchSetupHolder.java # GUI 状态持有者
│ ├── listeners/
│ │ ├── EntityDamageListener.java # 伤害 / PVP 开关逻辑
│ │ ├── InventoryClickListener.java # GUI 点击处理
│ │ ├── OPSelectionListener.java # 权杖选择监听器
│ │ └── PlayerDeathListener.java # 死亡 / 退出处理
│ ├── managers/
│ │ ├── MatchManager.java # 比赛生命周期管理
│ │ ├── OPSelectionManager.java # OP 区域选择管理
│ │ ├── PVPManager.java # 个人 PVP 状态管理
│ │ └── RankingManager.java # 排名积分管理
│ ├── models/
│ │ ├── Match.java # 比赛 POJO
│ │ └── MatchType.java # 比赛类型枚举
│ └── utils/
│ ├── LocationUtils.java # 位置工具
│ └── MessageUtils.java # 消息工具
└── resources/
├── plugin.yml
└── config.yml
---
## 工作流图
### 排位 / 娱乐模式
玩家 A 运行 /sypvp ranked
│
▼
打开 GUI 以选择参与者数量 (2~8)
│
▼
点击“开始邀请” → 全服广播可点击的邀请链接
│
▼
其他玩家点击“点击加入”进入比赛
│
▼
人数满员后 → 传送所有参与者 + 强制开启 PVP
│
▼
标题倒计时 3-2-1-Start
│
▼
比赛中(死亡或 /sypvp 投降决定败者)
│
▼
结算(排位模式 +/- 积分,娱乐模式无积分变化)
### OP 活动模式
管理员运行 /sypvp opactivity wand → 获得选择权杖
│
▼
左键设置点 1 / 右键设置点 2 → 定义区域
│
▼
/sypvp opactivity start ranked:true|false [maxPlayers]
│
▼
广播邀请 → 玩家加入 → 人数满员后,传送到区域内随机位置
│
▼
倒计时 → 比赛 → 结算(积分根据 ranked 参数确定)
---
## 注意事项
1. **自动开启 PVP**:比赛期间,所有参与者的 PVP 将被强制开启,以确保伤害正常生效
2. **比赛隔离**:同一进行中比赛内的两名玩家之间的伤害不受 PVP 开关限制;与其他玩家的伤害仍受 PVP 开关约束
3. **断线处理**:比赛中断线视为投降;邀请阶段断线会将该玩家从参与者列表中移除,若发起者断线则取消比赛
4. **随机传送**:在世界出生点周围的环形区域内随机选择位置,并自动放置于最高地表方块上方
5. **本地化**:所有提示文本集中位于 `config.yml` 的 `messages` 部分,支持 `&` 颜色代码
---
## 兼容性
- ✅ Purpur 1.21.x
- ✅ Paper 1.21.x
- ✅ Spigot 1.21.x
- ✅ Java 21
---
## 版本历史
- **v2.0**:重构发布,实现了四大核心功能(个人开关、排位、娱乐、OP 活动)
SyPVP v2.0
A multi-functional PVP plugin for Minecraft 1.21.x Purpur / Paper / Spigot
Author: Shiyuan
Environment: Java 21 + Spigot API (compatible with Paper / Purpur)
Overview
SyPVP provides four core PVP gameplay modes:
| # |
Feature |
Description |
| 1 |
Personal PVP Toggle |
Players can enable/disable their own PVP state at any time; immune to other players' damage when disabled |
| 2 |
Ranked Season Mode |
Initiate server-wide PVP invitations via GUI; ranking points are adjusted on settlement |
| 3 |
Entertainment PVP Mode |
Same flow as ranked mode, but no points are calculated — purely for fun |
| 4 |
OP Activity Mode |
Admins use a stick to select a fixed match region; configurable whether ranking points are counted |
1. Personal PVP Toggle
- Command:
/pvp or /sypvp toggle
- When PVP is disabled, the player is immune to damage from other players
- When a player with PVP enabled attacks a player with PVP disabled:
- No damage is dealt
- The attacker receives a chat message containing a clickable "Invite to enable PVP" button
- Clicking the button sends the target a message with a clickable "Click to enable PVP" button
- The target can click the button to enable their own PVP
PVP state is persisted to pvp_states.yml and survives server restarts.
2. Ranked Season Mode
Flow
- Player runs
/sypvp ranked to open the GUI panel
- Select the total number of participants (2 ~ 8, configurable upper bound in config)
- Click the "Start Invitation" button to broadcast a clickable invitation to the whole server
- Other players click the "Click to Join" button in chat to join the match
- Invitation is valid for 2 minutes (configurable); cancelled if not full when expired
- When full:
- All participants are teleported to random locations in the main world (ring distribution, range configurable)
- Both sides see a Title countdown:
3 → 2 → 1 → Start!
- PVP is auto-enabled during countdown; the match officially begins
Win/Lose Determination
- The first player to die loses
- Or the first player to run
/sypvp surrender loses
- The killer (or the other participant in the match) wins
Point Settlement
| Result |
Points Change (default) |
| Win |
+25 points |
| Lose |
-15 points |
Points are persisted to ranking.yml and viewable via /sypvp top.
3. Entertainment PVP Mode
- Command:
/sypvp fun
- The entire flow is identical to the ranked season mode (GUI initiation, countdown, random teleport, death/surrender determination)
- Difference: No ranking points are adjusted on settlement — entertainment only
4. OP Activity Mode (Admin Only)
1. Obtain the Selection Stick
/sypvp opactivity wand
Receive a stick named "SyPVP Region Selection Stick".
2. Select the Match Region
- Left-click air/block: set point 1
- Right-click air/block: set point 2
The two points define a cuboid region used as the fixed match arena for this activity.
3. Start the Activity
/sypvp opactivity start <ranked:true|false> [maxPlayers]
ranked: whether to count ranking points (true / false)
maxPlayers: max participants (default 2, bounded by config)
After starting, participants are teleported to random locations within the selected region for PVP. The flow is the same as ranked mode.
Command Reference
| Command |
Permission |
Description |
/pvp |
sypvp.use |
Toggle own PVP state |
/sypvp toggle |
sypvp.use |
Same as /pvp |
/sypvp ranked |
sypvp.use |
Open the ranked mode GUI |
/sypvp fun |
sypvp.use |
Open the entertainment mode GUI |
/sypvp surrender |
sypvp.use |
Surrender the current match |
/sypvp top [n] |
sypvp.use |
View the top n ranking leaderboard (default 10) |
/sypvp join <id> |
sypvp.use |
Join the match with the given ID (usually triggered via button click) |
/sypvp invite <player> |
sypvp.use |
Invite a player to enable PVP |
/sypvp accept |
sypvp.use |
Accept an invitation and enable own PVP |
/sypvp opactivity wand |
sypvp.admin |
Obtain the region selection stick |
/sypvp opactivity start <ranked> [max] |
sypvp.admin |
Start an activity in the selected region |
/sypvp reload |
sypvp.admin |
Reload the configuration file |
sypvp.admin permission is owned by OPs by default.
Permission Nodes
| Permission |
Default |
Description |
sypvp.use |
All players |
Basic PVP feature usage |
sypvp.admin |
OP |
OP activity mode and reload permission |
Installation
- Ensure the server is Minecraft 1.21.x with Purpur / Paper / Spigot core
- Ensure the server runs on Java 21
- Place
target/SyPVP-2.0.jar (or the jar from the release page) into the server's plugins/ directory
- Restart the server
- The default
plugins/SyPVP/config.yml is generated on first launch; modify as needed and run /sypvp reload
Build Instructions
Requirements
Build Command
mvn clean package
The build artifact is located at target/SyPVP-2.0.jar.
Configuration
config.yml
settings:
ranking:
win-points: 25 # Points gained per win
loss-points: 15 # Points lost per loss
starting-points: 1000 # Initial ranking points
random-teleport:
min-range: 1000 # Minimum random teleport radius (blocks)
max-range: 5000 # Maximum random teleport radius (blocks)
invitation-duration: 120 # Invitation validity (seconds)
countdown-duration: 3 # Countdown seconds
max-participants: 16 # Maximum participants
invite-cooldown: 5000 # Invite button cooldown (milliseconds)
messages:
prefix: "&8[&cSyPVP&8]&r "
# ... other message texts are customizable, supporting & color codes and {placeholders}
All messages support & color codes and placeholder replacement (e.g. {player}, {count}).
Persisted Data Files
| File |
Purpose |
plugins/SyPVP/pvp_states.yml |
Players' personal PVP toggle states |
plugins/SyPVP/ranking.yml |
Server-wide ranking point data |
Project Structure
SyPVP 2/
├── pom.xml
├── README.md
└── src/main/
├── java/com/shiyuan/sypvp/
│ ├── SyPVP.java # Main class
│ ├── commands/
│ │ ├── PVPCommand.java # /pvp command
│ │ └── SyPVPCommand.java # /sypvp main command
│ ├── gui/
│ │ ├── MatchGUI.java # Match selection panel
│ │ └── MatchSetupHolder.java # GUI state holder
│ ├── listeners/
│ │ ├── EntityDamageListener.java # Damage / PVP toggle logic
│ │ ├── InventoryClickListener.java # GUI click handling
│ │ ├── OPSelectionListener.java # Stick selection listener
│ │ └── PlayerDeathListener.java # Death / quit handling
│ ├── managers/
│ │ ├── MatchManager.java # Match lifecycle management
│ │ ├── OPSelectionManager.java # OP region selection management
│ │ ├── PVPManager.java # Personal PVP state management
│ │ └── RankingManager.java # Ranking points management
│ ├── models/
│ │ ├── Match.java # Match POJO
│ │ └── MatchType.java # Match type enum
│ └── utils/
│ ├── LocationUtils.java # Location utilities
│ └── MessageUtils.java # Message utilities
└── resources/
├── plugin.yml
└── config.yml
Workflow Diagrams
Ranked / Entertainment Mode
Player A runs /sypvp ranked
│
▼
Open GUI to select participant count (2~8)
│
▼
Click "Start Invitation" → broadcast clickable invitation server-wide
│
▼
Other players click "Click to Join" to enter the match
│
▼
When full → teleport all participants + force-enable PVP
│
▼
Title countdown 3-2-1-Start
│
▼
Match in progress (death or /sypvp surrender determines the loser)
│
▼
Settlement (ranked mode +/- points, entertainment mode no point change)
OP Activity Mode
Admin runs /sypvp opactivity wand → receive the selection stick
│
▼
Left-click to set point 1 / right-click to set point 2 → define region
│
▼
/sypvp opactivity start <ranked:true|false> [maxPlayers]
│
▼
Broadcast invitation → players join → when full, teleport to random spots within the region
│
▼
Countdown → match → settlement (points based on the ranked parameter)
Notes
- Auto-enable PVP: All participants' PVP is force-enabled during a match to ensure damage works correctly
- Match Isolation: Damage between two players in the same in-progress match is not restricted by the PVP toggle; damage to/from other players is still subject to the PVP toggle
- Disconnect Handling: Disconnecting during a match counts as surrender; disconnecting during the invitation phase removes the player from the participant list, and if the initiator disconnects, the match is cancelled
- Random Teleport: Randomly selects locations in a ring around the world spawn point, automatically placed above the highest surface block
- Localization: All prompt texts are centralized in the
messages section of config.yml, supporting & color codes
Compatibility
- ✅ Purpur 1.21.x
- ✅ Paper 1.21.x
- ✅ Spigot 1.21.x
- ✅ Java 21
Version History
- v2.0: Refactored release implementing the four core features (personal toggle, ranked, entertainment, OP activity)
评论 0
登录后参与评分
还没有评论,来抢沙发吧