[LIB] CitizensAPI - Create NPCs quickly and easily [MC 1.8.x]

Citizens2 includes a nice API for developers wanting to create NPCs. Here's a guide on how to use it.

Why Citizens?
Citizens has been in development for nearly two years; it has lots of features to make developers' lives easier, and has been thoroughly tested. There's lots of information on the wiki and javadocs. Finally, I'm always willing to answer any questions and implement any feature both on IRC and via the JIRA.

Quick list of helpful features

• Any entity can be an NPC
• Full AI control with behaviour trees and an implementation of A* pathfinding
• Includes 'traits' that can be persistently attached to NPCs
• Easy persistent storage (@Persist)
• Easy command API for lots of commands (@Command)
• 3D region manipulation included: really fast region management in both 2D and 3D
• Handy NPC manipulation included via Citizens - this can be disabled if not needed
• Localisation support inbuilt via properties files - easily add translations to your addon
• Lots of servers already have Citizens - your addon already has a userbase

Setting up - User
Download and install Citizens here. This implements CitizensAPI and includes all dependencies.

Setting up - Developer
Either add the Citizens2 JAR to your build path, or add the following to your pom.xml.

Show Spoiler Hide Spoiler

<repositories>
<repository>
<id>everything</id>
<url>http://repo.citizensnpcs.co</url>
</repository>
</repositories>

<dependencies>
<dependency>
<groupId>net.citizensnpcs</groupId>
<artifactId>citizensapi</artifactId>
<version>LATEST</version>
<scope>provided</scope>
</dependency>
<dependencies>

Add the following to your plugin.yml to create a dependency.

Show Spoiler Hide Spoiler

depend: [Citizens] // if CitizensAPI is required *make sure you check the Citizens version in onEnable*
softdepend: [Citizens] // if CitizensAPI is optional *make sure you check the Citizens version in onEnable*

Developer examples
Creating an NPC

Code:JAVA

NPCRegistry registry = CitizensAPI.getNPCRegistry();
NPC npc = registry.createNPC(EntityType.PLAYER, "MyNPC");
npc.spawn(Bukkit.getWorlds().get(0).getSpawnLocation());

Setting an NPC's destination

Code:JAVA

npc.getNavigator().setTarget(Bukkit.getWorlds().get(0).getSpawnLocation()); // walk to a point
npc.getNavigator().setTarget(entity, true); // aggressively attack an entity

Traits
A trait sticks with an NPC over an extended period of time. It can save and load easily using a shorthand persistence API and manual saving.

Defining a trait:

Code:JAVA

public class MyTrait extends Trait {
@Persist private boolean data = false; // saves and loads automatically under "data"; can be done with lists, sets, and Map<String, Object>s.
@Override
public void run() {
Bukkit.broadcastMessage("Hello."); // say hello every tick
}
}

In onEnable() -

Code:JAVA

CitizensAPI.getTraitFactory().registerTrait(TraitInfo.create(MyTrait.class).withName("name"));

Further reading
There are many more features in the Citizens API - I encourage you to take a look through the javadocs. There's events, more persistence API features, an easy to use Command API, scripting features, A* pathfinding, and much more.

Helpful links
Wiki -- for information on Citizens features (find me on IRC if you want an account here)
Javadocs -- for developer documentation
JIRA -- for bug reports and feature suggestions
Jenkins -- developer builds
Source code -- source code for everything Citizens

Visit us on IRC at irc.esper.net #citizens, we're always happy to help. If you make something cool, let me know - I'll be happy to set you up on the wiki so other Citizens users can see your work easily.

Replies welcome, thanks for reading!

 

Great work, I'll be sure to try this out tomorrow.

 

Added some new APIs in the latest 2.0.7 release.

• PRTree - 3D cuboid library
• New named NPCRegistry methods in CitizensAPI for custom registries
• External translation APIs
• Bugfixes for the new AI behavior tree library

 

Updated for MC 1.5 in 2.0.8 (being pushed to dev.bukkit soon, but available in maven + jenkins).

 

Very nice library. Any plans to include non mob entities in the library like minecarts, experience orbs etc and be able to modify all of their behavior?

Thanks.

 

"LATEST" does not seem to exist in the repo, nor do 2.0.7 or 2.0.8.

 

I got it to work by using the version number

HTML:

        <dependency>
            <groupId>net.citizensnpcs</groupId>
            <artifactId>citizensapi</artifactId>
            <version>2.0.8-SNAPSHOT</version>
            <scope>provided</scope>
        </dependency>

 

That's weird, I missed those because I was expecting them to be in numerical order. Oh well, disregard the previous.

 

BRampersad - the plan is to migrate to non-mob entities eventually, but currently getBukkitEntity() returns a LivingEntity so that assumption would need to be changed.

 

Cool. If you need any help testing etc let me know.

 

How do I Download This?

 

golemblade - through maven or you can use the full Citizens2 JAR from the jenkins.

 

Just for the record, this is awesome and easy to use.

Ironically, I now have a question.

Do NPC ids ever change?

 

Ultimate_n00b - the same ID can refer to multiple NPCs over time - if NPC A is given ID 2 then deleted, the next created NPC will be given ID 2 as well.

 

fullwall
Then what is the best way to track a specific NPC?

 

Ultimate_n00b - Traits - they are kept around with the NPC. I have been thinking that globally unique IDs would probably be a good idea, so I may switch to that.

 

Yeah, global IDs would be nice. So I just persist a unique ID in the trait then save the ID in my files?

 

Ultimate_n00b - yep, that's best for now. I'll push globally unique IDs in the MC 1.6.1 update.

 

It seems that your Maven repo is down. Any ETA on when it will be back up?

 

dark navi - should be back up now, sorry about that.

 

No worries

 

All right, quick question. I forget, can mobs have custom names?

And did you put it in?

 

Ultimate_n00b - yes, getBukkitEntity().setCustomName(); Yes, globally unique IDs are in now.

 

fullwall
So just getId()?

 

Ultimate_n00b - yes.

 

Updated for MC 1.6.2.

 

The repo has been updated to http://repo.citizensnpcs.co

 

fullwall

Anyway to access NPC's armorContents or itemInHand via API?

 

Yeah, just get their entity.

 

So, working on another plugin that I thought would be cool to use NPCs.
I got the trait and all the other stuff working, though it seems I ran into an issue. The normal player NPC doesn't have the trait Inventory (where I thought) contains the player's inventory. Is there a different way where I am supposed to set the NPC's inventory?

EDIT: After looking through the GenericEquiper on the github, I found the Equipment trait. It seems though, that the NPC doesn't have that either.