### Create a Shop NPC with ZNPCsPlus API

Source: https://context7.com/pyrbu/znpcsplus/llms.txt

This Java snippet demonstrates setting up a shop NPC. It includes getting NPC types and worlds, creating the NPC, setting its skin and look behavior, configuring its hologram, and adding interaction actions. Ensure ZNPCsPlus is loaded before executing this code.

```java
import lol.pyr.znpcsplus.api.NpcApiProvider;
import lol.pyr.znpcsplus.api.NpcApi;
import lol.pyr.znpcsplus.api.entity.EntityProperty;
import lol.pyr.znpcsplus.api.interaction.*;
import lol.pyr.znpcsplus.api.npc.*;
import lol.pyr.znpcsplus.api.skin.SkinDescriptor;
import lol.pyr.znpcsplus.util.LookType;
import lol.pyr.znpcsplus.util.NpcLocation;
import org.bukkit.Bukkit;
import org.bukkit.World;
import org.bukkit.plugin.java.JavaPlugin;

public class ShopNpcExample extends JavaPlugin {

    @Override
    public void onEnable() {
        // Wait for ZNPCsPlus to load
        Bukkit.getScheduler().runTaskLater(this, this::createShopNpc, 20L);
    }

    private void createShopNpc() {
        NpcApi api = NpcApiProvider.get();

        // 1. Get type and world
        NpcType playerType = api.getNpcTypeRegistry().getByName("player");
        World world = Bukkit.getWorld("world");

        if (playerType == null || world == null) {
            getLogger().severe("Failed to create shop NPC!");
            return;
        }

        // 2. Create the NPC
        NpcLocation location = new NpcLocation(100.5, 65, 200.5, 180, 0);
        NpcEntry entry = api.getNpcRegistry().create("shop", world, playerType, location);
        entry.enableEverything();

        Npc npc = entry.getNpc();

        // 3. Set skin
        SkinDescriptor skin = api.getSkinDescriptorFactory().createStaticDescriptor("Notch");
        EntityProperty<SkinDescriptor> skinProp = 
            api.getPropertyRegistry().getByName("skin", SkinDescriptor.class);
        npc.setProperty(skinProp, skin);

        // 4. Set look behavior
        EntityProperty<LookType> lookProp = 
            api.getPropertyRegistry().getByName("look", LookType.class);
        npc.setProperty(lookProp, LookType.CLOSEST_PLAYER);

        // 5. Set up hologram
        npc.getHologram().addLine("&6&lSHOP");
        npc.getHologram().addLine("&7Right-click to browse");
        npc.getHologram().addLine("&e%server_online% &7players online");
        npc.getHologram().setRefreshDelay(100); // Refresh every 5 seconds

        // 6. Add actions
        ActionFactory actionFactory = api.getActionFactory();

        // Welcome message
        npc.addAction(actionFactory.createMessageAction(
            "&6Welcome to the shop, &e%player_name%&6!",
            InteractionType.RIGHT_CLICK, 0, 0
        ));

        // Open shop command
        npc.addAction(actionFactory.createPlayerCommandAction(
            "shop open",
            InteractionType.RIGHT_CLICK, 1, 10
        ));

        // 7. Save changes
        api.getNpcRegistry().save();

        getLogger().info("Shop NPC created successfully!");
    }
}
```

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

### NPC Skin Management

Source: https://github.com/pyrbu/znpcsplus/wiki/API

Examples of how to create and apply different types of skins to NPCs.

```APIDOC
## Static Skin (Using a Texture value and signature)

### Description
Creates a static skin descriptor using a texture URL and a signature.

### Method
`createStaticDescriptor(String textureValue, String signature)`

### Request Example
```java
SkinDescriptor staticTextureDescriptor = npcAPI.getSkinDescriptorFactory().createStaticDescriptor("ewogICJ0aW1lc3RhbXAiIDogMTczNTExNzEzNzY0MSwKICAicHJvZmlsZUlkIiA6ICIxNmQ4NjI4NzYzMWY0NDY2OGQ0NDM2ZTJlY2IwNTllNSIsCiAgInByb2ZpbGVOYW1lIiA6ICJSZXphVG91cm5leSIsCiAgInNpZ25hdHVyZVJlcXVpcmVkIiA6IHRydWUsCiAgInRleHR1cmVzIiA6IHsKICAgICJTS0lOIiA6IHsKICAgICAgInVybCIgOiAiaHR0cDovL3RleHR1cmVzLm1pbmVjcmFmdC5uZXQvdGV4dHVyZS81ODc0Nzk0OWMxOTUyMWEwYTAwOTgwYjNhMGVkODJjYzIzNmVkMjc5OWIzMGNiZDY4Nzk1ZGNiMDg5NTE5Y2NhIiwKICAgICAgIm1ldGFkYXRhIiA6IHsKICAgICAgICAibW9kZWwiIDogInNsaW0iCiAgICAgIH0KICAgIH0KICB9Cn0=", "ZzIpWZCCCT6H95QQk0SCwF8hWjWL+J764KqH8hhpmTl5SfCHnoj8W4wZnPevrO+q213NgzGmZVEVucR16stX/39+H+NmLFILOBh+FDbRQgEhheyZGYEIj+25gvKRHddHW5eLIS+fOrXDXFffktLR8ImEtFQzFNWVQ8YHb6jmth2OUJgVTxz76UYZ0RVo/8dYbARijWyypTc95+8rOImoJl2f77qiIsPptxeorHdJ6+i0LfFQnbQzGO9GDVjShso/B1UMdoFEITO4MVG8RYpV7F1Awd7891N2vdhIAPWptIADAK/VFU6HG5dyOJoB8FEjPK5vpV/qaH5MQ5JqO2tjT6re1BEeKamymRX+LsgNJYq360gJAsf93tR1Q7oI8GtJ/6KGymGNRH5X6dPVNAgIx6yRvqbBDFW12bYlWFGvdY3kTYn50xe5oFtm6gas5CHJdnGL86m4iunNVtE7GKvYrXtxcAEP2HzfZ5b4eOyK5LOi8A55Z2rNmCKn/5YPX50OjpooNsZivrOvu4+qrs7EMa7JOqqKeq8WE+duLykJr1qXoURY4cz7JDGqHLJrE7E2FaQf4JoMdzdxNZIfvwFzhIh9TcQ/6iSOf439lc54d6vJuGcXLXBjmSq7GNAawxNTy7d3V/Bo0bnrQEh1EKE1LlkUP3ubnw+CW7jJcx9pPd8");
```

```APIDOC
## Dynamic/Refreshing Skin (Using static player name)

