### Get Player Head as Legacy String with Specific Skin Source

Source: https://context7.com/ogminso/chatheadfont/llms.txt

This is a full-control version of getHeadAsString, allowing you to specify the overlay and SkinSource. The example demonstrates fetching a head without an overlay using the Minotar source and sending it as an action bar message.

```java
SkinSource minotar = new MinotarSource();
String headLegacy = ChatHeadAPI.getInstance()
        .getHeadAsString(player, false, minotar);  // no hat overlay, Minotar source

// Send as action bar via legacy string
player.sendMessage(headLegacy + " §aWelcome back!");
```

--------------------------------

### Get ChatHeadAPI Instance

Source: https://context7.com/ogminso/chatheadfont/llms.txt

Retrieve the singleton ChatHeadAPI instance. Ensure initialize() has been called first to avoid an IllegalArgumentException.

```java
// Safely retrieve the API instance inside an event handler
ChatHeadAPI api = ChatHeadAPI.getInstance();
// api is now ready to call getHead(), getHeadAsString(), etc.
```

--------------------------------

### Get Player Head as Adventure Component

Source: https://context7.com/ogminso/chatheadfont/llms.txt

Returns the player's head as a Kyori Adventure Component, suitable for modern Paper/Adventure API pipelines. The example shows creating a full message with the head component and player name, then broadcasting it.

```java
Component headComponent = ChatHeadAPI.getInstance()
        .getHeadAsComponent(player.getUniqueId(), true, ChatHeadAPI.defaultSource);

Component fullMessage = headComponent
        .append(Component.text(" " + player.getName() + " joined!")
                .color(TextColor.color(0xFFFF55)));

// Send using Adventure API (Paper 1.18+)
Bukkit.getServer().broadcast(fullMessage);
```

--------------------------------

### Chat Head Font Plugin Configuration

Source: https://context7.com/ogminso/chatheadfont/llms.txt

Example configuration for the Chat Head Font plugin, showing options for update checks, skin sources, auto-downloading resource packs, enabling/disabling features, and cache lifetime.

```yaml
# config.yml — Chat Head Font (placed in plugins/ChatHeadFont/)

# Check GitHub for new plugin versions on startup
check-for-updates: true

# Skin provider: MOJANG (default) | CRAFATAR | MINOTAR | MCHEADS
skin-source: MOJANG

# Automatically push the resource pack ZIP to connecting players
auto-download-pack: true

# Composite the hat layer over the base face in head icons
enable-skin-overlay: true

# Prepend head icon to join messages
enable-join-messages: true

# Prepend head icon to leave messages
enable-leave-messages: true

# Prepend head icon to chat messages
enable-chat-messages: true

# Prepend head icon to death messages
enable-death-messages: true

# Seconds to delay the join broadcast (allows resource pack to load first)
join-messages-delay-seconds: 3

# How long (seconds) each head stays in the cache before re-fetching
head-cache-entry-lifetime-seconds: 300
```

--------------------------------

### PlaceholderAPI Integration in Chat Format

Source: https://context7.com/ogminso/chatheadfont/llms.txt

Example of using Chat Head Font placeholders within a chat formatter plugin's configuration, such as EssentialsX, to prepend a player's head to their chat messages.

```yaml
# Example usage in a chat formatter plugin (e.g., EssentialsX chat format)
chat:
  format: '{%chathead%} {displayname}: {message}'

# Example in a scoreboard plugin title
scoreboard-title: '%chathead% &f%player_name%'
```

--------------------------------

### Custom SkinSource Implementation

Source: https://context7.com/ogminso/chatheadfont/llms.txt

Implement a custom SkinSource to define your own skin URL logic. This example shows how to build a skin URL based on player UUID and delegate pixel extraction to the parent class.

```java
public class CustomSource extends SkinSource {

    public CustomSource() {
        super(SkinSourceEnum.MOJANG, false, true);
    }

    @Override
    public BaseComponent[] getHead(OfflinePlayer player, boolean overlay) {
        // Build your own skin URL
        String skinUrl = "https://example.com/skins/" + player.getUniqueId() + ".png";

        // Delegate pixel extraction and component assembly to parent helpers
        String[] hexColors = getPixelColorsFromSkin(skinUrl, overlay);
        return toBaseComponent(hexColors);
    }
}
```

--------------------------------

### Retrieving a Player Head

Source: https://github.com/ogminso/chatheadfont/blob/main/README.md

