Developer API Overview

Hook into the ShyamDuels API to fetch stats, listen to match events, manage queues, and start custom duels.

Maven Integration

Build shyamduels-2.0-api.jar with ./gradlew apiJar and compile against that small public artifact. Never shade or bundle it inside an add-on; ShyamDuels supplies the API classes at runtime.

gradledependencies {
    compileOnly files("libs/shyamduels-2.0-api.jar")
}

For Maven repositories, publish the API artifact under the following coordinates and keep the dependency scope provided:

xml<dependency>
    <groupId>com.shyamstudio</groupId>
    <artifactId>shyamduels</artifactId>
    <version>2.0</version>
    <scope>provided</scope>
</dependency>

Declaring Soft-Dependencies

To ensure that your plugin enables after ShyamDuels on server startup, declare it in your plugin.yml configuration:

yamlname: MyIntegrationPlugin
version: 1.0
main: com.myname.integration.IntegrationPlugin
api-version: '1.21'
depend: [ShyamDuels]    # Guarantees ShyamDuels enables first

Accessing the API

The public entry point is ShyamDuelsAPI. Bukkit's service registry is preferred; the static provider remains as a compatible convenience accessor:

javaimport com.shyamstudio.shyamduels.api.ShyamDuelsAPI;
import com.shyamstudio.shyamduels.api.ShyamDuelsProvider;
import com.shyamstudio.shyamduels.api.meta.ApiVersion;
import org.bukkit.plugin.java.JavaPlugin;

public class IntegrationPlugin extends JavaPlugin {

    private ShyamDuelsAPI api;

    @Override
    public void onEnable() {
        this.api = getServer().getServicesManager().load(ShyamDuelsAPI.class);
        if (api == null) this.api = ShyamDuelsProvider.get();
        
        if (api == null) {
            getLogger().severe("ShyamDuels was not found! Disabling integration.");
            getServer().getPluginManager().disablePlugin(this);
            return;
        }

        getLogger().info("Successfully hooked into ShyamDuels API!");

        // Fail clearly when an add-on needs a newer incompatible API.
        if (!api.metadata().apiVersion().isCompatibleWith(new ApiVersion(2, 0, 0))) {
            throw new IllegalStateException("Unsupported ShyamDuels API " + api.metadata().apiVersion());
        }
    }
}

Available Services

The ShyamDuelsAPI interface exposes the following service accessors. See Services Reference for method details.

Accessor	Service	Notes
`metadata()`	ApiMetadata	Semantic API version and capability discovery
`players()`	PlayerService	Immutable cross-feature player snapshots
`extensions()`	ExtensionService	Typed, owner-scoped add-on contracts
`duels()`	DuelService	Match lifecycle, invites, party duels
`arenas()`	ArenaService	Arena lookup and availability
`kits()`	KitService	Kit definitions and player layouts
`kitShare()`	KitShareService	Edited-kit sharing codes
`queue()`	QueueService	Ranked matchmaking queues
`commands()`	CommandService	Command restriction helpers
`parties()`	PartyService	Party creation and management
`ffa()`	FFAService	Free-for-all arenas
`spectators()`	SpectatorService	Match spectating
`rematch()`	RematchService	Post-duel rematch offers
`stats()`	StatsService	Player statistics and ELO
`settings()`	SettingsService	Per-player preferences
`tab()`	TabService	Tab list management
`scoreboard()`	ScoreboardService	Scoreboard display
`nameTags()`	NameTagService	Nametag formatting
`animations()`	AnimationService	Tab/scoreboard animations
`friends()`	FriendsService	Friends list
`placeholders()`	PlaceholderService	Internal placeholder resolution
`tournaments()`	TournamentService	Tournament registration and bracket control
`country()`	CountryService	GeoIP detection, flag display and 224-entry registry
`practice()`	PracticeService	Optional: practice module features
`customKits()`	CustomKitsService	Optional: player-built custom kits
`kitEditor()`	KitEditorService	Optional: kit editor / kit room

Services marked Optional return Optional.empty() when their module is disabled in config.yml.