Denizen/0.7: Difference between revisions

From Citizens Wiki
No edit summary
 
(143 intermediate revisions by 5 users not shown)
Line 1: Line 1:
'''{{color|red|white|THIS PAGE IS UNDER CONSTRUCTION AND INFORMATION MAY BE INACCURATE AS WE'RE UPDATING FROM 0.6 to 0.7. IF YOU SEE AN ERROR, PLEASE LET US KNOW. IF YOU HAVE ANY QUESTIONS, VISIT US ON #DENIZEN-DEV on EsperNET.}}
<div class="infobox" style="width: 295; font-size: 12px; background: #FFFFFF; float: right; border: 1px solid #CCCCCC; margin-left:2.5em; padding: 9px;">
<div class="infobox" style="width: 295; font-size: 12px; background: #FFFFFF; float: right; border: 1px solid #CCCCCC; margin-left:2.5em; padding: 9px;">
{{Box|
{{Box|
Line 10: Line 8:
HEADING = ''' ''' |
HEADING = ''' ''' |
CONTENT = [[image:denizen.png|center]]
CONTENT = [[image:denizen.png|center]]
<div class="padded" style="padding: 19px; font-family:museo-sans; font-size:110%;">
<div class="padded" style="padding: 19px; font-family:camingodos-web; font-size:110%;">


'''Denizen''' is an extension for Citizens that allows scripting of NPCs to handle tasks, quests, player interaction and more!  
'''Denizen''' is an extension for Citizens that allows scripting of NPCs to handle tasks, quests, player interaction and more!  


'''Current Version:''' 0.7 BETA
'''Current Version:''' 0.7.6 Pre-release BETA


'''Developers:''' aufdemrand
'''Developers:''' aufdemrand
Line 20: Line 18:
'''Source:''' [https://github.com/aufdemrand/Denizen Github]
'''Source:''' [https://github.com/aufdemrand/Denizen Github]


'''Development Builds:''' [http://jenkins.citizensnpcs.net/job/Denizen/ Jenkins]
'''Development Builds:''' [http://jenkins.citizensnpcs.com/job/Denizen/ Jenkins]


'''Latest Developmental Build:''' [http://ci.citizensnpcs.net/job/Denizen/lastSuccessfulBuild/ {{Version2}}]
'''Latest Developmental Build:''' [http://ci.citizensnpcs.com/job/Denizen/lastSuccessfulBuild/ {{Version2}}]


'''Support tickets:''' [http://github.com/aufdemrand/Denizen/issues/ Tickets on Github], but please read the entirety of this document first.
'''Support tickets:''' [http://github.com/aufdemrand/Denizen/issues/ Tickets on Github], but please read the entirety of this document first.
Line 38: Line 36:
</div>
</div>


<div style="float:right; clear:both; width:295px; margin-left:2.5em; margin-top:2.0em; font-family:museo-sans; font-size:110%; margin-bottom:2.0em" >__TOC__</div>
<div style="padding:10px; font-family:camingodos-web; font-size:110%;">
[[image:Denizen-Logo-Large.png|center]]


<div style="margin-right:2.0em; padding:10px; font-family:museo-sans; font-size:110%;">
{{#ev:youtube|oKTe8-joBUI|305|right|A small glimpse of Denizen.}}
Denizens are a great way to add [http://en.wikipedia.org/wiki/MUD 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 [[Scripting|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.


'''If you are having problems getting a script working please see [[Denizen/Troubleshooting|Troubleshooting]]


