🏳️ Players Flag

Automatically display player country flags across your Minecraft server.

Players Flag automatically detects players' countries based on their IP address and provides ready-to-use placeholders for chat, tablist, scoreboards, and custom GUI menus.

• Author: Controll3r24
• Target Version: Paper 26.2 (or compatible forks)
• Java Requirement: Java 25+

---

✨ Features

• 🌍 Automatic IP Detection: Instant country resolution upon player join.
• 🏷️ PlaceholderAPI Integration: Full support for %player_flag% and custom prefixes.
• 🧑‍🎨 In-Text Head Skins: Renders head textures directly inline using Minecraft's <head:...> MiniMessage tag.
• 😀 Emoji Fallbacks: Automatically falls back to standard emoji flags if custom head textures are unconfigured.
• 📜 Interactive Flag List: Integrated /pf list command complete with pagination.
• 🛠️ Manual Overrides: Administrative commands to set or reset custom player flags manually.
• 💾 Smart Caching: Local database caching eliminates redundant external API requests.
• 🥇 Custom Gold Gradients: Beautiful custom text rendering with custom gradient tags (<gg>).
• 👋 First-Run Admin Welcome: Helpful onboarding message delivered upon initial setup.
• ⚙️ Fully Configurable: Complete customization via config.yml.

---

📦 Requirements

Dependency	Required Version / Notes
Server Software	Paper 26.2 (or compatible forks)
Java	Java 25 or higher
PlaceholderAPI	Recommended (Required for placeholder expansion)

---

🚀 Quick Start & Installation

1. Download PlayersFlag-1.0.0.jar and place it into your server's plugins/ directory.
2. Install PlaceholderAPI if it is not already present.
3. Download the PlaceholderAPI Player expansion (required for %player_flag% compatibility):

   /papi ecloud download Player
   /papi reload
   

4. Restart your Minecraft server.
5. Log in as a server administrator to view the automated setup welcome message.
6. Configure head textures inside plugins/PlayersFlag/config.yml (see guide below).

---

🏷️ Placeholders

Placeholder	Description	Example Output
%player_flag%	Flag icon (Head texture or emoji fallback)	<head:...> / 🇮🇹
%player_flag_code%	Two-letter ISO country code	IT
%player_flag_country%	Full country name	Italy
%player_flag_emoji%	Native Unicode emoji flag	🇮🇹
%playersflag_flag%	Standalone alternative to %player_flag%	<head:...> / 🇮🇹
%playersflag_flag_code%	Standalone alternative to %player_flag_code%	IT
%playersflag_flag_country%	Standalone alternative to %player_flag_country%	Italy
%playersflag_flag_emoji%	Standalone alternative to %player_flag_emoji%	🇮🇹

ℹ️ Note on %player_flag% Overriding:
%player_flag% integrates directly into PlaceholderAPI's native Player expansion namespace. Players Flag intercepts flag requests while transparently forwarding all other %player_*% calls to the original expansion. If you encounter conflicts, use %playersflag_flag% or disable this behavior in config.yml by setting placeholder.override-player: false.

⚠️ Formatting Notice:
Flags rendered via head tags return MiniMessage formatted strings. The target plugin (chat manager, tablist, scoreboards) must support MiniMessage parsing, otherwise raw tags will appear in text.

---

🧑‍🎨 Head Texture Configuration

Players Flag utilizes the <head:...> tag format to render player head textures inline within text components.

1. Supported Head Tag Formats

• Player Name: <head:PlayerName>
• UUID: <head:00000000-0000-0000-0000-000000000000>
• Texture URL: <head:https://textures.minecraft.net/texture/...>
• Base64 String: <head:eyJ0ZXh0dXJlcyI6...>

To enable the secondary skin layer (hat/outer layer), append :true (e.g., <head:value:true>).

2. Sourcing Flag Textures

Search for flag skins on Minecraft head repositories (such as minecraft-heads.com). Copy either the Base64 value, Texture URL, or Owner UUID/Name.

3. Populating config.yml

Open plugins/PlayersFlag/config.yml and add flag entries under the flags: section using two-letter ISO 3166-1 country codes:

flags:
  IT: "italy-head-texture-value"
  US: "usa-head-texture-value"
  DE: "germany-head-texture-value"
  FR: "france-head-texture-value"

4. Customizing the Tag Format

You can customize how head tags are formatted globally. %value% is replaced dynamically by the entry defined in flags::

head:
  format: "<head:%value%>"

To enable outer skin layers across all head tags:

head:
  format: "<head:%value%:true>"

5. Fallback Options

If no head value is defined for a country, the plugin defaults to its Unicode emoji flag (e.g., 🇮🇹). You can disable emoji fallbacks and supply custom static text instead:

fallback:
  emoji: false
  unknown-text: "<gray>?</gray>"

6. Verification Steps

