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)booleanTrue if the player is in an active duel round.
isParticipatingInDuel(Player)booleanTrue if the player is in a duel (including between rounds).
getDuel(Player)DuelCurrent duel for the player, or null.
getDuelById(UUID)DuelLookup a duel by its UUID.
getEndingDuel(Player)DuelDuel currently ending for the player (post-match cleanup), or null.
getOpponent(Player)Player1v1 opponent, or null.
getDuelRespawnLocation(Player)LocationRespawn point for the player in the current duel round.
getActiveDuels()List<Duel>All currently active duel instances.
sendInvite(sender, target, kit, rounds)voidSends a ranked duel invitation.
acceptInvite(acceptor, sender)voidAccepts a pending duel invite.
denyInvite(target, sender)voidDenies a pending duel invite.
startDuel(p1, p2, kit, rounds)voidImmediately starts a 1v1 duel.
startDuel(team1, team2, kit, mode, rounds)booleanStarts a team duel; returns false if arena allocation fails.
forfeitDuel(Player)voidForfeits the player's current duel.
forceEnd(Duel)voidImmediately terminates a duel and returns players to lobby.
eliminatePlayer(victim, killer)voidHandles a player elimination inside a duel round.
sendPartyDuelInvite(senderParty, targetParty, kit)voidSends a party-vs-party challenge.
acceptPartyDuelInvite(acceptor)voidAccepts a pending party duel invite (party leader).
startPartyDuel(team1Party, team2Party, kit)voidStarts a party-vs-party match.
startPartyFFA(players, kit, party)voidStarts a party free-for-all inside one arena.
getSelfRelation(Player)StringMiniMessage relation tag for the player's own nametag context.
getRelationPlaceholder(viewer, target)StringRelational 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.
saveStats(PlayerStats stats) CompletableFuture<Void> Saves modifications back to the SQLite or MySQL database pools.
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 Gets an available arena for a kit without claiming, or null.
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)PartyCreates a party with the player as owner.
disbandParty(Party)voidDisbands a party.
invitePlayer(sender, target)voidSends a party invite.
acceptInvite(Player)voidAccepts a pending party invite.
denyInvite(Player)voidDenies a pending party invite.
joinPublicParty(player, targetOwner)voidJoins a public party by leader name.
leaveParty(Player)voidRemoves the player from their party.
kickPlayer(owner, target)voidKicks a member (leader only).
setPublic(Player, boolean)voidToggles public/private join mode.
setPartyMode(Player, PartyMode)voidSets queue/split/ffa/duel party behavior.
setMemberLimit(Player, int)voidSets a custom member cap.
cyclePlayMode(Player)voidCycles the party play mode.
toggleChat(Player)voidToggles party-only chat for the player.
isInParty(Player)booleanWhether the player is in a party.
getParty(Player)PartyActive party for the player, or null.
getPartyByMember(UUID)PartyParty containing the UUID, or null.
getPartyById(UUID)PartyParty by party UUID, or null.
getAllParties()Collection<Party>All active parties.
getPublicParties()List<Party>Parties with public join enabled.
getMaxPartySize(Party)intEffective max size for a party.
getMaxPartySize(Player)intMax size the player could create based on permissions.
hasPendingInvite(Player)booleanWhether the player has an unhandled party invite.
handlePlayerDisconnect(Player)voidCleans 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()intConfigured friend list cap.
getFriendUuids(UUID)Set<UUID>Friend UUIDs for a player.
getStatus(UUID)FriendStatusOnline/offline status aggregate.
isNotificationsEnabled(UUID)booleanWhether friend notifications are on.
areFriends(UUID, UUID)booleanWhether two players are friends.
hasIncomingRequest(receiver, sender)booleanPending 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)voidEvicts cached friend data.
sendRequest(sender, target)SendResultSends a friend request (enum result).
acceptRequest(receiver, sender)AcceptResultAccepts a friend request.
denyRequest(receiver, sender)voidDenies a friend request.
removeFriend(playerId, targetId)voidRemoves a friend.

QueueService

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

Key MethodsDescription
addPlayer(player, kit, mode)voidAdds a player to a kit queue.
joinRandomQueue(player, mode)voidQueues for a random needed kit.
removePlayer(player)voidRemoves a player from all queues.
removeKitFromQueue(player, key)voidRemoves one specific queue entry.
addParty(party, kit, mode)voidQueues an entire party together.
removeParty(party)voidRemoves a party from all queues.
isQueued(player)booleanWhether the player is in any queue.
isActivelyQueued(player)booleanWhether the player is waiting for a match (not in-game).
isQueuedForKit(player/uuid, kitName, mode)booleanQueued for a specific kit+mode.
isPrimaryQueuedKit(player/uuid, kitName, mode)booleanWhether this is the player's primary queue slot.
getPlayerQueueKey(player)QueueKeyPrimary queue key, or null.
getPrimaryQueueKey(uuid)QueueKeyPrimary queue key by UUID.
getPlayerQueueKeys(player)List<QueueKey>All active queue keys (multi-kit).
getPlayerQueueCount(player)intNumber of kits queued.
getQueueSize(kitName, mode)intPlayers waiting in a queue.
getInGameSize(kitName, mode)intPlayers currently in matches from that queue.
resolveQueueRounds(kit)intEffective round count for queue matches.
isMultipleKitsEnabled()booleanWhether multi-kit queueing is on.
pickRandomNeededKit(mode)KitKit most needed for matchmaking, or null.
resetPlayerState(player)voidClears queue UI/state for a player.
handlePlayerDisconnect(player)voidRemoves player from queues on quit.

