### Text Formatting and Color Example

Source: https://github.com/toxicity188/betterhealthbar3/wiki/layouts

Shows how to apply color and text formatting (bold, obfuscated) within the 'pattern' definition for text elements in BetterHealthBar3. This allows for rich text display.

```yaml
pattern: "name : <red><b>[papi:player_name]</b></red>"
```

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

### Build BetterHealthBar3 Plugin with Gradle

Source: https://github.com/toxicity188/betterhealthbar3/blob/master/README.md

This command initiates the build process for the BetterHealthBar3 plugin using Gradle. It compiles the plugin and packages it for distribution. Ensure you have Gradle installed and are in the project's root directory.

```bash
./gradlew build
```

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

### MythicMobs Mob Definition Example (YAML)

Source: https://github.com/toxicity188/betterhealthbar3/wiki/mobs

An example of a MythicMob definition, specifying its type, display name, health, and damage. This serves as a base for further configuration with other plugins.

```yaml
SkeletalKnight:
  Type: WITHER_SKELETON
  Display: '&aSkeletal Knight'
  Health: 40
  Damage: 8
  ...
```

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

### BetterHealthBar Type Integration Example (YAML)

Source: https://github.com/toxicity188/betterhealthbar3/wiki/mobs

Demonstrates how to define custom types in MythicMobs configuration to be recognized by BetterHealthBar. This allows specific health bars to be applied based on mob types.

```yaml
AngrySludge:
  types: 
  - some_type
  ...
```

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

### BetterHealthBar Healthbar Application Example (YAML)

Source: https://github.com/toxicity188/betterhealthbar3/wiki/mobs

Shows how to configure health bars in BetterHealthBar to apply to specific mob types defined in MythicMobs. The 'applicable-types' field links the health bar to the mob's type.

```yaml
default_healthbar:
  applicable-types: 
  - some_type #matched!
```

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

### Define Mob Functionality with Health Bars

Source: https://github.com/toxicity188/betterhealthbar3/wiki/healthbars

Example of defining mob types and associating them with specific health bars. This demonstrates how mobs can be configured to use custom health bars.

```yaml
AngrySludge:
  types:
  - some_type
  healthbars:
  - some_healthbar
```

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

### MythicMobs Basic Mob Configuration (YAML)

Source: https://github.com/toxicity188/betterhealthbar3/wiki/mobs

A basic example of a MythicMob configuration file, defining mob properties like types, healthbars, and height. This format is used to integrate with plugins like BetterHealthBar.

```yaml
AngrySludge:
  types:
  - normal
  - Angry
  healthbars:
  - normal_mobs
  height: 0
  #blacklist: true
  #ignore-default: true
```

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

### Associate Health Bar with Mob Type

Source: https://github.com/toxicity188/betterhealthbar3/wiki/healthbars

Example of how a health bar is linked to a specific mob type. This configuration ensures that 'default_healthbar' is applied when 'some_type' is matched.

```yaml
default_healthbar:
  applicable-types:
  - some_type #matched!
```

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

### Java API: List and Inspect Health Bars

Source: https://context7.com/toxicity188/betterhealthbar3/llms.txt

Demonstrates how to access the HealthBarManager to retrieve registered health bar configurations. It shows how to get a specific health bar by name and iterate through all available health bars, accessing properties like UUID, scale, duration, and applicability.

```java
import kr.toxicity.healthbar.api.BetterHealthBar;
import kr.toxicity.healthbar.api.healthbar.HealthBar;
import kr.toxicity.healthbar.api.manager.HealthBarManager;
import org.bukkit.util.Vector;
import java.util.UUID;
import java.util.Set;

public class HealthBarExample {

    public void listHealthBars() {
        HealthBarManager manager = BetterHealthBar.inst().healthBarManager();

        // Get a specific health bar by name
        HealthBar defaultBar = manager.healthBar("default_healthbar");
        if (defaultBar != null) {
            // Access health bar properties
            UUID uuid = defaultBar.uuid();
            Vector scale = defaultBar.scale();
            int duration = defaultBar.duration();
            boolean isDefault = defaultBar.isDefault();
            Set<String> applicableTypes = defaultBar.applicableTypes();
            Set<HealthBarTriggerType> triggers = defaultBar.triggers();

            System.out.println("Health Bar: " + defaultBar.name());
            System.out.println("Scale: " + scale.getX() + ", " + scale.getY() + ", " + scale.getZ());
            System.out.println("Duration: " + duration + " ticks");
            System.out.println("Is Default: " + isDefault);
        }

        // Iterate all registered health bars
        for (HealthBar bar : manager.allHealthBars()) {
            System.out.println("Found health bar: " + bar.name());
        }
    }
}
```

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

