Skip to main content

BharatCore Developer API

BharatCoreAPI is the open gateway allowing any external or custom server plugin (BMCAuction, AxTrade, AuraSkills, custom minigames, etc.) to integrate with BharatCore's persistent infrastructure, player profiles, settings menu, cross-server currency, and gameplay managers.

1. Setup & Dependency​

Add BharatCore as a dependency in your plugin's plugin.yml or paper-plugin.yml:

name: MyCustomPlugin
version: 1.0.0
main: com.example.myplugin.MyPlugin
api-version: '1.21'
depend:
  - bharatcore # Ensures BharatCore loads before your plugin

Accessing the API Gateway​

In your Java code, access the singleton instance:

import com.sryel.bharatcore.api.BharatCoreAPI;

BharatCoreAPI api = BharatCoreAPI.getInstance();

2. Dynamic Settings API (Custom Plugin Settings in /settings)​

You can dynamically inject custom toggles, preference buttons, or shortcut icons into the /settings GUI directly via code without modifying configuration files.

A. Registering a Custom Toggle Setting​

import com.sryel.bharatcore.api.BharatCoreAPI;
import com.sryel.bharatcore.api.SettingItem;
import org.bukkit.Material;

public void onEnable() {
    // Register custom trade requests toggle
    SettingItem tradeToggle = SettingItem.builder("trade_requests", "MyCustomPlugin")
        .slot(20)                                           // GUI Slot index
        .material(Material.EMERALD)                        // Display item
        .displayName("<#7AFB00><bold>Trade Requests")       // Item name
        .lore(
            "<gray>Toggle incoming trade requests from players.",
            "",
            "<gray>Status: {status}",
            "",
            "<yellow>» Click to toggle!"
        )
        .statusEnabled("<green>ENABLED")
        .statusDisabled("<red>DISABLED")
        .defaultValue(true)                                 // Default state for new players
        .metaKey("custom_trade_enabled")                    // Persistent metadata key in DB
        .onClick(player -> {
            player.sendMessage("You updated your trade preferences!");
        });

    BharatCoreAPI.getInstance().registerSetting(tradeToggle);
}

B. Checking a Player's Setting State​

From anywhere in your plugin, check the current preference of a player:

UUID playerUuid = player.getUniqueId();

// Returns true if enabled, false if disabled, falling back to defaultValue
boolean tradesEnabled = BharatCoreAPI.getInstance().getPlayerSetting(playerUuid, "trade_requests", true);

if (!tradesEnabled) {
    player.sendMessage("This player has disabled trade requests in /settings!");
    return;
}

C. Updating a Player's Setting Programmatically​

BharatCoreAPI.getInstance().setPlayerSetting(playerUuid, "trade_requests", false);

D. Cleaning Up On Plugin Disable​

@Override
public void onDisable() {
    BharatCoreAPI.getInstance().getSettingsRegistry().unregisterAllByPlugin("MyCustomPlugin");
}

3. Player Profiles & Persistent Metadata API​

BharatCore provides a persistent metadata store backed by centralized PostgreSQL/H2 database and Redis cache. Plugins can store arbitrary strings, flags, and states without creating custom database tables.

// Store persistent metadata (survives reloads and cross-server transfers)
api.setPlayerMetadata(uuid, "guild_tag", "VIKINGS");
api.setPlayerMetadata(uuid, "last_bounty", "5000");

// Retrieve persistent metadata
String guildTag = api.getPlayerMetadata(uuid, "guild_tag");

4. Economy & Shards API​

Access player balances and premium shard balances safely:

// Vault Economy Balance
double balance = api.getBalance(uuid);
api.setBalance(uuid, balance + 500.0);

// Network Shards Economy
long shards = api.getShards(uuid);
api.addShards(uuid, 50L);

5. Subsystem & Manager Access​

BharatCoreAPI exposes direct access to core managers:

ManagerMethodDescription
Settingsapi.getSettingsRegistry()Register custom settings and GUI items
Feature Togglesapi.isFeatureEnabled("chat")Check if a module is enabled in config.yml
Combatapi.getCombatManager()Check combat tag status and PVP restrictions
Fly / TempFlyapi.getFlyManager()Manage flight states and temporary flight duration
Staff & Vanishapi.getStaffManager()Check vanish status, staff modes, auto-vanish
Teleportationapi.getTpaManager() / getHomesManager()Manage teleport requests and homes
Cosmeticsapi.getTagsManager() / getChatColorManager()Query player cosmetics, prefixes, and colors
Databaseapi.getDatabaseManager()Reuse centralized database pool connection
Redisapi.getRedisManager()Publish and subscribe to cross-server messages

6. Example: Complete Third-Party Integration​

package com.example.spawnerboost;

import com.sryel.bharatcore.api.BharatCoreAPI;
import com.sryel.bharatcore.api.SettingItem;
import org.bukkit.Material;
import org.bukkit.entity.Player;
import org.bukkit.plugin.java.JavaPlugin;

public class SpawnerBoostPlugin extends JavaPlugin {

    @Override
    public void onEnable() {
        if (getServer().getPluginManager().isPluginEnabled("bharatcore")) {
            BharatCoreAPI.getInstance().registerSetting(
                SettingItem.builder("spawner_alerts", "SpawnerBoost")
                    .slot(21)
                    .material(Material.SPAWNER)
                    .displayName("<#22DEFF><bold>Spawner Notifications")
                    .lore(
                        "<gray>Receive alerts when your spawners upgrade.",
                        "",
                        "<gray>Status: {status}",
                        "",
                        "<yellow>» Click to toggle!"
                    )
                    .defaultValue(true)
                    .metaKey("spawner_alerts_on")
                    .build()
            );
        }
    }

    public boolean canSendAlert(Player player) {
        return BharatCoreAPI.getInstance().getPlayerSetting(player.getUniqueId(), "spawner_alerts", true);
    }
}