### Description
Creates a dynamic skin descriptor that refreshes based on a static player name.

### Method
`createRefreshingDescriptor(String playerName)`

### Request Example
```java
SkinDescriptor dynamicSteveDescriptor = npcAPI.getSkinDescriptorFactory().createRefreshingDescriptor("Steve");
```
```

```APIDOC
## Dynamic/Refreshing Skin (Using placeholder)

### Description
Creates a dynamic skin descriptor that refreshes using a placeholder for player names.

### Method
`createRefreshingDescriptor(String placeholder)`

### Request Example
```java
SkinDescriptor dynamicPlaceholderDescriptor = npcAPI.getSkinDescriptorFactory().createRefreshingDescriptor("%top_player_1_name%");
```
```

```APIDOC
## URL Skin

### Description
Creates a skin descriptor from a URL.

### Method
`createUrlDescriptor(String url, String model)`

### Request Example
```java
SkinDescriptor urlDescriptor = npcApi.getSkinDescriptorFactory().createUrlDescriptor("https://www.minecraftskins.com/uploads/skins/2024/12/24/iceman-22953593.png?v737", "slim");
```
```

```APIDOC
## File Skin

### Description
Creates a skin descriptor from a local file. The file should be located in `./plugins/ZNPCsPlus/skins`.

### Method
`createFileDescriptor(String fileName)`

### Request Example
```java
SkinDescriptor fileDescriptor = npcAPI.getSkinDescriptorFactory().createFileDescriptor("skin2.png");
```
```

```APIDOC
## Applying the Skin

### Description
Applies a created skin descriptor to an NPC.

### Method
`npc.setProperty(EntityProperty<SkinDescriptor> property, SkinDescriptor descriptor)`

### Request Example
```java
// Get the "skin" property
EntityProperty<SkinDescriptor> skinProperty = npcApi.getPropertyRegistry().getByName("skin", SkinDescriptor.class);

// Apply the skin to the NPC
playerNpc.getNpc().setProperty(skinProperty, staticSteveDescriptor);
```
```

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

### NPC Serialization and Deserialization

Source: https://github.com/pyrbu/znpcsplus/wiki/API

Examples for saving NPCs to YAML format and loading them back.

```APIDOC
## Serializing an NPC

### Description
Saves an NPC to a YAML configuration format.

### Method
`npcSerializer.serialize(NpcEntry npcEntry)`

### Request Example
```java
NpcSerializer<YamlConfiguration> yamlSerializer = npcApi.getNpcSerializerRegistry().getSerializer(YamlConfiguration.class);
YamlConfiguration serializedPlayerNpc = yamlSerializer.serialize(playerNpc);
```
```

```APIDOC
## Deserializing and Registering an NPC

### Description
Loads an NPC from a YAML configuration and registers it with the NPC registry.

### Method
`npcSerializer.deserialize(YamlConfiguration yamlConfig)` and `npcApi.getNpcRegistry().register(NpcEntry npcEntry)`

### Request Example
```java
NpcEntry deserializedPlayerNpc = yamlSerializer.deserialize(serializedPlayerNpc);
pcApi.getNpcRegistry().register(deserializedPlayerNpc);
```
```

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

### Setup NPC Hologram Lines

Source: https://context7.com/pyrbu/znpcsplus/llms.txt

Clears existing hologram lines and adds new text and item lines to an NPC. Supports MiniMessage, legacy color codes, and PlaceholderAPI.

```java
import lol.pyr.znpcsplus.api.NpcApiProvider;
import lol.pyr.znpcsplus.api.hologram.Hologram;
import lol.pyr.znpcsplus.api.npc.NpcEntry;

public class NpcHologramManager {

    public void setupHologram(String npcId) {
        NpcEntry entry = NpcApiProvider.get().getNpcRegistry().getById(npcId);
        if (entry == null) return;

        Hologram hologram = entry.getNpc().getHologram();

        // Clear existing lines
        hologram.clearLines();

        // Add text lines (supports MiniMessage format and legacy color codes)
        hologram.addLine("&6&lSHOP NPC");
        hologram.addLine("&7Click to open the shop");
        hologram.addLine("&eOnline: &f%server_online%"); // PlaceholderAPI support

        // Add an item line (displays floating item)
        hologram.addLine("item:diamond_sword");
    }

