GracePlugin

Feature Systems

• Independent per-world grace timers, each with its own boss bar.
• Optional automatic startup grace.
• Optional per-player grace timers.
• Optional join-based personal grace start.
• Personal grace management commands to grant, check, and reset player timers.
• Region claiming and region-specific protection rules.
• Global protection rules.
• World-specific default rule values.
• Rule priority: a region rule overrides its world's rule, which overrides the global rule.
• Boss bar countdown during active grace, with customizable color and style per world.
• Optional action bar countdown showing each player's remaining personal grace time.
• Warning broadcast system at configurable time checkpoints.
• Configurable sounds for start, end, warnings, and blocked actions.
• Optional extra-life system with configurable lives per player, optional daily reset, and per-permission amounts.
• Optional hunger freeze during grace (eating still restores hunger).
• Deathban system with a master switch, per-world settings, delay, duration, reason, spectator transition, and optional IP ban. The deathban applies when a player dies while protected by an active grace.
• Start/end automation: console commands and broadcasts on grace start or end, plus scheduled start/stop times of day.
• Region management panel for viewing, editing, teleporting to, and deleting regions.
• Particle outlines for region selections and claimed regions.
• Protection bypass permission exempting players from all restrictions.
• Dedicated runtime storage so grace state, personal grace, and extra lives survive reloads and restarts.
• Placeholder support for scoreboards, chat formats, and HUD plugins.
• Admin GUI panels for fast timer, flag, and region management.

Commands

• /grace help
  Show the help menu.

• /grace start [world] [seconds]
  Start grace. Without a world, starts all grace-enabled worlds. With a custom duration, that duration is used for the started timer only and never changes the configured defaults.

• /grace stop [world]
  End grace immediately. Without a world, stops all active worlds.

• /grace pause [world]
  Pause the active grace timer. Without a world, pauses all active worlds.

• /grace resume [world]
  Resume a paused grace timer. Without a world, resumes all active worlds that are paused.

• /grace extend <seconds> [world]
  Add time to active grace. Without a world, extends all active worlds. Works correctly while paused.

• /grace reduce <seconds> [world]
  Remove time from active grace. If the remaining time drops to zero or below, grace ends.

• /grace status
  Show grace status, remaining time per world, and current global rule values.

• /grace reload
  Reload plugin settings, messages, and region data. Runtime state is never lost.

• /grace tools
  Get the region selection tools: a wooden pickaxe for corner 1 and a wooden shovel for corner 2. Right-click a block with each tool to set its corner, then use /grace claim.

• /grace gui
  Open the admin control panel.

• /grace regions
  Open the region management panel. Left-click a region to edit its flags, right-click to teleport to it, shift-click to delete it.

• /grace claim <name>
  Create a region from the two selected corners. Names may only contain letters, numbers, dashes, and underscores. All rules start enabled; use /grace setflag or the region panel to change them.

• /grace delete <name>
  Delete a region.

• /grace list
  List all regions.

• /grace info <name>
  Show region details and rule values.

• /grace setflag <region> <flag> <true/false>
  Set a region rule value.

• /grace flag <flag> <true/false>
  Set a global rule value.

• /grace grant <player> [seconds]
  Grant (or refresh) personal grace to a player. Without seconds, the personal grace duration from the config is used.

• /grace check <player>
  Show a player's personal grace status and remaining time.

• /grace reset <player>
  Clear a player's personal grace data so their grace can start again.

• /grace visualize <region>
  Toggle the particle outline for a claimed region.

• /grace <region> <flag> <true/false>
  Legacy shorthand for setting region rule values. Only works when the first argument matches an existing region.

Permissions

• grace.start
  Start grace.

• grace.stop
  Stop grace.

• grace.pause
  Pause grace.

• grace.resume
  Resume grace.

• grace.extend
  Extend grace.

• grace.reduce
  Reduce grace.

• grace.status
  View grace status.

• grace.reload
  Reload settings.

• grace.tools
  Receive region tools.

• grace.gui
  Open admin GUI panels.

• grace.regions
  Open the region management panel.

• grace.claim
  Create regions.

• grace.delete
  Delete regions.

• grace.list
  List regions.

• grace.info
  View region details.

• grace.flags
  Edit region rule values.

• grace.globalflag
  Edit global rule values.

• grace.grant
  Grant personal grace to players.

• grace.check
  Check a player's personal grace.

• grace.reset
  Reset a player's personal grace.

• grace.visualize
  Toggle region outlines.

