SyPVP

Minecraft 版本： 1.21 1.21.1 1.21.2 1.21.3 1.21.4 1.21.5 1.21.6 1.21.7 1.21.8 1.21.9 1.21.10 1.21.11 26.1 26.1.1 26.1.2 26.2

平台： bukkit paper purpur spigot

标签： game-mechanics management social

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:

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

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

sypvp.admin permission is owned by OPs by default.

Permission Nodes

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

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)