    public void insertLine(String npcId, int index, String text) {
        NpcEntry entry = NpcApiProvider.get().getNpcRegistry().getById(npcId);
        if (entry != null) {
            // Insert at specific position (0 = top)
            entry.getNpc().getHologram().insertLine(index, text);
        }
    }

    public void removeLine(String npcId, int index) {
        NpcEntry entry = NpcApiProvider.get().getNpcRegistry().getById(npcId);
        if (entry != null) {
            entry.getNpc().getHologram().removeLine(index);
        }
    }

    public void setRefreshRate(String npcId, long delayTicks) {
        NpcEntry entry = NpcApiProvider.get().getNpcRegistry().getById(npcId);
        if (entry != null) {
            // Set how often placeholder text refreshes (-1 = never)
            entry.getNpc().getHologram().setRefreshDelay(delayTicks);
        }
    }

    public void printHologramInfo(String npcId) {
        NpcEntry entry = NpcApiProvider.get().getNpcRegistry().getById(npcId);
        if (entry == null) return;

        Hologram hologram = entry.getNpc().getHologram();
        System.out.println("Hologram has " + hologram.lineCount() + " lines:");

        for (int i = 0; i < hologram.lineCount(); i++) {
            System.out.println("  Line " + i + ": " + hologram.getLine(i));
        }

        System.out.println("Refresh delay: " + hologram.getRefreshDelay() + " ticks");
    }
}
```

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

### Create Refreshing Skin Descriptor

Source: https://github.com/pyrbu/znpcsplus/wiki/API

Use this to create a skin descriptor that dynamically updates based on a player's name or a placeholder. The name 'Steve' is used as an example.

```java
SkinDescriptor dynamicSteveDescriptor = npcAPI.getSkinDescriptorFactory().createRefreshingDescriptor("Steve");
```

```java
SkinDescriptor dynamicPlaceholderDescriptor = npcAPI.getSkinDescriptorFactory().createRefreshingDescriptor("%top_player_1_name%");
```

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

### Getting ZNPCsPlus API Instance in a Java Plugin

Source: https://context7.com/pyrbu/znpcsplus/llms.txt

Obtain the ZNPCsPlus API instance using `NpcApiProvider.get()` to access NPC registries and factories. This code should be placed within your plugin's `onEnable` method.

```java
import lol.pyr.znpcsplus.api.NpcApi;
import lol.pyr.znpcsplus.api.NpcApiProvider;
import lol.pyr.znpcsplus.api.npc.NpcRegistry;
import lol.pyr.znpcsplus.api.npc.NpcTypeRegistry;
import lol.pyr.znpcsplus.api.entity.EntityPropertyRegistry;

public class MyPlugin extends JavaPlugin {

    @Override
    public void onEnable() {
        // Get the main API instance
        NpcApi npcApi = NpcApiProvider.get();

        // Access various registries
        NpcRegistry npcRegistry = npcApi.getNpcRegistry();           // Create/manage NPCs
        NpcTypeRegistry typeRegistry = npcApi.getNpcTypeRegistry();  // Get NPC types
        EntityPropertyRegistry propRegistry = npcApi.getPropertyRegistry(); // Get/set properties

        getLogger().info("ZNPCsPlus API loaded successfully!");
    }
}
```

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

### Configure NPC Skins using SkinDescriptorFactory

Source: https://context7.com/pyrbu/znpcsplus/llms.txt

Demonstrates various methods to create and apply different skin types including static, dynamic, mirror, URL, and file-based skins.

```java
import lol.pyr.znpcsplus.api.NpcApiProvider;
import lol.pyr.znpcsplus.api.NpcApi;
import lol.pyr.znpcsplus.api.entity.EntityProperty;
import lol.pyr.znpcsplus.api.npc.NpcEntry;
import lol.pyr.znpcsplus.api.skin.SkinDescriptor;
import lol.pyr.znpcsplus.api.skin.SkinDescriptorFactory;

public class NpcSkinManager {

    public void setStaticSkin(String npcId, String playerName) {
        NpcApi api = NpcApiProvider.get();
        SkinDescriptorFactory factory = api.getSkinDescriptorFactory();

        // Static skin - fetched once from the player name, won't update
        SkinDescriptor skin = factory.createStaticDescriptor(playerName);
        applySkin(npcId, skin);
    }

    public void setStaticSkinFromTexture(String npcId, String textureValue, String signature) {
        NpcApi api = NpcApiProvider.get();
        SkinDescriptorFactory factory = api.getSkinDescriptorFactory();

        // Static skin from raw texture data (e.g., from Minecraft profile)
        SkinDescriptor skin = factory.createStaticDescriptor(textureValue, signature);
        applySkin(npcId, skin);
    }

    public void setDynamicSkin(String npcId, String playerName) {
        NpcApi api = NpcApiProvider.get();
        SkinDescriptorFactory factory = api.getSkinDescriptorFactory();

        // Dynamic skin - updates when the player changes their skin
        // Also supports PlaceholderAPI placeholders
        SkinDescriptor skin = factory.createRefreshingDescriptor(playerName);
        applySkin(npcId, skin);
    }