• grace.bypass
  Exempts the player from all protection restrictions (damage, block rules, item rules, commands, and flight rules).

• grace.deathban.ignore
  Bypass deathban when the ignore-permission option is enabled.

• grace.extralives.<n>
  Grants <n> extra lives during grace (2 through 10). The highest matching permission wins; otherwise the extra-lives config value is used.

Rules and Flags

All rules use:

• true = allowed
• false = blocked

Rules are permanent protection rules — they apply at all times, not only during grace. When a player acts, the plugin checks the region they are in first, then the world defaults, then the global value.

Available flags:

• allow-pvp — Controls PvP between players.
• allow-block-breaking — Controls breaking blocks.
• allow-block-placing — Controls placing blocks.
• allow-mob-damage — Controls damaging mobs.
• allow-mob-spawning — Controls mob spawning.
• allow-player-damage — Controls players taking damage.
• allow-commands — Controls command usage.
• allow-flight — Controls flight ability.
• allow-item-drop — Controls dropping items.
• allow-item-pickup — Controls picking up items.

Configuration Guide

Runtime state (active grace timers, personal grace, extra lives) is stored in a separate data.yml file in the plugin folder and is managed automatically. Settings live in config.yml.

Core Timing

• grace-duration-seconds
  Default grace length in seconds for manual starts. Changing this affects future /grace start commands that have no world duration and no custom duration. A custom duration on a start never overwrites this value.

• auto-start-duration-seconds
  Fallback duration used for auto-start and scheduled starts when a world duration is not set.

• auto-start
  If enabled, grace starts automatically at server startup in all grace-enabled worlds. Set to true to enable, false to disable.

Personal Grace

• per-player-grace-enabled
  Enables individual grace timers per player. While enabled, players are protected by their own personal grace instead of world timers. A player's personal grace starts on their first join and ends after the personal duration; once it ends it is not granted again unless an admin grants or resets it.

• per-player-grace-duration
  Length of personal grace in seconds. Also used as the default for /grace grant.

• grace-starts-from-join
  Starts personal grace when a player first joins the server. Works with or without per-player grace enabled.

Protection Toggles

• no-damage-everything
  Blocks all damage to players during grace, overriding rules. Set to true to enable.

• extra-life-enabled
  Gives players extra lives during grace — each time they die while protected with a life remaining, one life is used and they respawn with their items instead of being deathbanned. Set to true to enable.

• extra-lives
  Number of extra lives each player gets. 0 disables the safety net entirely.

• extra-lives-daily-reset
  If enabled, extra lives are restored to the full amount once per day.

• no-hunger-loss
  Prevents hunger from decreasing during grace. Eating still restores hunger. Set to true to enable.

• action-bar-countdown
  If enabled, players with active personal grace see their remaining time in the action bar.

Boss Bar Settings

• bossbar.color
  Color of the per-world boss bars (PINK, BLUE, RED, GREEN, YELLOW, PURPLE, WHITE).

• bossbar.style
  Style of the per-world boss bars (SOLID, SEGMENTED_6, SEGMENTED_10, SEGMENTED_12, SEGMENTED_20).

• worlds.<world>.bossbar-color / worlds.<world>.bossbar-style
  Optional per-world overrides for the boss bar color and style.

Sound Settings

• sounds.grace-start
  Sound played to players in the world when grace starts.

• sounds.grace-end
  Sound played to players in the world when grace ends.

• sounds.warning
  Sound played when a warning broadcast fires.

• sounds.action-blocked
  Sound played when a player's action is blocked.

• sounds.volume
  Volume of all plugin sounds (0.0 to 1.0).

• sounds.pitch
  Pitch of all plugin sounds.

Warning Intervals

• warning-intervals
  Map of seconds-to-end and message text. When the remaining time crosses one of these values, the message is broadcast to the world's players. Use %time% in messages for formatted remaining time.

Global Defaults

• default-flags.*
  Server-wide default values for all flags. Used for the global rules and as the fallback for worlds without their own value.

Blocked Commands

• blocked-commands
  List of commands blocked when allow-commands is false. Each entry is a command name without the slash. Only the listed commands are blocked; all other commands still work.

World Settings

• worlds.<world>.grace-enabled
  Enables grace handling for that world. Only worlds with this set to true are protected during an active grace and are included in automatic starts.

• worlds.<world>.duration
  Per-world grace duration used by start logic when no custom duration is provided. A value of 0 falls back to the default duration.

• worlds.<world>.flags.*
  Per-world default flag values, used when no region rule applies.