Examples of how to retrieve a player's head using the Chat Head Font API, with and without skin overlay, and as a legacy string.

```APIDOC
### Retrieving a Player Head
The API now uses caching internally. The default skin source is automatically selected from your configuration (`skin-source`), but you can also specify your own source if desired.
#### Examples
```java
// Get a player's head (with skin overlay) as a BaseComponent[] (cached for 5 minutes)
BaseComponent[] headComponents = ChatHeadAPI.getInstance().getHead(player);

// Get a player's head without the overlay:
BaseComponent[] headComponentsNoOverlay = ChatHeadAPI.getInstance().getHead(player, false);

// Get a player's head as a legacy formatted String:
String headString = ChatHeadAPI.getInstance().getHeadAsString(player);
```
***Note: The API caches each player’s head for 5 minutes, reducing the need for repeated asynchronous skin fetches.***
```

--------------------------------

### PlaceholderAPI Chat Head Placeholders

Source: https://context7.com/ogminso/chatheadfont/llms.txt

Examples of PlaceholderAPI placeholders for Chat Head Font. These can be used to display a player's own head or another player's head in PAPI-compatible plugins.

```plaintext
# Use the requesting player's own head
%chathead%
%chathead_self%

# Use another player's head by name
%chathead_other:Notch%
%chathead_other:Herobrine%
```

--------------------------------

### Convert Hex Colors to Chat Components

Source: https://context7.com/ogminso/chatheadfont/llms.txt

Convert an array of hex color strings into chat components for display. This example demonstrates creating a solid red head for testing and displaying it in the action bar.

```java
// Manually supply pixel colors (e.g., from a custom image processor)
String[] pixelColors = new String[64];
Arrays.fill(pixelColors, "#FF5555"); // Solid red 8×8 head for testing

SkinSource source = new MojangSource();
BaseComponent[] redHead = source.toBaseComponent(pixelColors);

player.spigot().sendMessage(ChatMessageType.ACTION_BAR, redHead);
// Output: a solid red 8×8 pixel block in the player's action bar
```

--------------------------------

### Get Player Head by UUID

Source: https://context7.com/ogminso/chatheadfont/llms.txt

Retrieve and display a player's head using their UUID. This is useful for handling offline players or asynchronous contexts where an OfflinePlayer reference is not available. The example demonstrates fetching Notch's head and broadcasting it.

```java
UUID targetUUID = UUID.fromString("069a79f4-44e9-4726-a5be-fca90e38aaf5"); // Notch

Bukkit.getScheduler().runTaskAsynchronously(plugin, () -> {
    BaseComponent[] head = ChatHeadAPI.getInstance().getHead(targetUUID, true);

    // Switch back to main thread to send message
    Bukkit.getScheduler().runTask(plugin, () -> {
        BaseComponent[] msg = new ComponentBuilder()
                .append(head)
                .append(" Notch's head retrieved!", ComponentBuilder.FormatRetention.NONE)
                .create();
        Bukkit.broadcast(TextComponent.toLegacyText(msg), Server.BROADCAST_CHANNEL_USERS);
    });
});
```

--------------------------------

### Get Player Head as Legacy String

Source: https://context7.com/ogminso/chatheadfont/llms.txt

Converts the player's head into a legacy-formatted String with color codes. This is useful for APIs that only accept plain strings, such as BossBar titles or older chat plugins. The example shows using it as a BossBar title upon player join.

```java
@EventHandler
public void onPlayerJoin(PlayerJoinEvent event) {
    Player player = event.getPlayer();

    String headString = ChatHeadAPI.getInstance().getHeadAsString(player);

    // Use legacy string as a BossBar title
    BossBar bar = Bukkit.createBossBar(
            headString + " " + player.getName(),
            BarColor.GREEN,
            BarStyle.SOLID
    );
    bar.setProgress(1.0);
    bar.addPlayer(player);

    // Output: legacy-coloured 8×8 head pixels followed by the player's name
}
```

--------------------------------

### Retrieve Player Head with Overlay

Source: https://github.com/ogminso/chatheadfont/blob/main/README.md

Get a player's head as a BaseComponent array, including the skin overlay. The API caches heads for 5 minutes.

```java
BaseComponent[] headComponents = ChatHeadAPI.getInstance().getHead(player);
```

--------------------------------

### Retrieve Player Head without Overlay

Source: https://github.com/ogminso/chatheadfont/blob/main/README.md

Get a player's head as a BaseComponent array, without the skin overlay. Caching is applied.