</div>
For more up-to-date information and full details on specific features (individual commands or tags, for example), check the [https://one.denizenscript.com/denizen/cmds/ Meta Documentation].


If you want a full tutorial to help get you set up, check out the [https://one.denizenscript.com/denizen/cmds/denizen/vids Tutorial Videos] on youtube or the [https://guide.denizenscript.com/ Beginner's Guide] text website.


== Table of Contents ==
If you need quick help, visit our [https://discord.gg/Q6pZGSR Discord group].
<div style="margin-right:2.0em; padding:10px; font-family:museo-sans; font-size:110%; font-weight:800;">
* [[Denizen/Before Using Denizen]]
* [[Denizen/Quickstart Guide]]
** [[Denizen/config.yml|config.yml]]
* [[Denizen/In Game Commands|In Game Commands]]
* [[Denizen/Assignments]]
** [[Denizen/assignments.yml|assignments.yml]]
* [[Denizen/Interact Scripts]]
** [[Denizen/scripts.yml|scripts.yml]]
** [[Denizen/Interact Scripts/Triggers|Interact Triggers]]
** [[Denizen/Interact Scripts/Custom Triggers|Custom Interact Triggers]]
** [[Denizen/Interact Scripts/Interact Requirements|Interact Requirements]]
** [[Denizen/Interact Scripts/Custom Requirements|Custom Interact Requirements]]
** [[Denizen/Interact Scripts/Commands|Interact Commands]]
** [[Denizen/Interact Scritps/Custom Commands|Custom Interact Commands]]
* [[Denizen/Task Scripts]]
* [[Denizen/Activity Scripts]]
** [[Denizen/Activity Scripts/Activities|Activities]]
** [[Denizen/Activity Scripts/Custom Activities|Custom Activities]]
* [[Denizen/Example Scripts]]
** [[Denizen/Example Scripts/Beginner Scripts|Beginner Scripts]]
** [[Denizen/Example Scripts/Advanced Scripts|Advanced Scripts]]
</div>


== Script Repository ==
<br><br><br>
<imagemap>Image:Script Repository.png|
rect 2 26 280 104 [http://form.jotform.us/form/21498151597160|]
rect 286 26 555 104 [https://www.dropbox.com/sh/hw6x3f980maa8d9/DNtzAw8cn3]
#<!-- Created by Online Image Map Editor (http://www.maschek.hu/imagemap/index) -->
</imagemap>


<span style="font-family:natalya-alternate-one; font-size:300%; margin-right:-7px; margin-left:-10px;">This wiki is outdated, please view the tutorial videos/guide, meta documentation, or Discord group (all linked above) for up-to-date information!</span>


== Change Log ==
<div style="margin-right:2.0em; padding:10px; font-family:museo-sans; font-size:110%;">
First, thanks for being patient, I know there has been a lot of anxious people waiting for the new release. This took a lot longer to do than I thought, but it's worth it! Updating code and adding content is easier than ever, so keep those feature requests coming in! I also want to put out there that I took OUT the PLAYERTASK command, so please be patient with me as I know a lot of you were looking for more 'quest types'. I am instead placing this in another plugin that will extend Denizen called the Adventurer. This will have similar functionality to the 1.2 Quester, but use Denizen as the core so it can be more flexible and powerful than ever!


Second, a huge sorry to current faithful users. I have made a promise to myself and you to try to maintain compatibility throughout the evolution of Denizen. I take that seriously, and that being said, I had to change some syntax around in regards to new commands to make way for cleaner code and the ability to have greater flexibility. The upside to this is there are more options and modifiers for commands than ever before! The downside is there's probably a few commands that you will have to check and fix syntax for if trying to run a 0.6 Denizen Script with the new builds. I am EXTREMELY sorry, but expect some syntax to change on some Requirements soon, too!


Here's what's changed!
<span style="font-size:110%">{{color|red|yellow|This is the old Wiki for Denizen 0.7.6! Information found here does not apply to later versions of Denizen.}}</span>
<s>
<br><br><br>
<span style="font-family:natalya-alternate-one; font-size:750%; margin-right:-7px; margin-left:-10px;">D</span>enizen is a great way to add [http://en.wikipedia.org/wiki/MUD 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 [[Scripting|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.


 
<br><br>
'''0.7 BETA builds #125 - #280:'''
<div style="padding:20px; font-family:camingodos-web; font-size:110%; background-color:#EEDDEE; border-style:dotted; border-width:1px; width:55%; font-weight:500;">If you are coming from Denizen 0.6, we've attempted to compile a [[Denizen/0.7/Migration|list for helping with migration]] for users upgrading who need a brief on what needs to be changed to become compatible.
 
* {{color|red|white|'''Updated!'''}} Less bugs! We're still in beta, but there has been some major code cleanup!
 
* {{color|red|white|'''New!'''}} Triggers, Commands, and Activities are now extensible by plugin programmers. See: [http://wiki.citizensnpcs.net/Custom_Denizen_Commands Custom Denizen Commands on the Citizens2 Wiki]. Documentation for extending Triggers and Activities coming soon. Note: Requirements will be extensible very soon.
 
* {{color|red|white|'''New!'''}} [[#Debug_Mode|Debug Mode]] will let you see the logic of interaction and script execution to help you find problems in scripts faster than ever.
 
* {{color|red|white|'''New!'''}} [[#Info-click|Info-Click]] lets you see Denizen stats and specifics, such as script assignments and associated bookmarks with just a crouch and a click.
 
* {{color|red|white|'''New!'''}} [[#Proximity_Trigger|Proximity Triggers]] can trigger a script when a Player comes near.
 
* {{color|red|white|'''New!'''}} [[#Location_Trigger|Location Triggers]] can trigger a script when a Player walks over a Location Bookmark.
 
* {{color|red|white|'''New!'''}} [[#Damage_Trigger|Damage Triggers]] separate the left and right clicks for more control over interaction.
 
* {{color|red|white|'''New!'''}} [[#Overlay_Interact_Script_Assignments|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!
 
* {{color|red|white|'''New!'''}} [[#Interact Script Commands|ANNOUNCE command]] can make global server announcements.
 
* {{color|red|white|'''New!'''}} [[#Interact Script Commands|RANDOM command]] will leave command execution to chance.
 
* {{color|red|white|'''New!'''}} [[#Interact Script Commands|HINT command]] will hint to the Player acceptable Chat Triggers for the current step and script.
 
* {{color|red|white|'''New!'''}} [[#Interact Script Commands|FLAG command]] lets you set 'flags', on players to store progress, important information, or other variables that can be used with the FLAG requirement.
 
* {{color|red|white|'''New!'''}} [[#Requirement Types|FLAG requirement]] can require special flags and values to be set in order to be eligible for a script.
 
* {{color|red|white|'''New!'''}} [[#Requirement Types|POWERED requirement]] can check if a block bookmark has redstone power.
 
* {{color|red|white|'''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 with bukkit commands or script commands.
 
* {{color|red|white|'''New!'''}} [[#In-game_Commands|In-game commands]] now let you easily manage assignments, texts, and bookmarks!
 
* {{color|red|white|'''Updated!'''}} Extended/unified command syntax for almost every existing command.
 
<br>
You can see more at the full [[Denizen changelog]].
</div>
 
== Interact Scripts ==
<div style="margin-right:2.0em; padding:10px; font-family:museo-sans; font-size:110%;">
Hopefully you've gotten a basic idea of a script by reading about Assignments in the previous section. If you have, you'll notice that the general structure of a script should always include the 'Name', 'Type', 'Requirements', and 'Steps' nodes.
 
Scripts are defined in the plugins/Denizen/scripts/ folder. Any .yml file in that directory will be loaded into Denizen. For example purposes on this website, reference to script.yml is made, but again, jimbobjoe.yml or 'skeeter the cat.yml' would work just the same..
</div>
</div>
==== General layout of an Interact Script ====
<div style="margin-right:2.0em; padding:10px; font-family:museo-sans; font-size:110%;">
<pre>
'Name of script':  # Name Node
  Type: Interact    # Type Node
  Requirements:    # Requirements Node
    ...:
    ...:
      - ...
      - ...
  Steps:            # Steps Node
    ...:
      - ...
    ...:
</pre>
</div>
</div>


==== Name Node ====
<div style="margin-right:2.0em; padding:10px; font-family:museo-sans; font-size:110%;">
This node is pretty self-explanatory, but here are some things to keep in mind.
* Names, just like nodes are case-sensitive! <code>'This script name'</code> is different than <code>'THIS SCRIPT NAME'</code>.
* Names that contain spaces should have single or double quotes around it. ie: <code>"This script":</code> or <code>'This script':</code> is acceptable.
* If the name includes a single quote in it, you must use double quotes around it, or 'escape' the quote with another quote. ie: <code>"John's Script":</code> or <code>'John<nowiki>''</nowiki>s Script':</code>
</div>


==== Type Node ====
<div style="padding:10px; font-family:camingodos-web; font-size:110%;">
<div style="margin-right:2.0em; padding:10px; font-family:museo-sans; font-size:110%;">
===How it works===
Let's Denizen know the type of script. For interact scripts, as explained in this section, use <code>TYPE: INTERACT</code>. For reference, there are also TASK scripts and ACTIVITY scripts, which is covered later.
Denizen is an extension of Citizens2 that adds an incredible amount of interactivity and automation to NPCs and Players with some of these major features:
</div>


==== Requirements Node ====
* '''The Script Engine''' carries out and sends all the commands to be executed in an orderly and predictable fashion; this is the backbone of Denizen. Currently has 3 queues, one for the Player, one for Denizen, and one for Tasks. There's not much to see on the outside, this is the interworkings of Denizen, but rest assured that this is high performance machine behind the scenes!
<div style="margin-right:2.0em; padding:10px; font-family:museo-sans; font-size:110%;">
* '''Interact Scripts''' are the meat of Denizen, allowing Players and NPCs to interact with each other and the world. These are highly customizable with 20+ requirement types, 40+ script commands, and thousands of different ways to use them together. This with the Denizen Script Engine also allows commands to help control the rest of Denizen with script flow commands and such.
This node sets the rules for the player to qualify for the script. There are a couple different options that you should know when using requirements. For example:
* '''Activity Scripts''' are exciting. Imagine Johnny Appleseed planting trees, on his own, or simple villagers wandering around and socializing. Activities, of course, work with the rest of Denizen's other functions and features, allowing hundreds of ways to use Activities to add automation and liveliness to your world.
* '''Activity Scheduler''' takes Activity Scripts one step further, allowing Denizen NPCs to have daily schedules, based on the Minecraft day, to allow certain functionality to different times of the day. This also enables certain Script Commands to be executed and carried out, as well.
* '''Task Scripts''' are simple scripts that can be carried out in a variety of different ways. These can be used along side both Activity and Interact Scripts, but perhaps the most powerful way to use them is by allowing your plugin to utilize them, if you're a developer, or using other plugins that harness the ability to run a Denizen Task Script as well.
* '''Listeners''' are currently in an 'experimental phase', but are already allowing control over minecraft and bukkit events like nothing other. This already allows scripts to keep track of and assign 'quest-like' objectives, such as a 'kill quest', if you're familiar with the C1 Quester. But whereas many quest plugins are limited to this feature alone, Denizen, of course, allows you to use this in addition and along side the rest of the plugin, making room for extremely dynamic and intricate 'quest scripts'.
* '''Flag System''' is the key to Denizen being dynamic. An intricate, yet easy to learn 'Flag/Variable' system has been implemented into Denizen to help keep track of events, items, numbers, players, and more. The new Flag System is still getting more powerful each and every day.. it's the key to a spectacular script is sure to have a flag or two.
* '''Extensible Commands/Requirements/Activities and more''' make it easy to add-on to Denizen with very little Java knowledge. This also makes it extremely easy to let users utilize your plugin with script commands. Denizen also has API Events to use.
* '''Denizen Debugger'''' is an extremely friendly and informative way to test out scripts and interactions. Commands, events, and interactions are all logged in an easy to read format to show the exact progression of a script and its surroundings. No more guessing! Less headaches!


<code>
  Requirements:
    Mode: All
    List:
    - TIME Night
    - MONEY 1000000
    - STORMY
</code>


This would be a difficult script to obtain, for sure. To trigger, the time must be night-time, the player would need one million units of currency, and the weather must be storming, but it shows the flexibility of requirements. First is the 'Mode'. Currently there are three different types. Second is the requirement type, with arguments if applicable.
Seem overwhelming? Stop! Start small! Denizen is easy, Denizen is simple. But. Denizen is hard, Denizen is complex. Simply put: Denizen is what you make it! Our advice? Start small, and build upon what you have. Read the wiki articles, watch the youtube videos, test our your scripts, and test out some of the sample scripts! Before you know it, you'll be a Denizen poweruser, drunken with power, just like us!
</code>
</div>
</div>


===== Requirements Mode =====
<div style="margin-right:2.0em; padding:10px; font-family:museo-sans; font-size:110%;">
<code>[] indicates required field.</code>


{{Denizen Requiremnt Type Color |white|
<div style="margin-right:2.0em; padding:10px; font-family:camingodos-web; border-style:none; font-size:110%; font-weight:500;width:100%;border-width:0px;">
ALL
| &nbsp;&nbsp;Requires all requirements listed to be met.
}}
{{Denizen Requiremnt Type Color |white|
ANY [#]
| &nbsp;&nbsp;Requires the specified number of requirements to be met out of the total of requirements.
}}
{{Denizen Requiremnt Type Color |white|
NONE
| &nbsp;&nbsp;No requirements need to be met. There is also no need to have a <tt>LIST</tt> node if using <tt>NONE</tt>.
}}
</div>
 
===== Requirements =====
<div style="margin-right:2.0em; padding:10px; font-family:museo-sans; font-size:110%;">
Note: Requirements are due for a re-code to make them extensible like Commands. This will improve tolerence and allow for better debugging, as well as make it easy for other plugin programmers to extend Denizen. What this means to you is that it will probably change up some syntax formatting in future updates.
 
<code>[] indicates required field, () indicates an optional field, | indicates alternative usage.</code>


Click on any requirement to get more information and example usages.
=Denizen=
If you are new to Denizen, see [[Denizen/0.7/Before Using Denizen|Before Using Denizen: Getting Started]].
<br>If you are having problems getting a script working please see [[Denizen/0.7/Troubleshooting|Troubleshooting]].<br>
If you're hooked, we recommend you read all the sections in order and try out some sample scripts!
</div>
</div>
{|class="wikitable" style="text-align: left; border-color:white; border-style:none; vertical-align: text-top; background-color:white;"
|- style="vertical-align:top;"
| style="width: 60%;" |
<div style="vertical-align: text-top; padding:16px; border-style:none; border-color:white;font-family:camingodos-web; font-size:110%; font-weight:500;width:85%;border-width:0px;">
===Table of Contents===


''' Player Requirements '''
# [[Denizen/0.7/Before Using Denizen|Before Using Denizen & Getting Started]]
<div style="margin-right:2.0em; padding:10px; font-family:museo-sans; font-size:110%;">
#* [[Denizen/0.7/Start-up kit|The Start-up Kit]]
{{Denizen Requiremnt Type Color|ivory|
# [[Denizen/0.7/Troubleshooting|Denizen Troubleshooting]]
[[Interact_Script_Requirements#Name|NAME]]
# [[Denizen/0.7/File_Structure|The File Structure]]
| &nbsp;&nbsp;<nowiki>[Player Name]&nbsp;&nbsp;(Player Name)&nbsp;&nbsp;(Player Name) ...</nowiki>
#* [[Denizen/0.7/config.yml|Default config.yml]]
}}
# [[Denizen/0.7/In Game Commands|In Game and Console Commands]]
{{Denizen Requiremnt Type Color|ivory|
# Writing Scripts
[[Interact_Script_Requirements#Item|ITEM]]
#* [[Denizen/0.7/Interact Scripts|Introduction to Interact Scripts]]
| &nbsp;&nbsp;<nowiki>[[ITEM_NAME]|[#]:[#]]&nbsp;&nbsp;(Quantity)</nowiki>
#** [[Denizen/0.7/Interact Scripts/Triggers|Interact Triggers]]
}}
#** [[Denizen/0.7/Interact Scripts/Interact Requirements|Interact Script Requirements]]
{{Denizen Requiremnt Type Color|ivory|
#** [[Denizen/0.7/Interact Scripts/Commands|Script Commands]]
[[Interact_Script_Requirements#Holding|HOLDING]]
#* [[Denizen/0.7/Task Scripts|Task Scripts and the Task Queue]]
| &nbsp;&nbsp;<nowiki>[[ITEM_NAME]|[#]:[#]]&nbsp;&nbsp;(Quantity)</nowiki>
#* [[Denizen/0.7/Activity Scripts|Activity Scripts and the Scheduler]]
}}
#** [[Denizen/0.7/Activity Scripts/Activities|Activities and Goals]]
{{Denizen Requiremnt Type Color|ivory|
# [[Denizen/0.7/Assignments|Assigning Scripts]]
[[Interact_Script_Requirements#Wearing|WEARING]]
# [[Denizen/0.7/Flags|Denizen Flag System]]
| &nbsp;&nbsp;<nowiki>[[ITEM_NAME]|[#]:[#]]</nowiki>
# [[Denizen/0.7/Replaceables|Replaceable Data Tags]]
}}
# [[Denizen/0.7/Listeners|Denizen Listeners and Events]]
{{Denizen Requiremnt Type Color|ivory|
# Examples
[[Interact_Script_Requirements#Hunger|HUNGER]]
#* [[Denizen/0.7/Example Scripts/Beginner Scripts|Beginner Scripts]]
| &nbsp;&nbsp;<nowiki>[Full|Hungry|Starving]</nowiki>
#* [[Denizen/0.7/Example Scripts/Advanced Scripts|Advanced Scripts]]
}}
#* [[Sentry/Sentry and Denizen|Denizen and Sentry]]
{{Denizen Requiremnt Type Color|ivory|
#* [[Sentry/Builder and Denizen|Denizen and Builder]]
[[Interact_Script_Requirements#Wearing|LEVEL]]
# Extending Denizen
| &nbsp;&nbsp;<nowiki>[# or higher]&nbsp;&nbsp;OR&nbsp;&nbsp;LEVEL&nbsp;&nbsp;[At least this Level #]&nbsp;&nbsp;[No more than this Level #]</nowiki>
#* [[Denizen/0.7/Interact Scritps/Custom_Commands|Extending Custom Commands]]
}}
#* [[Denizen/0.7/Interact Scripts/Custom_Requirements|Extending Custom Requirements]]
{{Denizen Requiremnt Type Color|ivory|
#* [[Denizen/0.7/Interact Scripts/Custom_Triggers|Extending Custom Triggers]]
[[Interact_Script_Requirements#Wearing|POTIONEFFECT]]
#* [[Denizen/0.7/Activity Scripts/Custom_Activities|Extending Custom Activities]]
| &nbsp;&nbsp;<nowiki>[POTION_TYPE]</nowiki>
#* [[Denizen/0.7/Activity Scripts/Event_API|Utilizing Denizen Event API]]
}}
# Bonus Content
{{Denizen Requiremnt Type Color|ivory|
#* [[Denizen/0.7/Bonus Content/Pictures|Denizen Bonus Pictures]]
[[Interact_Script_Requirements#Wearing|DURABILITY]]
| &nbsp;&nbsp;<nowiki>[>,<,=] [#|#%]</nowiki>
}}
</div>
</div>
| style="width: 40%;" |


''' WORLD REQUIREMENTS '''
<div style="padding:16px; vertical-align: text-top;border-color:white; border-style:none; font-family:camingodos-web; font-size:110%; font-weight:500;width:95%;border-width:0px;">
<div style="margin-right:2.0em; padding:10px; font-family:museo-sans; font-size:110%;">
{{Denizen Requiremnt Type Color|aliceblue|
[[Interact_Script_Requirements#Name|WORLD]]
| &nbsp;&nbsp;<nowiki>[World Name]&nbsp;&nbsp;(World Name)&nbsp;&nbsp;(World Name) ...</nowiki>
}}
{{Denizen Requiremnt Type Color|aliceblue|
[[Interact_Script_Requirements#Time|TIME]]
| &nbsp;&nbsp;<nowiki>[Day|Night|Dusk|Dawn]  OR  TIME [0-23999] [1-24000]</nowiki>
}}
{{Denizen Requiremnt Type Color|aliceblue|
[[Interact_Script_Requirements#Time|POWERED]]
| &nbsp;&nbsp;<nowiki>[Block Bookmark]</nowiki>
}}
{{Denizen Requiremnt Type Color|aliceblue|
[[Interact_Script_Requirements#Sunny|SUNNY]]
| &nbsp;&nbsp;
}}
{{Denizen Requiremnt Type Color|aliceblue|
[[Interact_Script_Requirements#Sunny|PRECIPITATING]]
| &nbsp;&nbsp;
}}
{{Denizen Requiremnt Type Color|aliceblue|
[[Interact_Script_Requirements#Storming|STORMY]]
| &nbsp;&nbsp;
}}
</div>


''' SCRIPT REQUIREMENTS
===Sample Scripts===
<div style="margin-right:2.0em; padding:10px; font-family:museo-sans; font-size:110%;">
{{Denizen Requiremnt Type Color|mintcream|
[[Interact_Script_Requirements#Finished|FINISHED]]
| &nbsp;&nbsp;<nowiki>(# of times)&nbsp;&nbsp;[Script Name]</nowiki>
}}
{{Denizen Requiremnt Type Color|mintcream|
[[Interact_Script_Requirements#Failed|FAILED]]
| &nbsp;&nbsp;<nowiki>(# of times)&nbsp;&nbsp;[Script Name]</nowiki>
}}
{{Denizen Requiremnt Type Color|mintcream|
[[Interact_Script_Requirements#Sunny|ACTIVITY]]
| &nbsp;&nbsp;[Name of Activity]
}}
{{Denizen Requiremnt Type Color|mintcream|
[[Interact_Script_Requirements#Sunny|FLAGGED]]
| &nbsp;&nbsp;(FlagName:Value OR FlagName #)
}}
</div>


'''VAULT REQUIREMENTS'''
[[Denizen/0.7/Example_Scripts/Beginner_Scripts#Denizen_Basics|Denizen Basics]]
<div style="margin-right:2.0em; padding:10px; font-family:museo-sans; font-size:110%;">
* [[Denizen/0.7/Example_Scripts/Beginner_Scripts#Denizen_Basics|The Click and Damage Triggers]]
These requirements only work if you have Vault installed and a compatible permissions/economy plugin.
* [[Denizen/0.7/Example_Scripts/Beginner_Scripts#Denizen_Basics|The Chat and Proximity Triggers]]
[[Denizen/0.7/Example_Scripts/Beginner_Scripts#Simple,_random_conversations|Simple, random conversations]]
* [[Denizen/0.7/Example_Scripts/Beginner_Scripts#A_conversation_with_RANDOM|A conversation with RANDOM]]
* [[Denizen/0.7/Example_Scripts/Beginner_Scripts#A_conversation_with_ZAP_RANDOM|A conversation with ZAP RANDOM]]
* [[Denizen/0.7/Example_Scripts/Beginner_Scripts#The_server_rules|The Server Rules]]
* [[Denizen/0.7/Example_Scripts/Beginner_Scripts#Simple_Bank_teller|Simple Bank Teller]]
* [[Denizen/0.7/Example_Scripts/Beginner_Scripts#Advanced_Bank_teller|Advanced Bank Teller]]


{{Denizen Requiremnt Type Color|whitesmoke|
[[Interact_Script_Requirements#Permission|PERMISSION]]
| &nbsp;&nbsp;[permission.node]
}}
{{Denizen Requiremnt Type Color|whitesmoke|
[[Interact_Script_Requirements#Sunny|GROUP]]
| &nbsp;&nbsp;<nowiki>[Group Name]&nbsp;&nbsp;(Group Name)&nbsp;&nbsp;(Group Name) ...</nowiki>
}}
{{Denizen Requiremnt Type Color|whitesmoke|
[[Interact_Script_Requirements#Money|MONEY]]
| &nbsp;&nbsp;[Quantity]
}}
</div>
</div>
| style="width: 20%;" |


'''Negative Requirements
<div style="padding:16px; vertical-align: text-top;border-color:white; border-style:none; font-family:camingodos-web; font-size:110%; font-weight:500;width:95%;">
<div style="margin-right:2.0em; padding:10px; font-family:museo-sans; font-size:110%;">
Requirements can also be 'negative' requirements. In the Requirements List, just place a '-' in front of the requirement to inverse its logic. For example, 'HOLDING IRON_SWORD' would require the player to be holding an Iron Sword. '-HOLDING IRON_SWORD' would require the player to NOT be holding an Iron Sword. All requirements have a negative alternative, even ones whose function may overlap, such as '-WEATHER Precipitating' and 'WEATHER Sunny', which technically do the same thing. If anything, it can add to script readability. The negative requirement '-' should not be confused with the 'list item -' with a trailing space in front of each Requirement in the List, as that is standard YAML list format. See below:


<code>
===Index===
  Requirements:
    Mode: All
    List:
    - -TIME Night
    - -MONEY 1000000
    - -STORMY
</code>


Negative requirements can completely change the original example around. In this 'revised' example, for this script to trigger, time needs to be day, the weather in the current world must NOT be storming, and the player have less than 1000000 units of currency on them.
If you are having problems getting a script working please see [[Denizen/0.7/Troubleshooting|Denizen/Troubleshooting]].
</div>
</div>
|}


==== Steps Node ====
=== Change Log ===
<div style="margin-right:2.0em; padding:10px; font-family:museo-sans; font-size:110%;">
<div style="margin-right:2.0em; padding:10px; font-family:camingodos-web; font-size:110%;">
Steps are the meat of the script. They control what to listen for and what actions to take. Each script can have multiple steps, each with multiple triggers. Let's use an example.
Here's what's changed!


<pre>
'Welcome to Harbortown':
  Type: Interact
  Requirements:
    Mode: NONE
  Steps:
    '1':
      Click Trigger:
        Script:
        - CHAT 'What's your name, stranger?'
      Chat Trigger:
        '1':
          Trigger: My name is /<PLAYER>/.
          Script:
          - CHAT 'Ah ha, your name sounds familiar! '
          - CHAT 'Are you from around this area?'
          - ZAP
    '2':
      Click Trigger:
        Script:
        - HINT
      Chat Trigger:
        '1':
          Trigger: /Yes/, I grew up in Harbortown!
          Script:
          - CHAT 'I thought so, welcome back!
            Have you heard about Tom the Taylor?
            Isn't that just horrible?'
          - ZAP 3
        '2':
          Trigger: /No/, you must be mistaken.
          Script:
          - CHAT 'Oh, sorry about that.'
          - CHAT 'Hey, if you're looking for some work,
            Bill the Baker is understaffed!
            This is the bakery's busy season.'
          - ZAP 4
    '3':
      Click Trigger:
        Script:
        - CHAT 'I wonder if Tom the Taylor is doing any better.'
        - NARRATE 'Perhaps you should check on Tom the Taylor.'
    '4':
      Click Trigger:
        Script:
        - CHAT 'Oh, nice to see you again <PLAYER>!'
        - CHAT 'Have you stopped by the bakery?'
</pre>


The sub-sections below reference this example.
'''0.7.5 BETA build #455'''
</div>


====Trigger Nodes====
* {{color|red|white|'''New!'''}} OWNER requirement will require ownership of the NPC interacting. Could be used for 'command interfaces' that only the owner can access.
<div style="margin-right:2.0em; padding:10px; font-family:museo-sans; font-size:110%;">
Steps handle the flow of commands and messages with triggers.


'''Denizen Triggers''' trigger from interaction with Denizens. They are defined in the Steps: node.
* {{color|red|white|'''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.


* '''Click Trigger'''s activate when the Denizen is right-clicked.
* {{color|red|white|'''New!'''}} Queue-time flag replacement can let you dynamically use flag data in a script entry. For example: - GIVE <FLAG:ExampleItemFlag> QTY:<FLAG:ExampleQtyFlag>
<pre>
Click Trigger:
  Script:
  - CHAT "Teehee, that tickles!"
  - EMOTE "giggles"
</pre>


* '''Damage Trigger'''s activate when the Denizen is left-clicked. If the Denizen has Damage Triggers disabled, this will count as a Click Trigger.
* {{color|red|white|'''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.
<pre>
Damage Trigger:
  Script:
  - CHAT "OUCH, You'll pay for that!"
  - STRIKE <PLAYER>
</pre>


* '''Proximity Trigger'''s activate when a player walks close to the Denizen.
* {{color|red|white|'''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'.


<pre>
* {{color|red|white|'''New!'''}} Use <*> to use Chat Trigger text in EXECUTE or talk commands.
Proximity Trigger:
  Script:
  - CHAT 'Eek! get away, you smell bad, <PLAYER>.'
</pre>


* {{color|red|white|'''New!'''}} Use <*> in FLAG command to remember player input. Example usage: - FLAG PLAYER_RESPONSE:<*>


* '''Chat Trigger'''s activate when players chat with Denizens. Players' chat within the configurable range will be directed to the Denizen instead of global chat. Chat also follows the configuration setting. a single chat trigger entry can handle multiple words, see below:


<pre>
'''0.7.5 BETA build #440:'''
Chat Trigger:
  '1':
    Trigger: The word needed to /Trigger/ is inside slashes, this whole sentence will appear to be said by the player
    Script:
    - CHAT "Good to know!"
  '2':
    Trigger: A chat trigger can also catch on any word not otherwise caught using /*/.
    Script:
    - CHAT "I don't know what <*> mean, <PLAYER>!"
</pre>


* '''Location Trigger'''s activate when players walk near a [[Location Bookmark]]. Like chat triggers, multiple locations can be defined in one Location Trigger. They are similar in format to Chat Triggers in the fact that there can be multiple triggers per step.
* {{color|red|white|'''New!'''}} API Events make extending Denizen more powerful than ever!


<pre>
* {{color|red|white|'''New!'''}} RUNTASK/CANCELTASK allows delayed tasks to be set, and cancelled.
Location Trigger:
  '1':
    Trigger: TreasureRoom
    - TELEPORT BOOKMARK:Jail
  '2':
    Trigger: BedRoom
    - NARRATE 'You enter the bedroom of the dead man, looking for clues'
</pre>


For a full list of commands, see [[#Script Commands]]
* {{color|red|white|'''New!'''}} HOLD command can change what a Denizen NPC is wielding.
</div>


== Task Scripts in detail ==
* {{color|red|white|'''New!'''}} Replaceable data for dynamically putting flags into texts!
<div style="margin-right:2.0em; padding:10px; font-family:museo-sans; font-size:110%;">
Task scripts are script that are called by either the RUNTASK command or PLAYERTASK command. These are more basic than trigger scripts since they have no requirements or step nodes. The types of commands are also more limited since there is no NPC Denizen associated with the script, but useful for certain situations.
</div>


==== General layout of a Trigger Script ====
* {{color|red|white|'''New!'''}} ISLIQUID requirement can sense if a block bookmark is solid, or liquid.
<div style="margin-right:2.0em; padding:10px; font-family:museo-sans; font-size:110%;">
<pre>
'Name of script':  # Name Node
  Type: Task        # Type Node
  Script:          # Script Node
  - ...
  - ...
</pre>
</div>


==== Using a Task Script with RUNTASK ====
* {{color|red|white|'''New!'''}} IF command can evaluate a FLAG and run a TASK script.
<div style="margin-right:2.0em; padding:10px; font-family:museo-sans; font-size:110%;">
Imagine a scenario where you'd like to check a single outcome from multiple sources. Say, for instance, you have multiple 'quests' that all have the same outcome. You could check the completion for each quest, or, you could have all the quests call a Task Script and check against that.


This is a very basic example for something that can in theory be very complex. Imagination, hoooo!


<pre>
'''0.7 BETA builds #125 - #280:'''
'Apple Reward':
  Type: Task   
  Script:     
  - NARRATE You've received some APPLES. Nice!
  - GIVE APPLE 10
  - FINISH


'Apple Quest 1':
* {{color|red|white|'''Updated!'''}} Less bugs! We're still in beta, but there has been some major code cleanup!
  Type: Trigger
  Requirements:
    Mode: All
    List:
    - -FINISHED Apple Reward
  Steps:
    '1':
      Click Trigger:
        Script:
        - CHAT Welcome to my house, have some apples!
        - RUNTASK Apple Reward
 
'Apple Quest 2':
  Type: Trigger
  Requirements:
    Mode: All
    List:
    - -FINISHED Apple Reward
  Steps:
    '1':
      Click Trigger:
        Script:
        - CHAT Welcome to my orchard, have some apples!
        - RUNTASK Apple Reward
</pre>
</div>


==== Using a Task Script with PLAYERTASK ====
* {{color|red|white|'''New!'''}} Triggers, Commands, Requirements and Activities are now extensible by plugin programmers. See: [http://wiki.citizensnpcs.net/Custom_Denizen_Commands Custom Denizen Commands on the Citizens2 Wiki]. Documentation coming soon!
<div style="margin-right:2.0em; padding:10px; font-family:museo-sans; font-size:110%;">
Tasks scripts are very straight forward when using with a PLAYERTASK command. The script that is called when the 'player task' is complete is a Task script.


<pre>
* {{color|red|white|'''New!'''}} [[#Debug_Mode|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.
'Graveyard Investigation':
  Type: Trigger
  Requirements:
    Mode: NONE
  Steps:
    '1':
      Click Trigger:
        Script:
        - CHAT Go investigate the graveyard for me!
        - PLAYERTASK LOCATION graveyard 20 120 Graveyard Search


'Graveyard Search':
* {{color|red|white|'''New!'''}} [[#Info-click|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!
  Type: Task   
  Script:     
  - NARRATE You are thoroughly spooked out. Maybe you should return to Dave.
  - FINISH


'Graveyard Investigated Complete':
* {{color|red|white|'''New!'''}} [[#Proximity_Trigger|Proximity Triggers]] can trigger a script when a Player comes near. The most requested trigger type I got during the previous betas.
  Type: Trigger
  Requirements:
    Mode: All
    List:
    - FINISHED Graveyard Search
  Steps:
    '1':
      Click Trigger:
        Script:
        - CHAT Ahhh, dang. You couldn't find anything? Ah well, thanks for your help!
</pre>
</div>


== Interact Script Commands ==
* {{color|red|white|'''New!'''}} [[#Location_Trigger|Location Triggers]] can trigger a script when a Player walks over a Location Bookmark. This is kind of like a PLAYERTASK LOCATION, but better! :)
<div style="margin-right:2.0em; padding:10px; font-family:museo-sans; font-size:110%;">
Note: There are plenty more to come, be patient, more are coming! Have ideas for a good command? Let me know!


<code>[] indicates required field, () indicates an optional field, OR indicates alternative usage.</code>
* {{color|red|white|'''New!'''}} [[#Damage_Trigger|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!
</div>


====Script Flow Commands====
* {{color|red|white|'''New!'''}} [[Denizen/Assignments#Overlay_Assignment_Mode|Script 'Overlay' Assignment]] 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!
<div style="margin-right:2.0em; padding:10px; font-family:museo-sans; font-size:110%;">
These commands have no external affect on the world, but can control the flow of scripts within Denizen. Though not required, and with the exception of <tt>WAIT</tt>, it is generally recommended to run these as <tt>Instant Commands</tt> to ensure smooth Script feedback to players.


{{Denizen Command Color|mintcream|
* {{color|red|white|'''New!'''}} [[#Interact Script Commands|ANNOUNCE command]] can make global server announcements.
ENGAGE
| DURATION:[#]) (NPCID:[#])
| <p>Blocks player interaction from triggering the NPC. This may be useful if a long script required the player to listen or watch a series of events and you didn't want the Player to be able to interact while these commands were being taken out. Use with either a <tt>DURATION</tt> or <tt>DISENGAGE</tt>. <tt>DURATION</tt> will automatically <tt>DISENGAGE</tt> after the specified amount of seconds. If no <code>NPCID</code> is included, the Denizen triggered is used. Remember: While <tt>ENGAGED</tt>, no scripts will trigger, so be diligent in using!</p>
'''Example Usages'''
<pre>- ENGAGE
- ENGAGE DURATION:12 NPCID:3
- ENGAGE NPCID:2</pre>
}}
{{Denizen Command Color|mintcream|
DISENGAGE
| &nbsp;&nbsp;(NPCID:[#])
| <p>Allowed an <tt>ENGAGED</tt> Denizen to be interacted with again, the counterpart to the <tt>ENGAGE</tt> command. Can also specify the NPCID of a different Denizen</p>
}}
{{Denizen Command Color|mintcream|
ZAP
|([Step #])&nbsp;('SCRIPT:[Name of Script]')&nbsp;(DURATION:[#])&nbsp;('RANDOM:[#] (#)')
| <p>A very powerful command, indeed. This is how Scripts progress through their steps. It is not done automatically, instead, you get to decide how to progress. ZAP used alone will simply progress the Player to the next step in the Script. Note: Denizen does not check whether the step exists, so you can use that to your advantage in an Overlay Script Assignment. If an Integer is used, that step will be used.</p>
<p>Specify a <tt>SCRIPT</tt> to change the active step for a Player in a specific Script. If not specified, the triggering Script is used. A <tt>DURATION</tt> can be set to provide an automatic "DEZAP" of sorts, reverting the step back after a specific amount of seconds, unless, in that duration another ZAP command has taken place. This can be used as a 'timeout' of sorts. <tt>RANDOM</tt> can be used to let chance select the step to progress the Player to. If one Integer is included, steps 1 through the chosen number will be randomly selected. You can also use a range of numbers if two Integers are used.</p>
'''Example Usages'''
<pre>- ZAP
- ZAP 'RANDOM:3 6' DURATION:60
- ZAP 'SCRIPT:Another Script' 6</pre>
}}
{{Denizen Command Color|mintcream|
WAIT
| &nbsp;&nbsp;[# of Seconds]&nbsp;&nbsp;(QUEUE:TASK<nowiki>|</nowiki>TRIGGER)
| <p>Pauses a Queue for a specified amount of seconds. If no <tt>QUEUE</tt> is specified, the sending queue is used. For example, if the command is sent from an Interact (Triggered) Script, the queue that will be held is the 'Trigger Queue'. Could be useful in advanced usage situations when using both Task Scripts and Interact Scripts together.</p>
'''Example Usages'''
<pre>- WAIT 6
- WAIT 30 QUEUE:TASK</pre>
}}
{{Denizen Command Color|mintcream|
FLAG
| <nowiki>&nbsp;&nbsp;'[Flag Name]'&nbsp;OR&nbsp;'[[Flag Name]:[Flag Value]]'&nbsp;OR&nbsp;[[Flag Name]:++|--]'&nbsp;(DURATION:[#])</nowiki>
| <p>Requires one of the above arguments. <tt>FLAG</tt> store variables, or 'flags', to a Player. This can be used to keep track of information that can be check against with the FLAGGED requirement. Usage of the command is easy, and can be used in 3 different ways. A Boolean (true/false) value can be set with only a flag name. If set, the value is <tt>TRUE</tt>. When <tt>RESET</tt>, it is <tt>FALSE</tt>. <tt>FLAG</tt> can also set Integer (or number) variables, and easily increment or decrease them with the use of the <tt>++</tt> and <tt>--</tt> arguments accordingly. The command can also store a String value, see the example below. Using a <tt>DURATION</tt> will revert the value of the flag to the previous value, if during the duration the flag has not changed.</p>
'''Example Usages'''
<pre>- FLAG 'Sample Boolean Flag'
- FLAG Alignment:++
- FLAG Alignment:--
- FLAG 'Active Item:60 Feathers'
- FLAG HasHealingFlag DURATION:180</pre>
}}
{{Denizen Command Color|mintcream|
FINISH
|&nbsp;&nbsp;('SCRIPT:[Name of Script]')
| <p>Marks a script as 'Finished' to check against with the <tt>FINISHED</tt> requirement. This is kind of like a built-in flag for scripts, and acts much like a Counter, ie. You can <tt>FINISH</tt> a script multiple times and it will keep track of the total number, unless <tt>RESET</tt>.</p>
'''Example Usages'''
<pre>- FINISH
- FINISH 'SCRIPT:Another Script'</pre>
}}
{{Denizen Command Color|mintcream|
FAIL
|&nbsp;&nbsp;('SCRIPT:[Name of Script]')
| <p>Marks a script as 'Failed' to check against with the <tt>FAILED</tt> requirement. This is identical to the <tt>FINISH</tt> command, except keeps track of 'fails' instead. Again, this is kind of like a built-in flag for scripts, and acts much like a Counter, ie. You can <tt>FAIL</tt> a script multiple times and it will keep track of the total number, unless <tt>RESET</tt>. Note: A script can be both 'finished' and 'failed', the two commands work independently.</p>
'''Example Usages'''
<pre>- FAIL
- FAIL 'SCRIPT:Magic Feathers'</pre>
}}
{{Denizen Command Color|mintcream|
RESET
| &nbsp;&nbsp;('SCRIPT:[Name of Script]')
| <p>Sets either FINISHED or FAILED of the specified script to False. Remember: Script names are case sensitive!</p>
'''Example Usages'''
<pre>- FAIL
- RESET FINISHED 'SCRIPT:Magic Feathers'</pre>
}}
</div>


====Server Commands====
* {{color|red|white|'''New!'''}} [[#Interact Script Commands|RANDOM command]] will leave command execution to chance. Duck-duck-goose.
<div style="margin-right:2.0em; padding:10px; font-family:museo-sans; font-size:110%;">
{{Denizen Command Color|mintcream|
EXECUTE
| <nowiki>[ASPLAYER|ASSERVER|ASNPC]</nowiki> '[command with arguments]'
| <p>Runs a Minecraft/Bukkit command. Specifying <tt>ASPLAYER, ASSERVER, or ASNPC</tt> defines how the command should be executed. ASNPC will run the command as the Denizen interacting, temporarily granting OP privileges, if the Denizen NPC is a Human-type NPC. Running ASSERVER will run as a console command, and running ASPLAYER will simply run the command as the Player. When specifying the command and arguments, it is not necessary to use the '/' that is generally used when running commands in-game. You may also use <PLAYER> and <WORLD> as variables inside the command arguments.</p>
'''Example Usages'''
<pre>EXECUTE ASSERVER 'gamemode <PLAYER> 2'
EXECUTE ASNPC 'toggledownfall'
EXECUTE ASPLAYER 'spawn'</pre>
}}
</div>


====Text Commands====
* {{color|red|white|'''New!'''}} [[#Interact Script Commands|HINT command]] will hint to the Player acceptable Chat Triggers for the current step and script. Language support coming soon!
<div style="margin-right:2.0em; padding:10px; font-family:museo-sans; font-size:110%;">
These commands show some text to the player interacting, and usually to bystanders around. Note that all text commands must be surrounded by quotes single ' or double ". See: [[Which_Quotes|Which Quotes?]] for more information. Text commands also have some auto-formatting, such as making sure no words will be cut off on long messages, and applying color codes. See: [[Color_Codes|Denizen Color Codes]]. Formatting for how NPCs and Players talk can be customized in the [[config.yml]].


{{Denizen Command Color|lavender|
* {{color|red|white|'''New!'''}} [[#Interact Script Commands|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!
CHAT
|["The text to chat."] (NPCID:[#]) (NOPLAYER)
| Makes the Denizen talk to the player. This is the standard chat mechanism in Denizen. You can also change the NPC doing the talking by specifying a Denizen's C2 NPCID. If you would rather the Denizen NPC not speak to the Player directly, use the <tt>NOPLAYER</tt> argument.
'''Example Usages'''
<pre>
- CHAT NOPLAYER "Here ye, hear ye!"
- CHAT "Hello there, children!"
- CHAT NPCID:6 'I only supply tools to builders!'
</pre>
}}
{{Denizen Command Color|lavender|
WHISPER
|["The text to whisper."] (NPCID:[#]) (NOPLAYER)
| Whispers the text to the player. Really just an alternative to CHAT. By default, bystanders can't hear what the NPC whispers to the interacting Player. As with the <tt>CHAT</tt> command, NPCID can be specified. Using NOPLAYER is possible too, since it may be of use in some circumstances. But remember: by default, no bystanders can see the actual text the NPC Denizen whispers. This can be changed in the [[config.yml]].
'''Example Usages'''
<pre>
- WHISPER "The password is.. 42."
- WHISPER NPCID:2 "Hey, I didn't want to blurt this out so everyone could hear, but..."
</pre>
}}
{{Denizen Command Color|lavender|
SHOUT
|["The text to chat."] (NPCID:[#]) (NOPLAYER)
| Shouts the text to players nearby. The range that a bystander can hear an NPC Denizen shout is larger then that of a standard <tt>CHAT</tt>, so it also has some technical advantages. <tt>NPCID</tt> can be specified. Using <tt>NOPLAYER</tt> will drop reference to the Player when talking. You can still reference <PLAYER>, however, if need be. See the example below for an idea for usage.
'''Example Usages'''
<pre>
- SHOUT "EEEK! a spider!"
- SHOUT NOPLAYER "<PLAYER> is a thief! Get him!"
</pre>
}}
{{Denizen Command Color|lavender|
EMOTE
|['The text to emote.'] (NPCID:[#])
| Let's the Denizen NPC show emotion. Similar to the /me command in IRC, for example. Could be useful for describing to the player what an NPC Denizen may need, or how the NPC Denizen is feeling. <tt>NPCID</tt> can be specified to change the Denizen NPC doing the 'emote'.
'''Example Usages'''
<pre>
- EMOTE 'is looking a bit nervous.'
- EMOTE NPCID:82 'thinks you should ask a few questions.'
- EMOTE "could use a stiff drink."
</pre>
}}
{{Denizen Command Color|lavender|
NARRATE
|['The text to narrate.']
| Makes a message appear to player without sender information.
'''Example Usages'''
<pre>
- NARRATE "There is a small mailbox here."
</pre>
}}
{{Denizen Command Color|lavender|
ANNOUNCE
|['The text to announce.']
| Sends the text as a sever announcement to all players, regardless of their place in the world. Could be especially useful for any kind of administration script.
'''Example Usages'''
<pre>
- ANNOUNCE "<PLAYER> has found a secret!"
</pre>
}}
</div>


====Denizen NPC Commands====
* {{color|red|white|'''New!'''}} [[#Requirement Types|FLAG requirement]] can require special flags and values to be set in order to be eligible for a script. Again, this is HUGE!
Denizen NPC commands are meant to help bring your Denizen to life by allowing fine-control of small movements. These are not necessarily meant for making the Denizen NPC do large/long activities, those will instead be done by the [[Activity Engine]], which is just now starting to be implemented into Denizen. The next 'large' update will focus on Activities.


{{Denizen Command Color|mintcream|
* {{color|red|white|'''New!'''}} [[#Requirement Types|POWERED requirement]] can check if a block bookmark has redstone power. Great idea, instinx!
LOOK
| LOOK [[DIRECTION]|BOOKMARK:[BOOKMARK_NAME]|[CLOSE|AWAY]] (NPCID:[#]) (DURATION:[#])
| <p>This command controls where the NPC Denizen is looking. It requires either a Direction, Bookmark, or look-close trait state. Valid directions: <tt>UP, DOWN, LEFT, RIGHT, NORTH, SOUTH, EAST, WEST, AT, and BACK</tt>. Looking <tt>AT</tt> or <tt>BACK</tt> takes the Player's position for reference. AT will look at the Player, <tt>BACK</tt> will look away from the player. Using <tt>CLOSE|AWAY</tt> will toggle the NPC's <tt>look-close trait</tt>. <tt>CLOSE</tt> will make the NPC's head follow the closest Player to it. You can toggle off this behavior by using <tt>AWAY</tt>, not to be confused with <tt>BACK</tt>. If you specify a Location Bookmark instead of a direction, the NPC will take the pitch and yaw from the information stored in the bookmark. Note: This does not affect the actual position of the NPC Denizen, only the head position. Using a <tt>DURATION</tt> argument will restore the previous head position after that amount of time. Note: The script queue will continue as normal, so if the NPC moves or uses another LOOK command in this duration, it may get glitchy. Either time your commands appropriately, or use a <tt>WAIT</tt> command to compensate. The optional argument <tt>NPCID</tt> will change the Denizen NPC doing the looking.
'''Example Usages'''
<pre>- LOOK UP
- LOOK CLOSE NPCID:32
- LOOK BOOKMARK:HiddenChest DURATION:3</pre>
}}


* FOLLOW [PLAYER|NOBODY]
* {{color|red|white|'''New!'''}} The activity engine has been implemented which will allow your Denizen 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!
*: </code>Makes the Denizen follow the player, or stop following the player.<code>


* WALKTO [Location Bookmark]
* {{color|red|white|'''New!'''}} [[#In-game_Commands|In-game commands]] now let you easily manage triggers, bookmarks, and debug info.
*: </code>Makes the Denizen walk to a specified location.<code>
Note: I've been having problems getting the NPCs to WALKTO a bookmarked location that is far away, perhaps in a different chunk? Working on it with the C2 team. I may have another workaround as well.


* WALK [Z] [X] [Y]  Note: Z(-NORTH(2)/+SOUTH(0)) X(-WEST(1)/+EAST(3)) Y (+UP/-DOWN)
* {{color|red|white|'''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!
*: </code>Makes the Denizen walk. This is not for making the Denizen to specific coordinates. The values for X Y and Z will get added or subtracted from the Denizen's current location.<code>


* RETURN
<br>
*: </code>Can be used after initiating a WALK command.  This will make the denizen return to its previous location.<code>
You can see more at the full [https://github.com/aufdemrand/Denizen/commits/master Denizen Changelog].
 
* RESPAWN [Location Bookmark]
*: </code>Despawns the Denizen and respawns it to a bookmarked location.<CODE>
Note: There is something funny going on with NPCs spawning to a location you are very near to. You sometimes have to back away before they show up. This seems to be an issue with Craftbukkit and/or Minecraft Server.</code>
 
====Vault Commands====
<div style="margin-right:2.0em; padding:10px; font-family:museo-sans; font-size:110%;">
The commands below require Vault and a valid permissions and economy system. Though Vault is not required to use Denizen, the commands below DO require Vault and its dependencies to be installed. Remember: Vault is not an economy or permissions system, merely a hook to help Denizen connect to your favorite systems!
 
{{Denizen Command Color|lavender|
PERMISS
|<nowiki>[permission.node]|['GROUP:group name'] (WORLD)|('WORLD:NAME')</nowiki>
| <p>Gives the Player either a permissions node or adds a group, if supported by your permissions system. Note: You should not include both a permissions node and a group. If you specify a <tt>WORLD</tt> argument, it will apply the permissions node/group only to the current world. You can alternatively specify a world with <tt>WORLD:worldName</tt>.</p>
'''Example Usages'''
<pre>
- PERMISS modifyworld.*
- PERMISS GROUP:HillsideEnemy
- PERMISS citizens.* WORLD:testworld
</pre>
}}
{{Denizen Command Color|lavender|
REFUSE
|<nowiki>[permission.node]|['GROUP:group name'] (WORLD)|('WORLD:NAME')</nowiki>
| Removes from the Player either a permissions node or a group, if supported by your permissions system. Note: You should not include both a permissions node and a group. If you specify a <tt>WORLD</tt> argument, it will remove the permissions node/group only to the current world. You can alternatively specify a world with <tt>WORLD:worldName</tt>. Generally, however you add your permissions or group with <tt>PERMISS</tt>, you should do the same when removing with <tt>REFUSE</tt>.
'''Example Usages'''
<pre>
- REFUSE modifyworld.*
- REFUSE GROUP:HillsideEnemy
- REFUSE citizens.* WORLD:testworld
</pre>
}}
</div>
</div>


====World Interaction Commands====
__NOTOC__
These commands do something physical to the world or player.
 
* SWITCH [Block Bookmark]
*: </code>If a lever is found at the block location, it will be switched ON or OFF.<CODE>
 
* SPAWN [ENTITY_TYPE] [AMOUNT] (Location Bookmark)
*: </code>Spawns a specified amount of entities. If the location bookmark is missing, they will spawn near the Denizen.<CODE>
 
* TELEPORT [Denizen Name] OR [BOOKMARK:BookmarkName] OR ['BOOKMARK:Denizen Name:BookmarkName']
*: </code>Teleports the player interacting to a bookmark or Denizen/ <code>
 
* STRIKE
*: </code>Strikes the player with lightning.<CODE>
 
====Player Interaction Commands====
* GIVE [MONEY|#(:#)|MATERIAL_TYPE(:#)] (QTY:#)
*: </code>Denizen will drop specified items.<CODE>
 
* TAKE [MONEY|ITEMINHAND|#(:#)|MATERIAL_TYPE(:#)] (QTY:#)
*: </code>Takes specific item or money from the player.<CODE>
 
* CAST [POTION_TYPE] [Duration in seconds] [Amplifier]
*: </code>Gives the player interacting a potion effect. Note: [[Alchemist#Valid_Effects | Valid potion types are the same as the Alchemist's.]] Amplifier specifies 'level, strength, or duration', depending on the type of potion effect. Try 1-5 for most types.<CODE>
 


<CODE>
[[Category:Denizen 0.7]]</s>
</code>
</div>

Latest revision as of 16:07, 24 March 2020

Denizen.png

Denizen is an extension for Citizens that allows scripting of NPCs to handle tasks, quests, player interaction and more!

Current Version: 0.7.6 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.

Denizen-Logo-Large.png
A small glimpse of Denizen.


For more up-to-date information and full details on specific features (individual commands or tags, for example), check the Meta Documentation.

If you want a full tutorial to help get you set up, check out the Tutorial Videos on youtube or the Beginner's Guide text website.

If you need quick help, visit our Discord group.




This wiki is outdated, please view the tutorial videos/guide, meta documentation, or Discord group (all linked above) for up-to-date information!


This is the old Wiki for Denizen 0.7.6! Information found here does not apply to later versions of Denizen.


Denizen is 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.



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.


How it works

Denizen is an extension of Citizens2 that adds an incredible amount of interactivity and automation to NPCs and Players with some of these major features:

  • The Script Engine carries out and sends all the commands to be executed in an orderly and predictable fashion; this is the backbone of Denizen. Currently has 3 queues, one for the Player, one for Denizen, and one for Tasks. There's not much to see on the outside, this is the interworkings of Denizen, but rest assured that this is high performance machine behind the scenes!
  • Interact Scripts are the meat of Denizen, allowing Players and NPCs to interact with each other and the world. These are highly customizable with 20+ requirement types, 40+ script commands, and thousands of different ways to use them together. This with the Denizen Script Engine also allows commands to help control the rest of Denizen with script flow commands and such.
  • Activity Scripts are exciting. Imagine Johnny Appleseed planting trees, on his own, or simple villagers wandering around and socializing. Activities, of course, work with the rest of Denizen's other functions and features, allowing hundreds of ways to use Activities to add automation and liveliness to your world.
  • Activity Scheduler takes Activity Scripts one step further, allowing Denizen NPCs to have daily schedules, based on the Minecraft day, to allow certain functionality to different times of the day. This also enables certain Script Commands to be executed and carried out, as well.
  • Task Scripts are simple scripts that can be carried out in a variety of different ways. These can be used along side both Activity and Interact Scripts, but perhaps the most powerful way to use them is by allowing your plugin to utilize them, if you're a developer, or using other plugins that harness the ability to run a Denizen Task Script as well.
  • Listeners are currently in an 'experimental phase', but are already allowing control over minecraft and bukkit events like nothing other. This already allows scripts to keep track of and assign 'quest-like' objectives, such as a 'kill quest', if you're familiar with the C1 Quester. But whereas many quest plugins are limited to this feature alone, Denizen, of course, allows you to use this in addition and along side the rest of the plugin, making room for extremely dynamic and intricate 'quest scripts'.
  • Flag System is the key to Denizen being dynamic. An intricate, yet easy to learn 'Flag/Variable' system has been implemented into Denizen to help keep track of events, items, numbers, players, and more. The new Flag System is still getting more powerful each and every day.. it's the key to a spectacular script is sure to have a flag or two.
  • Extensible Commands/Requirements/Activities and more make it easy to add-on to Denizen with very little Java knowledge. This also makes it extremely easy to let users utilize your plugin with script commands. Denizen also has API Events to use.
  • Denizen Debugger' is an extremely friendly and informative way to test out scripts and interactions. Commands, events, and interactions are all logged in an easy to read format to show the exact progression of a script and its surroundings. No more guessing! Less headaches!


Seem overwhelming? Stop! Start small! Denizen is easy, Denizen is simple. But. Denizen is hard, Denizen is complex. Simply put: Denizen is what you make it! Our advice? Start small, and build upon what you have. Read the wiki articles, watch the youtube videos, test our your scripts, and test out some of the sample scripts! Before you know it, you'll be a Denizen poweruser, drunken with power, just like us!


Denizen

If you are new to Denizen, see Before Using Denizen: Getting Started.
If you are having problems getting a script working please see Troubleshooting.
If you're hooked, we recommend you read all the sections in order and try out some sample scripts!

Index

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! 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' Assignment 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! 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 Denizen 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.

Retrieved from ‘https://wiki.citizensnpcs.co/index.php?title=Denizen/0.7&oldid=5228’