• worlds.<world>.bossbar-color / worlds.<world>.bossbar-style
  Optional per-world boss bar appearance overrides.

• worlds.<world>.deathban.*
  Optional per-world deathban overrides (see Deathban Settings below).

Deathban Settings

The deathban applies when a player dies during an active grace they are protected by. Every value below can be overridden per world under worlds.<world>.deathban.

• deathban.enabled
  Master switch for the entire deathban system. Set to false to disable all deathbans.

• deathban.banreason
  The reason shown when a player is banned and kicked.

• deathban.ban-delay
  Seconds after death before the ban is applied.

• deathban.spectator-after-death
  If enabled, the player watches as a spectator for a few seconds before being kicked. If disabled, they are kicked immediately.

• deathban.ban-time
  Length of the ban in seconds. A value of 0 makes the ban permanent. Applies to name and IP bans alike.

• deathban.ban-ip
  If enabled, the player's IP address is banned as well, with the same expiry.

• deathban.ignore-permission
  If enabled, players with the bypass permission are not banned.

Automation

• automation.on-start-commands
  Console commands run when a grace period starts in any world. Use %world% for the world name.

• automation.on-end-commands
  Console commands run when a grace period ends in any world.

• automation.on-start-broadcast / automation.on-end-broadcast
  Messages broadcast to the whole server when grace starts or ends in any world. Use %world% for the world name. Leave empty to broadcast nothing.

• automation.schedule.enabled
  If enabled, grace is started and stopped automatically at the configured times each day.

• automation.schedule.start-time / automation.schedule.end-time
  Times of day (server local time, HH:mm format) at which grace starts and stops in all grace-enabled worlds.

Region Visualization

• region-visualization.enabled
  Master switch for particle outlines. Set to false to disable.

• region-visualization.particle
  The particle used for outlines (e.g. FLAME).

• region-visualization.show-selection
  If enabled, an outline is shown around your two selected corners.

Message Settings

All messages support & color codes. Every event and blocked action has a configurable message under messages.*. Placeholders like %time%, %player%, %region%, %world%, %flag%, %value%, %lives%, %reason%, and %location% are available where relevant. The main ones:

• messages.grace-started — Broadcast in the world when grace starts.
• messages.grace-end-title / messages.grace-end-subtitle / messages.grace-end-message — Title, subtitle, and message when grace ends naturally.
• messages.grace-stopped-title / messages.grace-stopped-subtitle / messages.grace-stopped — Shown when grace is stopped.
• messages.pvp-disabled / messages.pvp-disabled-grace — Shown when PvP is blocked by rules or by grace.
• messages.block-break-disabled, messages.block-place-disabled, messages.mob-damage-disabled, messages.item-drop-disabled, messages.item-pickup-disabled, messages.command-blocked — Shown when an action is blocked.
• messages.personal-grace-start, messages.personal-grace-end, messages.personal-grace-end-title, messages.personal-grace-end-subtitle, messages.personal-grace-actionbar — Personal grace messages.
• messages.grace-paused-broadcast, messages.grace-resumed-broadcast, messages.grace-extended-broadcast, messages.grace-reduced-broadcast — Timer control broadcasts.
• messages.deathban-broadcast — Broadcast when a player is deathbanned.
• messages.extra-life-used, messages.extra-life-used-broadcast, messages.extra-life-lives-left — Extra life messages.
• messages.region-* — All region creation, deletion, selection, and visualization messages.
• messages.no-permission, messages.config-reloaded, messages.unknown-command — General messages.

Placeholder Support

Requires the PlaceholderAPI plugin. All placeholders use the grace identifier.

• %grace_active%
  Whether any world grace is active.

• %grace_paused%
  Whether any grace is paused.

• %grace_remaining%
  Remaining grace time in seconds (the longest active world).

• %grace_remaining_formatted%
  Remaining grace time, formatted (e.g. "5 minute(s) and 30 second(s)").

• %grace_remaining_short%
  Remaining grace time in short format (e.g. "05:30").

• %grace_player_active%
  Whether the player is currently protected by grace.

• %grace_player_remaining%
  Player's remaining personal grace time in seconds.

• %grace_player_remaining_formatted%
  Player's remaining personal grace time, formatted.

• %grace_player_remaining_short%
  Player's remaining personal grace time in short format.

• %grace_region%
  Name of the region the player is currently in, or none.

• %grace_world_grace_enabled%
  Whether grace is enabled in the player's world.

• %grace_flag_<flagname>%
  Current value of a global flag (e.g. %grace_flag_allow-pvp%). Unknown flags return nothing.