```java
BaseComponent[] headComponentsNoOverlay = ChatHeadAPI.getInstance().getHead(player, false);
```

--------------------------------

### Get Player Head as BaseComponent Array

Source: https://context7.com/ogminso/chatheadfont/llms.txt

Retrieves a player's head as a BaseComponent array with the hat overlay applied. Uses HeadCache for efficient retrieval, fetching asynchronously on the first call.

```java
@EventHandler
public void onChat(AsyncPlayerChatEvent event) {
    event.setCancelled(true);
    Player player = event.getPlayer();

    // Get head as BaseComponent array (overlay on, default source)
    BaseComponent[] head = ChatHeadAPI.getInstance().getHead(player);

    // Build "HEAD  PlayerName: message"
    BaseComponent[] message = new ComponentBuilder()
            .append(head)
            .append(" ")
            .append(player.getName() + ": " + event.getMessage(),
                    ComponentBuilder.FormatRetention.NONE)
            .create();

    for (Player p : Bukkit.getOnlinePlayers()) {
        p.spigot().sendMessage(message);
    }
}
```

--------------------------------

### Get Player Head with Specific Skin Source

Source: https://context7.com/ogminso/chatheadfont/llms.txt

Use this overload when you need to force a specific SkinSource for a particular context, such as using Crafatar for offline-mode servers.

```java
SkinSource crafatar = new CrafatarSource();
BaseComponent[] head = ChatHeadAPI.getInstance().getHead(player, true, crafatar);

BaseComponent[] message = new ComponentBuilder()
        .append(head)
        .append(" " + player.getName() + " has joined!", ComponentBuilder.FormatRetention.NONE)
        .create();

Bukkit.broadcast(BaseComponent.toLegacyText(message), "myplugin.chat");
```

--------------------------------

### Get Player Head with Optional Overlay

Source: https://context7.com/ogminso/chatheadfont/llms.txt

Retrieve a player's head, with an option to include or exclude the hat layer. Useful for different display contexts like action bars.

```java
// With overlay (hat layer included)
BaseComponent[] withHat    = ChatHeadAPI.getInstance().getHead(player, true);

// Without overlay (base face only)
BaseComponent[] withoutHat = ChatHeadAPI.getInstance().getHead(player, false);

player.spigot().sendMessage(ChatMessageType.ACTION_BAR, withHat);
```

--------------------------------

### Custom Join/Leave Chat Messages with Player Heads

Source: https://context7.com/ogminso/chatheadfont/llms.txt

Suppresses default join/quit messages and re-broadcasts them with the player's head prepended. This example requires implementing the Listener interface and handling both join and quit events.

```java
public class JoinLeaveChatExample implements Listener {

    @EventHandler
    public void onPlayerJoin(PlayerJoinEvent event) {
        event.setJoinMessage(""); // suppress default
        Player player = event.getPlayer();

        BaseComponent[] head = ChatHeadAPI.getInstance()
                .getHead(player, true, ChatHeadAPI.defaultSource);
        TextComponent msg = new TextComponent(
                ChatColor.YELLOW + " " + player.getName() + " joined the game");

        BaseComponent[] joinMsg = new ComponentBuilder()
                .append(head).append(msg).create();

        for (Player p : Bukkit.getOnlinePlayers()) {
            p.spigot().sendMessage(joinMsg);
        }
    }

    @EventHandler
    public void onPlayerQuit(PlayerQuitEvent event) {
        event.setQuitMessage(""); // suppress default
        Player player = event.getPlayer();

        BaseComponent[] head = ChatHeadAPI.getInstance()
                .getHead(player, true, ChatHeadAPI.defaultSource);
        TextComponent msg = new TextComponent(
                ChatColor.YELLOW + " " + player.getName() + " left the game");

        BaseComponent[] quitMsg = new ComponentBuilder()
                .append(head).append(msg).create();

        for (Player p : Bukkit.getOnlinePlayers()) {
            p.spigot().sendMessage(quitMsg);
        }
    }
}
```

--------------------------------

### Create Boss Bar with Player Head Title

Source: https://context7.com/ogminso/chatheadfont/llms.txt

Creates a BossBar with the player's head as part of the title using the legacy string conversion path. This example demonstrates converting BaseComponent[] to a legacy string suitable for BossBar titles.

