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

Discussion in 'Resources' started by fullwall, Feb 6, 2013.

  1. 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


    Add the following to your plugin.yml to create a dependency.
    Show 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
    1. NPCRegistry registry = CitizensAPI.getNPCRegistry();
    2. NPC npc = registry.createNPC(EntityType.PLAYER, "MyNPC");
    3. npc.spawn(Bukkit.getWorlds().get(0).getSpawnLocation());
    Setting an NPC's destination
    1. npc.getNavigator().setTarget(Bukkit.getWorlds().get(0).getSpawnLocation()); // walk to a point
    2. npc.getNavigator().setTarget(entity, true); // aggressively attack an entity
    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:
    1. public class MyTrait extends Trait {
    2. @Persist private boolean data = false; // saves and loads automatically under "data"; can be done with lists, sets, and Map<String, Object>s.
    3. @Override
    4. public void run() {
    5. Bukkit.broadcastMessage("Hello."); // say hello every tick
    6. }
    7. }
    In onEnable() -
    1. 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!
  2. Great work, I'll be sure to try this out tomorrow.
  3. 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
  4. Updated for MC 1.5 in 2.0.8 (being pushed to dev.bukkit soon, but available in maven + jenkins).
  5. Offline


    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?

  6. Offline


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


    I got it to work by using the version number

  8. Offline


    That's weird, I missed those because I was expecting them to be in numerical order. Oh well, disregard the previous.
  9. 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.
  10. Offline


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


    How do I Download This?
  12. golemblade - through maven or you can use the full Citizens2 JAR from the jenkins.
  13. Just for the record, this is awesome and easy to use.

    Ironically, I now have a question.

    Do NPC ids ever change?
    Last edited by a moderator: Jan 29, 2016
  14. 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.
  15. fullwall
    Then what is the best way to track a specific NPC?
  16. 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.
  17. Yeah, global IDs would be nice. So I just persist a unique ID in the trait then save the ID in my files?
  18. Ultimate_n00b - yep, that's best for now. I'll push globally unique IDs in the MC 1.6.1 update.
  19. It seems that your Maven repo is down. Any ETA on when it will be back up?
  20. dark navi - should be back up now, sorry about that.

  21. No worries :)
  22. All right, quick question. I forget, can mobs have custom names?

    And did you put it in?
  23. Ultimate_n00b - yes, getBukkitEntity().setCustomName(); Yes, globally unique IDs are in now.
  24. Updated for MC 1.6.2.
  25. fullwall

    Anyway to access NPC's armorContents or itemInHand via API?
  26. Yeah, just get their entity.
  27. 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.

Share This Page