Перейти к содержимому
Mineforgian

Event-PVP-Plugin

A comprehensive Minecraft plugin combining custom event management and PvP wager system with a modern web interface. Build engaging player experiences with customizable events, arenas, equipment sets, and betting mechanics.

Загрузки
219
Подписчики
2
Обновлён
11 июня 2026 г.
Лицензия
MIT

Опубликован 7 декабря 2025 г.

Исходный код

Event-PVP-Plugin - Description

A comprehensive Minecraft plugin that combines custom event management and PvP wager system into one unified solution.

Upgrading from 1.0.7 to 1.0.8

You do not need to replace your entire config.yml! The plugin will automatically add missing settings with default values. Here's the step-by-step guide:

Important Notes

  • Config Files: No manual config editing required! New options are automatically added to your existing config files with default values.
  • Web Interface: After upgrading, all new features (including optional integrations) will appear in the web interface where you can easily enable/disable them.
  • Language Files: These are NOT automatically overwritten! To get the new GUI localization keys, you need to update your language files.

Step-by-Step Upgrade

  1. Back up your existing files (config.yml, worlds.yml, equipment.yml, messages_*.yml)
  2. Stop your server
  3. Replace the plugin JAR file with version 1.0.8
  4. Update Language Files (IMPORTANT!):
    • Option 1: Delete your old messages_*.yml files and restart the server to regenerate them with all new keys. Then manually reapply any customizations.
    • Option 2: Manually merge the new messages.gui.* keys from the updated language files into your existing customized files.
  5. Start your server - the plugin will handle the rest!
  6. Enable New Features (optional):
    • Open the web interface
    • Navigate to the integrations section
    • Enable/disable the new features (PvPManager, AJLeaderboards, DecentHolograms) as desired
    • Save your changes

🌍 Multilingual Support: Available in 8 Languages (English, German, French, Spanish, Russian, Polish, Japanese, Chinese)

What Does This Plugin Do?

Event System

Host custom server events with:

  • Multiple event types (PvP Arena, Capture the Flag, Free-for-All, etc.)
  • Automated event scheduling
  • Configurable spawn systems (single point, random, team-based)
  • Custom rewards for winners and participants
  • Statistics tracking and leaderboards

PvP Wager System

Let players bet on PvP matches:

  • Challenge other players with item or money wagers
  • Multiple arena configurations
  • Pre-configured equipment sets
  • Spectator mode for watching matches
  • Match management (draw votes, surrender, timeouts)

Web Interface

Configure everything through a modern browser interface:

  • Edit all YAML configurations visually
  • Create events and equipment sets with live preview
  • Token-based secure access
  • Multi-language support: 8 languages (EN, DE, FR, ES, RU, PL, JA, ZH)

Important Dependencies

⚠️ Multiverse-Core (REQUIRED)

This plugin fundamentally requires Multiverse-Core for proper operation:

  • World Loading: Loads event/arena worlds when matches start
  • World Cloning: Creates temporary world copies from templates
  • World Regeneration: Resets worlds after events/matches
  • World Unloading: Unloads worlds to save server resources

Without Multiverse-Core, the plugin will have limited functionality and may not work correctly.

⚠️ Multiverse-Inventories (STRONGLY RECOMMENDED)

Multiverse-Inventories is essential for proper inventory restoration. Here's why:

The Problem:

  • When players join an event or PvP match, they are teleported to a different world
  • Their inventory is cleared and replaced with event/match equipment
  • When returning to the main world, they need their original inventory back

The Solution: Multiverse-Inventories handles this automatically:

  • Separate Inventories: Each world group (main, event, pvp) has its own inventory
  • Automatic Switching: When players change worlds, their inventory is automatically restored
  • No Data Loss: Player inventories are preserved by Multiverse-Inventories

Without Multiverse-Inventories:

  • The plugin has a fallback inventory backup system, but it's still experimental and buggy
  • Players may lose items or experience inventory issues
  • Inventory restoration is not guaranteed to work correctly

Recommended Setup:

Step 1: Install Plugins

  1. Install Multiverse-Core
  2. Install Multiverse-Inventories

Step 2: Configure World Groups (Command Line)

You can use the guided command /mvinv group or direct commands to set up your groups.

Option A: Guided Setup

  1. Run /mvinv group
  2. Select "create"
  3. Name your group (e.g., "event")
  4. Add your event world names (e.g., "event_world", "pvp_arena")
  5. Type "@" to continue
  6. Select shares (type "all" to share everything within the group)
  7. Type "@" to finish

