GracePeriod+

⚔ GracePeriod+

GracePeriod+ is a PaperMC plugin that protects new and specific players from PvP (and optionally mobs) for a configurable amount of time — perfect for survival, SMP, and competitive servers.

---

Features

- Live config reload - automatically protects players the first time they join - Live config reload - disable PvP for all players with a live countdown timer - Live config reload - grant individual players an additional grace period at any time - Live config reload - optionally prevent mobs from targeting or damaging grace players - Live config reload - real-time countdown shown above the hotbar or at the top of the screen, with a smooth fade-out when done - Live config reload - automatically assigns and removes a configurable `[GRACE]` group with a coloured prefix while a player is protected - Live config reload - grace timers survive server restarts and player disconnects - Live config reload - change settings without restarting the server

---

Special Mention

- Plugin idea from the owner of Purgatory SMP! - Check it out at the Discord

---

Requirements

| Dependency | Type | |---|---| | PaperMC 1.21.1+ | Required | | LuckPerms | Required |

---

Installation

1. Drop `GracePeriodPlus-1.0.0.jar` into your `plugins/` folder 2. Make sure LuckPerms is installed 3. Start the server - the plugin will generate a `config.yml` and create the `grace` LuckPerms group automatically

---

Commands

All commands require the `graceplugin.admin` permission (default: OP).

| Command | Description | |---|---| | `/grace specific <player> <time>` | Give a specific player a personal grace period | | `/grace period <time>` | Start a server-wide grace period (disables PvP for everyone) | | `/grace end` | End the active server-wide grace period early | | `/grace end <player>` | End a specific player's personal grace period early | | `/grace status [player]` | Check the grace status of yourself or another player | | `/grace reload` | Reload the config.yml without restarting |

Time Format

| Input | Meaning | |---|---| | `30s` | 30 seconds | | `5m` | 5 minutes | | `2h` | 2 hours | | `3d` | 3 days (max: 999d) | | `120` | 120 seconds (plain number = seconds) |

---

Permissions

| Permission | Description | Default | |---|---|---| | `graceplugin.admin` | Access to all `/grace` commands | OP | | `graceplugin.bypass` | Can attack grace-protected players freely | false |

---

Configuration

```yaml

How long (in seconds) a brand-new player is protected after their first join.

Set to 0 to disable.

new-player-grace-duration: 300

protection:

Prevent players from attacking grace-protected players (and vice versa)

block-player-damage: true

Prevent mobs from targeting or damaging grace-protected players

block-mob-damage: false

luckperms:

Name of the LuckPerms group assigned during grace (created automatically)

group-name: "GRACE"

Colour of the group prefix — MiniMessage format

Options: <green>, <red>, <gold>, <aqua>, <yellow>, <blue>, <white>, etc.

group-prefix-color: "<green>"

messages: grace-start: "<green><bold>✦ Grace Period</bold></green> <gray>You are protected from PvP for <yellow>{time}</yellow>.</gray>" grace-end: "<red><bold>✦ Grace Period Over</bold></red> <gray>You are no longer protected from PvP.</gray>" cannot-attack: "<red>You cannot attack players during your grace period!</red>" cannot-be-attacked: "<red><yellow>{player}</yellow> is currently in a grace period and cannot be attacked!</red>" specific-success: "<green>Grace period of <yellow>{time}</yellow> applied to <aqua>{player}</aqua>.</green>" period-start-broadcast: "<gold><bold>⚔ Server Grace Period</bold></gold> <gray>PvP disabled for <yellow>{time}</yellow>. Enjoy the peace!</gray>" period-end-broadcast: "<red><bold>⚔ Server Grace Period Over</bold></red> <gray>PvP has been re-enabled. Good luck!</gray>" reload-success: "<green>GracePeriod+ config reloaded successfully.</green>" no-permission: "<red>You don't have permission to use this command.</red>" usage: "<red>Usage: /grace <specific|period|reload></red>"

timer:

How to display the countdown — "actionbar" (above hotbar) or "bossbar" (top of screen)

display-type: "actionbar" actionbar-format: "<gold><bold>⚔ Grace Period:</bold></gold> <yellow>{time}</yellow>" bossbar-title: "<gold>⚔ Grace Period: <yellow>{time}</yellow>" bossbar-color: "YELLOW" # WHITE, YELLOW, GREEN, BLUE, RED, PURPLE, PINK bossbar-style: "SOLID" # SOLID, SEGMENTED_6, SEGMENTED_10, SEGMENTED_12, SEGMENTED_20

How long the timer takes to fade out when the grace period ends (in ticks, 20 = 1 second)

fade-out-ticks: 40 ```

---

LuckPerms Group

On first startup, GracePeriod+ automatically creates a LuckPerms group named `grace` (configurable) with a coloured prefix. Players are added to this group when their grace period starts and removed when it ends - even if they go offline mid-grace.

The prefix colour is configurable via MiniMessage tags in `config.yml`.

---

How It Works

New player grace: When a player joins for the first time, they are automatically placed in a personal grace period for the configured duration. During this time only that specific player is protected — other players are unaffected.

Personal grace (`/grace specific`): Grants an individual player a grace period at any time. Useful for welcoming returning players or staff discretion.

Server grace (`/grace period`): Disables PvP for the entire server for the specified duration. A live countdown is shown to all players via action bar or BossBar. PvP is automatically restored when the timer ends.

Mob protection: When `block-mob-damage: true`, mobs will completely ignore grace-protected players - they won't target, pathfind toward, or deal damage to them. Works for all mob types including projectiles.

---

<div align="center">

License

© 2025 JustBuddy. All Rights Reserved.

The compiled JAR is free to download and use on your server. The source code is available via my Patreon.

Purchasing grants you a personal, non-transferable license to view and modify the source code for private use only. This license is granted to the purchasing account only and may not be transferred to another person.

You may NOT redistribute or publish the source code, resell or relicense it, or share your copy with others. Violation of any of these terms immediately terminates your license and you must delete all copies of the source code.

</div>