Denizen/0.7

Denizen is an extension for Citizens that allows scripting of NPCs to handle tasks, quests, player interaction and more! Current Version: 0.75 Pre-release BETA Developers: aufdemrand Source: Github Development Builds: Jenkins Latest Developmental Build: 2.0.2 Support tickets: Tickets on Github, but please read the entirety of this document first. Donate: A lot of man hours has been put into Denizen. Your donations add a lot to the project and are always welcome! Your donations will probably help remodel my house and feed my kids. :) Donate to aufdemrand Don't forget to donate to the Citizens2 project as well, as none of this would be possible without that! Thank You: A lot of people have stepped forward to help out with Denizen, and that's awesome! Special thanks to everyone who has beta tested, and a huge to these people: fullwall, AgentKid, aPunch, NeonMaster, Instinx, tenowg, groggluebutt, Wreyth, jrbudda, spidi, the list could go on! CitizensUI: For a GUI interface, check out CitizensUI by jrbudda which provides an interface for Citizens NPCs as well as managing scripts and other NPC types.

While Denizen is in BETA, consider this page under construction! If you run into any inaccuracies, or you have any questions not provided by this document, please let us know in #DENIZEN-DEV on EsperNET.


Denizens are a great way to add MUD-style RPG Citizens to your server. Denizen NPCs use mini scripts with steps and events to interact with the player and world. Imagine interactive gate-keepers, magical wizards, experience trainers, bankers, talking townspeople and more! They can be used in thousands of different ways, from tutorials, to questing, to administrating.. your imagination is just about the limit! Though Denizen uses Scripting, it is not to be confused with Citizens2 Core Scripting which utilizes JavaScript and other major scripting languages to implement Goals. Instead, Denizen uses its own YML 'scripting language' which is designed to be easily read and edited by hand.

Denizen grants Citizens NPCs 2 major abilities: Interactions and Activities. Interactions occur when the player interacts with the NPC in some way, clicking, attacking, walking near, etc. These interactions trigger scripts based on conditions called 'Requirements'. Each interact script will run a series of commands to make the Denizen do or say something. Very complex gameplay can be created using these scripts. The other half of Denizen is activities. These scripts give the NPC continuous tasks to do that make them feel alive and provide useful functions. Wandering around, mining blocks, collecting items are all assignable activities. Denizens can perform multiple activities at one time, such as wandering and collecting garbage.

If you are coming from Denizen 0.6, we've attempted to compile a list for helping with migration for users upgrading who need a brief on what needs to be changed to become compatible.

Table of Contents

If you are having problems getting a script working please see Denizen/Troubleshooting. If you are just starting out, check out Getting Started. If you're hooked, we recommend you read all the sections in order! Getting Started Start-up Kit Troubleshooting Configuration Permissions In Game Commands Writing Scripts Interact Scripts Trigger Types Requirements Commands Task Scripts Activity Scripts Activities Assigning Scripts Examples Beginner Scripts Advanced Scripts Denizen And Sentry Extending Denizen Custom Commands Custom Requirements Custom Triggers Custom Activities Bonus Content Denizen Bonus Pictures

If you are having problems getting a script working please see Denizen/Troubleshooting. Change Log Here's what's changed! 0.7.5 BETA build #455 New! OWNER requirement will require ownership of the NPC interacting. Could be used for 'command interfaces' that only the owner can access. New! SNEAKING requirement requires the player be crouched when clicking. Careful on conflict with info-click for ops! Info-click can be disabled in the config. New! Queue-time flag replacement can let you dynamically use flag data in a script entry. For example: - GIVE <FLAG:ExampleItemFlag> QTY:<FLAG:ExampleQtyFlag> Experimental! Denizen NPCs now have their own Command Queue, and a TASK activity. This allows NPC's to use the activity scheduler to do tasks at certain times of the day. Experimental! LISTEN command implemented, KILL type implemented. Return of the 'Quester'. More types coming soon. Example usage: - LISTEN KILL ID:UniqueId TYPE:ENTITY NAME:ZOMBIE QTY:5 SCRIPT:FinishIt would require the player to kill 5 zombies. When completed, it will run the task script 'FinishIt'. New! Use <*> to use Chat Trigger text in EXECUTE or talk commands. New! Use <*> in FLAG command to remember player input. Example usage: - FLAG PLAYER_RESPONSE:<*> 0.7.5 BETA build #440: New! API Events make extending Denizen more powerful than ever! New! RUNTASK/CANCELTASK allows delayed tasks to be set, and cancelled. New! HOLD command can change what a Denizen NPC is wielding. New! Replaceable data for dynamically putting flags into texts! New! ISLIQUID requirement can sense if a block bookmark is solid, or liquid. New! IF command can evaluate a FLAG and run a TASK script. 0.7 BETA builds #125 - #280: Updated! Less bugs! We're still in beta, but there has been some major code cleanup! New! Triggers, Commands, Requirements and Activities are now extensible by plugin programmers. See: Custom Denizen Commands on the Citizens2 Wiki. Documentation coming soon! New! Debug Mode will let you see the logic of interaction and script execution to help you find problems in scripts faster than ever. I'm striving to make this as informational and clean as possible to help you test your scripts and get good feedback on behavior. New! Info-Click lets you see Denizen stats and specifics, such as script assignments, trigger status, activity schedule and associated bookmarks with just a crouch and a click. Requires OP.. use this! New! Proximity Triggers can trigger a script when a Player comes near. The most requested trigger type I got during the previous betas. New! Location Triggers can trigger a script when a Player walks over a Location Bookmark. This is kind of like a PLAYERTASK LOCATION, but better! :) New! Damage Triggers separate the left and right clicks for more control over interaction. Look forward to a whole new set of commands to go along with this! New! Script Overlay mode is a whole new way to assign a script. Less copying/pasting when working with multiple scripts, not to mention more control! If you're an advanced script-user, this is for you! New! ANNOUNCE command can make global server announcements. New! RANDOM command will leave command execution to chance. Duck-duck-goose. New! HINT command will hint to the Player acceptable Chat Triggers for the current step and script. Language support coming soon! New! FLAG command lets you set 'flags', on players to store progress, important information, or other variables that can be used with the FLAG requirement. This is HUGE! New! FLAG requirement can require special flags and values to be set in order to be eligible for a script. Again, this is HUGE! New! POWERED requirement can check if a block bookmark has redstone power. Great idea, instinx! New! The activity engine has been implemented which will allow your Denizens to do things on their own. There's a whole lot more to this concept, but you can try out the new WANDER activity in all its glory. This thing is cool, and customizable! New! In-game commands now let you easily manage triggers, bookmarks, and debug info. Updated! Extended/unified command syntax for almost every existing command. Once you get over the pain of upgrading, you will drop a jaw at the new capabilities! You can see more at the full Denizen changelog.