Option B: Direct Commands For advanced users, you can use direct commands:

  • Create group: /mvinv create-group default,world,world_nether,world_the_end all
  • Add worlds to group: /mvinv add-worlds event,event_world
  • Add more shares: /mvinv add-share event all

Recommended World Groups:

  • default group: Main/survival worlds (e.g., world, world_nether, world_the_end)
  • event group: Event worlds (e.g., your event world names)
  • pvp group: PvP arena worlds (e.g., your arena world names)

Step 3: Verify Setup

Run /mvinv list to see your groups and /mvinv info <groupname> to confirm worlds are assigned correctly.

Wildcard Support (Optional): If you use dynamic world names (e.g., event worlds that are cloned/regenerated), you can use wildcards:

  • Example: event_* matches any world starting with "event_"
  • Example: r=arena_[0-9]+ (regex) matches numbered arena worlds

Other Dependencies

  • Vault (Required): For economy integration (money wagers)

Optional Integrations

The plugin optionally supports several external plugins to enhance functionality. None of these are required — the plugin works fully without them.

Leaderboards & Holograms

Supports AJLeaderboards, DecentHolograms, and PlaceholderAPI for displaying event and PvP statistics.

Enable via web interface (or manually in config.yml):

settings:
  integrations:
    ajleaderboards:
      enabled: true
    decentholograms:
      enabled: true

PlaceholderAPI placeholders (use these in AJLeaderboards boards or DecentHologram lines):

Placeholder Stat
%eventpvp_event_wins% Event wins
%eventpvp_event_participations% Event participations
%eventpvp_pvp_wins% PvP wager wins
%eventpvp_pvp_losses% PvP wager losses
%eventpvp_pvp_draws% PvP wager draws

All placeholders return plain numbers (e.g. 15, 0) for compatibility with AJLeaderboards. Requires PlaceholderAPI to be installed on the server.

PvPManager (Combat Tagging)

Supports PvPManager to automatically remove combat tags when players leave an event or match, preventing false combat logging penalties.

Enable via web interface (or manually in config.yml):

settings:
  integrations:
    pvpmanager:
      enabled: true

Requires PvPManager to be installed on the server. On plugin startup, you'll see a message confirming integration is active. Without PvPManager or with this setting disabled, the plugin falls back to a no-op implementation (no errors).

Essential Commands

For Players

Events:

/event <name> join          - Join an event
/event <name> leave         - Leave an event
/event list                 - Show available events
/eventstats me              - View your event statistics

PvP Wagers:

/pvpask <player>                                      - Challenge a player (GUI)
/pvpa <player> <wager> <amount> <arena> <equipment>  - Challenge with full setup
/pvpaccept [player]                                   - Accept a challenge
/pvpdeny [player]                                     - Deny a challenge
/surrender                                            - Surrender current match
/draw                                                 - Vote for a draw
/pvp spectate <player>                                - Spectate a match
/pvpstats me                                          - View your PvP statistics

Examples:

/pvpa Steve DIAMOND_SWORD 1 PvPArena diamond_pvp    - Challenge Steve with item wager
/pvpa Alex MONEY 100 desert standard                - Challenge Alex with $100 wager
/pvpa Mike SKIP 0 forest pvp_starter                - Challenge Mike without wager

For Admins

/eventpvp reload            - Reload all configurations
/eventpvp webtoken          - Generate web interface access token
/event <name> start         - Start an event
/event <name> stop          - Stop an event
/event <name> forcestart    - Force start without minimum players
/pvpadmin reload            - Reload PvP configuration
/pvpadmin stopall           - Stop all active matches
/inventoryrestore <player> <ID>  - Restore player inventory (fallback)

Quick Start

  1. Install Dependencies:

    • Vault
    • Multiverse-Core
    • Multiverse-Inventories

  2. Configure World Groups (in Multiverse-Inventories): Use /mvinv group for guided setup, or direct commands:

    /mvinv create-group default,world,world_nether,world_the_end all
/mvinv create-group event,<your_event_world> all
/mvinv create-group pvp,<your_pvp_arena_world> all

  3. Verify World Groups:

    /mvinv list
/mvinv info event

  4. Configure the Plugin:

    • Edit config.yml, worlds.yml, equipment.yml
    • Or use the web interface: /eventpvp webtoken
    • Enable optional integrations via web interface (AJLeaderboards, DecentHolograms, PvPManager)

  5. Reload and Test:

    /eventpvp reload
/event pvparena start

Server Requirements

  • Platform: Paper/Spigot 1.19+
  • RAM: 4GB+ recommended (depending on world size)
  • Multiverse-Core: Latest version
  • Multiverse-Inventories: Latest version (strongly recommended)
  • Vault: Latest version