FFAService

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

Key MethodsDescription
joinFFA(player, arena)voidTeleports a player into an FFA arena.
leaveFFA(player)voidRemoves a player from FFA.
handleDeath(player)voidProcesses FFA death (respawn/kill regen).
getPlayerState(player)FFAStateNONE, IN_ARENA, etc.
getPlayerArena(player)ArenaArena the player is in, or null.
getPlayerKit(player)KitKit assigned in FFA, or null.
isInArena(player, arena)booleanWhether the player is in the given arena.
getPlayersInArena(arena)List<Player>All players in an FFA arena.
getPlayerCount(arena)intPlayer count in an arena.
getResetIntervalSeconds()longConfigured FFA reset interval.
getSecondsUntilReset(arena)longSeconds until the next scheduled reset.
resetArena(arena)voidTriggers an FFA map reset.
getLobbyLocation()LocationLobby spawn location.
teleportToLobby(player)CompletableFuture<Boolean>Async-safe lobby teleport.

SpectatorService

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

Key MethodsDescription
joinSpectate(spectator, target)voidStarts spectating a player's duel.
leaveSpectate(spectator)voidStops spectating.
endSpectateForDuel(duel)voidEnds all spectators when a duel ends.
redirectSpectatorsFrom(deadPlayer, duel)voidRedirects spectators after a player dies.
isSpectating(player)booleanWhether the player is spectating.
getDuel(spectator)DuelDuel being spectated, or null.
getSpectatingArena(spectator)ArenaArena being spectated, or null.
getSpectatorsOfDuel(duel)List<UUID>Spectator UUIDs for a duel.
getSpectatorCount(duel)intNumber 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 MethodsDescription
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 MethodsDescription
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 MethodsDescription
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 MethodsDescription
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 MethodsDescription
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

MethodReturnsDescription
getSettings(UUID)PlayerSettingsCached settings for a player.
loadPlayer(Player)CompletableFuture<PlayerSettings>Async load from database.
saveSettings(PlayerSettings)voidPersists settings changes.
unloadPlayer(UUID)voidFlushes and evicts cached settings.

PlaceholderService

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

MethodReturnsDescription
getCurrentMode(Player)StringCurrent game mode label (lobby, duel, queue, etc.).
isInFight(Player)booleanWhether the player is in any active fight.
isFFA(Player)booleanWhether the player is in FFA.
isInParty(Player)booleanWhether the player is in a party.
isEditor(Player)booleanWhether the player has an open kit editor session.
doPlaceholders(Player, text)StringResolves internal placeholders in a string.
getKitDisplayName(Player)StringCurrent kit display name.
getQueueKitDisplayName(Player)StringPrimary queued kit name.
getQueueModeDisplay(Player)StringQueue mode label (1v1, 2v2, etc.).
getQueueWaitTime(Player)StringFormatted queue wait duration.
getQueueKitsList(Player)StringComma-separated queued kit names.
getQueueElapsedSeconds(UUID)longSeconds spent in queue.
invalidatePlayer(Player)voidClears cached placeholder state.

CommandService

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

MethodReturnsDescription
rootCommand(message)StringParses the root command from a chat line.
evaluateBlock(player, rootCommand)StringMessages.yml block key if blocked, else null.
isAllowed(rootCommand)booleanAlways-allowed command list.
isBlockedInParty(rootCommand)booleanBlocked while in a party lobby.
isBlockedInMatchGlobal(rootCommand)booleanBlocked during any match.
shouldBlockInDuel(rootCommand)booleanBlocked during duels.
shouldBlockInFfa(rootCommand)booleanBlocked during FFA.
shouldBlockInSpectate(rootCommand)booleanBlocked while spectating.
reload()voidReloads rules from config.

Optional Services

Available when the corresponding module is enabled:

CustomKitsService

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

Key MethodsDescription
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 MethodsDescription
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.

TournamentService

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

Method SignatureReturnsDescription
hasActiveTournament()booleanTrue if a tournament registration or match phase is in progress.
getCurrentTournament()TournamentReturns current active tournament session or null.
createAndStartRegistration(String kitName, CommandSender starter)booleanStarts registration for a new tournament.
joinTournament(Player)booleanAdds player to the active registration.
leaveTournament(Player)booleanRemoves player from the active registration.
isInTournament(Player)booleanTrue if player is participating in the current tournament.
cancelTournament(String reason)voidCancels active tournament.