⚔ 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

• New player grace period - automatically protects players the first time they join
• Server-wide grace period - disable PvP for all players with a live countdown timer
• Per-player grace - grant individual players an additional grace period at any time
• Mob protection - optionally prevent mobs from targeting or damaging grace players
• Action bar / BossBar timer - real-time countdown shown above the hotbar or at the top of the screen, with a smooth fade-out when done
• LuckPerms integration - automatically assigns and removes a configurable [GRACE] group with a coloured prefix while a player is protected
• Persistent grace periods - 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

# 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.

---