```java
public class BossbarExample implements Listener {

    @EventHandler
    public void onPlayerJoin(PlayerJoinEvent event) {
        Player player = event.getPlayer();

        BaseComponent[] head = ChatHeadAPI.getInstance()
                .getHead(player, true, ChatHeadAPI.defaultSource);

        // BossBar API accepts legacy strings, so convert first
        String title = TextComponent.toLegacyText(head);

        BossBar bossBar = Bukkit.createBossBar(
                title,
                BarColor.BLUE,
                BarStyle.SOLID
        );
        bossBar.addPlayer(player);
        // Result: boss bar title shows the coloured 8×8 pixel head
    }
}
```

--------------------------------

### Instantiate and Use Skin Sources

Source: https://context7.com/ogminso/chatheadfont/llms.txt

Demonstrates how to instantiate concrete SkinSource implementations (Mojang, Crafatar, Minotar, McHeads) and pass them to the getHead() method. It also shows how to configure MojangSource for offline-mode servers.

```java
SkinSource mojang   = new MojangSource();
SkinSource crafatar = new CrafatarSource();
SkinSource minotar  = new MinotarSource();
SkinSource mcheads  = new McHeadsSource();

// Offline-mode servers: pass true to use name-based lookup fallback
SkinSource offlineMojang = new MojangSource(/* useUUIDWhenRetrieve= */ false);

BaseComponent[] head = ChatHeadAPI.getInstance().getHead(player, true, crafatar);
```

--------------------------------

### Java API Initialization

Source: https://github.com/ogminso/chatheadfont/blob/main/README.md

How to initialize the Chat Head Font API in your plugin's main class.

```APIDOC
## API Usage
In your plugin’s main class, initialize the API in the `onEnable()` method:
``` java
@Override
public void onEnable() {
    ChatHeadAPI.initialize(this);
    // ... additional initialization code
}
```
```

--------------------------------

### ChatHeadAPI.initialize(Main plugin)

Source: https://context7.com/ogminso/chatheadfont/llms.txt

Initializes the ChatHeadAPI singleton. This method must be called exactly once in your plugin's onEnable() method before any other API calls are made. It configures the default skin source based on the plugin's config.yml.

```APIDOC
## ChatHeadAPI.initialize(Main plugin)

### Description
Initializes the singleton instance of `ChatHeadAPI`. Must be called exactly once in your plugin's `onEnable()`. Reads `skin-source` from `config.yml` to set the global default `SkinSource`. Throws `IllegalStateException` if called a second time.

### Method
`public static void initialize(Main plugin)`

### Parameters
* **plugin** (Main) - Required - The main plugin instance.

### Request Example
```java
public final class MyPlugin extends JavaPlugin {

    @Override
    public void onEnable() {
        // Initialize ChatHeadFont API — must happen before any getHead() calls
        ChatHeadAPI.initialize(this);

        // Register your own listeners after initialization
        getServer().getPluginManager().registerEvents(new MyChatListener(), this);
    }
}
```
```

--------------------------------

### SkinSource Implementations

Source: https://context7.com/ogminso/chatheadfont/llms.txt

Details the available `SkinSource` implementations, including Mojang, Crafatar, Minotar, and McHeads. These can be instantiated directly and passed to `getHead()` overloads for custom skin retrieval.

```APIDOC
## `SkinSource` — Abstract Base & Implementations

### Description
`SkinSource` is the abstract base for all skin providers. Concrete implementations cover four external services. You can instantiate any source directly and pass it to `getHead()` overloads.

### Available Sources
| Class | `SkinSourceEnum` | UUID support | Username support |
|---|---|---|---|
| `MojangSource` | `MOJANG` | Yes | Yes (via name→UUID lookup) |
| `CrafatarSource` | `CRAFATAR` | Yes | No |
| `MinotarSource` | `MINOTAR` | Yes | Yes |
| `McHeadsSource` | `MCHEADS` | Yes | Yes |

### Request Example
```java
// Explicitly choose a skin source at call site
SkinSource mojang   = new MojangSource();
SkinSource crafatar = new CrafatarSource();
SkinSource minotar  = new MinotarSource();
SkinSource mcheads  = new McHeadsSource();

// Offline-mode servers: pass true to use name-based lookup fallback
SkinSource offlineMojang = new MojangSource(/* useUUIDWhenRetrieve= */ false);

BaseComponent[] head = ChatHeadAPI.getInstance().getHead(player, true, crafatar);
```
```

--------------------------------

### ChatHeadAPI.getInstance()

Source: https://context7.com/ogminso/chatheadfont/llms.txt

Retrieves the singleton ChatHeadAPI instance. This method should be called after `initialize()` has successfully completed. Calling it before initialization will result in an exception.

