Services Reference

Comprehensive guide detailing the individual service interfaces exposed by ShyamDuelsAPI.

Overview of Services

Each service interface manages a specific aspect of the plugin (matchmaking, players, statistics, structures). Resolve a service instance from your resolved API entry point:

javaShyamDuelsAPI api = ShyamDuelsProvider.require();
DuelService duelService = api.duels();
StatsService statsService = api.stats();

DuelService

Interface: com.shyamstudio.shyamduels.api.duel.DuelService
Manages active duel instances, invitations, and match structures:

Method Signature	Returns	Description
`isInDuel(Player)`	boolean	True if the player is in an active duel round.
`isParticipatingInDuel(Player)`	boolean	True if the player is in a duel (including between rounds).
`getDuel(Player)`	Duel	Current duel for the player, or null.
`getDuelById(UUID)`	Duel	Lookup a duel by its UUID.
`getEndingDuel(Player)`	Duel	Duel currently ending for the player (post-match cleanup), or null.
`getOpponent(Player)`	Player	1v1 opponent, or null.
`getDuelRespawnLocation(Player)`	Location	Respawn point for the player in the current duel round.
`getActiveDuels()`	List<Duel>	All currently active duel instances.
`sendInvite(sender, target, kit, rounds)`	void	Sends a ranked duel invitation.
`acceptInvite(acceptor, sender)`	void	Accepts a pending duel invite.
`denyInvite(target, sender)`	void	Denies a pending duel invite.
`startDuel(p1, p2, kit, rounds)`	void	Immediately starts a 1v1 duel.
`startDuel(team1, team2, kit, mode, rounds)`	boolean	Starts a team duel; returns false if arena allocation fails.
`forfeitDuel(Player)`	void	Forfeits the player's current duel.
`forceEnd(Duel)`	void	Immediately terminates a duel and returns players to lobby.
`eliminatePlayer(victim, killer)`	void	Handles a player elimination inside a duel round.
`sendPartyDuelInvite(senderParty, targetParty, kit)`	void	Sends a party-vs-party challenge.
`acceptPartyDuelInvite(acceptor)`	void	Accepts a pending party duel invite (party leader).
`startPartyDuel(team1Party, team2Party, kit)`	void	Starts a party-vs-party match.
`startPartyFFA(players, kit, party)`	void	Starts a party free-for-all inside one arena.
`getSelfRelation(Player)`	String	MiniMessage relation tag for the player's own nametag context.
`getRelationPlaceholder(viewer, target)`	String	Relational placeholder color between two players.

StatsService

Interface: com.shyamstudio.shyamduels.api.stats.StatsService
Fetches and updates player ELO ratings, kills, deaths, winstreaks, and ranks:

Method Signature	Returns	Description
`getStats(Player player)`	PlayerStats	Gets the player's cached statistics.
`getStats(UUID uuid)`	PlayerStats	Gets cached statistics for a UUID.
`loadPlayer(Player player)`	CompletableFuture<PlayerStats>	Asynchronously loads and caches a player's statistics from the database.
`savePlayer(Player player)`	void	Persists a player's cached statistics to the database.
`unloadPlayer(Player player)`	void	Flushes and evicts a player's cached statistics.
`recordKill(Player killer, Player victim)`	void	Records a kill for the killer (increments kills and killstreak).
`recordDeath(Player victim)`	void	Records a death for the victim (increments deaths, resets killstreak).
`recordWin(Player winner)`	void	Records a win for the player.
`recordWin(Player winner, Collection<UUID> opponents)`	void	Records a win and applies ELO changes against the given opponents.
`recordLoss(Player loser)`	void	Records a loss for the player.
`recordLoss(Player loser, Collection<UUID> opponents)`	void	Records a loss and applies ELO changes against the given opponents.
`getKills(UUID uuid)`	int	Convenience getter for a player's total kills.
`getDeaths(UUID uuid)`	int	Convenience getter for a player's total deaths.
`getWins(UUID uuid)`	int	Convenience getter for a player's total wins.
`getLosses(UUID uuid)`	int	Convenience getter for a player's total losses.
`getElo(UUID uuid)`	int	Convenience getter for a player's current ELO rating.
`getRank(Player player)`	Rank	Resolves the player's current rank from their ELO.
`isEloEnabled()`	boolean	Whether the ELO system is enabled.
`shouldUpdateElo(Duel duel)`	boolean	Whether ELO changes are applied for the given duel (module/match-type gating).
`saveStats(PlayerStats stats)`	CompletableFuture<Void>	Saves modifications back to the SQLite or MySQL database pools.
`getKitStats(Player player, String kitName)`	KitStats	Gets cached statistics for a player and specific kit.
`getKitStats(UUID uuid, String kitName)`	KitStats	Gets cached statistics for a UUID and specific kit.
`getKitElo(UUID uuid, String kitName)`	int	Convenience getter for a player's ELO rating in a specific kit.
`getKitWins(UUID uuid, String kitName)`	int	Convenience getter for a player's wins with a specific kit.
`getKitLosses(UUID uuid, String kitName)`	int	Convenience getter for a player's losses with a specific kit.
`getKitKills(UUID uuid, String kitName)`	int	Convenience getter for a player's kills with a specific kit.
`getKitDeaths(UUID uuid, String kitName)`	int	Convenience getter for a player's deaths with a specific kit.
`getTopPlayers(String stat, int limit)`	CompletableFuture<List<PlayerStats>>	Asynchronously fetches an overall leaderboard ordered by a stat (e.g. "elo", "kills", "wins", "winstreak").
`getTopPlayers(String kitName, String stat, int limit)` / `getTopKitPlayers(...)`	CompletableFuture<List<KitLeaderboardEntry>>	Asynchronously fetches per-kit leaderboard entries ordered by a stat (e.g. "elo", "wins", "kills", "killstreak", "winstreak").

ArenaService

Interface: com.shyamstudio.shyamduels.api.arena.ArenaService
Coordinates FAWE reset states and lists active arena environments:

Method Signature	Returns	Description
`getArena(String name)`	Arena	Resolves an Arena model by its case-insensitive name.
`getArenas()`	Collection<Arena>	Returns a list of all registered arenas.
`resetArena(Arena arena)`	void	Force-queues an immediate schematic reset paste on the arena.
`claimArena(String kitName)` / `claimArena(Kit)`	Arena	Claims an available arena for a kit, or null.
`releaseArena(Arena)`	void	Marks an arena free again after a match.
`hasAvailableArena(String kitName)` / `hasAvailableArena(Kit)`	boolean	Whether an available arena exists for a kit.
`hasArenaForKit(String kitName)` / `hasArenaForKit(Kit)`	boolean	Whether any arena is configured for a kit.
`getAvailableArena(String kitName)`	Arena	Deprecated: atomically claims (sets IN_USE) via `claimArena(kitName)` - it does claim. Use `claimArena` directly.
`getAvailableDuelArenaCount()`	int	Number of arenas currently free for duels.
`regenerateArena(Arena)` / `regenerateArena(Arena, Runnable)`	void	Queues a schematic repaste; optional completion callback.
`setSpawn(String arenaName, int id, Location)`	void	Sets spawn 1/2 for an arena.
`saveArena(Arena)`	void	Persists arena data.
`getBaseWorldName()`	String	The configured base world name.
`isArenaWorld(String)`	boolean	Whether a world name belongs to the arena system.

KitService

Interface: com.shyamstudio.shyamduels.api.kit.KitService
Manages kit configuration templates, per-player edited kits, and their share metadata:

