# API Reference

# API Reference

KS Nameplates provides a public API for cross-mod integration via `NameplatesAPI`.

## Availability Check

```java
if (NameplatesAPI.isAvailable()) {
    NameplatesAPI api = NameplatesAPI.getInstance();
    // Use API
}
```

## Tag Management

### Get Tags

```java
// Get a specific tag by ID
Tag tag = api.getTag("vip");

// Get all tags
Collection<Tag> allTags = api.getAllTags();

// Get a group
TagGroup group = api.getGroup("ranks");

// Get all groups
Collection<TagGroup> allGroups = api.getAllGroups();
```

### Player Tags

```java
UUID playerUuid = player.getUuid();

// Activate a tag for a player
api.activateTag(playerUuid, "vip");

// Deactivate a tag
api.deactivateTag(playerUuid, "vip");

// Clear all tags
api.clearTags(playerUuid);

// Get active tag IDs
Set<String> active = api.getActiveTags(playerUuid);

// Get active tags sorted by priority
List<Tag> sorted = api.getActiveTagsSorted(playerUuid);
```

### Nameplate Text

```java
// Get the formatted nameplate text for a player
String text = api.getNameplateText(playerUuid, "PlayerName");
// Returns e.g., "[VIP] [Builder] PlayerName"
```

### Admin Operations

```java
// Create or update a tag
Tag newTag = new Tag("event_2026", "[Event]", "#FF44FF", "nameplates.tag.event", "events", TagType.PREFIX, 50, false);
api.addTag(newTag);

// Remove a tag
api.removeTag("event_2026");

// Manage groups
api.addGroup(new TagGroup("events", "Event Tags", 5, false));
api.removeGroup("events");

// Refresh all nameplates
api.refreshAll();
```

## Tag Data Model

```java
public class Tag {
    String id;              // Unique identifier
    String displayText;     // Display text (e.g., "[VIP]")
    String chatColor;       // Hex color (e.g., "#FFD700")
    String permission;      // Permission node (null = no restriction)
    String groupId;         // Group ID
    TagType type;           // PREFIX, SUFFIX, or ABOVE
    int priority;           // Sort order (lower = first)
    boolean defaultActive;  // Auto-activate on permission
    String imagePath;       // PNG path for image tags (optional)
}
```