FriendGuard

FriendGuard protects a configurable list of players from accidental or unwanted bans and kicks on your Paper server.

Protected players are automatically kept online and unbanned when necessary, while the plugin periodically checks the standard server ban lists to catch offline bans as well.

How It Works

FriendGuard monitors player moderation actions in real time:

• Kicks are immediately cancelled for protected online players.
• Bans are immediately cancelled when they target a protected player who is currently online.
• Banned protected players are automatically pardoned when they attempt to join.
• A configurable background task periodically checks for offline bans and removes them as well.
• Unbanning is performed using the same pardon / pardon-ip commands available to server administrators, rather than relying directly on Paper's low-level BanList<T> API.

This approach avoids depending on version-sensitive internals. In newer Paper versions, the ban-list API is strongly typed and IP entries use InetAddress instead of String, which can make direct API usage unnecessarily fragile between builds.

Configuration

config.yml provides the following options:

protected-players:
  - PlayerName

protected-uuids:
  - uuid-here

protected-ips:
  - 127.0.0.1

settings:
  log-to-console: true
  check-interval-ticks: 20

Configuration Options

protected-players Player names that should be protected.

protected-uuids UUIDs of protected players. Useful when you want protection to remain tied to the player rather than their current name.

protected-ips IP addresses that should be protected from IP bans.

settings.log-to-console Controls whether FriendGuard reports protection actions to the server console.

settings.check-interval-ticks Controls how often the background protection check runs. For example, 20 ticks is approximately one second.

Commands

/friendguard reload Reload the configuration.

/friendguard check Immediately run a protection check.

Alias:

/fg

Compatibility

FriendGuard works with the standard Paper/Vanilla ban system — the same ban lists used by:

• /ban
• /ban-ip
• /pardon
• /pardon-ip

Third-Party Ban Plugins

FriendGuard does not automatically integrate with separate ban systems such as LiteBans, AdvancedBan, or other plugins that maintain their own ban database.

If your server uses a custom ban system instead of the standard Paper/Vanilla ban lists, FriendGuard may not be able to detect or remove those bans. In that case, a dedicated integration for that ban plugin would be required.