### Java API: Manage Player Health Bar Visibility

Source: https://context7.com/toxicity188/betterhealthbar3/llms.txt

Provides examples of how to interact with the PlayerManager to obtain and manage health bar data for individual players. It covers retrieving a HealthBarPlayer object using Bukkit Player or UUID, accessing its underlying Bukkit player, viewing active updaters, clearing all health bars, and uninjecting the player.

```java
import kr.toxicity.healthbar.api.BetterHealthBar;
import kr.toxicity.healthbar.api.player.HealthBarPlayer;
import kr.toxicity.healthbar.api.manager.PlayerManager;
import kr.toxicity.healthbar.api.healthbar.HealthBarUpdaterGroup;
import org.bukkit.entity.Player;
import java.util.UUID;
import java.util.Map;

public class PlayerHealthBarExample {

    public void managePlayerHealthBars(Player bukkitPlayer) {
        PlayerManager manager = BetterHealthBar.inst().playerManager();

        // Get HealthBarPlayer from Bukkit Player
        HealthBarPlayer player = manager.player(bukkitPlayer);

        // Or get by UUID (returns null if player not online)
        HealthBarPlayer playerByUuid = manager.player(bukkitPlayer.getUniqueId());

        // Get the underlying Bukkit player
        Player underlying = player.player();

        // Get all active health bar updaters for this player
        Map<UUID, HealthBarUpdaterGroup> updaters = player.updaterMap();
        for (Map.Entry<UUID, HealthBarUpdaterGroup> entry : updaters.entrySet()) {
            System.out.println("Active health bar for entity: " + entry.getKey());
        }

        // Clear all health bars for this player
        player.clear();

        // Uninject the player (cleanup on disconnect)
        player.uninject();
    }
}
```

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

### Listener Image Configuration

Source: https://github.com/toxicity188/betterhealthbar3/wiki/layouts

Illustrates the use of a 'listener' for images in BetterHealthBar3. This allows an image to be dynamically linked to a specific class, such as 'health', enabling visual feedback based on game state.

```yaml
default_layout:
  images:
    1:
      image: listener
      listener:
        class: health
```

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

### Configure Pack Generation Type and Build Folder

Source: https://github.com/toxicity188/betterhealthbar3/wiki/Config

Sets the type of resource pack to generate (folder, zip, or none) and the output directory. Specific settings are recommended when using Nexo for automatic merging.

```yaml
pack-type: folder #folder, zip, none
build-folder: "BetterHealthBar/build"
```

```yaml
build-folder: Nexo/pack/external_packs/betterhealthbar3
```

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

### Integrate BetterHealthBar3 API into Your Project

Source: https://github.com/toxicity188/betterhealthbar3/blob/master/README.md

This snippet shows how to include the BetterHealthBar3 plugin's API as a dependency in your project's build script. It specifies the necessary repositories and the dependency coordinates. Replace 'VERSION' with the actual version of the BetterHealthBar3 plugin you are using.

```kotlin
repositories {
  mavenCenteral()
  maven("https://jitpack.io")
}

dependencies {
  compileOnly("com.github.toxicity188:BetterHealthBar3:VERSION")
}
```

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

### Image Layout Configuration

Source: https://github.com/toxicity188/betterhealthbar3/wiki/layouts

Demonstrates how to configure image layouts within BetterHealthBar3. It shows setting a single image, a listener-based image that reacts to health changes, and conditional images based on health percentage.

```yaml
default_layout:
  images:
    1:
      image: single
    3:
      image: listener
      listener:
        class: health
      conditions:
        1:
          first: health_percentage
          second: 0.33
          operation: "<"
```

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

### Configure Listener Image for Variable Bars

Source: https://github.com/toxicity188/betterhealthbar3/wiki/images

The 'listener' image type creates a variable bar, such as a health bar. It requires a 'file' property for the image and supports 'split' and 'split-type' for customization. 'split' determines the number of resources created, affecting detail and capacity, while 'split-type' ('up', 'down', 'left', 'right') defines the direction of decrease.

```yaml
first:
  type: listener
  file: first.png
  split-type: left
  split: 25
```

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

### Configure Single Image Display

Source: https://github.com/toxicity188/betterhealthbar3/wiki/images

The 'single' image type is used for displaying a static image. It is universal and requires a 'file' property to specify the image path. The image can be loaded with a given ID from the assets folder.

```yaml
image_id:
  type: single
  file: "example.png"
```

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

### Configure Animated Sequence Image

Source: https://github.com/toxicity188/betterhealthbar3/wiki/images

The 'sequence' image type is used for creating animated images. It works on a per-tick basis for each frame. The 'files' property takes a list of image paths. Duration can be set per frame using a colon followed by the tick count.

