LimitedGrace

A lightweight and configurable death protection plugin for Paper servers.

LimitedGrace gives players a limited number of protected deaths during which they keep their inventory and experience.

It is designed for survival servers that want to make early-game accidents less punishing without permanently removing the consequences of death.

New in v1.4.0: LimitedGrace now detects the keepInventory game rule in the player's world. By default, deaths do not consume LimitedGrace protection charges when the game rule already preserves the player's inventory. This behavior can be changed in config.yml.

✨ Features

• Limited death protection
  Players keep their inventory and experience while protection is active.

• Two protection layers
  Combines automatically calculated newbie protection with administrator-granted extra protection.

• keepInventory-aware charge handling
  Avoids consuming LimitedGrace charges when the world's keepInventory game rule already preserves the player's inventory. Server administrators can configure this behavior.

• Personal protection control
  Players can enable or disable their own protection using /lg switch.

• Global protection control
  Administrators can enable or disable death protection server-wide.

• Extra protection management
  Extra charges can be added or set without modifying the player's actual death count.

• Unlimited protection permission
  Selected players can receive death protection without consuming charges.

• Low-charge warnings
  Players can be notified when their remaining protection reaches configured thresholds.

• Customizable messages
  Commands, warnings, and administrative messages can be changed in config.yml.

• Persistent player data
  Death counts, extra charges, and personal protection states are stored with the player. No database is required.

• Asynchronous update checking
  LimitedGrace can check GitHub Releases for new versions without blocking the server thread. It only displays a console notification and never downloads updates automatically.

• No required dependencies
  Install the plugin and start the server—no additional plugins or databases are required.

---

🚀 Installation

1. Download the latest LimitedGrace .jar.
2. Stop your server.
3. Place the file in the server's plugins directory.
4. Start the server.
5. Edit plugins/LimitedGrace/config.yml if needed.
6. Run /lg reload after changing the configuration.

LimitedGrace will generate its configuration automatically on the first startup.

---

🛡️ How It Works

Each player can receive protection from two sources:

Newbie Protection

Newbie protection is calculated from the configured protection limit and the player's death count.

With the default configuration, the first 10 deaths are protected.

Extra Protection

Extra protection charges are granted by administrators. They are used after the player's newbie protection has been exhausted.

A player's total remaining protection is calculated as:

Remaining protection = Newbie protection + Extra protection

When death protection is applied:

• Inventory items are kept.
• Experience and levels are kept.
• One applicable protection charge is consumed.
• A warning may be displayed when the remaining charge count reaches a configured threshold.

Protection is not applied when:

• Global death protection is disabled.
• The player has disabled their personal protection.
• The player has no remaining protection charges.

Players with limitedgrace.unlimited receive protection without consuming newbie or extra protection charges.

Players with limitedgrace.unlimited are still subject to the global and personal protection switches. If either switch is disabled, death protection will not be applied.

keepInventory Behavior

LimitedGrace checks the keepInventory game rule in the world where the player dies.

keepinventory-consumes-charge: false

• false (default) — LimitedGrace does not consume a protection charge when keepInventory is enabled. Inventory and experience retention are handled by the game rule.
• true — LimitedGrace processes the death normally, and an applicable protection charge is consumed even when keepInventory is enabled.

Because keepInventory is configured per world, different worlds can use different game-rule states while sharing the same LimitedGrace setting.

---

💻 Commands

The main command is /limitedgrace. All commands can also use the shorter /lg alias.

Arguments enclosed in < > are required. Arguments enclosed in [ ] are optional.

Command	Description	Permission	Default
/limitedgrace help	Show the command help	None	Everyone
/limitedgrace get	View your remaining protection charges	limitedgrace.get	Everyone
/limitedgrace get <player>	View another player's protection charges	limitedgrace.get.it	OP
/limitedgrace getDeaths	View your current death count	limitedgrace.get	Everyone
/limitedgrace getDeaths <player>	View another player's death count	limitedgrace.get.it	OP
/limitedgrace add <count>	Add extra protection charges to yourself	limitedgrace.add	OP
/limitedgrace add <player> <count>	Add extra protection charges to another player	limitedgrace.add	OP
/limitedgrace switch	Toggle your own death protection	limitedgrace.switch	Everyone
/limitedgrace switch <player>	Toggle another player's death protection	limitedgrace.switch.it	OP
/limitedgrace switchAll	Toggle death protection globally	limitedgrace.switch.all	OP
/limitedgrace set <player> <count>	Set a player's extra protection charges	limitedgrace.set	OP
/limitedgrace setDeath <player> <count>	Set a player's actual death count	limitedgrace.setdeath	OP
/limitedgrace reload	Reload the plugin configuration	limitedgrace.reload	OP

Commands targeting another player currently require that player to be online.

---

🔑 Permissions

Permission	Description	Default
limitedgrace.admin	LimitedGrace administrator permission	OP
limitedgrace.unlimited	Prevents charges from being consumed when death protection is used	False
limitedgrace.reload	Allows the configuration to be reloaded	OP
limitedgrace.set	Allows extra protection charges to be set	OP
limitedgrace.setdeath	Allows actual death counts to be set	OP
limitedgrace.get	Allows players to view their own protection information	Everyone
limitedgrace.get.it	Allows another player's protection information to be viewed	OP
limitedgrace.add	Allows extra protection charges to be added	OP
limitedgrace.switch	Allows players to toggle their own death protection	Everyone
limitedgrace.switch.it	Allows another player's protection state to be toggled	OP
limitedgrace.switch.all	Allows death protection to be enabled or disabled globally	OP

limitedgrace.unlimited defaults to false. Server operators do not receive it automatically. Grant it explicitly with a permissions plugin such as LuckPerms.