    public void setMirrorSkin(String npcId) {
        NpcApi api = NpcApiProvider.get();
        SkinDescriptorFactory factory = api.getSkinDescriptorFactory();

        // Mirror skin - shows each viewer their own skin
        SkinDescriptor skin = factory.createMirrorDescriptor();
        applySkin(npcId, skin);
    }

    public void setUrlSkin(String npcId, String url, boolean slim) {
        NpcApi api = NpcApiProvider.get();
        SkinDescriptorFactory factory = api.getSkinDescriptorFactory();

        // URL skin - downloads skin from URL
        // Variant: "classic" for 4-pixel arms, "slim" for 3-pixel arms (Alex style)
        String variant = slim ? "slim" : "classic";
        SkinDescriptor skin = factory.createUrlDescriptor(url, variant);
        applySkin(npcId, skin);
    }

    public void setFileSkin(String npcId, String filename) {
        NpcApi api = NpcApiProvider.get();
        SkinDescriptorFactory factory = api.getSkinDescriptorFactory();

        // File skin - loads from ./plugins/ZNPCsPlus/skins/
        SkinDescriptor skin = factory.createFileDescriptor(filename);
        applySkin(npcId, skin);
    }

    private void applySkin(String npcId, SkinDescriptor skin) {
        NpcApi api = NpcApiProvider.get();
        NpcEntry entry = api.getNpcRegistry().getById(npcId);
        EntityProperty<SkinDescriptor> skinProperty =
            api.getPropertyRegistry().getByName("skin", SkinDescriptor.class);

        if (entry != null && skinProperty != null) {
            entry.getNpc().setProperty(skinProperty, skin);
        }
    }
}
```

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

### Initialize NpcApi

Source: https://github.com/pyrbu/znpcsplus/wiki/API

Obtain the primary API instance to begin interacting with the plugin.

```java
NpcApi npcApi = NpcApiProvider.get();
```

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

### Create File Skin Descriptor

Source: https://github.com/pyrbu/znpcsplus/wiki/API

Create a skin descriptor from a local image file. The file must be placed in the './plugins/ZNPCsPlus/skins' directory.

```java
SkinDescriptor fileDescriptor = npcAPI.getSkinDescriptorFactory().createFileDescriptor("skin2.png");
```

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

### Configure Gradle Repository

Source: https://github.com/pyrbu/znpcsplus/wiki/API

Add the ZNPCsPlus repository to your build.gradle file.

```gradle
maven {
    name "pyrSnapshots"
    url "https://repo.pyr.lol/snapshots"
}
```

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

### Display Version

Source: https://github.com/pyrbu/znpcsplus/wiki/Commands

Shows the current version of the ZNPCsPlus plugin, including build information.

```command
/npc version
```

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

### Other Znpcsplus Commands

Source: https://context7.com/pyrbu/znpcsplus/llms.txt

Commands for reloading configuration and checking the plugin version.

```bash
/npc reloadconfig
```

```bash
/npc version
```

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

### Entity Configuration Reference

Source: https://github.com/pyrbu/znpcsplus/wiki/NPC-Types

A list of supported NPC entities and their configurable properties.

```APIDOC
## Entity Configuration

### goat
- **Since Plugin Version:** v2.0.0
- **Minecraft Versions:** 1.17+
- **Available Properties:** has_left_horn, has_right_horn

### allay
- **Since Plugin Version:** v2.0.0
- **Minecraft Versions:** 1.19+
- **Available Properties:** hand, offhand

### frog
- **Since Plugin Version:** v2.0.0
- **Minecraft Versions:** 1.19+
- **Available Properties:** frog_variant, frog_target_npc

### tadpole
- **Since Plugin Version:** v2.0.0
- **Minecraft Versions:** 1.19+

### warden
- **Since Plugin Version:** v2.0.0
- **Minecraft Versions:** 1.19+
- **Available Properties:** warden_anger

### sniffer
- **Since Plugin Version:** v2.0.0
- **Minecraft Versions:** 1.20+
- **Available Properties:** sniffer_state

### camel
- **Since Plugin Version:** v2.0.0
- **Minecraft Versions:** 1.20+
- **Available Properties:** bashing, camel_sitting

### armadillo
- **Since Plugin Version:** v2.0.0
- **Minecraft Versions:** 1.20.5+
- **Available Properties:** armadillo_state

### bogged
- **Since Plugin Version:** v2.0.0
- **Minecraft Versions:** 1.21+
- **Available Properties:** bogged_sheared, entity_sitting

### breeze
- **Since Plugin Version:** v2.0.0
- **Minecraft Versions:** 1.21+

### creaking
- **Since Plugin Version:** v2.0.0
- **Minecraft Versions:** 1.21.2+
- **Available Properties:** creaking_active, creaking_crumbling (1.21.4+)
```

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

### Apply Skin to NPC

Source: https://github.com/pyrbu/znpcsplus/wiki/API

This snippet shows how to retrieve the 'skin' property from the registry and apply a created SkinDescriptor to an NPC.

```java
// Get the "skin" property
EntityProperty<SkinDescriptor> skinProperty = npcApi.getPropertyRegistry().getByName("skin", SkinDescriptor.class);