Method Signature	Returns	Description
`getKit(String name)`	Kit	Resolves a kit configuration template by name.
`getKits()`	Collection<Kit>	Returns all registered kit templates.
`getPublicKits()`	List<Kit>	Returns the kits flagged as publicly selectable.
`applyKitToPlayer(Player, Kit)`	void	Applies a base kit's contents to the player's inventory.
`getPlayerKit(UUID, String kitName)`	PlayerKit	Gets a player's saved edited version of a kit, or null.
`savePlayerKit(PlayerKit)`	void	Persists a player's edited kit asynchronously.
`resetPlayerKit(UUID, String kitName)`	void	Deletes a player's edited kit, reverting to the base layout.
`loadPlayerKits(Player)`	CompletableFuture<Void>	Asynchronously loads and caches a player's edited kits.
`getShareCode(PlayerKit)`	String	The share code assigned to an edited kit, or null.
`getImportCount(PlayerKit)`	int	How many times the edited kit has been imported by others.
`getCreatedAt(PlayerKit)`	long	Epoch millis when the edited kit was first created.
`getDisplayName(Kit)` / `getDisplayName(String)`	String	Resolves a kit's display name.
`kitPlaceholders(Kit)`	Map<String, String>	Placeholder name/value pairs for a kit.
`isBuildKit(Kit)`	boolean	Whether the kit enables block building.
`isInternalKit(String)`	boolean	Whether the name belongs to an internal (non-public) kit.
`getPlayerKitSync(UUID, String)`	PlayerKit	Synchronous player-kit lookup, or null.
`syncDisplayNameFromIcon(Kit, ItemStack)`	void	Updates a kit's display name from its GUI icon.
`getQueueRounds(Kit)` / `setQueueRounds(Kit, int)`	int / void	Queue round count for a kit.
`saveKit(Kit)`	void	Persists a kit's configuration.
`getCategories()`	List<KitCategory>	Returns all registered kit categories.
`getCategory(String id)`	KitCategory	Finds a kit category by its ID, or null.
`getCategoryForKit(String kitName)`	KitCategory	Gets the parent category linked to a kit, or null.
`getKitsForCategory(KitCategory)`	List<Kit>	Gets all kits belonging to a category.
`getUncategorizedKits()`	List<Kit>	Gets all standalone kits that are not in any category.

KitShareService

Interface: com.shyamstudio.shyamduels.api.kitshare.KitShareService
Drives the per-kit share-code system for both edited base kits and player-built custom kits. Resolve via api.kitShare(). Codes resolve against an in-memory registry of online owners only. Imports require the owner online and sharing enabled. Call importKit(...) on the main server thread; the resulting database/file writes run asynchronously inside the managers.

Method Signature	Returns	Description
`resolve(String code)`	KitShareManager.ShareRef	Resolves a share code to its owning kit reference, or null if unknown/owner offline.
`importKit(Player importer, String code)`	void	Imports the referenced kit into the importer's kits. Failures (invalid code, owner offline, sharing disabled, kit removed, self-import) are messaged to the importer.
`isSharing(UUID ownerId)`	boolean	Whether the player currently has the "Share Edited Kits" setting enabled.
`getShareCode(UUID ownerId, String kitName)`	String	The current share code for an owner's edited kit, or null.
`getImportCount(UUID ownerId, String kitName)`	int	How many times an owner's edited kit has been imported.
`regenerateCode(UUID ownerId, String kitName)`	String	Regenerates and returns a new share code for an owner's edited kit, or null.

PartyService

Interface: com.shyamstudio.shyamduels.api.party.PartyService
Tracks active parties, member indices, and team divisions:

Method Signature	Returns	Description
`createParty(Player)`	Party	Creates a party with the player as owner.
`disbandParty(Party)`	void	Disbands a party.
`invitePlayer(sender, target)`	void	Sends a party invite.
`acceptInvite(Player)`	void	Accepts a pending party invite.
`denyInvite(Player)`	void	Denies a pending party invite.
`joinPublicParty(player, targetOwner)`	void	Joins a public party by leader name.
`leaveParty(Player)`	void	Removes the player from their party.
`kickPlayer(owner, target)`	void	Kicks a member (leader only).
`setPublic(Player, boolean)`	void	Toggles public/private join mode.
`setPartyMode(Player, PartyMode)`	void	Sets queue/split/ffa/duel party behavior.
`setMemberLimit(Player, int)`	void	Sets a custom member cap.
`cyclePlayMode(Player)`	void	Cycles the party play mode.
`toggleChat(Player)`	void	Toggles party-only chat for the player.
`isInParty(Player)`	boolean	Whether the player is in a party.
`getParty(Player)`	Party	Active party for the player, or null.
`getPartyByMember(UUID)`	Party	Party containing the UUID, or null.
`getPartyById(UUID)`	Party	Party by party UUID, or null.
`getAllParties()`	Collection<Party>	All active parties.
`getPublicParties()`	List<Party>	Parties with public join enabled.
`getMaxPartySize(Party)`	int	Effective max size for a party.
`getMaxPartySize(Player)`	int	Max size the player could create based on permissions.
`hasPendingInvite(Player)`	boolean	Whether the player has an unhandled party invite.
`handlePlayerDisconnect(Player)`	void	Cleans up party state on quit.