Need Help?

  • Check the full README.md for detailed documentation
  • Review configuration examples in CONFIG_EXAMPLES.md
  • Test spawn configurations using SpawnExamples.md

Remember: Multiverse-Core and Multiverse-Inventories are not just optional - they are essential for this plugin to work properly!

Ченджлог

1.0.8Релиз26.1, 26.1.1, 26.1.2 · 11 июня 2026 г.

Changelog for 1.0.8

Summary

Version 1.0.8 focuses on four areas: full localization of the PvP wager GUI flow, optional leaderboard/hologram integrations (AJLeaderboards, DecentHolograms), PlaceholderAPI support so external plugins can read numeric player statistics, and optional PvPManager integration to prevent false combat logging penalties.

Upgrading from 1.0.7

You do not need to replace your entire config.yml! The plugin will automatically add missing settings with default values.

Important Notes

  • Config Files: No manual config editing required! New options are automatically added to your existing config files with default values.
  • Web Interface: After upgrading, all new features (including optional integrations) will appear in the web interface where you can easily enable/disable them.
  • Language Files: These are NOT automatically overwritten! To get the new GUI localization keys, you need to update your language files.

Step-by-Step Upgrade:

  1. Back up your existing files (config.yml, worlds.yml, equipment.yml, messages_*.yml)
  2. Stop your server
  3. Replace the plugin JAR file with version 1.0.8
  4. Update Language Files (IMPORTANT!):
    • Option 1: Delete your old messages_*.yml files and restart the server to regenerate them with all new keys. Then manually reapply any customizations.
    • Option 2: Manually merge the new messages.gui.* keys from the updated language files into your existing customized files.
  5. Start your server - the plugin will handle the rest!
  6. Enable New Features (optional):
    • Open the web interface
    • Navigate to the integrations section
    • Enable/disable the new features (PvPManager, AJLeaderboards, DecentHolograms) as desired
    • Save your changes

Added

PvPManager Integration (Combat Tagging)

  • Added optional PvPManager support via a bridge interface
  • Registered automatically on startup when PvPManager is installed and enabled in config
  • Automatically removes combat tags when players:
    • Leave an event (voluntarily or eliminated)
    • Finish a PvP wager match (win/lose/draw)
    • Server shuts down during an active match
  • Fallback to no-op implementation if PvPManager isn't installed or integration is disabled
  • Enable in config.yml:
    settings:
  integrations:
    pvpmanager:
      enabled: true

PlaceholderAPI Integration

  • Added optional PlaceholderAPI support via the EventPvpExpansion class
  • Registered automatically on startup when PlaceholderAPI is installed
  • All placeholders return plain numeric strings (e.g., "15", "0") — no color codes or formatting — so AJLeaderboards can parse them correctly
  • Available placeholders:
Placeholder Description
%eventpvp_event_wins% Total event wins for the player
%eventpvp_event_participations% Total event participations for the player
%eventpvp_pvp_wins% Total PvP wager wins
%eventpvp_pvp_losses% Total PvP wager losses
%eventpvp_pvp_draws% Total PvP wager draws

Note: Kills and deaths are not tracked by this plugin. Event stats only include wins and participations; PvP stats only include wins, losses, and draws.

Optional AJLeaderboards & DecentHolograms Support

  • Added optional integration bridges for AJLeaderboards and DecentHolograms
  • Both integrations are fully optional — the plugin works without them
  • Enable in config.yml under settings.integrations:
    settings:
  integrations:
    ajleaderboards:
      enabled: true
    decentholograms:
      enabled: true
    refresh-interval-ticks: 20

Extended GUI Localization (Wager System)

  • Previously hardcoded GUI text in the PvP wager flow has been moved to language files under messages.gui.*
  • This affects all wager-related screens:
    • Wager Main GUI (challenge setup, overview, arena/equipment selection)
    • Item Selection GUI (add/remove wager items, slot labels, error messages)
    • Money Selection GUI (amount picker, balance display, adjust buttons)
    • Confirmation GUI (final review before sending a challenge)
    • Response GUI (accept/decline incoming challenges, counter-wager setup)
    • Response Item/Money Selection GUIs (opponent-side wager editing)
    • Negotiation GUI (final offer review, counter-offer, accept/decline)
  • Updated language files: messages.yml (default), messages_en.yml, messages_de.yml, messages_es.yml, messages_fr.yml, messages_pl.yml, messages_ru.yml, messages_ja.yml