// Apply the skin to the NPC
playerNpc.getNpc().setProperty(skinProperty, staticSteveDescriptor);
```

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

### Import NPC Data Commands

Source: https://github.com/pyrbu/znpcsplus/wiki/Converting

Use these commands to import NPC data from various plugins. Ensure the source plugin data files are present in their respective directories.

```markdown
/npc storage import znpcs
```

```markdown
/npc storage import znpcsplus_legacy
```

```markdown
/npc storage import citizens
```

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

### Manage Player NPC Skins

Source: https://context7.com/pyrbu/znpcsplus/llms.txt

Commands to set static or dynamic skins from player names, mirror the viewer's skin, or use a skin from a URL.

```bash
/npc skin <id> static <player>   # Static skin from player name
```

```bash
/npc skin <id> dynamic <player>  # Dynamic skin (updates when player changes skin)
```

```bash
/npc skin <id> mirror            # Mirror viewer's skin
```

```bash
/npc skin <id> url <variant> <url>  # Skin from URL (classic/slim)
```

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

### Create URL Skin Descriptor

Source: https://github.com/pyrbu/znpcsplus/wiki/API

Create a skin descriptor directly from a URL. The second argument specifies the skin model, e.g., 'slim'.

```java
SkinDescriptor urlDescriptor = npcApi.getSkinDescriptorFactory().createUrlDescriptor("https://www.minecraftskins.com/uploads/skins/2024/12/24/iceman-22953593.png?v737", "slim");
```

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

### Configure Maven Repository

Source: https://github.com/pyrbu/znpcsplus/wiki/API

Add the ZNPCsPlus repository to your pom.xml to resolve dependencies.

```xml
<repository>
  <id>pyr-snapshots</id>
  <name>Pyr's Repo</name>
  <url>https://repo.pyr.lol/snapshots</url>
</repository>
```

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

### Reload Configuration

Source: https://github.com/pyrbu/znpcsplus/wiki/Commands

Refreshes the ZNPCsPlus configuration settings without requiring a server restart.

```command
/npc reloadconfig
```

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

### ZNPCsPlus Storage Commands

Source: https://github.com/pyrbu/znpcsplus/blob/2.X/plugin/src/main/resources/messages/storage.txt

Commands for managing NPC storage.

```APIDOC
## ZNPCsPlus Storage Commands

### Description
Commands for managing NPC storage.

### Commands

#### `/npc storage save`
Saves the current NPC storage.

#### `/npc storage reload`
Reloads the NPC storage.

#### `/npc storage import <importer>`
Imports NPC data from a specified importer.
- **importer** (string) - Required - The name of the importer to use.

#### `/npc storage migrate <from> <to> [force]`
Migrates NPC data from one format to another.
- **from** (string) - Required - The source format.
- **to** (string) - Required - The target format.
- **force** (boolean) - Optional - Whether to force the migration.
```

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

### Create and Assign Interaction Actions

Source: https://github.com/pyrbu/znpcsplus/wiki/API

Define an interaction action and attach it to an NPC.

```java
// Create an action that sends a message when left-clicked
InteractionAction action = npcApi.getActionFactory().createMessageAction(
    "Hello, world!", // Message
    InteractionType.LEFT_CLICK, // Interaction type
    5, // Cooldown in seconds
    0 // Delay in ticks
);

// Assign the action to the NPC
zombieNpc.getNpc().addAction(action);
```

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

### Configure Gradle Dependency

Source: https://github.com/pyrbu/znpcsplus/wiki/API

Include the ZNPCsPlus API dependency in your build.gradle file.

```gradle
compileOnly "lol.pyr:znpcsplus-api:{version}"
```

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

### Configure NPC Skins

Source: https://github.com/pyrbu/znpcsplus/wiki/API

Define skin descriptors for player-type NPCs.

```java
SkinDescriptor mirrorDescriptor = npcApi.getSkinDescriptorFactory().createMirrorDescriptor();
```

```java
SkinDescriptor staticSteveDescriptor = npcApi.getSkinDescriptorFactory().createStaticDescriptor("steve");
```

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

### Create and Register NPC

Source: https://github.com/pyrbu/znpcsplus/wiki/API

Instantiate and configure an NPC. Enabling 'processed' is required for standard features like look behavior and visibility.

```java
NpcEntry playerNpc = npcApi.getNpcRegistry().create(
    "npc1", // NPC ID
    Bukkit.getWorlds().get(0), // World instance
    playerNpcType, // NPC type
    new NpcLocation(0, 100, 0, 0, 0) // x, y, z, yaw, pitch
);

// Enable the NPC to be processed by the plugin
playerNpc.setProcessed(true);
/*
 * If you need custom logic for NPC visibility per player, keep "processed" disabled.
 * Note: Disabling "processed" will prevent certain properties (e.g., look behavior, 
 * view distance, permission-based visibility, and knockback properties) from functioning.
 */

// Enable the NPC to be saved in the plugins storage
playerNpc.setSave(true);

// Enable the NPC to be modified by commands
playerNpc.setAllowCommandModification(true);

// Alternatively, you can use the following method to enable all of the above at once
playerNpc.enableEverything();
```

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

### Entity Configuration Properties

Source: https://github.com/pyrbu/znpcsplus/wiki/NPC-Types

Reference for entity types and their associated configurable properties.

```APIDOC
## Entity Properties Reference

### Description
This reference lists the available properties for various entities supported by ZNPCsPlus (v2.0.0+).