```APIDOC
## ChatHeadAPI.getInstance()

### Description
Returns the singleton `ChatHeadAPI` instance. Throws `IllegalArgumentException` if `initialize()` has not been called yet.

### Method
`public static ChatHeadAPI getInstance()`

### Response Example
```java
// Safely retrieve the API instance inside an event handler
ChatHeadAPI api = ChatHeadAPI.getInstance();
// api is now ready to call getHead(), getHeadAsString(), etc.
```
```

--------------------------------

### Pre-warm Cache on Player Login

Source: https://context7.com/ogminso/chatheadfont/llms.txt

Pre-warm the head cache upon player login to ensure the head is ready by the time join messages are displayed. This avoids a delay for the first head fetch.

```java
// Practical implication: pre-warm the cache on login
@EventHandler
public void onLogin(PlayerLoginEvent event) {
    // Trigger async cache population immediately at login
    // so the head is ready by the time join messages fire
    ChatHeadAPI.getInstance().getHead(event.getPlayer());
}
```

--------------------------------

### Initialize ChatHeadAPI in onEnable

Source: https://context7.com/ogminso/chatheadfont/llms.txt

Call ChatHeadAPI.initialize(this) exactly once in your plugin's onEnable() method before any other API calls. This sets the global default skin source.

```java
public final class MyPlugin extends JavaPlugin {

    @Override
    public void onEnable() {
        // Initialize ChatHeadFont API — must happen before any getHead() calls
        ChatHeadAPI.initialize(this);

        // Register your own listeners after initialization
        getServer().getPluginManager().registerEvents(new MyChatListener(), this);
    }
}
```

--------------------------------

### PlaceholderAPI Placeholders

Source: https://github.com/ogminso/chatheadfont/blob/main/README.md

These placeholders can be used in chat plugins or configuration files to display player heads.

```APIDOC
## PlaceholderAPI Integration

If PlaceholderAPI is installed on your server, Chat Head Font automatically registers a hook that provides the following placeholders:

- **`%chathead%` or `%chathead_self%`**  
  Returns the head of the player using the placeholder.  
  **Usage:** In chat plugins or configuration files, simply use `%chathead%` to show the head of the player who requested it.

- **`%chathead_other:<player>%`**  
  Returns the head of the specified player.  
  **Example:** `%chathead_other:Notch%` will display Notch’s head.

If a player is not found or is offline when using `%chathead_self%`, an appropriate message will be returned.
```

--------------------------------

### Add ChatHeadFont Dependency (Gradle)

Source: https://github.com/ogminso/chatheadfont/blob/main/README.md

Add this to your Gradle project's build file to include the Chat Head Font API.

```gradle
dependencyResolutionManagement {
        repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
        repositories {
            mavenCentral()
            maven { url 'https://jitpack.io' }
        }
    }

    dependencies {
        implementation 'com.github.OGminso:ChatHeadFont:API-v0.0.5'
    }
```

--------------------------------

### Display Player Head in Action Bar

Source: https://context7.com/ogminso/chatheadfont/llms.txt

Sends an 8x8 pixel player head to the player's action bar. Requires the player object and ChatHeadAPI instance.

```java
public class ActionBarExample implements Listener {

    @EventHandler
    public void onPlayerJoin(PlayerJoinEvent event) {
        Player player = event.getPlayer();

        BaseComponent[] head = ChatHeadAPI.getInstance()
                .getHead(player, true, ChatHeadAPI.defaultSource);

        // Sends the 8×8 pixel head to the player's action bar
        player.spigot().sendMessage(ChatMessageType.ACTION_BAR, head);
    }
}
```

--------------------------------

### Retrieve Player Head as Legacy String

Source: https://github.com/ogminso/chatheadfont/blob/main/README.md

Obtain a player's head as a legacy formatted String. This method also utilizes the internal caching mechanism.

```java
String headString = ChatHeadAPI.getInstance().getHeadAsString(player);
```

--------------------------------

### ChatHeadAPI.getHeadAsComponent(UUID uuid, boolean overlay, SkinSource skinSource)

Source: https://context7.com/ogminso/chatheadfont/llms.txt

Returns the player's head as a Kyori Adventure `Component`. This is ideal for modern Paper/Adventure API pipelines, allowing for rich text formatting and integration.