FriendsService

Interface: com.shyamstudio.shyamduels.api.friend.FriendsService
Manages friend requests and friend list states:

Method Signature	Returns	Description
`getMaxFriends()`	int	Configured friend list cap.
`getFriendUuids(UUID)`	Set<UUID>	Friend UUIDs for a player.
`getStatus(UUID)`	FriendStatus	Online/offline status aggregate.
`isNotificationsEnabled(UUID)`	boolean	Whether friend notifications are on.
`areFriends(UUID, UUID)`	boolean	Whether two players are friends.
`hasIncomingRequest(receiver, sender)`	boolean	Pending request from sender to receiver.
`getIncomingRequests(UUID)`	Set<UUID>	All pending incoming request senders.
`loadPlayerFuture(UUID)`	CompletableFuture<Void>	Async load of friend data.
`unloadPlayer(UUID)`	void	Evicts cached friend data.
`sendRequest(sender, target)`	SendResult	Sends a friend request (enum result).
`acceptRequest(receiver, sender)`	AcceptResult	Accepts a friend request.
`denyRequest(receiver, sender)`	void	Denies a friend request.
`removeFriend(playerId, targetId)`	void	Removes a friend.

QueueService

Interface: com.shyamstudio.shyamduels.api.queue.QueueService
Manages ranked/unranked matchmaking queues for solo players and parties:

Key Methods	Description
`addPlayer(player, kit, mode)`	void	Adds a player to a kit queue.
`joinRandomQueue(player, mode)`	void	Queues for a random needed kit.
`removePlayer(player)`	void	Removes a player from all queues.
`removeKitFromQueue(player, key)`	void	Removes one specific queue entry.
`addParty(party, kit, mode)`	void	Queues an entire party together.
`removeParty(party)`	void	Removes a party from all queues.
`isQueued(player)`	boolean	Whether the player is in any queue.
`isActivelyQueued(player)`	boolean	Whether the player is waiting for a match (not in-game).
`isQueuedForKit(player/uuid, kitName, mode)`	boolean	Queued for a specific kit+mode.
`isPrimaryQueuedKit(player/uuid, kitName, mode)`	boolean	Whether this is the player's primary queue slot.
`getPlayerQueueKey(player)`	QueueKey	Primary queue key, or null.
`getPrimaryQueueKey(uuid)`	QueueKey	Primary queue key by UUID.
`getPlayerQueueKeys(player)`	List<QueueKey>	All active queue keys (multi-kit).
`getPlayerQueueCount(player)`	int	Number of kits queued.
`getQueueSize(kitName, mode)`	int	Players waiting in a queue.
`getInGameSize(kitName, mode)`	int	Players currently in matches from that queue.
`resolveQueueRounds(kit)`	int	Effective round count for queue matches.
`isMultipleKitsEnabled()`	boolean	Whether multi-kit queueing is on.
`pickRandomNeededKit(mode)`	Kit	Kit most needed for matchmaking, or null.
`resetPlayerState(player)`	void	Clears queue UI/state for a player.
`handlePlayerDisconnect(player)`	void	Removes player from queues on quit.

FFAService

Interface: com.shyamstudio.shyamduels.api.ffa.FFAService
Controls FFA join/leave, arena state, and resets:

Key Methods	Description
`joinFFA(player, arena)`	void	Teleports a player into an FFA arena.
`leaveFFA(player)`	void	Removes a player from FFA.
`handleDeath(player)`	void	Processes FFA death (respawn/kill regen).
`getPlayerState(player)`	FFAState	`NONE`, `FFA_STARTING`, or `IN_FFA`.
`getPlayerArena(player)`	Arena	Arena the player is in, or null.
`getPlayerKit(player)`	Kit	Kit assigned in FFA, or null.
`isInArena(player, arena)`	boolean	Whether the player is in the given arena.
`getPlayersInArena(arena)`	List<Player>	All players in an FFA arena.
`getPlayerCount(arena)`	int	Player count in an arena.
`getResetIntervalSeconds()`	long	Configured FFA reset interval.
`getSecondsUntilReset(arena)`	long	Seconds until the next scheduled reset.
`resetArena(arena)`	void	Triggers an FFA map reset.
`getLobbyLocation()`	Location	Lobby spawn location.
`teleportToLobby(player)`	CompletableFuture<Boolean>	Async-safe lobby teleport.

SpectatorService

Interface: com.shyamstudio.shyamduels.api.spectate.SpectatorService

Key Methods	Description
`joinSpectate(spectator, target)`	void	Starts spectating a player's duel.
`leaveSpectate(spectator)`	void	Stops spectating.
`endSpectateForDuel(duel)`	void	Ends all spectators when a duel ends.
`redirectSpectatorsFrom(deadPlayer, duel)`	void	Redirects spectators after a player dies.
`isSpectating(player)`	boolean	Whether the player is spectating.
`getDuel(spectator)`	Duel	Duel being spectated, or null.
`getSpectatingArena(spectator)`	Arena	Arena being spectated, or null.
`getSpectatorsOfDuel(duel)`	List<UUID>	Spectator UUIDs for a duel.
`getSpectatorCount(duel)`	int	Number of spectators on a duel.
`getActiveDuels()`	List<Duel>	All duels that can be spectated.

RematchService

Interface: com.shyamstudio.shyamduels.api.rematch.RematchService
Manages the post-duel rematch offer between two 1v1 opponents:

Key Methods	Description
`offerRematch(duel)`	Offers a rematch to both players of a finished 1v1 duel.
`handleRematchClick(player)`	Processes a player accepting the rematch offer.
`handlePlayerDisconnect(player)`	Cancels a pending rematch when a player disconnects.

TabService

Interface: com.shyamstudio.shyamduels.api.tab.TabService
Controls the tab list, nametags, scoreboard visibility, and the match-found animation:

Key Methods	Description
`isTabEnabled()`	Whether the tab-list module is active.
`refreshTab(player)`	Rebuilds and resends a player's tab list.
`updateHeaderFooter(player)`	Updates only the tab header and footer.
`applyTabViewPreference(player)`	Applies the player's saved tab view preference.
`isNameTagsEnabled()`	Whether the nametag module is active.
`refreshNameTags(viewer)`	Resends nametag teams to a viewer.
`refreshAllNameTags()`	Resends nametag teams to all online players.
`isScoreboardEnabled()`	Whether the scoreboard module is active.
`showScoreboard(player)`	Creates the sidebar scoreboard for a player.
`hideScoreboard(player)`	Removes the sidebar scoreboard for a player.
`refreshScoreboard(player)`	Forces an immediate scoreboard refresh.
`playMatchFoundAnimation(player, kitItem)`	Closes the player's GUI and plays the totem match-found animation showing the kit item.

ScoreboardService

Interface: com.shyamstudio.shyamduels.api.scoreboard.ScoreboardService
Controls the sidebar scoreboard per player:

Key Methods	Description
`isEnabled()`	Whether the scoreboard module is active.
`isDisabled(player)`	Whether the scoreboard is hidden for a player.
`setDisabled(player, disabled)`	Hides or shows the scoreboard for a player.
`show(player)`	Creates the sidebar scoreboard for a player.
`hide(player)`	Removes the sidebar scoreboard for a player.
`refresh(player)`	Forces an immediate scoreboard refresh.
`reload()`	Rebuilds all scoreboards from config.
`getUpdateTime()`	In-match scoreboard update interval (ticks).
`getLobbyUpdateTime()`	Lobby scoreboard update interval (ticks).

NameTagService

Interface: com.shyamstudio.shyamduels.api.nametag.NameTagService
Controls the above-head nametag teams:

