GeoBlock

A Paper plugin that filters incoming connections by country using a local MaxMind GeoLite2 database, with bypass support for trusted IPs and UUIDs, optional VPN/proxy detection and Discord webhook notifications.

Features

• Country-based filtering in blacklist or whitelist mode (ISO 3166-1 alpha-2 codes).
• IP and UUID bypass list with IPv4/IPv6 CIDR support.
• Permission integration through the standard Bukkit API: works with LuckPerms when present, falls back to vanilla /op otherwise.
• Async Discord webhook for connection denials, with toggleable IP inclusion for privacy-conscious deployments.
• Hot configuration reload via /geoblock reload.

Build

./gradlew build

The shaded jar is produced at build/libs/GeoBlock-<version>.jar with all runtime dependencies relocated under fr.horizonsmp.geoBlock.lib.* to avoid clashes with other plugins.

Run a development server

./gradlew runServer

Boots a Paper development server with the plugin loaded.

Requirements

• Java 25
• Paper 1.21.x (Minecraft 26.1.2 API target)
• A MaxMind GeoLite2 license key for automatic database updates, or a manually provided MMDB file under the plugin data folder.

Configuration

After the first run, edit the files generated under plugins/GeoBlock/:

• config.yml — filtering mode, country list, GeoIP, VPN and Discord options. Each option is documented inline.
• messages.yml — user-facing strings (kick reasons, command output).
• whitelist.yml — bypass list (managed through commands).

The plugin reads config.yml, messages.yml and whitelist.yml at startup and through /geoblock reload.

Commands

Command	Permission	Description
/geoblock reload	geoblock.command.reload	Reload all configuration files
/geoblock bypass add ip <ip|cidr>	geoblock.command.bypass	Add an IP or CIDR to the bypass list
/geoblock bypass add uuid <uuid>	geoblock.command.bypass	Add a player UUID to the bypass list
/geoblock bypass remove ip <ip>	geoblock.command.bypass	Remove an IP/CIDR entry
/geoblock bypass remove uuid <uuid>	geoblock.command.bypass	Remove a UUID entry
/geoblock bypass list	geoblock.command.bypass	Show every bypass entry
/geoblock help	geoblock.admin	Print the command summary

geoblock.admin (default op) implies the two child permissions, so operators get full access on a server without LuckPerms.

License

See LICENSE file.