Improved Multiverse-Inventories Documentation

  • Added detailed setup guide for Multiverse-Inventories world groups
  • Included both guided command (/mvinv group) and direct command options
  • Added wildcard/regex support tips for dynamic world names

Changed

  • Wager GUI classes (AbstractWagerGui and subclasses) now resolve all visible text through messages.gui.* keys instead of hardcoded strings
  • External display refresh is scheduled automatically when AJLeaderboards and/or DecentHolograms integrations are enabled
  • plugin.yml now includes PvPManager in softdepend
  • pom.xml now includes PvPManager dependency (scope: provided) via CodeMC repository

Goals

  • Eliminate hardcoded GUI text so the entire wager UI respects the configured server language
  • Provide consistent, translatable labels, lore text, error messages, and button titles across all wager dialogs
  • Allow server owners to display event and PvP statistics on leaderboards and holograms without custom code
  • Prevent false combat logging penalties by integrating with PvPManager
  • Provide clear, step-by-step Multiverse-Inventories setup instructions

How to Verify Changes In-Game

Language Changes

  1. Prepare language files: Language files in the plugin data folder are not automatically overwritten on update. To get the new messages.gui.* keys, either delete old language files (after backing up) or manually merge the new sections.
  2. Switch language in config.yml (or via web interface) and run /eventpvp reload
  3. Test all GUI screens using two test accounts (Player A challenges Player B)

Integration Checks

  • PlaceholderAPI: Run /papi list and verify eventpvp expansion is present, test with /papi parse me %eventpvp_pvp_wins%
  • PvPManager: Check server logs for integration activation message, test by getting in combat during an event/match then leaving/finishing
  • AJLeaderboards/DecentHolograms: Enable the integrations via web interface, then create a board/hologram using the placeholders and verify stats update

Upgrade Notes

  • Language files: Not auto-replaced on update. Delete or manually merge messages_*.yml in the plugin data folder to receive new GUI keys
  • PlaceholderAPI: Install PlaceholderAPI on the server; the expansion registers automatically
  • AJLeaderboards / DecentHolograms: Install the plugins, enable in config.yml, and use the %eventpvp_*% placeholders in board/hologram lines
  • PvPManager: Install PvPManager, enable integration in config.yml — no extra setup needed
1.0.7Релиз26.1, 26.1.1, 26.1.2 · 24 мая 2026 г.

Changelog

[1.0.7] - 2026-05-24

Changed

  • Code Refactoring: Removed the wrapper class de.zfzfg.pvpwager.utils.MultiverseHelper.java
  • The Multiverse functionality now uses the central de.zfzfg.core.world.MultiverseHelper class directly
  • This change simplifies the codebase by removing an unnecessary abstraction layer

Added

  • Version Check Command: Added /epvp version and /eventpvp version commands
    • Requires eventpvp.admin permission (same as reload/debug)
    • Displays current plugin version
    • Triggers update check and shows update status
    • Shows download link if update is available
    • Added to help menu and tab completion
  • Command Cooldown System: Integrated CommandCooldownManager into the main plugin
    • Applied to /pvp challenge command with 3-second default cooldown
    • Includes memory leak prevention with automatic player cleanup on quit
    • Customizable cooldown messages via message provider
  • Web Server Rate Limiting: Added rate limiting to the embedded HTTP server
    • Prevents API abuse with per-IP rate counters (100 requests per window)
    • Note: Rate limit counters are not automatically cleared - may require future cleanup mechanism
    • Improves security and stability of the web interface
  • Text Utility Performance: Added color caching to TextUtil
    • Caches colored text to improve performance
    • Reduces redundant color code processing
    • Note: Cache has no size limit - may require monitoring for memory usage with many unique messages
  • Improved Task Management: Enhanced countdown task handling in MatchManager
    • Changed from single task to task list for better management
    • Allows multiple concurrent countdown operations
  • Memory Management: Added player cleanup method to prevent memory leaks
    • CommandCooldownManager.removePlayer() called on player quit
    • Ensures proper cleanup of player-specific data
  • Update Reminder System: Added automatic update checking via Modrinth API
    • Checks for newer plugin versions on server startup with configurable delay
    • Notifies admins with eventpvp.admin.updatenotify permission on join
    • Console logging when updates are available
    • Caching mechanism to prevent repeated API calls
    • Configurable via settings.update-check in config.yml
    • Supports all languages: German, English, Spanish, French, Japanese, Polish, Russian
    • Includes proper User-Agent header for Modrinth API compliance
    • SemVer-based version comparison
    • Uses Modrinth project ID pqJQdZ6R

