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

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

Thread Status:
Not open for further replies.
  1. Offline

    fullwall

    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

    <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

    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
    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
    Code:JAVA
    1. npc.getNavigator().setTarget(Bukkit.getWorlds().get(0).getSpawnLocation()); // walk to a point
    2. 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
    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() -
    Code:JAVA
    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. Offline

    Liam Allan

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

    fullwall

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

    fullwall

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

    BRampersad

    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.
     
  6. Offline

    jb_aero

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

    BRampersad

    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>
     
  8. Offline

    jb_aero

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

    fullwall

    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

    BRampersad

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

    golemblade

    How do I Download This?
     
  12. Offline

    fullwall

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

    Ultimate_n00b

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

    fullwall

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

    Ultimate_n00b

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

    fullwall

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

    Ultimate_n00b

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

    fullwall

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

    dark navi

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

    fullwall

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

    dark navi


    No worries :)
     
  22. Offline

    Ultimate_n00b

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

    And did you put it in?
     
  23. Offline

    fullwall

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

    Ultimate_n00b

  25. Offline

    fullwall

  26. Offline

    fullwall

    Updated for MC 1.6.2.
     
  27. Offline

    fullwall

  28. Offline

    Deleted user

    fullwall

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

    Ultimate_n00b

    Yeah, just get their entity.
     
  30. Offline

    Ultimate_n00b

    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.
     
Thread Status:
Not open for further replies.

Share This Page