Skip to content

GETTING_STARTED.md

Latest commit

 

History

History
148 lines (115 loc) · 3.38 KB

GETTING_STARTED.md

File metadata and controls

148 lines (115 loc) · 3.38 KB
Raw

Getting Started with LocatorBarAPI

LocatorBarAPI can be integrated into your server setup using one of two approaches:

  1. As a Standalone Plugin: Drop the jar in your server plugins/ directory and compile your plugin against it.
  2. As a Shaded Library: Bundle the API directly inside your own plugin jar without requiring users to install an extra plugin.

1. Standalone Plugin Setup

Server Installation

  1. Download or build LocatorBarAPI-1.0.0.jar.
  2. Place LocatorBarAPI-1.0.0.jar into your Paper server's plugins/ folder.
  3. Start or reload the server. LocatorBarAPI will automatically enable the locatorBar gamerule across all worlds.

Plugin Dependency Configuration

paper-plugin.yml

If your plugin uses Paper's modern plugin loader:

name: MyCustomPlugin
version: 1.0.0
main: com.example.plugin.MyCustomPlugin
api-version: '1.21'
dependencies:
  server:
    LocatorBarAPI:
      load: BEFORE
      required: true

plugin.yml (Spigot / Legacy Paper)

name: MyCustomPlugin
version: 1.0.0
main: com.example.plugin.MyCustomPlugin
api-version: '1.21'
depend: [LocatorBarAPI]

Gradle (Kotlin DSL)

repositories {
    mavenCentral()
    maven("https://jitpack.io")
}

dependencies {
    compileOnly("com.github.mukulx:LocatorBarAPI:v1.0.0")
}

Maven

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>com.github.mukulx</groupId>
        <artifactId>LocatorBarAPI</artifactId>
        <version>v1.0.0</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

2. Shaded Library Setup

If you want your plugin to be self-contained as a single jar without requiring server administrators to install a separate API plugin:

Gradle (Kotlin DSL) with Shadow Plugin

plugins {
    `java-library`
    id("com.gradleup.shadow") version "8.3.5"
}

repositories {
    mavenCentral()
    maven("https://jitpack.io")
}

dependencies {
    implementation("com.github.mukulx:LocatorBarAPI:v1.0.0")
}

tasks.shadowJar {
    relocate("dev.mukulx.locatorbarapi", "com.example.plugin.libs.locatorbarapi")
}

Initializing in JavaPlugin

When shaded, call LocatorBarAPI.init(this) inside your plugin's onEnable() method and LocatorBarAPI.shutdown() in onDisable():

package com.example.plugin;

import dev.mukulx.locatorbarapi.LocatorBarAPI;
import org.bukkit.plugin.java.JavaPlugin;

public final class MyCustomPlugin extends JavaPlugin {

    @Override
    public void onEnable() {
        // Initialize the LocatorBarAPI system
        LocatorBarAPI.init(this);

        if (!LocatorBarAPI.isAvailable()) {
            getLogger().warning("LocatorBarAPI could not bind to NMS on this server build.");
            return;
        }

        getLogger().info("LocatorBarAPI initialized successfully.");
    }

    @Override
    public void onDisable() {
        // Stop background tick tasks and release resources
        LocatorBarAPI.shutdown();
    }
}

3. Verifying Installation

To check if LocatorBarAPI is functional at runtime:

if (LocatorBarAPI.isAvailable()) {
    // Safe to use LocatorBarAPI methods
}

You can also check if the world gamerule is enabled for a given player:

boolean enabled = LocatorBarAPI.isLocatorBarEnabled(player);