```yaml
test_gif:
  type: sequence
  files:
    - test/test_00000.png
    - test/test_00001.png
    - test/test_00002.png
    - test/test_00003.png
    - test/test_00004.png
    - test/test_00005.png
    - test/test_00006.png
    - test/test_00007.png
    - test/test_00008.png
    - test/test_00009.png
    - test/test_00010.png
```

```yaml
test_gif:
  type: sequence
  files:
    - test/test_00000.png:4
    - test/test_00001.png
    - test/test_00002.png:2
```

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

### Configure Resource Pack Type (YAML)

Source: https://github.com/toxicity188/betterhealthbar3/wiki/Install

Sets the resource pack type and build folder for the BetterHealthBar plugin. 'folder' is used for automatic generation, 'none' for Nexo integration, and 'zip' for manual merging.

```yaml
pack-type: folder
build-folder: "BetterHealthBar/build"
```

```yaml
pack-type: none
```

```yaml
build-folder: Nexo/pack/external_packs/betterhealthbar3
```

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

### Text Layout Configuration

Source: https://github.com/toxicity188/betterhealthbar3/wiki/layouts

Details the configuration for text elements in BetterHealthBar3. This includes specifying the font, alignment, the pattern for displayed text (with placeholders), and positioning using x/y coordinates and scale.

```yaml
default_layout:
  texts:
    1:
      text: default_text
      pattern: "[entity_name]"
      align: center
      x: 60
      y: 20
      scale: 0.5
```

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

### Configure Text Placeholders (YAML)

Source: https://context7.com/toxicity188/betterhealthbar3/llms.txt

Define text patterns that display dynamic values using built-in placeholders or PlaceholderAPI. This allows for customizable text elements in health bars, such as entity names, health values, and player statistics.

```yaml
# Text pattern examples
texts:
  1:
    text: custom_font
    # Built-in placeholders use [placeholder_name]
    pattern: "[entity_name]"

  2:
    text: number_font
    # Health display with colors
    pattern: "<red>[health]</red> / <gray>[max_health]</gray>"

  3:
    text: info_font
    # PlaceholderAPI placeholders
    pattern: "Level: [papi:cmi_user_level]"

  4:
    text: custom_font
    # Combined with text formatting
    pattern: "<b><gold>[entity_name]</gold></b>"

# Color types: <#hex>, <black>, <gold>, <gray>, <blue>, <green>, <aqua>, <red>, <yellow>, <white>
# Format types: <b> (bold), <obf> (obfuscated)

```

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

### Configure Shader Usage

Source: https://github.com/toxicity188/betterhealthbar3/wiki/Config

Controls the activation of shaders for text elements and the core shader system. Setting `use-core-shaders` to `false` can make shaders visible to players but may impact performance.

```yaml
shaders:
  text.vsh: true
  text.fsh: true
use-core-shaders: true
```

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

### Configure Conditions for Layout Elements (YAML)

Source: https://context7.com/toxicity188/betterhealthbar3/llms.txt

Control the visibility of layout elements based on placeholder values and comparison operations. Conditions allow for dynamic display logic, ensuring elements only appear when specific criteria are met.

```yaml
# Condition examples in layouts
conditions:
  # Show when health is below 33%
  1:
    first: health_percentage
    second: 0.33
    operation: "<"  # >, >=, <, <=, ==, !=

  # Show when health is between 33% and 66%
  2:
    first: health_percentage
    second: 0.33
    operation: ">="
    gate: and  # and, or (default: and)
  3:
    first: health_percentage
    second: 0.66
    operation: "<"

  # Using PlaceholderAPI (without brackets in conditions)
  4:
    first: "(number)papi:player_level"
    second: 10
    operation: ">="

  # String comparison (use quotes for string numbers)
  5:
    first: "papi:player_world"
    second: "'world_nether'"
    operation: "=="

```

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

### Correct PAPI Formatting for BetterHealthBar Conditions

Source: https://github.com/toxicity188/betterhealthbar3/wiki/conditions

Shows the correct way to reference PAPI placeholders within conditions, emphasizing the exclusion of square brackets to avoid errors during comparison.

```yaml
conditions:
  1:
    first: "[papi:player_x]"
    second: "'1'"
    operation: '=='
```

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

### String Comparison with PAPI in BetterHealthBar Conditions

Source: https://github.com/toxicity188/betterhealthbar3/wiki/conditions

Illustrates how to compare a PAPI placeholder treated as a string against a specific string value. This is crucial when the PAPI variable is not explicitly cast as a number.

```yaml
conditions:
  1:
    first: "papi:player_x"
    second: "'1'"
    operation: '=='
```

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

