# API

### Usage

To get started using our API, import our library via either Gradle or Maven. Found at [https://maven.halosdev.com](https://maven.halosdev.com/#/) .<br>

### Implement Repository

Add the Maven repository to your Gradle or Maven project. Check out [ https://maven.halosdev.com/#/releases](< https://maven.halosdev.com/#/releases>)

#### Maven

```xml
<repository>
  <id>halosdev-releases</id>
  <name>HalosDev Repository</name>
  <url>https://maven.halosdev.com/releases</url>
</repository>
```

#### Gradle Groovy

```groovy
maven {
    name "halosdevReleases"
    url "https://maven.halosdev.com/releases"

```

#### Gradle Kotlin

```kotlin
maven {
    name = "halosdevReleases"
    url = uri("https://maven.halosdev.com/releases")
}
```

### Declare Dependencies

Declare the dependencies, Check out <https://maven.halosdev.com/#/releases/com/halosdev/spoofer/api-spigot>

#### Maven

```xml
<dependency>
  <groupId>com.halosdev.spoofer</groupId>
  <artifactId>api-spigot</artifactId>
  <version>3.2.5</version>
</dependency>
```

#### Gradle Groovy

```groovy
implementation "com.halosdev.spoofer:api-spigot:3.2.5"
```

#### Gradle Kotlin

```kotlin
implementation("com.halosdev.spoofer:api-spigot:3.2.5")
```

### FakePlayer Global Event

You can get the instance of a fake player from all platform.

<pre class="language-java"><code class="lang-java">import com.halos.spoofer.shared.core.player.FakePlayer;
import com.halos.spoofer.shared.core.account.type.UsernameAccount;
import com.halos.spoofer.shared.core.account.type.UUIDAccount;
import java.util.UUID;
import com.halos.spoofer.shared.core.profile.Profile;

var player = (FakePlayer) null;

player.account(); // can be null; either a UsernameAccount or UUIDAccount
<strong>String name = player.profile().name(); // name of fake player
</strong>UUID uniqueId = player.profile().uniqueId(); // uuid of fake player
Profile.Texture = texture = player.profile().texture(); // skin texture of fake player
long joinedAt = player.joinedAt(); // join time stamp
long expiresAt = player.expiresAt(); // when the player will leave the server
boolean chatter = player.chatter(); // if the player can chat
FakePlayerMetadata metadata = player.metadata(); // metadata for fake player

// use metadata to store different values
// caution: metadata will be saved. For example the Vote &#x26; Rank Module utilizes this.
// so clear keys on the destroy event to prevent many files

boolean createdByFluctuation = metadata.has(MetadataKey.FLUCTUATION); // check if player is created by fluctuation

metadata.put("rank", "default"); // store a property
metadata.getOrDefault("rank", "default") // retrieve a property
</code></pre>

### Spigot Events

We provide several events, that are called when a fake player is created on the current server

```java
import com.halos.spoofer.api.spigot.event.FakePlayerCreatedEvent;
import com.halos.spoofer.api.spigot.event.FakePlayerDestroyEvent;
import com.halos.spoofer.api.spigot.event.FakePlayerLoginEvent;

// This event is called after a fake player is created & joined the server.
var playerCreatedEvent = (FakePlayerCreatedEvent) null;
// This event is called before a fake player gets destroyed.
var playerDestroyEvent = (FakePlayerDestroyEvent) null;
// This event is called before a fake player logs in.
var playerLoginEvent = (FakePlayerLoginEvent) null;

playerCreatedEvent.fakePlayer(); // get the fake player
playerCreatedEvent.player(); // get the bukkit player

playerDestroyEvent.fakePlayer(); // get the fake player
playerDestroyEvent.player(); // get the bukkit player

playerLoginEvent.fakePlayer(); // get the fake player

```

```java
import com.halos.spoofer.api.spigot.SpigotSpooferAPI;
import com.halos.spoofer.shared.core.player.FakePlayer;

var api = SpigotSpooferAPI.get(); // access the spigot spoofer api

api.isFakePlayer("username");
api.isFakePlayer(UUID.randomUUID());
api.isFakePlayer(Bukkit.getPlayer("username"));

// careful: all find methods return optionals with FakePlayer
FakePlayer fakePlayer = api.find("username").orElseThrow();
FakePlayer fakePlayer = api.find(UUID.randomUUID().orElseThrow());
FakePlayer fakePlayer = api.find(Bukkit.getPlayer("username").orElseThrow());

CompletableFuture<FakePlayer> future = api.createFakePlayer(new Profile("username", UUID.randomUUID(), new Profile.Texture("value", "signature")));
CompletableFuture<FakePlayer> future = api.createFakePlayer(new UsernameAccount("rexlManu")); // this fetches the profile from a profile fetcher type
CompletableFuture<FakePlayer> future = api.createFakePlayer(new UUIDAccount(UUID.randomUUID())); // this fetches the profile from a profile fetcher type

// future will fail with a FakePlayerNotFoundException if player can't be found
CompletableFuture<Void> future = api.removeFakePlayer(UUID.randomUUID());
CompletableFuture<Void> future = api.removeFakePlayer("username");
CompletableFuture<Void> future = api.removeFakePlayer(Bukkit.getPlayer("username"));
CompletableFuture<Void> future = api.removeFakePlayer(fakePlayer);
```

### BungeeCord / Velocity Events

Both platforms provide a similar api like spigot with the exception of creating / removing fake players. When creating a fake player on spigot, the fake player will also be created on the proxy.

<pre class="language-java"><code class="lang-java"><strong>import com.halos.spoofer.api.bungee.event.FakePlayerCreatedEvent;
</strong>import com.halos.spoofer.api.bungee.event.FakePlayerDestroyEvent;
import com.halos.spoofer.api.velocity.event.FakePlayerCreatedEvent;
import com.halos.spoofer.api.velocity.event.FakePlayerDestroyEvent;

// all events give access to fakePlayer via FakePlayerEvent#fakePlayer() 
// and FakePlayerCreatedEvent#player() for velocity
// or proxied player instance on bungeecord

import com.halos.spoofer.api.velocity.VelocitySpooferAPI;
import com.halos.spoofer.api.bungee.BungeeSpooferAPI;

// both apis are called similar like the spigot variant exempt the creation / removing methods.
// the native platforms give access to get fake players by ProxiedPlayer or Player from velocity

</code></pre>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://wiki.halosdev.com/halos-player-spoofer/api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.