API Reference

1. ShardsAPI

The ShardsAPI interface is the central entry point for accessing all other API managers and systems.

Usage

All methods in this class are static, meaning you can call them directly without needing an instance of the class.

import com.zeltuv.shards.api.ShardsAPI;
import com.zeltuv.shards.api.AFKManagerAPI;

// Get the AFK Manager instance
AFKManagerAPI afkManager = ShardsAPI.getAfkManager();

Methods

Method	Return Type	Description
getUserMap()	Map<UUID, OfflineUserAPI>	Gets an unmodifiable map of all loaded users.
getLeaderboardManager()	LeaderboardAPI	Gets the leaderboard manager instance.
getAfkManager()	AFKManagerAPI	Gets the AFK manager instance.
getCategoryLoader()	CategoryLoaderAPI	Gets the shop system (category loader) instance.
getGenMultiplayer()	GenMultiplayerAPI	Gets the generation multiplayer bonus system.
getKillMultiplayer()	KillMultiplayerAPI	Gets the kill multiplayer bonus system.

2. OfflineUserAPI

This interface provides methods for accessing and modifying a player's data, primarily their shard balance. It can be used for both online and offline players, as long as their data is loaded.

Usage

First, retrieve the OfflineUserAPI object for a specific player from the user map.

import com.zeltuv.shards.api.ShardsAPI;
import com.zeltuv.shards.api.OfflineUserAPI;
import org.bukkit.entity.Player;

Player player = /* get player object */;
OfflineUserAPI user = ShardsAPI.getUserMap().get(player.getUniqueId());

if (user != null) {
    // Add 100 shards to the player's balance
    user.addShards(100);
}

Methods

Method	Return Type	Description
getUuid()	UUID	Gets the player's unique identifier.
getLastUsername()	String	Gets the player's last known username.
getShards()	long	Gets the current shard balance.
setShards(long)	void	Sets the shard balance to a specific value.
addShard()	void	Adds a single shard to the balance.
addShards(long)	void	Adds a specified amount of shards.
takeShard(long)	void	Removes a specified amount of shards.

3. CategoryLoaderAPI (Shop System)

This interface allows you to interact with the in-game shard shop. You can open shop menus for players, retrieve category information, and reload the shop configuration.

Usage

import com.zeltuv.shards.api.ShardsAPI;
import org.bukkit.entity.Player;

Player player = /* get player object */;

// Opens the main shop menu on the first page (page 0)
ShardsAPI.getCategoryLoader().openMainMenu(player, 0);

Methods

Method	Return Type	Description
getCategory(String)	CategoryHolder	Gets a specific shop category by its ID.
getAvailableCategories()	Map<String, CategoryHolder>	Gets a map of all available shop categories.
getMainMenu()	CategoryHolder	Gets the main menu category holder.
openMainMenu(Player, int)	void	Opens the main shop menu for a player at a specific page.
reloadAll()	void	Reloads all shop configurations and categories.
isMultiCategory()	boolean	Checks if the shop is configured to use multiple categories.
isCloseGuiOnPurchase()	boolean	Checks if the shop GUI is configured to close after a purchase.
getMainCategory()	String	Gets the name of the main category if multi-category is disabled.

4. AFKManagerAPI

Use this interface to manage the Away-From-Keyboard system, including teleporting players and checking their status.

Usage

import com.zeltuv.shards.api.ShardsAPI;
import org.bukkit.entity.Player;

Player player = /* get player object */;

// Start the AFK teleport countdown for the player
ShardsAPI.getAfkManager().teleportToAFK(player);

Methods

Method	Return Type	Description
setAFKLocation(Location)	void	Sets the location where players are teleported when they go AFK.
teleportToAFK(Player)	void	Starts the teleportation countdown for a player to the AFK location.
cancelAFKTeleport(Player)	void	Cancels a player's ongoing AFK teleport countdown.
hasMovedSignificantly(Player)	boolean	Checks if a player has moved too far from their initial position.

5. Shard Multipliers

These APIs handle permission-based shard bonuses that players can receive for performing certain in-game actions.

GenMultiplayerAPI (Generation)

Manages shard bonuses from generators or similar sources.

Example: Getting a Player's Generation Bonus

import com.zeltuv.shards.api.ShardsAPI;
import org.bukkit.entity.Player;

Player player = /* get player object */;
long bonus = ShardsAPI.getGenMultiplayer().getGenShards(player);
System.out.println(player.getName() + "'s generation bonus is " + bonus + " shards.");

Method	Return Type	Description
getGenMultiplayer()	HashMap<String, Long>	Gets a map of permission nodes to their shard bonus amounts.
hasGenMultiplayerPerm(Player)	boolean	Checks if a player has any generation multiplayer permission.
getGenShards(Player)	long	Gets the highest generation shard bonus a player is entitled to.

KillMultiplayerAPI (Player Kills)

Manages shard bonuses for killing other players.

Example: Getting a Player's Kill Bonus

import com.zeltuv.shards.api.ShardsAPI;
import org.bukkit.entity.Player;

Player player = /* get player object */;
long bonus = ShardsAPI.getKillMultiplayer().getKillShards(player);
System.out.println(player.getName() + "'s kill bonus is " + bonus + " shards.");

Method	Return Type	Description
getKillMultiplayer()	HashMap<String, Long>	Gets a map of permission nodes to their shard bonus amounts.
isPreventAbuse()	boolean	Checks if the anti-farming/abuse system for kill rewards is enabled.
getKillShards(Player)	long	Gets the highest kill shard bonus a player is entitled to.

6. LeaderboardAPI

The LeaderboardAPI interface is included for future expansion but does not currently expose any methods for public use.