### Configure Default Layout with Images and Text

Source: https://github.com/toxicity188/betterhealthbar3/wiki/layouts

Defines the default layout for the health bar, including image display with conditional listeners and text elements with specified patterns and alignment. This configuration is typically used in a YAML file.

```yaml
default_layout:
  images:
    1:
      image: empty
    2:
      image: first
      listener:
        class: health_before
    4:
      image: yellow
      listener:
        class: health
      conditions:
        1:
          first: health_percentage
          second: 0.33
          operation: ">="
        2:
          first: health_percentage
          second: 0.66
          operation: "<"
  texts:
    1:
      text: default_text
      pattern: "[entity_name]"
      align: center
      x: 60
      y: 20
      scale: 0.5
```

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

### Set Up Custom Fonts (YAML)

Source: https://context7.com/toxicity188/betterhealthbar3/llms.txt

This YAML snippet defines custom fonts for displaying text within the health bars. It specifies the font file (TTF or OTF) located in the 'fonts' folder and a scale factor for rendering. This allows for customized text appearance beyond default Minecraft fonts.

```yaml
# BetterHealthBar/texts/fonts.yml
custom_font:
  file: custom_font.ttf  # Place .ttf or .otf in fonts folder
  scale: 16

number_font:
  file: digits.otf
  scale: 14

title_font:
  file: bold_font.ttf
  scale: 20
```

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

### Add BetterHealthBar3 as a Dependency (Gradle Kotlin)

Source: https://context7.com/toxicity188/betterhealthbar3/llms.txt

Integrate the BetterHealthBar3 plugin into your Java/Kotlin project by adding it as a dependency using Gradle. This involves configuring repositories and specifying the dependency in your build.gradle.kts file.

```kotlin
// build.gradle.kts
repositories {
    mavenCentral()
    maven("https://jitpack.io")
}

dependencies {
    compileOnly("com.github.toxicity188:BetterHealthBar3:3.11.0")
}

```

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

### Configure Plugin Settings (YAML)

Source: https://context7.com/toxicity188/betterhealthbar3/llms.txt

This snippet shows the main configuration file for BetterHealthBar3. It controls general plugin behavior, resource pack generation, shader usage, and entity type blacklisting. Adjust these settings to customize the plugin's operation.

```yaml
# BetterHealthBar/config.yml
debug: false
metrics: true
pack-type: folder  # folder, zip, or none
namespace: "betterhealthbar"
default-duration: 60
build-folder: "BetterHealthBar/build"
default-height: 1
look-degree: 20
look-distance: 15
merge-other-folder: []
create-pack-mcmeta: false
enable-self-host: false
number-format: "#,###.0"
blacklist-entity-type:
  - ARMOR_STAND
  - TEXT_DISPLAY
  - BLOCK_DISPLAY
  - ITEM_DISPLAY
disable-to-invulnerable-mob: true
disable-to-invisible-mob: true
shaders:
  text.vsh: true
  text.fsh: true
use-core-shaders: true
show-me-healthbar: true
resource-pack-obfuscation: false
```

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

### Java API: Programmatically Show Health Bars

Source: https://context7.com/toxicity188/betterhealthbar3/llms.txt

Illustrates how to use the BetterHealthBar API to display health bars for specific entities to particular viewers. This involves obtaining the HealthBar configuration, HealthBarPlayer, and HealthBarEntity wrappers, creating a custom trigger, and then calling the showHealthBar method.

```java
import kr.toxicity.healthbar.api.BetterHealthBar;
import kr.toxicity.healthbar.api.entity.HealthBarEntity;
import kr.toxicity.healthbar.api.healthbar.HealthBar;
import kr.toxicity.healthbar.api.player.HealthBarPlayer;
import kr.toxicity.healthbar.api.trigger.HealthBarTrigger;
import kr.toxicity.healthbar.api.trigger.HealthBarTriggerType;
import org.bukkit.entity.LivingEntity;
import org.bukkit.entity.Player;

public class ShowHealthBarExample {

    public void showHealthBarToPlayer(Player viewer, LivingEntity target) {
        BetterHealthBar api = BetterHealthBar.inst();

        // Get the health bar configuration
        HealthBar healthBar = api.healthBarManager().healthBar("boss_healthbar");
        if (healthBar == null) return;

        // Get the player wrapper
        HealthBarPlayer player = api.playerManager().player(viewer);

        // Get the entity wrapper
        HealthBarEntity entity = api.mobManager().entity(target);

        // Create a custom trigger (EMPTY type for API-triggered health bars)
        HealthBarTrigger trigger = () -> HealthBarTriggerType.EMPTY;

        // Show the health bar to the player for the target entity
        player.showHealthBar(healthBar, trigger, entity);
    }
}
```

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