### Entities
- **skeleton**: helmet, chestplate, leggings, boots, hand, offhand, entity_sitting, skeleton_type (1.8-1.10)
- **slime**: size
- **snow_golem**: derpy_snowgolem
- **villager**: hand, villager_type, villager_profession, villager_level
- **witch**: hand
- **wither**: invulnerable_time
- **wolf**: wolf_begging, wolf_collar, wolf_angry, tamed, sitting, wolf_variant (1.20.5+)
- **zombie**: helmet, chestplate, leggings, boots, hand, offhand, entity_sitting
- **zombified_piglin**: helmet, chestplate, leggings, boots, hand, offhand, entity_sitting
- **shulker**: attach_direction, shield_height, shulker_color
- **polar_bear**: polar_bear_standing
- **donkey**: has_chest
- **mule**: has_chest
- **elder_guardian**: is_retracting_spikes

### Note
Entities such as skeleton_horse, spider, squid, and zombie_horse have no configurable properties listed.
```

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

### Create and Delete NPCs

Source: https://context7.com/pyrbu/znpcsplus/llms.txt

Commands to create, delete, and list NPCs. Specify NPC ID and type during creation.

```bash
/npc create <id> <type>          # Create NPC: /npc create shop_npc player
```

```bash
/npc delete <id>                 # Delete NPC: /npc delete shop_npc
```

```bash
/npc clone <source_id> <new_id>  # Clone NPC: /npc clone shop_npc shop_npc_2
```

```bash
/npc list                        # List all NPCs
```

```bash
/npc changeid <old> <new>        # Rename NPC: /npc changeid old_npc new_npc
```

```bash
/npc toggle <id>                 # Toggle visibility
```

```bash
/npc type <id> <type>            # Change type: /npc type my_npc zombie
```

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

### Configure Maven Dependency

Source: https://github.com/pyrbu/znpcsplus/wiki/API

Include the ZNPCsPlus API dependency in your project.

```xml
<dependency>
  <groupId>lol.pyr</groupId>
  <artifactId>znpcsplus-api</artifactId>
  <version>{version}</version>
  <scope>provided</scope>
</dependency>
```

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

### Create Static Skin Descriptor

Source: https://github.com/pyrbu/znpcsplus/wiki/API

Use this to create a skin descriptor from a texture value and signature. Ensure the texture value and signature are correctly formatted.

```java
SkinDescriptor staticTextureDescriptor = npcAPI.getSkinDescriptorFactory().createStaticDescriptor("ewogICJ0aW1lc3RhbXAiIDogMTczNTExNzEzNzY0MSwKICAicHJvZmlsZUlkIiA6ICIxNmQ4NjI4NzYzMWY0NDY2OGQ0NDM2ZTJlY2IwNTllNSIsCiAgInByb2ZpbGVOYW1lIiA6ICJSZXphVG91cm5leSIsCiAgInNpZ25hdHVyZVJlcXVpcmVkIiA6IHRydWUsCiAgInRleHR1cmVzIiA6IHsKICAgICJTS0lOIiA6IHsKICAgICAgInVybCIgOiAiaHR0cDovL3RleHR1cmVzLm1pbmVjcmFmdC5uZXQvdGV4dHVyZS81ODc0Nzk0OWMxOTUyMWEwYTAwOTgwYjNhMGVkODJjYzIzNmVkMjc5OWIzMGNiZDY4Nzk1ZGNiMDg5NTE5Y2NhIiwKICAgICAgIm1ldGFkYXRhIiA6IHsKICAgICAgICAibW9kZWwiIDogInNsaW0iCiAgICAgIH0KICAgIH0KICB9Cn0=", "ZzIpWZCCCT6H95QQk0SCwF8hWjWL+J764KqH8hhpmTl5SfCHnoj8W4wZnPevrO+q213NgzGmZVEVucR16stX/39+H+NmLFILOBh+FDbRQgEhheyZGYEIj+25gvKRHddHW5eLIS+fOrXDXFffktLR8ImEtFQzFNWVQ8YHb6jmth2OUJgVTxz76UYZ0RVo/8dYbARijWyypTc95+8rOImoJl2f77qiIsPptxeorHdJ6+i0LfFQnbQzGO9GDVjShso/B1UMdoFEITO4MVG8RYpV7F1Awd7891N2vdhIAPWptIADAK/VFU6HG5dyOJoB8FEjPK5vpV/qaH5MQ5JqO2tjT6re1BEeKamymRX+LsgNJYq360gJAsf93tR1Q7oI8GtJ/6KGymGNRH5X6dPVNAgIx6yRvqbBDFW12bYlWFGvdY3kTYn50xe5oFtm6gas5CHJdnGL86m4iunNVtE7GKvYrXtxcAEP2HzfZ5b4eOyK5LOi8A55Z2rNmCKn/5YPX50OjpooNsZivrOvu4+qrs7EMa7JOqqKeq8WE+duLykJr1qXoURY4cz7JDGqHLJrE7E2FaQf4JoMdzdxNZIfvwFzhIh9TcQ/6iSOf439lc54d6vJuGcXLXBjmSq7GNAawxNTy7d3V/Bo0bnrQEh1EKE1LlkUP3ubnw+CW7jJcx9pPd8=");
```

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

### Create NPC

Source: https://github.com/pyrbu/znpcsplus/wiki/Commands

Use this command to create a new NPC. Specify a unique ID and the NPC type. Refer to the NPC-Types documentation for a list of available types.

```command
/npc create <id> <type>
```

```command
/npc create my_npc zombie
```

```command
/npc create npc1 player
```

```command
/npc create shop_npc villager
```

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

### List All NPCs

Source: https://github.com/pyrbu/znpcsplus/wiki/Commands

Displays a list of all NPCs currently present in the world.

```command
/npc list
```

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

### NPC Storage Commands

Source: https://context7.com/pyrbu/znpcsplus/llms.txt

Utilize these commands for saving, reloading, importing, or migrating NPC data.

```bash
/npc storage save
```

```bash
/npc storage reload
```

```bash
/npc storage import <importer>
```

```bash
/npc storage migrate <from> <to>
```

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

### Maven Repository Configuration for ZNPCsPlus API

Source: https://context7.com/pyrbu/znpcsplus/llms.txt

Add the ZNPCsPlus API to your project's Maven dependencies. Ensure you use the provided repository for snapshot versions.

```xml
<repository>
  <id>pyr-snapshots</id>
  <name>Pyr's Repo</name>
  <url>https://repo.pyr.lol/snapshots</url>
