> For the complete documentation index, see [llms.txt](https://mending-dev.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mending-dev.gitbook.io/docs/bossbarhud/developer-guide/getting-started.md).

# Getting started

Add the BossbarHUD API to your plugin project.

The API contains only interfaces. The implementation is the BossbarHUD plugin on the server, so your plugin needs the API at compile time only.

## Repository and coordinates

|             |                                        |
| ----------- | -------------------------------------- |
| Group       | `dev.mending.bossbarhud`               |
| Artifact    | `api`                                  |
| Coordinates | `dev.mending.bossbarhud:api:<version>` |
| Releases    | `https://repo.mending.dev/releases`    |
| Snapshots   | `https://repo.mending.dev/snapshots`   |

## Which version do I use?

| You want                     | Version                                                           | Repository |
| ---------------------------- | ----------------------------------------------------------------- | ---------- |
| A stable release             | the tag without the `v`, for example `1.0.0` for the tag `v1.0.0` | releases   |
| The latest development build | the snapshot version, for example `1.0.0-SNAPSHOT`                | snapshots  |

A release version never changes. A snapshot version is overwritten with every push to `main` or `develop`.

## Add the dependency

Choose your build tool. The examples show a release and a snapshot.

<details>

<summary>Maven</summary>

**Release**

```xml
<repositories>
    <repository>
        <id>mending-releases</id>
        <url>https://repo.mending.dev/releases</url>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>dev.mending.bossbarhud</groupId>
        <artifactId>api</artifactId>
        <version>1.0.0</version>
        <scope>provided</scope>
    </dependency>
</dependencies>
```

**Snapshot**

```xml
<repositories>
    <repository>
        <id>mending-snapshots</id>
        <url>https://repo.mending.dev/snapshots</url>
        <releases>
            <enabled>false</enabled>
        </releases>
        <snapshots>
            <enabled>true</enabled>
            <updatePolicy>always</updatePolicy>
        </snapshots>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>dev.mending.bossbarhud</groupId>
        <artifactId>api</artifactId>
        <version>1.0.0-SNAPSHOT</version>
        <scope>provided</scope>
    </dependency>
</dependencies>
```

</details>

<details>

<summary>Gradle (Groovy)</summary>

**Release**

```groovy
repositories {
    maven {
        url = uri("https://repo.mending.dev/releases")
        mavenContent { releasesOnly() }
        content { includeGroup("dev.mending.bossbarhud") }
    }
}

dependencies {
    compileOnly "dev.mending.bossbarhud:api:1.0.0"
}
```

**Snapshot**

```groovy
repositories {
    maven {
        url = uri("https://repo.mending.dev/snapshots")
        mavenContent { snapshotsOnly() }
        content { includeGroup("dev.mending.bossbarhud") }
    }
}

// Gradle caches snapshots for 24 hours by default
configurations.all {
    resolutionStrategy.cacheChangingModulesFor 0, "seconds"
}

dependencies {
    compileOnly "dev.mending.bossbarhud:api:1.0.0-SNAPSHOT"
}
```

</details>

<details>

<summary>Gradle (Kotlin)</summary>

**Release**

```kotlin
repositories {
    maven("https://repo.mending.dev/releases") {
        mavenContent { releasesOnly() }
        content { includeGroup("dev.mending.bossbarhud") }
    }
}

dependencies {
    compileOnly("dev.mending.bossbarhud:api:1.0.0")
}
```

**Snapshot**

```kotlin
repositories {
    maven("https://repo.mending.dev/snapshots") {
        mavenContent { snapshotsOnly() }
        content { includeGroup("dev.mending.bossbarhud") }
    }
}

// Gradle caches snapshots for 24 hours by default
configurations.all {
    resolutionStrategy.cacheChangingModulesFor(0, "seconds")
}

dependencies {
    compileOnly("dev.mending.bossbarhud:api:1.0.0-SNAPSHOT")
}
```

**Version catalog (optional)**

`gradle/libs.versions.toml`:

```toml
[versions]
bossbarhud = "1.0.0"

[libraries]
bossbarhud-api = { module = "dev.mending.bossbarhud:api", version.ref = "bossbarhud" }
```

`build.gradle.kts`:

```kotlin
dependencies {
    compileOnly(libs.bossbarhud.api)
}
```

</details>

{% hint style="warning" %}
Use `compileOnly` (Gradle) or `provided` (Maven). Never shade the API into your plugin.
{% endhint %}

## Update to a new version

* **Release:** change the version number, then reload the Gradle or Maven project in your IDE.
* **Snapshot:** run `./gradlew build --refresh-dependencies` to fetch the newest build.

## Declare the plugin dependency

Your plugin needs BossbarHUD on the server and must load after it.

{% code title="paper-plugin.yml" %}

```yaml
dependencies:
  server:
    BossbarHUD:
      load: BEFORE
      required: true
      join-classpath: true
```

{% endcode %}

{% code title="plugin.yml" %}

```yaml
depend: [BossbarHUD]
```

{% endcode %}

## Your first HUD

```java
HudAPI api = HudAPI.get();

Hud hud = api.createHud(plugin, "welcome")
        .segment("greeting", 0, Component.text("Welcome to the server!"))
        .build();

hud.show(player);
```

`HudAPI.get()` throws an `IllegalStateException` if BossbarHUD is not enabled.

{% content-ref url="/pages/Qjxkc9WUrVjmg6XhiC9r" %}
[Using the API](/docs/bossbarhud/developer-guide/using-the-api.md)
{% endcontent-ref %}