### Configure Default Health Bar Settings

Source: https://github.com/toxicity188/betterhealthbar3/wiki/healthbars

Defines the default health bar configuration, including its scale and trigger conditions. This section specifies if the health bar is the default and sets its scaling factors.

```yaml
default_healthbar:
  default: true
  applicable-types: []
  scale:
    x: 0.75
    y: 0.75
    z: 0.75
  triggers:
    - damage
    - look
  groups:
    - default_layout
    - mob_effect_absorption
```

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

### Java API - Register Custom Mob Providers

Source: https://context7.com/toxicity188/betterhealthbar3/llms.txt

Implement custom mob detection logic to integrate with other mob plugins by registering a custom MobProvider. This involves checking entity data, retrieving configurations, and returning a HealthBarMob implementation. Dependencies include BetterHealthBar API classes and Bukkit's PersistentDataContainer.

```java
import kr.toxicity.healthbar.api.BetterHealthBar;
import kr.toxicity.healthbar.api.mob.HealthBarMob;
import kr.toxicity.healthbar.api.mob.MobConfiguration;
import kr.toxicity.healthbar.api.mob.MobProvider;
import kr.toxicity.healthbar.api.manager.MobManager;
import org.bukkit.entity.LivingEntity;
import org.bukkit.persistence.PersistentDataType;
import org.bukkit.NamespacedKey;

public class CustomMobProvider implements MobProvider {

    private final NamespacedKey mobIdKey;

    public CustomMobProvider(JavaPlugin plugin) {
        this.mobIdKey = new NamespacedKey(plugin, "custom_mob_id");
    }

    @Override
    public HealthBarMob provide(LivingEntity entity) {
        // Check if entity has custom mob data
        String mobId = entity.getPersistentDataContainer()
            .get(mobIdKey, PersistentDataType.STRING);

        if (mobId == null) return null;

        // Get configuration from MobManager
        MobManager mobManager = BetterHealthBar.inst().mobManager();
        MobConfiguration config = mobManager.configuration(mobId);

        if (config == null) return null;

        // Return custom HealthBarMob implementation
        return new HealthBarMob() {
            @Override
            public String id() {
                return mobId;
            }

            @Override
            public Object handle() {
                return entity;
            }

            @Override
            public MobConfiguration configuration() {
                return config;
            }
        };
    }

    public void register() {
        BetterHealthBar.inst().mobManager().addProvider(this);
    }
}
```

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

### Add BetterHealthBar3 as a Dependency (Maven)

Source: https://context7.com/toxicity188/betterhealthbar3/llms.txt

Integrate the BetterHealthBar3 plugin into your Java project by adding it as a dependency using Maven. This involves configuring repositories and specifying the dependency in your pom.xml file.

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

<dependencies>
    <dependency>
        <groupId>com.github.toxicity188</groupId>
        <artifactId>BetterHealthBar3</artifactId>
        <version>3.11.0</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

```

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

### Bash: BetterHealthBar3 Commands

Source: https://context7.com/toxicity188/betterhealthbar3/llms.txt

Shows the command-line interface for the BetterHealthBar3 plugin. These commands allow server administrators to reload plugin configurations and regenerate resource packs. The primary command is '/healthbar' with an alias '/hb'.

```bash
# Reload plugin configuration and regenerate resource pack
/healthbar
# Alias
/hb

# Required permission
betterhealthbar.reload
```

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

### Configure Images for Health Bars (YAML)

Source: https://context7.com/toxicity188/betterhealthbar3/llms.txt

This YAML configures the images used in health bars. It supports static images, dynamic listener-based images that deplete (e.g., health bars), and animated sequences for effects like damage indicators. The 'split-type' and 'split' parameters control how listener images are rendered.

```yaml
# BetterHealthBar/images/health_images.yml
# Static background image
background_bar:
  type: single
  file: "bar_background.png"

# Dynamic health bar that depletes left-to-right
health_bar:
  type: listener
  file: "bar_fill.png"
  split-type: left  # up, down, left, right
  split: 25  # Number of segments (higher = smoother, larger resource pack)

# Animated effect
damage_effect:
  type: sequence
  files:
    - effects/damage_00.png:4   # 4 ticks duration
    - effects/damage_01.png     # 1 tick (default)
    - effects/damage_02.png:2   # 2 ticks duration
    - effects/damage_03.png
    - effects/damage_04.png
    - effects/damage_05.png:3
```

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

### Configure Custom Font in YAML

Source: https://github.com/toxicity188/betterhealthbar3/wiki/fonts

This YAML snippet demonstrates how to define a custom font for use in the BetterHealthBar. It specifies the font file name and a scaling factor. Ensure the font file exists in the 'fonts' directory.

```yaml
example_font:
  file: example.ttf
  scale: 16