```APIDOC
## `ChatHeadAPI.getHeadAsComponent(UUID uuid, boolean overlay, SkinSource skinSource)`

### Description
Returns the head as a Kyori Adventure `Component`, suitable for modern Paper/Adventure API pipelines.

### Method
`getHeadAsComponent`

### Parameters
#### Path Parameters
- `uuid` (UUID) - Required - The UUID of the player whose head to retrieve.
- `overlay` (boolean) - Required - Whether to apply an overlay to the head.
- `skinSource` (SkinSource) - Required - The source to use for retrieving the skin.

### Request Example
```java
Component headComponent = ChatHeadAPI.getInstance()
        .getHeadAsComponent(player.getUniqueId(), true, ChatHeadAPI.defaultSource);

Component fullMessage = headComponent
        .append(Component.text(" " + player.getName() + " joined!")
                .color(TextColor.color(0xFFFF55)));

// Send using Adventure API (Paper 1.18+)
Bukkit.getServer().broadcast(fullMessage);
```
```

--------------------------------

### ChatHeadAPI.getHeadAsString(OfflinePlayer player, boolean overlay, SkinSource skinSource)

Source: https://context7.com/ogminso/chatheadfont/llms.txt

A full-control version of `getHeadAsString` that allows specifying the overlay and skin source. This provides flexibility for integrating player heads into various string-based contexts.

```APIDOC
## `ChatHeadAPI.getHeadAsString(OfflinePlayer player, boolean overlay, SkinSource skinSource)`

### Description
Full-control version of `getHeadAsString`, accepting overlay and skin source flags. Note: despite the parameter names in the UUID-accepting overload, it always uses the default source and overlay=true for UUID inputs.

### Method
`getHeadAsString`

### Parameters
#### Path Parameters
- `player` (OfflinePlayer) - Required - The player whose head to retrieve.
- `overlay` (boolean) - Required - Whether to apply an overlay to the head.
- `skinSource` (SkinSource) - Required - The source to use for retrieving the skin.

### Request Example
```java
SkinSource minotar = new MinotarSource();
String headLegacy = ChatHeadAPI.getInstance()
        .getHeadAsString(player, false, minotar);  // no hat overlay, Minotar source

// Send as action bar via legacy string
player.sendMessage(headLegacy + " §aWelcome back!");
```
```

--------------------------------

### Initialize Chat Head Font API

Source: https://github.com/ogminso/chatheadfont/blob/main/README.md

Initialize the Chat Head Font API in your plugin's onEnable method. This is required before using other API functions.

```java
@Override
public void onEnable() {
    ChatHeadAPI.initialize(this);
    // ... additional initialization code
}
```

--------------------------------

### Chat Head Font Configuration

Source: https://github.com/ogminso/chatheadfont/blob/main/README.md

Default configuration options for the Chat Head Font plugin. Customize skin sources, auto-download behavior, and message inclusions.

```yaml
# Whether to check for new updates from GitHub.
check-for-updates: true

# Which skin source to use (MOJANG, CRAFATAR, MINOTAR, or MCHEADS). Default is MOJANG.
skin-source: MOJANG

# Whether the resource pack will be automatically downloaded and applied for every player.
auto-download-pack: true

# Whether to display the player head with its hat overlay.
enable-skin-overlay: true

# Should join messages include the player head.
enable-join-messages: true

# Should leave messages include the player head.
enable-leave-messages: true

# Should chat messages include the player head.
enable-chat-messages: true

```

--------------------------------

### Add ChatHeadFont Dependency (Maven)

Source: https://github.com/ogminso/chatheadfont/blob/main/README.md

Include this dependency in your Maven project to use the Chat Head Font API.

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

    <dependencies>
        <dependency>
            <groupId>com.github.OGminso</groupId>
            <artifactId>ChatHeadFont</artifactId>
            <version>API-v0.0.5</version>
        </dependency>
    </dependencies>