Key Methods	Description
`isEnabled()`	Whether the nametag module is active.
`refresh(viewer)`	Resends nametag teams to a single viewer.
`refreshAll()`	Resends nametag teams to all online players.
`bootstrapAll()`	Rebuilds and sends all nametag teams.
`getTabFormat(target)`	Returns [tabprefix, tabsuffix, customtabname] for a player.

AnimationService

Interface: com.shyamstudio.shyamduels.api.animation.AnimationService
Plays configurable title animations from messages.yml:

Key Methods	Description
`has(name)`	Whether a title animation with that name exists.
`play(player, name)`	Plays a title animation for a player.
`play(player, name, placeholders)`	Plays a title animation with placeholder replacements.
`playAll(players, name, placeholders)`	Plays a title animation for multiple players.

SettingsService

Interface: com.shyamstudio.shyamduels.api.settings.SettingsService

Method	Returns	Description
`getSettings(UUID)`	PlayerSettings	Cached settings for a player.
`loadPlayer(Player)`	CompletableFuture<PlayerSettings>	Async load from database.
`saveSettings(PlayerSettings)`	void	Persists settings changes.
`unloadPlayer(UUID)`	void	Flushes and evicts cached settings.

PlaceholderService

Interface: com.shyamstudio.shyamduels.api.placeholder.PlaceholderService

Method	Returns	Description
`getCurrentMode(Player)`	String	Current game mode label (lobby, duel, queue, etc.).
`isInFight(Player)`	boolean	Whether the player is in any active fight.
`isFFA(Player)`	boolean	Whether the player is in FFA.
`isInParty(Player)`	boolean	Whether the player is in a party.
`isEditor(Player)`	boolean	Whether the player has an open kit editor session.
`doPlaceholders(Player, text)`	String	Resolves internal placeholders in a string.
`getKitDisplayName(Player)`	String	Current kit display name.
`getQueueKitDisplayName(Player)`	String	Primary queued kit name.
`getQueueModeDisplay(Player)`	String	Queue mode label (1v1, 2v2, etc.).
`getQueueWaitTime(Player)`	String	Formatted queue wait duration.
`getQueueKitsList(Player)`	String	Comma-separated queued kit names.
`getQueueElapsedSeconds(UUID)`	long	Seconds spent in queue.
`invalidatePlayer(Player)`	void	Clears cached placeholder state.

CommandService

Interface: com.shyamstudio.shyamduels.api.command.CommandService
Inspects command-restrictions from config:

Method	Returns	Description
`rootCommand(message)`	String	Parses the root command from a chat line.
`evaluateBlock(player, rootCommand)`	String	Messages.yml block key if blocked, else null.
`isAllowed(rootCommand)`	boolean	Always-allowed command list.
`isBlockedInParty(rootCommand)`	boolean	Blocked while in a party lobby.
`isBlockedInMatchGlobal(rootCommand)`	boolean	Blocked during any match.
`shouldBlockInDuel(rootCommand)`	boolean	Blocked during duels.
`shouldBlockInFfa(rootCommand)`	boolean	Blocked during FFA.
`shouldBlockInSpectate(rootCommand)`	boolean	Blocked while spectating.
`reload()`	void	Reloads rules from config.

Optional Services

Available when the corresponding module is enabled:

practice() - PracticeService for golden heads, totem practice, death messages
customKits() - CustomKitsService for player-built custom kit profiles
kitEditor() - KitEditorService for the practice kit editor

CustomKitsService

Interface: com.shyamstudio.shyamduels.api.customkits.CustomKitsService
Manages player-built custom kit profiles (optional, available via customKits()):

Key Methods	Description
`isEnabled()`	Whether the custom-kits module is active.
`getBaseKitName()`	The configured base kit name.
`getBaseKit()`	The internal base kit, or null.
`canQueueCustomKits()`	Whether an arena exists for custom-kit queueing.
`getPlayerKits(uuid)`	All saved custom kits for a player (slot to kit).
`getPlayerKit(uuid, kitId)`	A single saved custom kit, or null.
`savePlayerKit(uuid, kit)`	Saves/updates a player's custom kit.
`preloadPlayerKits(uuid)`	Warms a player's kit cache asynchronously.
`unloadPlayer(uuid)`	Flushes and evicts a player's cached kits.
`reload()`	Reloads the custom-kits configuration.