```

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

### Numeric Comparison with PAPI in BetterHealthBar Conditions

Source: https://github.com/toxicity188/betterhealthbar3/wiki/conditions

Demonstrates how to set up a condition to check if a player's PAPI value is greater than or equal to a number. This is useful for triggering display elements based on in-game stats.

```yaml
layout:
  images:
    1:
      image: example
      conditions:
        1:
          first: (number)papi:player_x
          second: 1
          operation: '>='
          gate: or
```

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

### Group Health Bar Layouts

Source: https://github.com/toxicity188/betterhealthbar3/wiki/healthbars

Allows grouping multiple health bar layouts together for organizational purposes. This is useful for managing complex configurations.

```yaml
groups:
  - default_layout
  - mob_effect_absorption
```

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

### Java API - Registering Custom Mob Providers

Source: https://context7.com/toxicity188/betterhealthbar3/llms.txt

Add custom mob detection logic to integrate with other mob plugins. This allows BetterHealthBar to recognize and manage health bars for custom entities.

```APIDOC
## Java API - Registering Custom Mob Providers

### Description
Add custom mob detection logic to integrate with other mob plugins. This allows BetterHealthBar to recognize and manage health bars for custom entities.

### Method
`MobProvider` Interface Implementation

### Endpoint
N/A (Registration)

### Parameters
#### `provide(LivingEntity entity)` Method Parameters
- **entity** (`LivingEntity`) - The entity to check for custom mob data.

#### `MobProvider` Interface Methods
- **`id()`**: Returns the unique identifier for the custom mob.
- **`handle()`**: Returns the entity object.
- **`configuration()`**: Returns the `MobConfiguration` for this mob.

### Request Example
```java
// Example implementation of CustomMobProvider
public class CustomMobProvider implements MobProvider {

    private final NamespacedKey mobIdKey;

    public CustomMobProvider(JavaPlugin plugin) {
        this.mobIdKey = new NamespacedKey(plugin, "custom_mob_id");
    }

    @Override
    public HealthBarMob provide(LivingEntity entity) {
        String mobId = entity.getPersistentDataContainer()
            .get(mobIdKey, PersistentDataType.STRING);

        if (mobId == null) return null;

        MobManager mobManager = BetterHealthBar.inst().mobManager();
        MobConfiguration config = mobManager.configuration(mobId);

        if (config == null) return null;

        return new HealthBarMob() {
            @Override
            public String id() { return mobId; }
            @Override
            public Object handle() { return entity; }
            @Override
            public MobConfiguration configuration() { return config; }
        };
    }

    public void register() {
        BetterHealthBar.inst().mobManager().addProvider(this);
    }
}
```

### Response
#### Success Response
N/A (Registration)

#### Response Example
N/A
```

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

### Define Health Bar Trigger Conditions

Source: https://github.com/toxicity188/betterhealthbar3/wiki/healthbars

Specifies the conditions under which a health bar will be displayed. Options include 'damage', 'look', and 'move', with an 'empty' option for API use.

```yaml
triggers:
  - damage
  - look
```

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

### Set Default Health Bar Option

Source: https://github.com/toxicity188/betterhealthbar3/wiki/healthbars

Configures whether a specific health bar should be used as the default. Setting this to 'false' means it will not be the default.

```yaml
default: false
```

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

### Java API - Handling HealthBarCreateEvent

Source: https://context7.com/toxicity188/betterhealthbar3/llms.txt

Listen to health bar creation events to modify behavior or cancel display. This allows for custom logic based on entity type, player permissions, or other conditions.

```APIDOC
## Java API - Handling HealthBarCreateEvent

### Description
Listen to health bar creation events to modify behavior or cancel display. This allows for custom logic based on entity type, player permissions, or other conditions.

### Method
`EventHandler` (Bukkit Event System)

### Endpoint
N/A (Event Listener)

### Parameters
#### Event Data
- **healthBar** (`HealthBar`) - The health bar instance being created.
- **player** (`HealthBarPlayer`) - The player associated with the health bar.
- **entity** (`HealthBarEntity`) - The entity the health bar is attached to.

#### Methods
- **`event.setCancelled(boolean)`**: Cancels the health bar creation.
- **`event.addPredicate(Predicate<HealthBarCreateEvent>)`**: Adds a condition that must be met for the health bar to be rendered.