```

--------------------------------

### Define Player Head Font Mapping

Source: https://context7.com/ogminso/chatheadfont/llms.txt

This JSON file defines the 'playerhead' font and maps Unicode code points to 1x1 pixel PNG textures for displaying player heads. Ensure the resource pack is auto-downloaded by setting 'auto-download-pack: true'.

```json
{
  "providers": [
    { "type": "bitmap", "file": "chathead:textures/pixel1.png", "ascent": 8, "height": 8, "chars": ["\uF001"] },
    { "type": "bitmap", "file": "chathead:textures/pixel2.png", "ascent": 8, "height": 8, "chars": ["\uF002"] },
    { "type": "bitmap", "file": "chathead:textures/pixel3.png", "ascent": 8, "height": 8, "chars": ["\uF003"] },
    { "type": "bitmap", "file": "chathead:textures/pixel4.png", "ascent": 8, "height": 8, "chars": ["\uF004"] },
    { "type": "bitmap", "file": "chathead:textures/pixel5.png", "ascent": 8, "height": 8, "chars": ["\uF005"] },
    { "type": "bitmap", "file": "chathead:textures/pixel6.png", "ascent": 8, "height": 8, "chars": ["\uF006"] },
    { "type": "bitmap", "file": "chathead:textures/pixel7.png", "ascent": 8, "height": 8, "chars": ["\uF007"] },
    { "type": "bitmap", "file": "chathead:textures/pixel8.png", "ascent": 8, "height": 8, "chars": ["\uF008"] }
  ]
}
```

--------------------------------

### ChatHeadAPI.getHead(OfflinePlayer player, boolean overlay, SkinSource skinSource)

Source: https://context7.com/ogminso/chatheadfont/llms.txt

Provides full control over retrieving a player's head, allowing for an explicit SkinSource to be specified. This is particularly useful in offline-mode servers where UUID lookups might differ.

```APIDOC
## `ChatHeadAPI.getHead(OfflinePlayer player, boolean overlay, SkinSource skinSource)`

### Description
Full-control overload that also accepts an explicit `SkinSource`. Useful when you need a different provider for a specific context (e.g., offline-mode servers where UUID lookups differ).

### Method
`getHead`

### Parameters
#### Path Parameters
- `player` (OfflinePlayer) - Required - The player whose head to retrieve.
- `overlay` (boolean) - Required - Whether to apply an overlay to the head.
- `skinSource` (SkinSource) - Required - The source to use for retrieving the skin.

### Request Example
```java
// Force Crafatar source for this particular message
SkinSource crafatar = new CrafatarSource();
BaseComponent[] head = ChatHeadAPI.getInstance().getHead(player, true, crafatar);

BaseComponent[] message = new ComponentBuilder()
        .append(head)
        .append(" " + player.getName() + " has joined!", ComponentBuilder.FormatRetention.NONE)
        .create();

Bukkit.broadcast(BaseComponent.toLegacyText(message), "myplugin.chat");
```
```

--------------------------------

### ChatHeadAPI.getHead(OfflinePlayer player)

Source: https://context7.com/ogminso/chatheadfont/llms.txt

Retrieves a BaseComponent array representing the player's head with the default skin source and the hat overlay applied. This method utilizes an internal cache for efficiency, fetching the skin asynchronously on the first call and returning cached results for subsequent calls within the cache duration.

```APIDOC
## ChatHeadAPI.getHead(OfflinePlayer player)

### Description
Retrieves an 8×8 pixel `BaseComponent[]` representing the player's head using the default skin source and with the hat overlay applied. Uses `HeadCache` internally — the first call triggers an async skin fetch; subsequent calls within the cache window return the cached result immediately.

### Method
`public BaseComponent[] getHead(OfflinePlayer player)`

### Parameters
* **player** (OfflinePlayer) - Required - The player whose head to retrieve.

### Response
#### Success Response (BaseComponent[])
An array of `BaseComponent` objects representing the player's head icon.

### Request Example
```java
@EventHandler
public void onChat(AsyncPlayerChatEvent event) {
    event.setCancelled(true);
    Player player = event.getPlayer();

    // Get head as BaseComponent array (overlay on, default source)
    BaseComponent[] head = ChatHeadAPI.getInstance().getHead(player);

    // Build "HEAD  PlayerName: message"
    BaseComponent[] message = new ComponentBuilder()
            .append(head)
            .append(" ")
            .append(player.getName() + ": " + event.getMessage(),
                    ComponentBuilder.FormatRetention.NONE)
            .create();

    for (Player p : Bukkit.getOnlinePlayers()) {
        p.spigot().sendMessage(message);
    }
}
```
```

--------------------------------

### Unicode Layout for Pixel Row

Source: https://context7.com/ogminso/chatheadfont/llms.txt

This illustrates the Unicode layout used for mapping characters to pixel textures within a row. Note the different advance values for the last character in the row.

```text
Unicode layout for a single pixel row in the grid:
  \uF001 (pixel col 1)  + \uF102 (−2px advance)
  \uF002 (pixel col 2)  + \uF102 (−2px advance)
  ...
  \uF007 (pixel col 7)  + \uF102 (−2px advance)
  \uF008 (pixel col 8)  + \uF101 (−1px advance, end of row)
