Yowsef Flags

Yowsef Flags displays player country flags across chat, nametags, scoreboards, and tablists using IP geolocation and PlaceholderAPI. It features a built-in HTTP server to generate and host custom pixel-art flag resource packs automatically, with Unicode emoji fallbacks for clients who decline resource packs.

Supported Platforms

Minecraft Version: 1.20 through 1.21+
Server Engines: Spigot, Paper, Purpur, Folia
Dependencies: PlaceholderAPI

Core Features

Real Flag Resource Pack Engine: Auto-generates high-definition pixel flag glyphs from PNG assets and delivers them to joining players.
Built-In HTTP Pack Host: Includes an internal web server on a configurable port so you do not need external web hosting or Dropbox links.
Unicode Fallback: Displays clean Unicode emoji country flags automatically if a player declines the resource pack.
Custom Player Overrides: Force a specific country code for any player regardless of their physical IP address.
PlaceholderAPI Integration: Insert flags anywhere with %yowsefflags_flag%, %yowsefflags_country%, and %yowsefflags_code%.

Commands and Permissions

Command	Purpose	Permission
`/yowsefflags lookup <player>`	Inspect the country and flag for an online player	`yowsefflags.admin`
`/yowsefflags reload`	Reload config and regenerate resource pack zip	`yowsefflags.admin`
`/yowsefflags info`	Display active GeoIP cache stats	`yowsefflags.admin`

Aliases

/yflags, /yf

Key Permissions

yowsefflags.admin: Access to lookup and administration commands.
yowsefflags.see: Permission to view flag placeholders (if restricted).
yowsefflags.bypass: Hides a player's flag from appearing to others.

Configuration Reference

The configuration file is located at plugins/YowsefFlags/config.yml:

# =====================================================
#             YowsefFlags Configuration
# =====================================================

enabled: true

# Built-in resource pack server for high-quality flag sprites
resource-pack:
  auto-host: true
  server-ip: "" # Leave empty to auto-detect
  server-port: 8765
  required: false
  prompt: "<gold>YowsefFlags</gold> <gray>— Download country flag textures</gray>"
  glyph-height: 10
  glyph-ascent: 9

# Geolocation API settings
geoip:
  enabled: true
  cache-duration: 30 # Minutes to cache player country
  api-endpoint: "http://ip-api.com/json/{ip}?fields=countryCode"

# Manual country overrides (Player: CountryCode)
custom-flags:
  # Notch: SE
  # AdminUser: US

default-flag: "NONE"