KitEditorService

Interface: com.shyamstudio.shyamduels.api.kiteditor.KitEditorService
Controls the practice kit editor (optional, available via kitEditor()):

Key Methods	Description
`isEnabled()`	Whether the kit editor module is active.
`hasActiveSession(player)`	Whether the player has an open editor session.
`openEditor(player)`	Opens the kit picker / editor for a player.
`reopenEditor(player)`	Reopens the editor after a sub-menu.

CountryService

Interface: com.shyamstudio.shyamduels.api.country.CountryService
GeoIP detection, manual flag selection (/countryflags), display resolution and head rendering backed by a 224-entry registry. Resolve via api.country(). All lookups are cache-first (ConcurrentHashMap) and safe for the tab/nametag hot path; mutations must be called on the main thread.

Method Signature	Returns	Description
`isDisplayAvailable()`	boolean	Whether country flag display is enabled (`country.enabled`). False hides all flags and rejects selections.
`isDetectionEnabled()`	boolean	Whether fresh IP detection is possible (display enabled and MaxMind reader loaded).
`isEnabled()`	boolean	Deprecated: prefer `isDetectionEnabled()` or `isDisplayAvailable()`.
`getCachedCountry(UUID)`	String	Cached ISO code without DB/GeoIP, or null if unknown.
`getDisplayCountry(UUID)` / `getDisplayCountry(Player)`	String	Respects visibility toggle; code to render or null (hidden/unknown). O(1) - safe for every nametag refresh.
`getCountry(UUID)` / `getCountry(Player)`	String	Alias for `getCachedCountry` (fast cache-only path).
`isManual(UUID)`	boolean	Whether the player's country was locked via the flag GUI (not MaxMind).
`isFlagVisible(UUID)`	boolean	Whether the player has not hidden their flag in /settings.
`setFlagVisible(UUID, boolean)`	void	Updates visibility cache when the COUNTRY_FLAG setting toggles.
`selectCountry(Player, String isoCode)`	boolean	Persists GUI selection, updates cache, fires `PlayerCountryChangeEvent(SELECT)` and refreshes displays. Main thread only.
`resetCountry(Player)`	boolean	Clears manual override back to GeoIP/none, fires `RESET` event, refreshes displays. Main thread only.
`getAllCountryCodes()`	Set<String>	All 224 ISO codes (unmodifiable snapshot).
`getAllTextures()`	Map<String,String>	ISO -> Base64 head texture map (224 entries).
`getTexture(String iso)`	String	Base64 texture for the code, or null.
`contains(String iso)`	boolean	Whether the registry contains the code.
`getCountryCount()`	int	Registered flag count (expected 224).
`getDisplayName(String iso)`	String	English name for the code (e.g. US -> United States).
`getSortedDisplayNames()`	List<String>	Cached sorted names for tab-completion (immutable).
`resolveIsoCode(String input)`	String	Resolves ISO, full name, underscore or prefix to canonical ISO (or null).
`getFlagComponent(String iso)`	Component	Adventure head component for the flag; empty if unknown.
`getFlagHeadString(String iso)`	String	MiniMessage snippet `<head:BASE64>` for embedding.
`getFlagForPlayer(UUID)` / `getFlagForPlayer(Player)`	Component	Flag component for the player's display country (respects visibility).
`createFlagHead(String iso)`	ItemStack	Player-head ItemStack for the flag (cloned from cache, safe to mutate).
`createFlagHead(String iso, String name, List<String> lore, boolean glow)`	ItemStack	Flag head with custom name/lore/glow (MiniMessage name, lore lines).
`lookupCountry(InetAddress)`	String	MaxMind lookup for an address, or null if private/disabled. Thread-safe.
`lookupCountry(String ip)`	String	MaxMind lookup for a string IP, or null if invalid/private. Thread-safe.
`isGeoIpEnabled()`	boolean	Whether the MaxMind reader is loaded and enabled.
`isGeoIpInitialized()`	boolean	Whether GeoIpService has been initialized.
`getDatabaseFile()`	File	Resolved MaxMind .mmdb file, or null.
`refreshDisplay(Player)`	void	Forces nametag/tab/scoreboard refresh (main thread).
`normalize(String code)`	String	Normalizes to uppercase (2-32 chars, registry-checked), or null if invalid.
`normalizeIso(String code)`	String	Strict ISO-only normalize (2 uppercase letters) or null.