1. Save config.yml and run /pf reload.
2. Execute /pf list — countries with valid head entries will display a (head) indicator.
3. Execute /pf info to verify your active country assignment and flag display.
4. Test overrides with /pf set <player> <code>, then return to automatic lookup using /pf reset <player>.

---

💬 Usage Examples

Integrate placeholders into any MiniMessage-compatible plugin setup. Example chat format:

%player_flag% <white>%player_name%</white> <gray>»</gray> <white>{message}</white>

---

🧾 Commands & Permissions

Commands

Command	Description	Permission
/pf help	Displays command usage help	playersflag.use
/pf list [page]	Lists all supported country flags and setup status	playersflag.use
/pf info [player]	Displays current flag and location data for a player	playersflag.use
/pf reload	Reloads plugin configuration and local cache	playersflag.admin
/pf set <player> <code>	Manually overrides a player's flag	playersflag.admin
/pf reset <player>	Clears manual override and restores automatic lookup	playersflag.admin
/pf refresh <player>	Forces a fresh geolocation lookup via IP	playersflag.admin
/pf welcome	Re-displays the initial administrator welcome message	playersflag.admin

• Command Alias: /playersflag

Permissions Matrix

Permission	Description	Default
playersflag.use	Grants access to general utility commands (/pf help, /pf list, /pf info)	Everyone
playersflag.admin	Grants full administrative control and reload capabilities	Operators (OP)

---

⚙️ Configuration Reference

All main settings are located in plugins/PlayersFlag/config.yml. Execute /pf reload to apply updates.

Custom Gold Gradient Styling (<gg>)

Use the custom <gg>text</gg> tag to apply smooth multi-color gradients. Define any number of hex colors (minimum 2):

style:
  gradient: ["#FFF3B0", "#FFD700", "#B8860B"]
  prefix: "<gg><bold>[Players Flag]</bold></gg> "

IP Geolocation Engine

geolocation:
  enabled: true
  provider-url: "http://ip-api.com/json/%ip%?fields=status,countryCode"
  timeout-seconds: 5
  request-delay-ms: 1500
  cache-days: 30
  default-flag-code: ""

• enabled: Toggles automatic IP lookup on or off.
• provider-url: API endpoint for geolocation services (%ip% is populated dynamically). Must return a JSON response containing countryCode.
• timeout-seconds: Connection timeout limit per lookup.
• request-delay-ms: Rate-limit throttle delay between consecutive requests.
• cache-days: Duration (in days) resolved location data remains cached locally.
• default-flag-code: Fallback ISO code assigned when local/private IP addresses are detected or lookups fail.

Flag List Presentation

list:
  per-page: 15
  entry: "{flag} <gg>{code}</gg> <gray>-</gray> <white>{country}</white>{mark}"
  mark-configured: " <green>(head)</green>"

country-names-language: "en"

Welcome Message Onboarding

welcome:
  enabled: true
  permission: "playersflag.admin"
  also-ops: true
  delay-ticks: 40
  lines:
    - "<gg>--------------------------------------------------</gg>"
    - "<gg><bold>Welcome to Players Flag!</bold></gg>"
    - ""
    - "<gg>Hello {player}, thanks for installing Players Flag v{version}.</gg>"
    - "<gg>--------------------------------------------------</gg>"

Available Placeholders: {player}, {version}, {author}.

---

🔒 Privacy & Compliance

To resolve player flags, user IP addresses are sent to the endpoint defined in geolocation.provider-url (defaults to ip-api.com, which is free for non-commercial use).

• Storage: Only resolved 2-letter country codes are stored alongside player UUIDs in data.yml.
• Data Protection: Player IP addresses are never stored or logged to disk.
• Control: Server owners can change provider endpoints or disable external lookup completely inside config.yml.
• Compliance Note: We recommend updating your server's privacy policy to inform users about external geolocation lookups upon joining.

---

❓ Frequently Asked Questions

Q: The tag <head:...> displays as literal text on my server.
A: The plugin displaying the placeholder does not parse MiniMessage formatting, or your client setup/version lacks support for rendering head tags inline.

Q: Players show an emoji flag instead of a head skin.
A: No head texture value has been defined for that country code under the flags: section in config.yml.

Q: %player_flag% shows as raw text and does not expand.
A: Verify that PlaceholderAPI and the Player expansion are correctly installed (/papi ecloud download Player). Alternatively, use %playersflag_flag%.

Q: A player has been assigned the incorrect country flag.
A: Override it manually using /pf set <player> <code> or re-query their IP address using /pf refresh <player>.

Q: Players on local network connections (127.0.0.1) do not receive a flag.
A: Private/local IP ranges cannot be geolocated externally. Specify a default-flag-code inside config.yml or assign flags manually using /pf set.

---

👤 Credits & Support

• Developer: Controll3r24
• YouTube: @Controll3r24