Example:

/lp user <player> permission set limitedgrace.unlimited true

---

⚙️ Configuration

The configuration is located at:

plugins/LimitedGrace/config.yml

Main Settings

Setting	Description	Default
enabled	Global death protection state	true
update-check.enabled	Check GitHub Releases when the plugin starts	true
keepinventory-consumes-charge	Consume a protection charge when keepInventory is enabled	false
death-protections-number	Number of newbie protection charges	10
default-added-protections-number	Default extra charges assigned to players	0
protect-warn	Remaining charge counts that trigger a warning	3, 1

Messages support Minecraft legacy color codes using §.

Depending on the message, dynamic values use {0}, {1}, %s, or %d. Keep the placeholder type used by the default message when customizing it.

Configuration Example

# Global death protection state.
# Use `/lg switchAll` to toggle it.
enabled: true

# Check GitHub Releases for a newer plugin version on startup.
update-check:
  enabled: true

# Whether deaths with the `keepInventory` game rule enabled consume a protection charge.
keepinventory-consumes-charge: false

# Number of protection charges.
death-protections-number: 10
default-added-protections-number: 0

# Remaining protection counts at which the player will receive a warning.
protect-warn:
  - 3
  - 1

# Messages support Minecraft color codes using `§`.
# Dynamic values use placeholders such as {0}, {1}, %s, and %d.
help-message:
  - "§6§lLimitedGrace Help"
  - "§e/lg help                         §7- Show plugin help"
  - "§e/lg switch [player]              §7- Toggle protection for yourself or another player"
  - "§e/lg switchAll                    §7- Toggle protection globally"
  - "§e/lg get [player]                 §7- View remaining protection charges"
  - "§e/lg getDeaths [player]           §7- View the death count"
  - "§e/lg set [player] <count>         §7- Set extra protection charges"
  - "§e/lg setDeath [player] <count>    §7- Set the death count"
  - "§e/lg add [player] <count>         §7- Add extra protection charges"
  - "§e/lg reload                       §7- Reload the plugin configuration"

protect-message: "§aPlayer §f{0} §ahas §e{1} §adeath protection charge(s)§f.\n§aThis includes §e{2} §anewbie protection charge(s) §fand §e{3} §aextra protection charge(s)§f."

protect-warn-message: "§aYou have only §e{0} §adeath protection charge(s) remaining§f.\n§aNewbie protection remaining: §e{1}§f; §aextra protection remaining: §e{2}§f."

death-message: "§aPlayer §f{0} §ahas died §e{1} §atime(s)."

not-permission-message: "§cYou do not have permission to use this command!"

reload-message: "§aConfiguration reloaded successfully!"

set-player-death-message: "§aSet player §f%s§a's death count to §e%d§a."

set-player-added-permission-message: "§aSet player §f%s§a's extra protection charges to §e%d§a."

player-404-message: "§cPlayer does not exist or is not online."

value-err-message: "§cInvalid value."

set-added-protect-message: "§aSet player §f{0}§a's extra protection charges to §e{1}§a."

integer-error-message: "§c{0} is not a valid integer."

value-unchanged-message: "§cThe value has not changed."

death-update-error-message: "§cFailed to update the player's death count."

protection-update-error-message: "§cFailed to update the player's extra protection charges."

switch-self-message: "Your death protection state has been changed to {0}."

switch-player-message: "{0}'s death protection state has been changed to {1}."

switch-all-message: "The global death protection state has been changed to {0}."

After editing the configuration, apply the changes with:

/lg reload

Disabling Update Checks

The update checker only requests release information from GitHub and reports available versions in the server console. It does not download or replace plugin files.

To disable it:

update-check:
  enabled: false

---

📋 Requirements

Component	Requirement
Minecraft	1.19.4 or newer
Server software	Paper 1.19.4 or newer
Java	Java 17 or newer
Dependencies	None

LimitedGrace targets Paper. Compatibility with unlisted Bukkit-derived server software is not guaranteed.

---

⬆️ Updating from an Older Version

Before updating:

1. Stop the server.
2. Back up plugins/LimitedGrace/config.yml.
3. Replace the old LimitedGrace .jar.
4. Start the server.

When updating to v1.4.0, add the following option to your existing config.yml:

# Whether deaths with the `keepInventory` game rule enabled consume a protection charge.
keepinventory-consumes-charge: false

Alternatively, back up and delete the old config.yml, then restart the server to generate the latest configuration.

Player protection data is stored separately from config.yml and is not removed when the configuration is regenerated.

---

❓ Frequently Asked Questions

Does LimitedGrace permanently enable keepInventory?

No. Inventory and experience retention are applied only when a player's LimitedGrace protection is active. The plugin does not change the world's keepInventory game rule.

What happens when a world already has keepInventory enabled?

By default, LimitedGrace skips charge consumption because the game rule already preserves the player's inventory. Set keepinventory-consumes-charge to true if these deaths should be processed normally and consume applicable LimitedGrace charges.

Does disabling personal protection consume charges?

No. When personal protection is disabled, the player dies normally and LimitedGrace protection charges are not used.

Do server operators automatically receive unlimited protection?

No. limitedgrace.unlimited defaults to false and must be granted explicitly.

Does the update checker automatically install updates?

No. It only checks GitHub Releases and prints a notification in the server console.

Is a database required?

No. LimitedGrace stores its player data through Minecraft's persistent player data system.

---

🔗 Links

• Source Code
• Releases
• v1.4.0 Release Notes
• Issue Tracker

---

LimitedGrace provides a simple and performance-friendly way to soften early-game death penalties while preserving the challenge of long-term survival.