Fixed

  • Missing Help Message Keys: Fixed YAML key collision causing help messages to be missing
    • Root cause: Multiple duplicate help: sections in YAML files caused key collision (YAML only keeps last instance)
    • Renamed sections to event-help:, pvp-help:, and command-help: in all language files
    • Updated EventCommand.java to use event-help. prefix for all help message lookups
    • Fixed /event help command showing raw message keys instead of actual text
    • Applied to all languages: German, English, Spanish, French, Japanese, Polish, and Russian
  • Incorrect Command Documentation: Updated PvP help to show correct command syntax
    • Changed /pvp <spieler> to /pvpask <spieler> in all language files
    • Updated help.challenge entries to reference the correct command with Wager-GUI hint
    • Applied to all languages with appropriate translations
  • Win/Loss Screen Placeholders: Fixed YAML key collision causing win/loss messages to show as placeholders
    • Root cause: Multiple duplicate match: sections in YAML files caused key collision
    • Renamed sections to match-display:, match-system:, and match-manager: in all language files
    • Updated MatchManager.java getMsg() method to route keys to correct YAML section based on key name
    • Fixed you-won-header, you-won, you-lost-header, and you-lost keys not being found
    • Applied to all language files
  • Draw Vote Expiration Bug: Fixed "expired" message showing after draw is accepted
    • Added match.isDrawVoteActive() check in DrawSubCommand.java timeout task
    • Prevents showing expired message when draw vote has already been accepted and deactivated
    • Resolves race condition where timeout task fires after draw acceptance
  • Update Checker Version Parsing: Fixed version comparison failing with non-numeric suffixes
    • Updated UpdateChecker.java to extract numeric part before parsing (e.g., "1.0.6-Multilingual" -> "1.0.6")
    • Prevents NumberFormatException when comparing versions with suffixes like "-Multilingual"
  • Error Handling Improvements: Added logging to all previously empty catch blocks
    • MatchManager: Added warning logs for task cancellation failures, snapshot save errors, and statistics recording failures
    • EventSession: Added warning logs for task cleanup failures, inventory snapshot errors, and health/food level setting errors
    • EquipmentManager: Added warning logs for allowed worlds parsing errors
    • PvpStatsStorage: Added warning logs for UUID parsing errors
    • SpawnManager: Added warning logs for teleport fallback failures
    • RequestManager & CommandRequestManager: Added warning logs for task cancellation errors
    • InventorySnapshotStorage: Added comment for regex error handling (expected fallback behavior)
  • Enum Switch Completeness: Added missing COMMAND case to spawn type switch in EventSession
    • Resolves compiler warning about unhandled enum constant
    • Delegates to executeSpawnCommand() method for command-based spawning
  • Material Caching: Added material name cache to EquipmentManager
    • Caches Material.valueOf() lookups to avoid repeated parsing
    • Cache is cleared on equipment reload to ensure consistency
  • Enchantment Caching: Added enchantment cache to EquipmentManager
    • Caches Registry.ENCHANTMENT.get() lookups for enchantment names
    • Cache is cleared on equipment reload to ensure consistency
  • HashMap Cloning Reduction: Replaced defensive copies with unmodifiable views
    • MatchManager.getMatches() now returns Collections.unmodifiableMap()
    • StatsManager.toMap() now returns Collections.unmodifiableMap()
    • Reduces memory allocation for admin/debug commands

Deprecated

  • PvPAcceptCommand: Marked as deprecated
    • Users should use /pvp accept instead
    • Old command kept for backward compatibility

Technical Details

  • The old wrapper class at src/main/java/de/zfzfg/pvpwager/utils/MultiverseHelper.java has been removed
  • Code that previously used the wrapper now imports and uses de.zfzfg.core.world.MultiverseHelper directly
  • This refactoring improves code maintainability and reduces complexity
  • Various code cleanups and optimizations across multiple files
  • Improved command registration with helper method in EventPlugin

Compatibility

  • No breaking changes for end users
  • All existing functionality remains intact
  • Plugin configuration and commands work exactly as before
  • Deprecated commands continue to function but users should migrate to new syntax

Upgrade Notes

  • Language Files: Language files are NOT automatically replaced when updating the plugin. If you have customized language files (messages_*.yml), you need to delete them from the plugin data folder and restart the server to let the plugin regenerate them with the new update notification messages, then manually reapply your customizations.

[1.0.6-Multilingual] - Previous Version

  • Multilingual support for German, English, Spanish, French, Japanese, Polish, and Russian
  • Event and PvP wager system integration
  • Web interface for configuration
  • Multiverse-Core integration for world management

Комментарии

Загружаем…