# Getting started

# Include the API in your project

To include the FancyNPCs API in your project, you need to add the following dependency to your build.gradle.kts or pom.xml file.

Gradle:

repositories {
    maven("https://repo.fancyplugins.de/releases")
}

dependencies {
    compileOnly("de.oliver:FancyNpcs:VERSION")
}

Maven:

<repository>
    <id>fancyplugins-releases</id>
    <name>FancyPlugins Repository</name>
    <url>https://repo.fancyplugins.de/releases</url>
</repository>

<dependency>
    <groupId>de.oliver</groupId>
    <artifactId>FancyNpcs</artifactId>
    <version>VERSION</version>
    <scope>provided</scope>
</dependency>

Replace VERSION with the version of the API you want to use. You can find the latest version on the download pages or in the GitHub releases.

# Create a new NPC

# 1. Create the NPC data

The NpcData class is used to store all the information about an NPC. You can create a new instance of NpcData by providing a name, the UUID of the creator, and the location where the NPC should be spawned.

NpcData data = new NpcData("myNpc", creatorUUID, location);
data.setSkin("OliverHD"); // use skin of the player OliverHD
data.setDisplayName("<red>cool displayname</red>");

# 2. Create the NPC

You can use the NpcData object to create a new NPC. Because the implementation of the NPC is different for every Minecraft version, FancyNpcs provides a factory to create the NPC.

Npc npc = FancyNpcsPlugin.get().getNpcAdapter().apply(data);

# 3. Register the NPC

To let FancyNpcs handle the NPC, you need to register it. FancyNpcs will take care of spawning, despawning, saving the NPC, and more.

FancyNpcsPlugin.get().getNpcManager().registerNpc(npc);

Do not register npcs in the first few seconds after the server has started. You need to wait at least 10 seconds before registering npcs. Otherwise, the npcs will not get registered correctly. You can also listen to the NpcsLoadedEvent to know when you can register npcs.

If you don't want to persist the npc, you can do the following: npc.setSaveToFile(false);

# 4. Initially spawn the NPC for all players

To spawn the NPC for all players, you can use the following methods.

npc.create();
npc.spawnForAll();

# Modify an existing NPC

# 1. Get the NPC object by name

You can get an NPC object by its name. The name is unique for every NPC (unless the player-npcs feature flag is enabled). Alternatively, you can get an NPC by its ID.

Npc npc = FancyNpcsPlugin.get().getNpcManager().getNpc("myNpc");
NpcData data = npc.getData();

# 2. Modify the NPC data

You can modify the NPC data object to change the NPC's properties.

data.setDisplayName("<green>new displayname</green>");
data.setSkin("https://url-to-skin.com/skin.png");

# 3. Update the NPC

After you have modified the NPC data, you need to update the NPC for all players.

npc.updateForAll();

Some changes require the NPC to be respawned. You can respawn the NPC for all players by doing the following:

npc.removeForAll();
npc.spawnForAll();

# Remove an NPC

To remove an NPC, you can use the following method.

FancyNpcsPlugin.get().getNpcManager().removeNpc(npc);
npc.removeForAll();

# JavaDocs and help

You can find the JavaDocs for the FancyNpcs API here.

Join the FancyPlugins Discord for help and support. There is a dedicated channel for help about the api (#npcs-dev).