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

1. Player runs /sypvp ranked to open the GUI panel
2. Select the total number of participants (2 ~ 8, configurable upper bound in config)
3. Click the "Start Invitation" button to broadcast a clickable invitation to the whole server
4. Other players click the "Click to Join" button in chat to join the match
5. Invitation is valid for 2 minutes (configurable); cancelled if not full when expired
6. 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

1. Ensure the server is Minecraft 1.21.x with Purpur / Paper / Spigot core
2. Ensure the server runs on Java 21
3. Place target/SyPVP-2.0.jar (or the jar from the release page) into the server's plugins/ directory
4. Restart the server
5. The default plugins/SyPVP/config.yml is generated on first launch; modify as needed and run /sypvp reload

---

Build Instructions

Requirements

• JDK 21
• Maven 3.6+

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

1. Auto-enable PVP: All participants' PVP is force-enabled during a match to ensure damage works correctly
2. 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
3. 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
4. Random Teleport: Randomly selects locations in a ring around the world spawn point, automatically placed above the highest surface block
5. 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)