### Request Example
```java
// Example of cancelling for Villagers
if (entity.entity().getType() == EntityType.VILLAGER) {
    event.setCancelled(true);
}

// Example of adding a rendering predicate
event.addPredicate(e -> {
    double healthPercent = e.getEntity().entity().getHealth() /
                           e.getEntity().entity().getAttribute(org.bukkit.attribute.Attribute.GENERIC_MAX_HEALTH).getValue();
    return healthPercent > 0.5;
});

// Example of cancelling based on player permission
if (!player.player().hasPermission("healthbar.view.boss")) {
    if (healthBar.name().equals("boss_healthbar")) {
        event.setCancelled(true);
    }
}
```

### Response
#### Success Response
N/A (Event modification)

#### Response Example
N/A
```

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

### Configure Mob-Specific Settings (YAML)

Source: https://context7.com/toxicity188/betterhealthbar3/llms.txt

Define custom settings for specific mobs, including MythicMobs integration, custom types, health bar assignments, and height adjustments. This allows for fine-grained control over how health bars are displayed for different entities.

```yaml
# BetterHealthBar/mobs/custom_mobs.yml
# MythicMobs integration - use MythicMob ID as key
SkeletalKnight:
  types:
    - boss
    - undead
  healthbars:
    - boss_healthbar
  height: 0.5  # Adjust health bar height offset

# Another custom mob
DragonBoss:
  types:
    - boss
    - dragon
  healthbars:
    - dragon_healthbar
  height: 2.0

# Blacklist a mob from showing health bars
InvisibleHelper:
  blacklist: true

# Ignore default health bar but allow custom ones
EliteSkeleton:
  types:
    - elite
  healthbars:
    - elite_healthbar
  ignore-default: true

```

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

### Java API: Register Custom Health Bar Listeners

Source: https://context7.com/toxicity188/betterhealthbar3/llms.txt

Demonstrates how to register custom listeners using the BetterHealthBar Java API. These listeners provide dynamic values for health bar images, such as armor percentage or custom mana values. It requires the BetterHealthBar API library.

```java
import kr.toxicity.healthbar.api.BetterHealthBar;
import kr.toxicity.healthbar.api.listener.HealthBarListener;
import kr.toxicity.healthbar.api.manager.ListenerManager;
import org.bukkit.attribute.Attribute;
import org.bukkit.configuration.ConfigurationSection;
import org.bukkit.entity.LivingEntity;

public class CustomListenerExample {

    public void registerCustomListeners() {
        ListenerManager manager = BetterHealthBar.inst().listenerManager();

        // Register a custom armor percentage listener
        manager.addListener("armor_percentage", section -> {
            return event -> {
                LivingEntity entity = event.getEntity().entity();
                var armorAttr = entity.getAttribute(Attribute.GENERIC_ARMOR);
                if (armorAttr == null) return 0;

                // Return value between 0.0 and 1.0
                double armor = armorAttr.getValue();
                double maxArmor = 20.0; // Minecraft max armor
                return Math.min(armor / maxArmor, 1.0);
            };
        });

        // Register a mana percentage listener (for custom mana plugins)
        manager.addListener("mana_percentage", section -> {
            // Read configuration options from section if needed
            String manaType = section.getString("mana-type", "default");

            return event -> {
                // Integration with your mana plugin
                LivingEntity entity = event.getEntity().entity();
                // double mana = ManaPlugin.getMana(entity);
                // double maxMana = ManaPlugin.getMaxMana(entity);
                // return mana / maxMana;
                return 1.0; // Placeholder
            };
        });

        // Use built-in constants for special cases
        HealthBarListener zero = HealthBarListener.ZERO;     // Always returns 0
        HealthBarListener invalid = HealthBarListener.INVALID; // Returns -1 (invalid)
    }
}

// Usage in layout YAML:
// images:
//   1:
//     image: armor_bar
//     listener:
//       class: armor_percentage

```

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

### Access BetterHealthBar3 Plugin Instance (Java)

Source: https://context7.com/toxicity188/betterhealthbar3/llms.txt

Obtain the main BetterHealthBar3 plugin instance in your Java plugin to access its various managers and functionalities. This is the primary entry point for interacting with the plugin's API.

```java
import kr.toxicity.healthbar.api.BetterHealthBar;
import kr.toxicity.healthbar.api.manager.*;

public class MyPlugin extends JavaPlugin {

    @Override
    public void onEnable() {
        // Get BetterHealthBar instance
        BetterHealthBar healthBar = BetterHealthBar.inst();

        // Access various managers
        HealthBarManager healthBarManager = healthBar.healthBarManager();
        PlayerManager playerManager = healthBar.playerManager();
        MobManager mobManager = healthBar.mobManager();
        ListenerManager listenerManager = healthBar.listenerManager();
        ConfigManager configManager = healthBar.configManager();
        ImageManager imageManager = healthBar.imageManager();
        LayoutManager layoutManager = healthBar.layoutManager();
        TextManager textManager = healthBar.textManager();

        // Check environment
        boolean isPaper = healthBar.isPaper();
        boolean isFolia = healthBar.isFolia();

        // Trigger plugin reload
        healthBar.reload();
    }
}