Constant: CountryService.UNKNOWN = "UNKNOWN". Registry invariants asserted by tests: exactly 224 ISO textures, zero extra textures, no synthetic ANKARA entry.

TournamentService

Interface: com.shyamstudio.shyamduels.api.tournament.TournamentService
Manage tournament registrations, active bracket duels, and player memberships:

Method Signature	Returns	Description
`hasActiveTournament()`	boolean	True if a tournament registration or match phase is in progress.
`getCurrentTournament()`	Tournament	Returns current active tournament session or null.
`isInTournament(Player)` / `isInTournament(UUID)`	boolean	True if the player is participating in the current tournament (accepts a Player or UUID).
`getTournamentPlayer(UUID)`	TournamentPlayer	Tournament participant data for the player, or null.
`createAndStartRegistration(String kitName, CommandSender starter)`	boolean	Starts registration for a new tournament.
`joinTournament(Player)`	boolean	Adds player to the active registration.
`leaveTournament(Player)`	boolean	Removes player from the active registration.
`forceStartTournament(CommandSender starter)`	void	Skips the remaining countdown and starts the bracket immediately.
`cancelTournament(String reason)`	void	Cancels active tournament.

PlayerService

Interface: com.shyamstudio.shyamduels.api.player.PlayerService
Thread-safe snapshots of player activity (no live Bukkit objects retained). Must be called on the server thread. Resolve via api.players():

Method Signature	Returns	Description
`snapshot(UUID)`	Optional<PlayerSnapshot>	Immutable snapshot (activity, duel/party/arena/kit/queues, tournament flag) or empty.
`snapshot(Player)`	PlayerSnapshot	Snapshot for an online player.
`onlineSnapshots()`	List<PlayerSnapshot>	Snapshots for all online players.

Models: PlayerSnapshot(playerId, playerName, activity, duelId, partyId, arenaName, kitName, queues, tournamentParticipant, capturedAt), QueueSnapshot(kitName, mode, displayMode, teamSize), PlayerActivity(LOADING, LOBBY, PARTY, KIT_EDITOR, TOURNAMENT, QUEUED, FFA, DUEL, SPECTATING). See Data Models.

ExtensionService

Interface: com.shyamstudio.shyamduels.api.extension.ExtensionService
Thread-safe registry for add-on contracts (ConcurrentHashMap). Auto-unregisters on plugin disable. Resolve via api.extensions():

Method Signature	Returns	Description
`register(key, ownerPlugin, contractType)`	ExtensionRegistration	Registers a contract; close/unregister to remove.
`find(key)`	Optional<ExtensionRegistration>	Looks up a registered contract.
`registeredExtensions()`	Collection<ExtensionDescriptor>	All active registrations (key, owner, contract type, timestamp).
`unregisterAll(ownerPlugin)`	void	Removes all contracts owned by a plugin.

PracticeService

Interface: com.shyamstudio.shyamduels.api.practice.PracticeService
Optional practice-module facade (available via practice() when the practice module is enabled):

Method Signature	Returns	Description
`isKitEditorEnabled()` / `isDuelCommandEnabled()` / `isRightClickDuelEnabled()`	boolean	Module feature gates.
`isDeathMessagesEnabled()` / `isGoldenHeadEnabled()` / `isTotemPracticeEnabled()`	boolean	Practice feature gates.
`openKitRoom(player)`	void	Opens the practice kit-room GUI.
`giveGoldenHead(player)`	void	Gives a golden head item.
`startTotemPractice(player)`	void	Starts the totem reaction game.
`reload()`	CompletableFuture<Void>	Reloads practice configs (async).