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:

Manager	Method	Description
Settings	api.getSettingsRegistry()	Register custom settings and GUI items
Feature Toggles	api.isFeatureEnabled("chat")	Check if a module is enabled in config.yml
Combat	api.getCombatManager()	Check combat tag status and PVP restrictions
Fly / TempFly	api.getFlyManager()	Manage flight states and temporary flight duration
Staff & Vanish	api.getStaffManager()	Check vanish status, staff modes, auto-vanish
Teleportation	api.getTpaManager() / getHomesManager()	Manage teleport requests and homes
Cosmetics	api.getTagsManager() / getChatColorManager()	Query player cosmetics, prefixes, and colors
Database	api.getDatabaseManager()	Reuse centralized database pool connection
Redis	api.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);
    }
}