GeoFlags

GeoFlags

Created by Lord Diablo.

Paper plugin (api-version 26.1). Finds each player's country from their IP and shows the country flag.

Supported Versions

• Server: Paper 1.21.9 and newer (including 26.x). Java 21 or newer
• Players: Minecraft 1.21.9 and newer (needed for skin head and flags in chat/tab)
• Resource pack: formats 69 and newer
• Must install skinrestore for chat skin

Summary

• Tab list: flag before the name (head, flag, name)
• Chat: skin head, flag, name, message
• Nametag above head: OFF (no scoreboard teams are created)
• Sidebar scoreboard: not part of this plugin
• Add the resource pack link below into your server.properties file so players see real flag images

Commands and Permissions

• /geoflag reload - reload config (geoflags.admin, op)
• /geoflag info [player] - show a player's country
• /geoflag set - set a flag by hand, example: /geoflag set Steve IN
• /flagtop - Top Countries leaderboard (geoflags.top, everyone)

Placeholders (PlaceholderAPI)

• %geoflag_flag% - flag character
• %geoflag_code% - country code, example IN
• %geoflag_country% - country name, example India

Config

• pack.url / pack.sha1 / pack.force - resource pack link, SHA-1, kick if refused
• tab.enabled / tab.position - flag in tab list, PREFIX or SUFFIX
• nametag.enabled / nametag.position - flag above head (uses scoreboard teams). Default OFF here
• chat.enabled / chat.format - placeholders {head} {flag} {name} {message}
• local-ip-fallback - AUTO or fixed code like IN, used when player IP is local/LAN
• unknown-country - code shown when lookup fails ("" = nothing)
• messages.prefix - prefix for plugin messages

Privacy

• The plugin does NOT write IPs to the console, logs or any file.
• data.yml stores only UUID -> country code. No IP is saved.
• The IP line in the console (Name[/1.2.3.4:5678] logged in) is printed by the server, not by this plugin. Hide it with the log4j2.xml provided (see GeoFlags-HideIP-log4j2.xml).
• The IP is sent to ip-api.com over plain HTTP (free plan). So the plugin is not the only one who sees it.

Shared IP / Tunnel / Proxy Servers

The plugin can only use the address the server sees. If your server is behind a tunnel, shared-IP or proxy host, the server sees the proxy's address, so the flag is wrong or missing. Fix it on the server side:

• Paper behind HAProxy/playit/similar with PROXY protocol: set proxies.proxy-protocol: true in config/paper-global.yml
• Velocity or BungeeCord: enable IP forwarding (Paper: proxies.velocity or settings.bungeecord)
• Addresses in 100.64.0.0/10 (carrier-grade NAT) are not treated as local by this version, so they are looked up and fail
• Workaround: set local-ip-fallback to a fixed code, example "IN"

Server Properties Setup

Add the resource pack settings to your server.properties file:

resource-pack= download.mc-packs.net/pack/fc2b64467e70f8c5e970…
resource-pack-sha1=fc2b64467e70f8c5e9705782aab65bbefe730c0f
resource-pack-id=45f92f96-6937-43a8-af80-ccc3edbf5599
resource-pack-prompt={"text":"Our server uses a custom resource pack!", "color":"gold"}
require-resource-pack=true