</repository>

<dependency>
  <groupId>lol.pyr</groupId>
  <artifactId>znpcsplus-api</artifactId>
  <version>2.1.0-SNAPSHOT</version>
  <scope>provided</scope>
</dependency>
```

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

### Add NPC Actions

Source: https://context7.com/pyrbu/znpcsplus/llms.txt

Define actions for NPCs to perform when interacted with. Specify action type, click type, cooldown, delay, and associated value.

```bash
/npc action add message shop_npc ANY_CLICK 5 0 &6Welcome to the shop!
```

```bash
/npc action add playercommand warp_npc RIGHT_CLICK 3 0 warp spawn
```

```bash
/npc action add consolecommand reward_npc LEFT_CLICK 60 0 give %player_name% diamond 1
```

```bash
/npc action add switchserver hub_npc ANY_CLICK 10 0 lobby
```

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

### NPC Storage Commands

Source: https://github.com/pyrbu/znpcsplus/wiki/Commands

Commands for managing the storage and persistence of NPCs.

```APIDOC
## /npc storage save

### Description
Saves all NPCs to their configured storage.

### Method
POST (conceptual, command-line execution)

### Endpoint
`/npc storage save`

### Request Example
```
/npc storage save
```
```

```APIDOC
## /npc storage reload

### Description
Reloads all NPCs from their configured storage.

### Method
GET (conceptual, command-line execution)

### Endpoint
`/npc storage reload`

### Request Example
```
/npc storage reload
```
```

```APIDOC
## /npc storage import <importer>

### Description
Imports NPCs from the specified importer.

### Method
POST (conceptual, command-line execution)

### Endpoint
`/npc storage import <importer>`

### Parameters
#### Path Parameters
- **importer** (string) - Required - The name or type of the importer to use.

### Notes
Refer to the [Converting](Converting) page for more information on importers.

### Request Example
```
/npc storage import YAML
```
```

```APIDOC
## /npc storage migrate <from> <to> [force]

### Description
Migrates NPCs from one storage type to another. This command allows you to convert NPCs from one storage format to another.

### Method
POST (conceptual, command-line execution)

### Endpoint
`/npc storage migrate <from> <to> [force]`

### Parameters
#### Path Parameters
- **from** (string) - Required - The source storage type (e.g., YAML, SQLITE).
- **to** (string) - Required - The destination storage type (e.g., YAML, SQLITE).
- **force** (boolean) - Optional - If true, forces migration and overwrites existing NPCs with the same ID in the destination storage.

### Request Example
```
/npc storage migrate YAML SQLITE
/npc storage migrate SQLITE YAML true
```
```

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

### Gradle Build Configuration for ZNPCsPlus API

Source: https://context7.com/pyrbu/znpcsplus/llms.txt

Configure your Gradle build file to include the ZNPCsPlus API dependency. This involves adding the repository and specifying the compile-only dependency.

```groovy
repositories {
    maven {
        name "pyrSnapshots"
        url "https://repo.pyr.lol/snapshots"
    }
}

dependencies {
    compileOnly "lol.pyr:znpcsplus-api:2.1.0-SNAPSHOT"
}
```

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

### Register Dummy Property

Source: https://github.com/pyrbu/znpcsplus/wiki/API

Register a custom property for testing purposes.

```java
npcApi.getPropertyRegistry().registerDummy("my_property", Boolean.class);
```

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

### Entity Properties Reference

Source: https://github.com/pyrbu/znpcsplus/wiki/NPC-Types

Documentation for entity-specific properties available in ZNPCsPlus.

```APIDOC
## Entity Properties

### Description
Lists the available properties for various entities supported by ZNPCsPlus.

