{"id":16329251,"url":"https://github.com/josantonius/minecraft-pvp","last_synced_at":"2025-10-18T07:44:52.101Z","repository":{"id":165747361,"uuid":"640096765","full_name":"josantonius/minecraft-pvp","owner":"josantonius","description":"Experience thrilling player-versus-player battles in Minecraft servers with this dynamic plugin","archived":false,"fork":false,"pushed_at":"2023-05-15T22:50:36.000Z","size":2268,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-17T10:13:16.243Z","etag":null,"topics":["minecraft","minecraft-plugin","minecraft-pvp","pvp"],"latest_commit_sha":null,"homepage":"https://josantonius.dev","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/josantonius.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["Josantonius"]}},"created_at":"2023-05-13T01:44:20.000Z","updated_at":"2023-05-15T22:46:52.000Z","dependencies_parsed_at":null,"dependency_job_id":"9e70666d-282a-444f-9e72-ee88887d034b","html_url":"https://github.com/josantonius/minecraft-pvp","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josantonius%2Fminecraft-pvp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josantonius%2Fminecraft-pvp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josantonius%2Fminecraft-pvp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josantonius%2Fminecraft-pvp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/josantonius","download_url":"https://codeload.github.com/josantonius/minecraft-pvp/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254304768,"owners_count":22048462,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["minecraft","minecraft-plugin","minecraft-pvp","pvp"],"created_at":"2024-10-10T23:14:55.721Z","updated_at":"2025-10-18T07:44:52.028Z","avatar_url":"https://github.com/josantonius.png","language":"Kotlin","funding_links":["https://github.com/sponsors/Josantonius"],"categories":[],"sub_categories":[],"readme":"# Minecraft PvP Plugin\n\n[![License](https://img.shields.io/github/license/josantonius/minecraft-pvp)](LICENSE)\n\nExperience thrilling player-versus-player battles in Minecraft servers with this dynamic plugin.\n\n## [Watch demo on YouTube](https://www.youtube.com/watch?v=6a3UklFQ0WY)\n\n## Requirements\n\n- Java 17 or higher.\n- Purpur server 1.19.3 or Bukkit/Spigot/Paper server compatible with the Purpur API version used.\n\n## Installation\n\n1. Download the JAR file: [pvp-1.0.0-purpur-1.19.3.jar](/build/libs/pvp-1.0.0-purpur-1.19.3.jar).\n\n1. Place the JAR file in the plugins folder of your Minecraft server.\n\n1. Restart the server to load the plugin.\n\n## Building\n\nTo build the plugin yourself, follow these steps:\n\n1. Make sure you have `Java 17` or higher and `Gradle` installed on your system.\n\n1. Clone the plugin repository on your local machine:\n\n    ```bash\n    git clone https://github.com/josantonius/minecraft-pvp.git\n    ```\n\n1. Navigate to the directory of the cloned repository:\n\n    ```bash\n    cd minecraft-pvp\n    ```\n\n1. Use Gradle to compile the plugin:\n\n    ```bash\n    gradle build\n    ```\n\n## How does it work?\n\n- Player A challenges player B to a PvP battle.\n  \n- Player A has 60 seconds to cancel the challenge while player B does not accept.\n\n  - If player A cancels the challenge:\n\n    - The cancellation of the challenge is announced.\n\n- Player B has 60 seconds to accept or reject the challenge:\n\n  - If player B accepts the challenge:\n\n    - Player B is teleported to player A's location:\n\n      - The beginning of the PvP battle is announced:\n\n        - When a player dies or disconnects:\n\n          - The winner is announced.\n\n          - The result is recorded.\n\n          - The PvP ends.\n\n    - [Both players are teleported to the PvP area and face towards the center:](#teleporting-players-to-specific-locations)\n\n      - [Players inside the PvP area are teleported to the spectator location.](#teleporting-spectators-to-specific-locations)\n\n      - [Doors of the PvP area are closed by placing blocks in them.](#blocking-doors)\n\n      - The beginning of the PvP battle is announced:\n\n        - When a player dies or disconnects:\n\n          - The winner is announced.\n\n          - The result is recorded.\n\n          - The doors of the area are opened by removing the blocks placed at the beginning.\n\n          - The PvP ends.\n\n  - If player B does not accept or reject the challenge within 60 seconds:\n\n    - The cancellation of the challenge is announced.\n\n- Operators can cancel the PvP challenge at any time.\n\n## Commands\n\n- `/pvp \u003cplayer\u003e` - Challenge another player to a PvP battle\n\n- `/pvpaccept` - Accept the PvP challenge\n\n- `/pvpdeny` - Reject the PvP challenge\n\n- `/pvpcancel` - Cancel the PvP challenge\n\n- `/pvphelp` - Display help for the PvP plugin commands\n\n- `/pvptop` - Display PvP win and loss statistics\n\n- `/pvpreload` - Reload the plugin\n\nAll commands excepts `/pvpreload` requires the `pvp.use` permission to be used.\n\nThe `/pvpreload` command requires the `pvp.admin` permission.\n\n## Configuration\n\nThe `plugins/PvP/config.yml` file contains specific plugin configurations.\n\n### Teleporting players to specific locations\n\nIf you want players to be teleported to specific locations, for example inside\na coliseum, and for both to face the same direction, you can configure both\nplayers' locations and the central point of the PvP zone as follows:\n\n```yaml\nworld: world\n\npvpZonePlayerOne:\n  x: 23.0\n  y: 63.0\n  z: -138.0\n\npvpZonePlayerTwo:\nx: 23.0\ny: 63.0\nz: -176.0\n\npvpZoneCenter:\n x: 23.0\n y: 62.0\n z: -157.0\n```\n\n### Teleporting spectators to specific locations\n\nIf you want players within a certain horizontal and vertical radius from the center of the PvP area\nto be teleported to a specific location, for example, a place where they can watch the fight, you\ncan configure the spectator location and the new vertical radius option as follows:\n\n```yaml\nworld: world\n\npvpZoneRadius: 60\n\npvpZoneVerticalRadius: 5\n\npvpZoneCenter:\n x: 23.0\n y: 62.0\n z: -157.0\n\npvpZoneSpectatorLocation:\n x: 23.0\n y: 72.0\n z: -157.0\n```\n\n### Blocking doors\n\nIf you want to block the doors of the PvP area, for example, to prevent players from escaping\nthe fight, you can configure the location of the blocks that will be placed in the doors to\nblock them as follows:\n\n```yaml\nworld: world\n\ndoorMaterial: \"RED_STAINED_GLASS\"\n\ndoorLocations:\n  door_1_1:     # Location of gate 1 where a pre-determined block will be placed\n    x: 46.0\n    y: 66.0\n    z: -158.0\n  door_1_2:     # Location of gate 1 where a pre-determined block will be placed\n    x: 46.0\n    y: 66.0\n    z: -157.0\n  door_2_1:    # Location of gate 2 where a pre-determined block will be placed\n    x: 46.0\n    y: 66.0\n    z: -156.0\n  door_2_2:    # Location of gate 2 where a pre-determined block will be placed\n    x: 46.0\n    y: 65.0\n    z: -158.0\n```\n\n**Keep in mind that the locations you set must be free (air blocks), as at the start of the fight,\nblocks of the specified type in `doorMaterial` will be placed at the indicated locations and at the\nend of the fight, they will be removed by replacing them again with air.**\n\n**The door area should be a protected area that players cannot break.\nThis plugin does not handle that.**\n\n### Change invite timeout for PvP challenge acceptance\n\nTo change the waiting time for accepting or rejecting the PvP challenge, you can configure the\ntime in seconds as follows:\n\n```yaml\ninviteTimeout: 60 \n```\n\n### Prevent players from using some commands during PvP\n\nYou can prevent players involved in a PvP battle from using certain commands during the battle,\nfor example, to prevent them from escaping the battle, by blocking them as follows:\n\n```yaml\nblockedCommands:\n  - \"/back\"\n  - \"/spawn\"\n  - \"/tp\"\n  - \"/home\"\n  - \"/ps\"\n```\n\n### Set health and saturation to maximum at the beginning of the PvP\n\nIf you want players to start the battle with maximum health and saturation, you can\nconfigure the plugin as follows:\n\n```yaml\nsetHealthAndSaturation: true\n```\n\n### Disable PvP commands in certain worlds\n\nIf you want players to be unable to execute the PvP plugin commands in certain worlds, you can\nconfigure the plugin as follows:\n\n```yaml\ndisabledWorlds:\n  - spawn\n  - world_nether\n```\n\n### Full configuration example\n\n```yaml\n# Name of the world where the PvP zone is located.\nworld: world\n\n# Names of the worlds where the use of PvP commands will be blocked.\ndisabledWorlds:\n  - spawn\n\n# Commands that players will not be allowed to use during a PvP.\nblockedCommands:\n  - \"/coliseo\"\n  - \"/back\"\n  - \"/spawn\"\n  - \"/tp\"\n  - \"/home\"\n  - \"/ps\"\n\n# Time in seconds that it will take for a challenge to be canceled if not accepted.\ninviteTimeout: 60 \n\n# If enabled, players will start PVP with the maximum level of hunger and health.\nsetHealthAndSaturation: true\n\n# The radius of the PvP zone.\npvpZoneRadius: 60\n\n# Vertical radius of the PvP zone for player height restrictions.\npvpZoneVerticalRadius: 5\n\n# The central point of the PvP zone.\npvpZoneCenter:\n x: 23.0\n y: 62.0\n z: -157.0\n\n# The location where the player who proposes the challenge will be teleported to start the PvP.\npvpZonePlayerOne:\n  x: 23.0\n  y: 63.0\n  z: -138.0\n\n# Location where the player who accepts the challenge will be teleported to start the PvP.\npvpZonePlayerTwo:\n  x: 23.0\n  y: 63.0\n  z: -176.0\n\n# Location where players not involved in the PvP will be teleported.\npvpZoneSpectatorLocation:\n  x: 23.0\n  y: 72.0\n  z: -157.0\n\n# Material that will be used to cover the doors of the PvP zone.\ndoorMaterial: \"RED_STAINED_GLASS\"\n\n# Locations of the blocks that will be blocked during the PvP.\ndoorLocations:\n  door_1_1:\n    x: 46.0\n    y: 66.0\n    z: -158.0\n  door_1_2:\n    x: 46.0\n    y: 66.0\n    z: -157.0\n  door_1_3:\n    x: 46.0\n    y: 66.0\n    z: -156.0\n  door_1_4:\n    x: 46.0\n    y: 65.0\n    z: -158.0\n  \n  door_2_1:\n    x: 24.0\n    y: 66.0\n    z: -134.0\n  door_2_2:\n    x: 23.0\n    y: 66.0\n    z: -134.0\n  door_2_3:\n    x: 22.0\n    y: 66.0\n    z: -134.0\n  door_2_4:\n    x: 24.0\n    y: 65.0\n    z: -134.0\n```\n\n## Messages\n\nThe `plugins/PvP/messages.yml` file contains all the messages that the plugin uses.\nYou can change the messages to your liking.\n\n## Stats\n\nThe `plugins/PvP/stats.yml` file stores the win and loss statistics of players\nin PvP battles.\n\n## TODO\n\n- [ ] Add new feature\n- [ ] Create tests\n- [ ] Improve documentation\n\n## Changelog\n\nDetailed changes for each release are documented in the\n[release notes](https://github.com/josantonius/minecraft-pvp/releases).\n\n## Contribution\n\nPlease make sure to read the [Contributing Guide](.github/CONTRIBUTING.md), before making a pull\nrequest, start a discussion or report a issue.\n\nThanks to all [contributors](https://github.com/josantonius/minecraft-pvp/graphs/contributors)! :heart:\n\n## Sponsor\n\nIf this project helps you to reduce your development time,\n[you can sponsor me](https://github.com/josantonius#sponsor) to support my open source work :blush:\n\n## License\n\nThis repository is licensed under the [MIT License](LICENSE).\n\nCopyright © 2023-present, [Josantonius](https://github.com/josantonius#contact)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjosantonius%2Fminecraft-pvp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjosantonius%2Fminecraft-pvp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjosantonius%2Fminecraft-pvp/lists"}