```

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

### Define Layouts for Health Bars (YAML)

Source: https://context7.com/toxicity188/betterhealthbar3/llms.txt

This YAML snippet defines the visual layout of a health bar by combining images and text elements. It supports conditional display of images based on health percentage and links text elements to dynamic data like entity names and health values using listeners and patterns.

```yaml
# BetterHealthBar/layouts/default_layout.yml
default_layout:
  images:
    1:
      image: background_bar
      layer: 0
    2:
      image: health_bar
      listener:
        class: health  # Links to health percentage
      layer: 1
    3:
      image: damage_indicator
      listener:
        class: health_before  # Shows damage animation
      layer: 2
    4:
      image: yellow_warning
      listener:
        class: health
      conditions:
        1:
          first: health_percentage
          second: 0.33
          operation: ">="
        2:
          first: health_percentage
          second: 0.66
          operation: "<"
      layer: 1
  texts:
    1:
      text: custom_font
      pattern: "[entity_name]"
      align: center
      x: 60
      y: 20
      scale: 0.5
      layer: 3
    2:
      text: number_font
      pattern: "<red>[health]</red>/<gray>[max_health]</gray>"
      align: center
      x: 60
      y: -5
      scale: 0.4
      layer: 3
```

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

### Java API - Handle HealthBarCreateEvent

Source: https://context7.com/toxicity188/betterhealthbar3/llms.txt

Listen to HealthBarCreateEvent to modify health bar behavior or cancel their display. This event provides access to the HealthBar, Player, and Entity involved. It allows for conditional cancellation and adding rendering predicates. Dependencies include the BetterHealthBar API classes.

```java
import kr.toxicity.healthbar.api.event.HealthBarCreateEvent;
import kr.toxicity.healthbar.api.entity.HealthBarEntity;
import kr.toxicity.healthbar.api.healthbar.HealthBar;
import kr.toxicity.healthbar.api.player.HealthBarPlayer;
import org.bukkit.entity.EntityType;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;

public class HealthBarEventListener implements Listener {

    @EventHandler
    public void onHealthBarCreate(HealthBarCreateEvent event) {
        // Get event data
        HealthBar healthBar = event.getHealthBar();
        HealthBarPlayer player = event.getPlayer();
        HealthBarEntity entity = event.getEntity();

        // Cancel health bar for specific conditions
        if (entity.entity().getType() == EntityType.VILLAGER) {
            event.setCancelled(true);
            return;
        }

        // Add additional predicates that are checked during rendering
        event.addPredicate(e -> {
            // Only show if entity health is above 50%
            double healthPercent = e.getEntity().entity().getHealth() /
                                   e.getEntity().entity().getAttribute(
                                       org.bukkit.attribute.Attribute.GENERIC_MAX_HEALTH
                                   ).getValue();
            return healthPercent > 0.5;
        });

        // Check if player has permission
        if (!player.player().hasPermission("healthbar.view.boss")) {
            if (healthBar.name().equals("boss_healthbar")) {
                event.setCancelled(true);
            }
        }
    }
}
```

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

### Specify Applicable Mob Types for Health Bar

Source: https://github.com/toxicity188/betterhealthbar3/wiki/healthbars

Defines the specific mob types for which a health bar should be displayed. This ensures the health bar only appears on designated mobs.

```yaml
applicable-types:
  - some_type
```

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

### Define Health Bars (YAML)

Source: https://context7.com/toxicity188/betterhealthbar3/llms.txt

This YAML defines custom health bars for mobs. It specifies which mob types they apply to, scaling, visibility triggers (like taking damage or player looking), and which layouts and effect groups to use. This allows for distinct health bar appearances for different mob categories.

```yaml
# BetterHealthBar/healthbars/default_healthbar.yml
default_healthbar:
  default: true  # Use as default health bar for all mobs
  applicable-types: []  # Leave empty for all types, or specify custom types
  scale:
    x: 0.75
    y: 0.75
    z: 0.75
  triggers:
    - damage  # Show when mob takes damage
    - look    # Show when player looks at mob
  groups:
    - default_layout
    - mob_effect_absorption

# Custom health bar for boss mobs
boss_healthbar:
  default: false
  applicable-types:
    - boss
    - elite
  scale:
    x: 1.0
    y: 1.0
    z: 1.0
  triggers:
    - damage
    - look
    - move  # Also show when mob moves
  groups:
    - boss_layout
    - boss_effects
```

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