NpcApi-Spigot/README.md

NPC Plugin on SpigotMC

NpcApi for PaperMC

NpcAPI

A powerful and easy-to-use NPC (Non-Player Character) API for Minecraft Spigot plugins that allows you to create, manage, and customize NPCs with advanced features.

Wiki

See the in-repo wiki pages under: 📚 Project Wiki

Features

• Create custom NPCs with ease
• Customize NPC appearance (skins, glowing effects, etc.)
• Handle click events and interactions
• Play animations and control NPC behavior
• Save and load NPCs persistently
• Show/hide NPCs for specific players
• Comprehensive NPC management system
• Let NPCs walk around

Installation

Choose your preferred installation method based on your project needs:

Method 1: Plugin Dependency (Recommended)

This method requires NpcPlugin to be installed as a separate plugin on the server.

Maven

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

<dependency>
    <groupId>com.github.Eisi05</groupId>
    <artifactId>NpcApi</artifactId>
    <version>3.4.0</version>
    <scope>provided</scope>
</dependency>

Gradle

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

dependencies {
    compileOnly 'com.github.Eisi05:NpcApi:3.4.0'
}

Plugin Configuration

Add NpcPlugin as a dependency in your plugin.yml:

# Required dependency (hard dependency)
depend: [NpcPlugin]

# Or optional dependency (soft dependency)
soft-depend: [NpcPlugin]

---

Method 2: Shaded Dependency

This method bundles NpcApi directly into your plugin JAR file.

Maven

Add the repository and dependency to your pom.xml:

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

<dependencies>
    <dependency>
        <groupId>com.github.Eisi05</groupId>
        <artifactId>NpcApi</artifactId>
        <version>3.4.0</version>
    </dependency>
</dependencies>

Gradle

Add the following to your build.gradle:

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

dependencies {
    implementation 'com.github.Eisi05:NpcApi:3.4.0'
}

Plugin Configuration

To enabled/disable the NpcApi add this to your Plugin Main class:

@Override
public void onEnable()
{
    // Initialize NpcAPI with default configuration
    NpcApi.createInstance(this, new NpcConfig());
}

@Override
public void onDisable()
{
    // Properly disable NpcAPI
    NpcApi.disable();
}

---

Usage Examples

Creating a Basic NPC

// Create a location where the NPC should spawn
Location location = new Location(world, x, y, z);

// Create a new NPC with a name
NPC npc = new NPC(location, WrappedComponent.create("Test"));

// Enable the NPC to make it visible to all players
npc.setEnabled(true);

Customizing NPC Appearance

// Make the NPC glow with a red color
npc.setOption(NpcOption.GLOWING, ChatColor.RED);

// Set a custom skin from a player
npc.setOption(NpcOption.SKIN, NpcSkin.of(Skin.fromPlayer(player)));

Handling Click Events

// Set up a click event handler
npc.setClickEvent(event -> {
    Player player = event.getPlayer();
    NPC clickedNpc = event.getNpc();
    player.sendMessage("You clicked " + clickedNpc.getName().toLegacy());
});

Managing NPC State

npc.save();
npc.setName(NpcName.of(WrappedComponent.create("New Name")));
npc.setLocation(newLocation);
npc.reload();

Advanced NPC Control

npc.playAnimation(/* animation parameters */);
npc.showNPCToPlayer(player);
npc.hideNpcFromPlayer(player);
npc.lookAtPlayer(player);
npc.delete();
npc.walkTo(path, player, walkSpeed, changeRealLocation);

NPC Management

Getting All NPCs

// Get a list of all available NPCs
List<NPC> allNpcs = NpcManager.getList();

Finding NPCs by UUID

// Get a specific NPC by its UUID
UUID npcUuid = /* your NPC's UUID */;
NPC npc = NpcManager.fromUUID(npcUuid);

API Reference

NPC Class

Method	Description
setOption(NpcOption, Object)	Set NPC options like glowing, skin, etc.
setClickEvent(Consumer<ClickEvent>)	Set the click event handler
setEnabled(boolean)	Enable/disable NPC visibility
save()	Save NPC to persistent storage
reload()	Reload NPC data
setName(NpcName)	Update NPC display name
setLocation(Location)	Move NPC to new location
playAnimation(...)	Play NPC animation
showNPCToPlayer(Player)	Show NPC to specific player
hideNpcFromPlayer(Player)	Hide NPC from specific player
lookAtPlayer(Player)	Make NPC look at player
delete()	Remove NPC permanently
walkTo(Path, double, boolean, Consumer<Result>, players)	Let the NPC walk along a path (can be created with PathfindingUtils class)

Requirements

• Java 21+
• Spigot 1.20.6+ (compatible with newer versions)
• Minecraft server with NPC support