### Entities
- **husk**: helmet, chestplate, leggings, boots, hand, offhand, entity_sitting (v2.0.0, MC 1.11+)
- **stray**: helmet, chestplate, leggings, boots, hand, offhand, entity_sitting (v2.0.0, MC 1.11+)
- **evoker**: entity_sitting, spell (v2.0.0, MC 1.11+)
- **llama**: carpet_color, llama_variant, body, has_chest (v2.0.0, MC 1.11+)
- **vex**: hand, offhand (v2.0.0, MC 1.11+)
- **vindicator**: celebrating, entity_sitting (v2.0.0, MC 1.11+)
- **wither_skeleton**: helmet, chestplate, leggings, boots, hand, offhand, entity_sitting (v2.0.0, MC 1.11+)
- **zombie_villager**: helmet, chestplate, leggings, boots, hand, offhand, entity_sitting (v2.0.0, MC 1.11+)
- **illusioner**: entity_sitting, spell (v2.0.0, MC 1.12+)
- **parrot**: parrot_variant, tamed, sitting (v2.0.0, MC 1.12+)
- **cod**: None (v2.0.0, MC 1.13+)
- **dolphin**: hand (v2.0.0, MC 1.13+)
- **drowned**: helmet, chestplate, leggings, boots, hand, offhand, entity_sitting (v2.0.0, MC 1.13+)
- **phantom**: size (v2.0.0, MC 1.13+)
- **pufferfish**: puff_state (v2.0.0, MC 1.13+)
- **salmon**: None (v2.0.0, MC 1.13+)
- **tropical_fish**: tropical_fish_pattern, tropical_fish_body_color, tropical_fish_pattern_color (v2.0.0, MC 1.13+)
```

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

### NPC Property Commands

Source: https://github.com/pyrbu/znpcsplus/wiki/Commands

Commands for setting and removing properties for specified NPCs.

```APIDOC
## POST /npc property set <id> <property> <value>

### Description
Sets a property for the specified NPC to the specified value.

### Method
POST

### Endpoint
`/npc property set <id> <property> <value>`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the NPC.
- **property** (string) - Required - The name of the property to set.
- **value** (string) - Required - The value to set for the property.

### Request Example
```json
{
  "example": "/npc property set my_npc dinnerbone true"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "example": "Property set successfully."
}
```
```

```APIDOC
## POST /npc property remove <id> <property>

### Description
Removes a property from the specified NPC.

### Method
POST

### Endpoint
`/npc property remove <id> <property>`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the NPC.
- **property** (string) - Required - The name of the property to remove.

### Request Example
```json
{
  "example": "/npc property remove my_npc dinnerbone"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "example": "Property removed successfully."
}
```
```

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

### NPC Types Configuration

Source: https://github.com/pyrbu/znpcsplus/wiki/NPC-Types

Overview of NPC types and their associated properties.

```APIDOC
## NPC Types Configuration

### Description
This section details the available NPC types and the properties that can be configured for each, including version compatibility and default settings.

### Common Properties (1.8+)
- **fire**, **invisible**, **silent**, **look**, **look_distance**, **look_return**, **view_distance**, **potion_color**, **potion_ambient**, **display_name**, **permission_required**, **player_knockback**, **player_knockback_exempt_permission**, **player_knockback_distance**, **player_knockback_vertical**, **player_knockback_horizontal**, **player_knockback_cooldown**, **player_knockback_sound**, **player_knockback_sound_name**, **player_knockback_sound_volume**, **player_knockback_sound_pitch**

### NPC Type: player
- **Version**: 1.8+
- **Available Properties**: helmet, chestplate, leggings, boots, hand, offhand, skin_cape, skin_jacket, skin_left_sleeve, skin_right_sleeve, skin_left_leg, skin_right_leg, skin_hat, shoulder_entity_left, shoulder_entity_right, force_body_rotation, entity_sitting

### NPC Type: armor_stand
- **Version**: 1.8+
- **Available Properties**: helmet, chestplate, leggings, boots, hand, offhand, small, arms, base_plate, head_rotation, body_rotation, left_arm_rotation, right_arm_rotation, left_leg_rotation, right_leg_rotation

### NPC Type: bat
- **Version**: 1.8+
- **Available Properties**: hanging

### NPC Type: blaze
- **Version**: 1.8+
- **Available Properties**: blaze_on_fire
```

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

### NPC Action Management

Source: https://context7.com/pyrbu/znpcsplus/llms.txt

Commands to manage interactive actions triggered by NPC clicks.

```APIDOC
## POST /npc action add

### Description
Adds a new action to an NPC.

### Method
POST

### Endpoint
/npc action add <type> <id> <click> <cooldown> <delay> <value>

### Parameters
#### Path Parameters
- **type** (string) - Required - Action type (message, playercommand, consolecommand, switchserver)
- **id** (string) - Required - NPC ID
- **click** (string) - Required - Trigger type (ANY_CLICK, RIGHT_CLICK, LEFT_CLICK)
- **cooldown** (integer) - Required - Cooldown in seconds
- **delay** (integer) - Required - Delay in ticks
- **value** (string) - Required - The action content or command
```

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

### Deserialize and Register NPC from YAML

Source: https://github.com/pyrbu/znpcsplus/wiki/API

Loads an NPC configuration from a YAML object and registers it with the NPC registry.

```java
NpcEntry deserializedPlayerNpc = yamlSerializer.deserialize(serializedPlayerNpc);
pcApi.getNpcRegistry().register(deserializedPlayerNpc);
```

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

### Add Hologram Line

Source: https://github.com/pyrbu/znpcsplus/wiki/Commands

Adds a line of text to an NPC's hologram display. Use '%blank%' for an empty line.

```command
/npc holo add <id> <text>
```

```command
/npc holo add my_npc Hello, I am an NPC
```

```command
/npc holo add npc1 &6Welcome to the server
```