```

--------------------------------

### ChatHeadAPI.getHead(OfflinePlayer player, boolean overlay)

Source: https://context7.com/ogminso/chatheadfont/llms.txt

Retrieves a BaseComponent array representing the player's head, allowing explicit control over whether the hat layer is included. Set `overlay` to `true` to include the hat layer, or `false` to display only the base face.

```APIDOC
## ChatHeadAPI.getHead(OfflinePlayer player, boolean overlay)

### Description
Same as above, but lets you control whether the hat layer of the skin is composited on top of the base face. Pass `false` to show only the base 8×8 face without the hat overlay.

### Method
`public BaseComponent[] getHead(OfflinePlayer player, boolean overlay)`

### Parameters
* **player** (OfflinePlayer) - Required - The player whose head to retrieve.
* **overlay** (boolean) - Required - `true` to include the hat layer, `false` for the base face only.

### Response
#### Success Response (BaseComponent[])
An array of `BaseComponent` objects representing the player's head icon.

### Request Example
```java
// With overlay (hat layer included)
BaseComponent[] withHat    = ChatHeadAPI.getInstance().getHead(player, true);

// Without overlay (base face only)
BaseComponent[] withoutHat = ChatHeadAPI.getInstance().getHead(player, false);

player.spigot().sendMessage(ChatMessageType.ACTION_BAR, withHat);
```
```

--------------------------------

### ChatHeadAPI.getHeadAsString(OfflinePlayer player)

Source: https://context7.com/ogminso/chatheadfont/llms.txt

Converts the player's head into a legacy-formatted String using `§` color codes. This is useful for APIs that only accept plain strings, such as BossBar titles or older chat plugins.

```APIDOC
## `ChatHeadAPI.getHeadAsString(OfflinePlayer player)`

### Description
Converts the `BaseComponent[]` grid into a legacy-formatted `String` (using `§` colour codes). Useful for APIs that only accept plain strings, such as `BossBar` titles or legacy chat plugins.

### Method
`getHeadAsString`

### Parameters
#### Path Parameters
- `player` (OfflinePlayer) - Required - The player whose head to convert to a string.

### Request Example
```java
@EventHandler
public void onPlayerJoin(PlayerJoinEvent event) {
    Player player = event.getPlayer();

    String headString = ChatHeadAPI.getInstance().getHeadAsString(player);

    // Use legacy string as a BossBar title
    BossBar bar = Bukkit.createBossBar(
            headString + " " + player.getName(),
            BarColor.GREEN,
            BarStyle.SOLID
    );
    bar.setProgress(1.0);
    bar.addPlayer(player);

    // Output: legacy-coloured 8×8 head pixels followed by the player's name
}
```
```

--------------------------------

### ChatHeadAPI.getHead(UUID uuid)

Source: https://context7.com/ogminso/chatheadfont/llms.txt

Retrieves a player's head using their UUID. This overload is suitable for asynchronous contexts or when only the player's UUID is available.

```APIDOC
## `ChatHeadAPI.getHead(UUID uuid)` / `getHead(UUID uuid, boolean overlay)` / `getHead(UUID uuid, boolean overlay, SkinSource skinSource)`

### Description
UUID-based overloads for use cases where only the player's UUID is available (e.g., handling offline players or async contexts where the `OfflinePlayer` reference is unavailable).

### Method
`getHead`

### Parameters
#### Path Parameters
- `uuid` (UUID) - Required - The UUID of the player whose head to retrieve.
- `overlay` (boolean) - Optional - Whether to apply an overlay to the head.
- `skinSource` (SkinSource) - Optional - The source to use for retrieving the skin.

### Request Example
```java
// Retrieve and display the head of any UUID — online or offline
UUID targetUUID = UUID.fromString("069a79f4-44e9-4726-a5be-fca90e38aaf5"); // Notch

Bukkit.getScheduler().runTaskAsynchronously(plugin, () -> {
    BaseComponent[] head = ChatHeadAPI.getInstance().getHead(targetUUID, true);

    // Switch back to main thread to send message
    Bukkit.getScheduler().runTask(plugin, () -> {
        BaseComponent[] msg = new ComponentBuilder()
                .append(head)
                .append(" Notch's head retrieved!", ComponentBuilder.FormatRetention.NONE)
                .create();
        Bukkit.broadcast(TextComponent.toLegacyText(msg), Server.BROADCAST_CHANNEL_USERS);
    });
});
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.