Denizen/0.6: Difference between revisions

From Citizens Wiki
No edit summary
No edit summary
 
(238 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{ExternalType}} {{CharacterType
 
 
For more up-to-date information and full details on specific features (individual commands or tags, for example), check the [https://meta.denizenscript.com/ Meta Documentation].
 
If you want a full tutorial to help get you set up, check out the [https://guide.denizenscript.com/ Beginner's Guide] text website.
 
If you need quick help, visit our [https://discord.gg/Q6pZGSR Discord group].
 
<br><br><br>
 
<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>
 
<br><br><br>
 
 
 
 
 
 
 
 
 
 
 
<s>{{Alert
|title = Version warning.
|text= This documentation is for Denizen 0.6 and is out of date.
 
Denizen 0.6 is not compatible with the latest builds of C2 or Bukkit 1.3.1.
 
See this link for the latest download of Denizen 0.7.
[http://ci.citizensnpcs.net/job/Denizen Link]'''
 
Preliminary documentation for Denizen 0.7 is available [[Denizen/0.7|here]] '''Please be aware this page may contain errors.
 
|bc= red
|bgc= white
}}</s>
 
{{CharacterWithExamples
| PICTURE      = Denizen.png
| PICTURE      = Denizen.png
| AUTHOR      = aufdemrand
| NAME        = Denizen
| NAME        = Denizen
| AUTHOR      = [[User:aufdemrand|aufdemrand]]
| VERSION   = 0.6 Build #124
| VERSION     = 0.5
| CITIZENSBUILD  = 2.0 Beta
| CITIZENSBUILD  = 2.0 Newest Dev
| DEVSTATUS    = BETA
| DEVSTATUS    = InDev
| DEPENDS = Vault
| DOWNLOADLINK =  
| DOWNLOADLINK = http://ci.citizensnpcs.net/view/Characters/job/Denizen/124/artifact/target/denizen-0.6.jar
| BUKKITDEVLINK =
| DOWNLOADEXAMPLESLINK = http://dl.dropbox.com/u/44002922/Start-up%20Kit.zip
| SOURCELINK = http://www.github.com/aufdemrand/Denizen
| DESCRIPTION  = Scriptable, interactive citizens!
| ISSUESLINK = http://www.github.com/aufdemrand/Denizen/Issues
| DESCRIPTION  = Denizens are helpful, interactive Citizens!
}}
}}
<s>
<div style="float:left clear:both; margin-left:0.5em; margin-bottom:2.0em">__TOC__</div>
<div style="margin-right:2.0em; padding:10px">
Denizens are a great way to add [http://en.wikipedia.org/wiki/MUD MUD-style] RPG Citizens (and some other features) 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!
</div>
== Script Repository ==
<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>
== Change Log ==
<div style="margin-right:2.0em; padding:10px">
Here's what's new!
'''Note to beta users pre-build 98:''' File structure has changed over the last few builds up to 98. The <code>Denizens:</code> node now has its own YML file called assignments. You will need to create this file and cut/paste the node from your config.yml. It's also recommended that you download the new [[Denizen config.yml]] since some nodes have changed or been expanded upon. Denizen location and block bookmarks are also now stored in saves.yml. You will need to migrate those there, or recreate them before using scripts that use bookmarks. See [[#File Structure]] for more information on the new file structure.
'''0.6 Build #104'''
* Added PLAYERTASK command. LOCATION QUESTS! (This is for you, Ratkoon)
'''0.6 Build #98'''
* Update to file structure. saves.yml now contains all information that the denizen plugin writes. This includes player progression/completion/etc. information, denizen location bookmarks, etc. If edited by hand, probably best to shut down the server first. Any existing information in the players: node and denizen location bookmark information needs to be either recreated or migrated into saves.yml.
* Added HEAL and HURT commands. Use HEAL [# of health] or HURT [# of health].
* Added CHANGE command to change the type of block at a block bookmark. Use CHANGE [Block Bookmark] [#:#|MATERIAL_TYPE].
* Added ATTACK command. Use like FOLLOW.
* GIVE and TAKE should now also accept #:# format as well as MATERIAL_TYPE.
* Added ENGAGE and DISENGAGE commands. When a Denizen is ENGAGE'd, no other interaction will be registered with the NPC until DISENGAGED. This could be useful for keeping players from 'repeating steps' while mid-script. Use ^ENGAGE at the beginning of the script and DISENGAGE at the end.
* Requirements using items can now use #:# syntax to check item typeId and data.
* Requirements WORLD, POTION_EFFECT, NAME, PERMISSION, and GROUP can check for multiple names/nodes.
* FINISHED can now check for a specific amount of times a player has finished. Use: FINISHED # [name of script].
* Script combiner should now only pick up .yml files.
* Various other bug fixes.
'''0.6 Build #82'''
* Requirements code reformat is done, thanks for being patient if you were watching the Jenkins!
* FINISH command now increments a counter so you can check for a certain number of FINISHes. Use: <code>FINISHED (# of times) [name of script]</code>. The # is optional and will assume 1 if not specified. There's a chance that this broke any recorded FINISHes that may be in your config. Sorry about that. You can manually change them from True to 1 to fix this. New FINISHes will overwrite without any issues.
* TIME requirement can now check for DAWN and DUSK in addition to DAY and NIGHT.
* Requirements that use items can now use the #:# (typeId:data) format. So, for gray wool, 35:7. You can still specify just WOOL and any color will do.
* Script combiner will now only read .yml files, this fixes issues with hidden files in your scripts file corrupting the combined read-only-scripts.yml.
* NAME, WORLD, PERMISSION, GROUP, POTION_EFFECT can now all use multiple arguments. For example, <code>WORLD world_1 world_2 world_3 world_4</code> will return true if one of the worlds listed matches. You can use up to 24 arguments.
'''0.6 Build #71'''
* Started code reformat, this will make it easier to extend.
* Added ability to use multiple scripts! Denizen will read any .yml file in the /plugins/Denizen/scripts/ folder. You will need to place your existing scripts.yml in that folder. Denizen will generate a read-only-scripts.yml to the main Denizen folder. This should be left alone. Also made config.yml generate automatically upon startup.
* Added config node chat_globally_if_no_chat_triggers
<br>
You can see more at the full [[Denizen changelog]].
</div>
== Known caveats ==
<div style="margin-right:2.0em; padding:10px">
There are some 'issues' with Denizen that we are aware of, and thought that you should be too. Keep in mind that we're working hard to fix these, as soon as possible.
* I've been having problems getting the NPCs to WALKTO a bookmarked location that is far away.
* When close to a Denizen that is RESPAWNing, it sometimes won't actually spawn until you back away from it.
* Multi-line CHATting loses color codes second line on.
</div>
== Before using Denizens ==
<div style="margin-right:2.0em; padding:10px">
Denizens are in BETA! Expect a few bugs here and there! There is little error handling for scripts that contain bad syntax, so if you are getting errors while processing a script, the first thing you should do it check the script syntax. I'm working hard to catch errors, but every once in awhile you'll find one that requires a /reload or server restart. If you do come across any errors beyond bad syntax, please  report them to the [http://www.github.com/aufdemrand/Denizen/issues Github Issues page for Denizens]. You can also get assistance with Denizens on the [irc://irc.esper.net #citizens IRC channel on EsperNET] from me (aufdemrand) when available. I'm usually there working hard to add awesome features and squashing bugs.
Denizen is not a drag-and-go type of plugin. In fact, Denizen won't do anything unless you assign and define scripts to NPCs. It's highly customizable and you should expect that to be able to write scripts, it is suggested you read the entirety of this wiki document. I'm always around IRC to help out, but please don't ask about the basics unless you have consulted here first.
Denizens '''REQUIRES''' you to have [http://dev.bukkit.org/server-mods/vault/ Vault] installed. You also should have a Permissions System and and Economy System for best results.
</div>
== Getting started with Denizen ==
<div style="margin-right:2.0em; padding:10px">
The easiest way to use Denizen for the first time is to download the [http://dl.dropbox.com/u/44002922/Start-up%20Kit.zip Start-up Kit] with sample .yml configuration files and scripts. This includes the default config file, sample scripts, and sample assignments to get you started. Denizen relies on a few files to run properly, so let's first go over the file structure.
</div>
=== File Structure ===
[[File:Figure 1 - Denizen file structure.png|250px|thumb|right|Denizen File Structure]]
<div style="margin-right:2.0em; padding:10px">
Denizen requires the use of a few different YML files to operate properly. This includes a config.yml, assignments.yml, scripts, and saves.yml.
</div>
==== config.yml ====
<div style="margin-right:2.0em; padding:10px">
The Denizen config.yml contains nodes to alter the stock behavior and look of Denizen. You'll notice that Denizen does not create its own config.yml. Why is this? Denizen stores its entire config inside memory, so it's not necessary to have a copy inside the Denizen folder unless you need to change the defaults. You can use the config.yml to override those defaults. Not having Denizen write to the config.yml itself (as well as scripts files, and assignments.yml) ensures that upon a <code>/denizen reload</code>, the config.yml, between a save and reload, is never changed when you don't want it to. This also keeps code comments inside the YML files stay intact, exactly the way you left them from last edit allowing you to leave yourself and others detailed notes and ideas.
This file can be reloaded into from disk to Denizen memory at any time by using <code>/denizen reload</code>.
See: [[Denizen config.yml]] for a stock copy and explanation of all available options.
</div>
==== assignments.yml ====
<div style="margin-right:2.0em; padding:10px">
This YML is where you can define all the options and information for your Denizen NPCs. This will be explained further along in this document, but the most common information in this file is [Interact Script Assignments], [Activity Script Schedule], and [Custom Interact Texts].


DENIZENS are helpful, interactive Citizens!
This file can be reloaded from disk into Denizen memory at any time by using <code>/denizen reload</code>.


Denizens are a great way to add MUD-style RPG Citizens (and some other features) to your server. Denizen NPCs use mini scripts with steps and events to interact with the player and world. They can be used in hundreds (thousands?) of different ways, from tutorials, to questing, to administrating and more!
See: [[#A basic assignment]] for information on how to get started with assignments.
</div>


Denizens are in BETA! Expect bugs, and if you would be so kind, please report them to the Github Issues page for Denizens. You can also get assistance with Denizens on the #citizens IRC channel on EsperNET from me (aufdemrand) when available. I'm working hard to add awesome features and to squash any bugs, but here's the tentative timeline I'm trying to follow.
==== saves.yml ====
<div style="margin-right:2.0em; padding:10px">
This file is not meant to be edited by hand, Denizen will create and populate this file automatically as needed. It stores important information such as player progression, Denizen location and block bookmarks, active activity script progression and more. If you absolutely need to make changes by hand, it's best to stop the server, edit, and then restart your server, as this file is constantly being written to by Denizen which will overwrite any changes you make.


<pre>
This file saves periodically, and automatically, upon progression and a server stop.
Timeline:
</div>
Beta 1 -- All functionality used in the example file.
 
Beta 2 -- Additional functionality of additional behaviors/requirements/triggers listed.
==== read-only-scripts.yml ====
1.0 -- Bug fixes from Beta.
<div style="margin-right:2.0em; padding:10px">
1.5 -- Standalone (Window) script writer.
This is another files that Denizen creates and should not be edited by hand. This is a combination of the files contained in the scripts folder that Denizen reads from.  
2.0 -- Profit.
</pre>


This file is populated on a server restart, or by using the <code>/denizen reload</code> command.
</div>


= How do Denizens work? =
==== /scripts/ folder ====
<div style="margin-right:2.0em; padding:10px">
This folder is where Denizen will read all the script information from. Upon a server load or <code>/denizen reload</code>, the files are combined and put into the read-only-scripts.yml for the Denizen to read from. This allows better organization of scripts to be maintained, since the amount of scripts can easily get into the triple digits.


There are lots of cool things that the Denizens plugin has to offer, but let's start with the basics. YAML scripted NPCs.
The files in the plugins/Denizen/scripts/ folder can be named whatever you please, as long as they end in <code>.yml</code>. Be sure not to duplicate script names from file to file as this will cause problems.  


See: [[#A basic trigger script]] for information on how to get started with scripts.
</div>


== A basic script ==
== Writing Scripts and Assignments ==
<div style="margin-right:2.0em; padding:10px">
Still reading? Great! You're on your way to writing some sweet scripts. Let's start out with the basics: Trigger Scripts and Assignments. Denizen needs two things to be functional. A script, and an assignment. Scripts, obviously, hold instructions that are carried out when triggered. Assignments hold information on which scripts should trigger, and when. Bear with me, and keep reading!
</div>


First, we need a script. Scripts can be simple or very powerful, thanks to a wide array of commands and functions at your disposal. Each script has at least 2 parts, Requirements and Steps. For now, let's take this very simple script as an example. We'll get more detailed later on.
==== A basic trigger script ====
<div style="margin-right:2.0em; padding:10px">
First, we need a script. The great thing about a Denizen script is that it can be simple or advanced, short or long, thanks to a wide array of commands and functions at your disposal. Scripts can work with, extend, and rely on one another to create rich, interactive gameplay. Each script has at least 2 parts, Requirements and Steps. For now, let's take this very simple script as an example. We'll get more detailed later on.


Scripts are defined in the Scripts node found in plugins/Denizens/config.yml
Remember: Scripts are defined in <code>plugins/Denizen/scripts/</code> folder. They can be put into any YML file contained in that directory. You may need to create the directory yourself if no scripts yet exist.


<pre>
<pre>
Scripts:
'Daytime in the City':   
  'Daytime in the City':   
  Type: Trigger
    Requirements:
  Requirements:
      Mode: All
    Mode: All
      List:
    List:
        - TIME Day
    - TIME Day
     Steps:
  Steps:
       0:
     1:
         Click Trigger:
       Click Trigger:
          - CHAT Welcome to the city! Isn't it beautiful in the daytime?
         Script:
        - CHAT Welcome to the city! Isn't it beautiful in the daytime?
</pre>
</pre>


So what just happened there? A quick literal translation: This script is named 'Daytime in the City'. This name is used when assigning Denizen NPCs their scripts to use. When the script is called by a trigger, in this case a 'Click Trigger', for it to activate the Requirements set must be met, more specifically ALL of the requirements set. In this example, the only requirement is that the time in the world is daytime. If the Requirements are met, the script defined in the 'Click Trigger' is sent to be run. It will have the Denizen NPC chat to the player 'Welcome to the city! Isn't it beautiful in the daytime?'.
So what just happened there? A quick literal translation: This script is named <code>'Daytime in the City'</code>. This name is used when assigning Denizen NPCs their scripts to use. When the script is called by a trigger, in this case a <code>'Click Trigger'</code>, for it to activate the Requirements set must be met, more specifically <code>ALL</code> of the requirements set. In this example, the only requirement is <code>TIME DAY</code> which requires the current time in the world to be daytime. If the Requirements are met, the script defined in the <code>'Click Trigger'</code> is sent to be run. It will have the Denizen NPC chat to the player 'Welcome to the city! Isn't it beautiful in the daytime?'.


But before the script can be triggered, it needs to be assigned.
But before the script can be triggered, it needs to be assigned.
</div>


==== A basic assignment ====
<div style="margin-right:2.0em; padding:10px">
In order for a Denizen to be associated with a script, he needs to be assigned to it. The following shows a simple assignment format.


== A basic assignment ==
Assignments are defined in the Denizens node found in plugins/Denizen/assignments.yml and must be done by hand. Once you edit the config.yml, immediately save and use /denizen reload in-game.


In order for a Denizen to be associated with a script, he needs to be assigned to it. The following shows a simple assignment format.  
<pre>
Denizens:                       
  'Steve':                       
    Interact Scripts:                     
    - 10 Daytime in the City 
    Texts:
      No Requirements Met: 'Come back during the day!'
</pre>
 
Let's break this down again. This assignement will work for Denizens named <code>'Steve'</code>. Triggers that involve this NPC, such as a <code>'Click Trigger'</code> will call the script named <code>'Daytime in the City'</code>. The <code>10</code> before the name is the script priority, useful when assigning multiple scripts, but we'll get into that next. If no scripts meet requirements (in this case -- if it's NOT daytime when clicking on Steve), the text defined in the <code>Texts:</code> node called 'No Requirements Met' will trigger instead. So to reiterate, if the player clicks on Steve during the daytime, the player will get a chat containing 'Welcome to the city! Isn't it beautiful in the daytime?' If the player clicks during the nighttime, since the script requirements are not met, the player will see a chat containing 'Come back during the day!'. Note that the default <code>No Requirements Met</code> text can be changed in the <code>config.yml</code>.
</div>


Assignments are defined in the Denizens node found in plugins/Denizens/config.yml
==== Multiple Script Assignments ====
<div style="margin-right:2.0em; padding:10px">
The key to Denizens being dynamic is their ability to handle multiple scripts in different situations. This is done by assigning a priority to script assignments. Let's take this example configs below to see how script priority is handled. The below code references <code>assignments.yml</code> and a <code>script.yml</code>.


<pre>
<pre>
---- assignments.yml ----
Denizens:                         
Denizens:                         
   'Steve':                         
   'Steve':                         
     Scripts:                       
     Interact Scripts:                       
      - 10 Daytime in the City  
    - 0 Regular Joe
     No Scripts To Trigger:
    - 10 Joe the Builder  
       - CHAT I have nothing to say to you at this time.
 
---- script.yml ----
 
'Regular Joe':
  Type: Trigger 
  Requirements:
    Mode: None
  Steps:
     1:
      Click Trigger:
        Script:
        - CHAT Hello <PLAYER>! I supply builders only!
 
'Joe the Builder':
  Type: Trigger  
  Requirements:
    Mode: All
    List:
    - PERMISSION modifyworld.*
  Steps:
    1:
       Click Trigger:
        Script:
        - ENGAGE
        - CHAT Hello <PLAYER> the Builder! Take this shovel!
        - GIVE WOOD_SPADE 1
        - FINISH
        - DISENGAGE
</pre>
</pre>


Another literal translation. This assignement will work for Denizens named 'Steve'. Triggers that involve this NPC, such as a 'Click Trigger' will call the script named 'Daytime in the City'. The 10 before the name is the script priority, useful when assigning multiple scripts, but we'll get into that later. If no scripts meet requirements (in this case -- if it's NOT daytime when clicking on Steve), 'No Scripts To Trigger' will run instead. So to reiterate, if the player clicks on Steve during the daytime, the player will get a chat containing 'Welcome to the city! Isn't it beautiful in the daytime?' If the player clicks during the nighttime, since the script requirements are not met, the player will see a chat containing 'I have nothing to say to you at this time.'
Denizen <code>Steve</code> has been assigned two scripts. Upon player interaction, each script is checked for met requirements. If only one script has their requirements met, it's clear what script will be returned. But what if both meet requirements? That's where the number before each script assigned comes in. Higher priority always wins. To break down this specific situation, if a player with the 'modifyworld.*' permission clicks on Steve, both scripts meet the requirements, but since the script 'Joe the Builder' has a priority of 10, and 'Regular Joe' only has a priority of 0, 'Joe the Builder' sends its script. 'Regular Joe' is simply ignored. Denizens can be issued as many scripts as you want.  If two scripts have the same priority, the first in the list will be the one to trigger, if both scripts meet their requirements.
</div>
 
==== Things to Note, Thus Far ====
<div style="margin-right:2.0em; padding:10px">
Denizens with the same name use the same script assignments. The plus to this is the ability to quickly make 'generic NPCs' such as a 'Townsman' or 'Miner'.
 
All the scripts and configuration nodes are in YAML. Remember! Spacing is CRITICAL when dealing with YAML files. Each parent node and sibling node should follow the spacing and formatting guidelines set forth by the YAML 1.0 standard.
 
In all the examples used in this guide, 2 spaces are used for indenting.  Generally, whatever you choose should be maintained through your YAML document. No tabs are allowed in YAML files.
 
In the YAML files, nodes are case sensitive! 'Scripts:' will work. 'scripts:' will not! All nodes are first letter capital, rest of the word lowercase. Scripts names follow this rule too!
 
YAML tutorials can be intimidating, but [http://wiki.ess3.net/wiki/YAML_Tutorial this small tutorial on the Essentials wiki] is pretty useful for basic YAML, which is the extent of which Denizens uses.
</div>


== Assignments in Detail ==


== Multiple Scripts ==
== Trigger Scripts in detail ==
<div style="margin-right:2.0em; padding:10px">
The general structure of a script should always include the 'Name', 'Type', 'Requirements', and 'Steps' nodes. These are required.


The key to Denizens being dynamic is their ability to handle multiple situations. This is done by multiple script assignments. Let's take this example config.yml below to see how script priority is handled.
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.
</div>


==== General layout of a Trigger Script ====
<div style="margin-right:2.0em; padding:10px">
<pre>
<pre>
Denizens:                        
'Name of script':  # Name Node
   'Steve':                      
  Type: Trigger    # Type Node
     Scripts:                    
   Requirements:    # Requirements Node
      - 0 Regular Joe
    ...:
      - 10 Joe the Builder  
    ...:
      - ...
      - ...
  Steps:            # Steps Node
    ...:
      - ...
    ...:
  Options:          # Options Node
    ...:
</pre>
</div>
 
==== Name Node ====
<div style="margin-right:2.0em; padding:10px">
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 must 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="margin-right:2.0em; padding:10px">
Let's Denizen know the type of script. For trigger scripts, as explained in this section, use <code>TYPE: TRIGGER</code>.
</div>
 
==== Requirements Node ====
<div style="margin-right:2.0em; padding:10px">
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:
 
<pre>
  Requirements:
     Mode: All
    List:
    - TIME Night
    - MONEY 1000000
    - STORMY
</pre>
 
This would be a difficult script to obtain, for sure. To trigger, the time would have to be after 16000, but before 0, the player would need one million dollars on hand (or whatever economy you use), 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.
</code>
</div>
 
===== Mode Types =====
<div style="margin-right:2.0em; padding:10px">
<code>[] indicates required field
 
* ALL
*: </code>Requires all requirements listed to be met.<code>
* ANY [#]
*: </code>Requires the specified number of requirements to be met, out of the total of requirements listed.<code>
* NONE
*: </code>Requires NO requirements to be met.<code>
</code>
</div>
 
===== Requirements Types =====
<div style="margin-right:2.0em; padding:10px">
<code>[] indicates required field, () indicates an optional field, OR indicates alternative usage.
 
* NAME [Player Name] (or this Player Name) ...
*: </code>Requires a specific player.<code>
 
* ITEM <nowiki>[</nowiki>[[ITEM_NAME|#:#]]<nowiki>]</nowiki> (# of that item, or more)
*: </code>Requires the player to have an item in their inventory.  You can also specify an amount.<code>
 
* WEARING <nowiki>[</nowiki>[[ITEM_NAME|#]]<nowiki>]</nowiki>
*: </code>Requires the player to be wearing a specific piece of armor.<code>
 
* HOLDING <nowiki>[</nowiki>[[ITEM_NAME|#:#]]<nowiki>]</nowiki> (# of that item, or more)
*: </code>Requires the player to have an item in their hand. You can also specify an amount.<code>
 
* TIME [Day|Night|Dusk|Dawn]  OR  TIME [0-23999] [1-24000]
*: </code>Requires day or night. Alternatively you can specify a time window.<code>
 
* HUNGER [Full|Hungry|Starving]
*: </code>Requires a specific hunger state.<code>
 
* PRECIPITATION
*: </code>Requires a rain or snow.<code>
 
* SUNNY
*: </code>Requires clear skies.  Note: This can still trigger at night as it does not check time.<code>
 
* WORLD [World Name] (or this World Name) (or this World Name) ...
*: </code>Requires the player to be in a specific world, or worlds. You can check as many as you'd like with one line.<code>
 
* PERMISSION [this.permission.node] (or this permission.node) ...
*: </code>Requires one of the listed permission nodes. Only one is required. If you require multiple permission nodes, use multiple entries.<code>
 
* LEVEL [This Level # or higher]  OR  LEVEL [At least this Level #] [But no more than this Level #]
*: </code>Requires a specific Minecraft XP level, or a range of levels.<code>
 
* FINISHED (# of times) [Script Name]
*: </code>Requires a specific script to be <code>FINISH</code>ed. Remember: Script names are case-sensitive! You can specify a certain number of times, as well. Using this as a negative requirement is a good way to put a limit on how many times a player can do a script.<code>
 
* FAILED [Script Name]
*: </code>Requires a specific script to be <code>FAIL</code>ed. Remember: Script names are case-sensitive!<code>
 
* GROUP [Name of Group] (or this Group) ...
*: </code>Requires the player be a member of a group. Requires a Permissions system that allows groups, such as PermissionsEX.<code>
 
* MONEY [Amount of Money, or more]
*: </code>Requires the player to have at least a certain amount of money on hand. Requires an economy system, such as iConomy.<code>
 
* POTIONEFFECT [POTION_EFFECT]
*: </code>Requires the player to be under the influence of a specific potion. You can use 'ANY' to specify the player just be under the influence of a potion, without being specific as to which type.
</div>


Scripts:  
===== Negative Requirements Types =====
  'Regular Joe'
<div style="margin-right:2.0em; padding:10px">
    Requirements:
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 overlaps, such as '-WEATHER Precipitating' and 'WEATHER Sunny' technically being the same thing. If anything, it can add to script readability.
      Mode: None
    Steps:
      0:
        Click Trigger:
          - CHAT Hello <PLAYER>! I supply builders only!


   'Joe the Builder':  
<pre>
     Requirements:
   Requirements:
      Mode: All
     Mode: All
     List:
     List:
      - PERMISSION modifyworld.*
    - -TIME Night
     Steps:
     - -MONEY 1000000
      0:
    - -STORMY
        Click Trigger:
          - CHAT Hello <PLAYER> the Builder! Take this shovel!
          - GIVE WOOD_SPADE 1
</pre>
</pre>


Denizen Steve has been assigned two scripts. Upon player interaction, each script is checked for met requirements. If only one script has their requirements met, it's clear what script will be returned. But what if both meet requirements? That's where the number before each script assigned comes in. Higher priority always wins. To break down this specific situation, if a player with the modifyworld.* permission clicks on Steve, both scripts meet the requirements, but since the script 'Joe the Builder' has a priority of 10, and 'Regular Joe' only has a priority of 0, 'Joe the Builder' sends its script. 'Regular Joe' is simply ignored. Denizens can be issued as many scripts as you want.  If two scripts have the same priority, the first in the list will be the one to trigger, if both scripts meet their requirements.
Negative requirements completely change our original example around. For this script to trigger, time needs to be Day, the weather in the current world must NOT be storming, and the player must not have more than 1000000 units of currency on them.
</div>


==== Steps Node ====
<div style="margin-right:2.0em; padding:10px">
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.


== Some other basic things to note ==
<pre>
'Welcome to Harbortown':
  Type: Trigger
  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>


Denizens with the same name use the same script assignments. The plus to this is the ability to quickly make 'generic NPCs' such as a 'Townsman' or 'Miner'.
The sub-sections below reference this example.
</div>


===== Trigger Types =====
<div style="margin-right:2.0em; padding:10px">
Steps handle the flow of commands and messages with triggers.


= Scripts in detail =
'''Denizen Triggers''' trigger from interaction with Denizens. They are defined in the Steps: node.


The general structure of a script should always include the 'Name', 'Requirements', and 'Steps' nodes. These are required. You can optionally include 'Options', which include other conditions, such as if the script should have a cool-down or is not repeatable.
* '''Click Trigger'''s activate when the Denizen is clicked on.


Scripts are defined in the plugins/Denizen/config.yml under the Scripts: node.  
<pre>
Click Trigger:
  Script:
  - CHAT Scripts are nested as a list.
  - CHAT You can use any command that
    you'd wish.
</pre>


Remember! Spacing is CRITICAL when dealing with YAML files. Each parent node and sibling node should follow the spacing and formatting guidelines set forth by the YAML 1.0 standard.


From the official 1.0 YAML Specs, this is section 4.2.1 on Indentation:
* '''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 <code>


<pre>YAML streams use lines and spaces to convey structure. This requires special processing rules for white space (space and tab).
<pre>
Chat Trigger:
  '1':
    Trigger: The word needed to /Trigger/ is inside slashes.  
    Script:
    - CHAT Scripts are nested as a list.
    - CHAT You can use any command that
      you'd wish.
</pre>
</code>
For a list of commands, see [[#Script Commands]]
</div>


In a YAML character stream, structure is often determined from indentation, where indentation is defined as a line break character followed by zero or more space characters. With one notable exception, a node must be more indented than its parent node. All sibling nodes must use the exact same indentation level, however the content of each such node could be further indented. Indentation is used exclusively to delineate structure and is otherwise ignored; in particular, indentation characters must never be considered part of the document's content.
== Task Scripts in detail ==
<div style="margin-right:2.0em; padding:10px">
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>


Tab characters are not allowed in indentation since different systems treat tabs differently. To maintain portability, YAML's tab policy is conservative; they shall not be used. Note that most modern editors may be configured so that pressing the tab key results in the insertion of an appropriate number of spaces.  
==== General layout of a Trigger Script ====
<div style="margin-right:2.0em; padding:10px">
<pre>
'Name of script':  # Name Node
  Type: Task        # Type Node
  Script:          # Script Node
  - ...
  - ...
</pre>
</pre>
</div>


In all the examples used in this guide, 2 spaces are used for indenting.  Generally, whatever you choose should be maintained through your YAML document.
==== Using a Task Script with RUNTASK ====
<div style="margin-right:2.0em; padding:10px">
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!


== General layout of a Script ==
<pre>
'Apple Reward':
  Type: Task   
  Script:     
  - NARRATE You've received some APPLES. Nice!
  - GIVE APPLE 10
  - FINISH
 
'Apple Quest 1':
  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 ====
<div style="margin-right:2.0em; padding:10px">
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>
<pre>
Scripts:             # Scripts Node
'Graveyard Investigation':
   'Name of script'# Name Node
   Type: Trigger
     Requirements:    # Requirements Node
   Requirements:
       ...:
     Mode: NONE
      ...:
  Steps:
         - ...
     '1':
         - ...
       Click Trigger:
     Steps:           # Steps Node
        Script:
      ...:
         - CHAT Go investigate the graveyard for me!
        - ...
         - PLAYERTASK LOCATION graveyard 20 120 Graveyard Search
      ...:
 
     Options:         # Options Node
'Graveyard Search':
       ...:
  Type: Task   
  Script:     
  - NARRATE You are thoroughly spooked out. Maybe you should return to Dave.
  - FINISH
 
'Graveyard Investigated Complete':
  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>
</pre>


== Script Commands ==
<div style="margin-right:2.0em; padding:10px">
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.
* ZAP (Step #)
*: </code>Progresses the player through the steps. ZAP used alone will progress to the next step. ZAP with a number following will progress the player to a specific step.<code>
* FINISH
*: </code>Marks the script as completed to check against with the requirement type 'FINISHED'.<code>
* ENGAGE
*: </code>Blocks player interaction from triggering the NPC.<code>
* DISENGAGE
*: </code>Opens the NPC back up to player interaction.<code>
* PLAYERTASK LOCATION [Location Bookmark] [Duration in seconds] [Block leeway] [Task Script to trigger]
*: </code>Starts a player task to the Denizen's location bookmark in which the player must stay within a certain amount of blocks (Block Leeway) for a specific duration. Once accomplished, a Task Script is called.<code>
* FAIL
*: </code>Marks the script as failed to check against with the requirement type 'FAILED'. Note: A script can be both completed and failed!<code>
* RESET [FINISHED|FAILED] [Name of Script]
*: </code>Sets either FINISHED or FAILED of the specified script to False. Remember: Script names are case sensitive!<code>
* WAIT [# of seconds]
*: </code>Will hold a player's Command Que for a specific amount of seconds. You can use this to put delays in your script. All lines of a script after the hold will execute after the time has passed.<CODE>
* LOOK [CLOSE|AWAY] or LOOK [Location Bookmark]
*: </code>Toggle 'lookclose' on the Denizen. Alternate use specifies a pitch/yaw from a Location bookmark.<code>
* GIVE [ITEM_NAME] (Quantity)
*: </code>Denizen will drop specified items.<CODE>
* TAKE [ITEM_NAME|MONEY] (Quantity)
*: </code>Takes specific item or money from the player.<CODE>
* CHAT [The text to chat.]
*: </code>Makes the Denizen talk to the player. Long messages will be formatted for multiple lines automatically.<code>
* NARRATE [The text to narrate.]
*: </code>Sends text to the player without branding the Denizen. Long messages will be formatted for multiple lines automatically.<code>
* FOLLOW [PLAYER|NOBODY]
*: </code>Makes the Denizen follow the player, or stop following the player.<code>
* WALKTO [Location Bookmark]
*: </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)
*: </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
*: </code>Can be used after initiating a WALK command.  This will make the denizen return to its previous location.<code>
* EXECUTE [ASPLAYER|ASNPC|ASSERVER] [command to execute]    Ex: EXECUTE ASSERVER toggledownfall
*: </code>Executes a command, issues from either the Player, NPC, or Server. No need for a /.<code>
* STRIKE
*: </code>Strikes the player with lightning.<CODE>
* WEATHER [Sunny|Stormy|Precipitating]
*: </code>Sets the weather for the world.<CODE>
* 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.
* TELEPORT [Location Bookmark]
*: </code>Teleports the player interacting to the Denizen's specified Location Bookmark/ <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>
* PERMISS [permission.node.to.add]
*: </code>Gives to the player interacting the specified permission node for the current world.<CODE>


== Name Node ==
* REFUSE [permission.node.to.take]
*: </code>Takes from the player interacting the specified permission node for the current world.<CODE>


This node is pretty self-explanatory, but here are some things to keep in mind.
* CAST [POTION_TYPE] [Duration in seconds] [Amplifier]
* Names are not case-sensitive. 'This script name' is exactly the same as 'THIS SCRIPT NAME'.
*: </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>
* Names that contain spaces must have single or double quotes around it. ie: "This script" or 'This script' 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: "John's Script": or 'John''s Script':
* SWITCH [Block Bookmark]
*: </code>If a lever is found at the block location, it will be switched ON or OFF.<CODE>
 
* PRESS [Block Bookmark]
*: </code>If a button is found at the block location, it will be pressed. Note: You may need a - WAIT 1 and a 2nd - PRESS [Block Bookmark] or the Denizen will hold the button.<CODE>
</code>
</div>
 
== Denizen in-game bukkit commands ==
<div style="margin-right:2.0em; padding:10px">
<code>/denizen reload|save</code>
* Reloads|saves the config.yml and scripts.yml. Useful for testing scripts without rebooting your server.
 
<code>/denizen bookmark location [name]</code>
* Stores a location to the selected Denizen for use with script commands such as RESPAWN and WALKTO. Note: Names can only be one word, and are unique to the Denizen.
 
<code>/denizen bookmark block [name]</code>
* Stores the Player crosshair's block location to the selected Denizen for use with script commands such as SWITCH. Note: Names can only be one word, and are unique to the Denizen.
 
<code>/denizen adddata|decdata|getdata</code>
* Nothing to do with Denizens, really, but handy for checking/switching block data. Try it on a tree.
 
<code>/denizen version</code>
* Gives you an approximation of what build you are using. I'll probably ask you this if you come to #citizens for any tech support.
</div></s>

Latest revision as of 18:57, 3 September 2021


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 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!









Version warning.: This documentation is for Denizen 0.6 and is out of date.

Denizen 0.6 is not compatible with the latest builds of C2 or Bukkit 1.3.1.

See this link for the latest download of Denizen 0.7. Link

Preliminary documentation for Denizen 0.7 is available here Please be aware this page may contain errors.


Denizen.png

Denizen

Author aufdemrand
Version 0.6 Build #124
Citizens build 2.0 Beta
Other dependencies Vault
Download Link
Download example scripts: Link
Description: Scriptable, interactive citizens!

Denizens are a great way to add MUD-style RPG Citizens (and some other features) 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!

Script Repository

http://form.jotform.us/form/21498151597160|https://www.dropbox.com/sh/hw6x3f980maa8d9/DNtzAw8cn3Script Repository.png
About this image

Change Log

Here's what's new!

Note to beta users pre-build 98: File structure has changed over the last few builds up to 98. The Denizens: node now has its own YML file called assignments. You will need to create this file and cut/paste the node from your config.yml. It's also recommended that you download the new Denizen config.yml since some nodes have changed or been expanded upon. Denizen location and block bookmarks are also now stored in saves.yml. You will need to migrate those there, or recreate them before using scripts that use bookmarks. See #File Structure for more information on the new file structure.

0.6 Build #104

  • Added PLAYERTASK command. LOCATION QUESTS! (This is for you, Ratkoon)

0.6 Build #98

  • Update to file structure. saves.yml now contains all information that the denizen plugin writes. This includes player progression/completion/etc. information, denizen location bookmarks, etc. If edited by hand, probably best to shut down the server first. Any existing information in the players: node and denizen location bookmark information needs to be either recreated or migrated into saves.yml.
  • Added HEAL and HURT commands. Use HEAL [# of health] or HURT [# of health].
  • Added CHANGE command to change the type of block at a block bookmark. Use CHANGE [Block Bookmark] [#:#|MATERIAL_TYPE].
  • Added ATTACK command. Use like FOLLOW.
  • GIVE and TAKE should now also accept #:# format as well as MATERIAL_TYPE.
  • Added ENGAGE and DISENGAGE commands. When a Denizen is ENGAGE'd, no other interaction will be registered with the NPC until DISENGAGED. This could be useful for keeping players from 'repeating steps' while mid-script. Use ^ENGAGE at the beginning of the script and DISENGAGE at the end.
  • Requirements using items can now use #:# syntax to check item typeId and data.
  • Requirements WORLD, POTION_EFFECT, NAME, PERMISSION, and GROUP can check for multiple names/nodes.
  • FINISHED can now check for a specific amount of times a player has finished. Use: FINISHED # [name of script].
  • Script combiner should now only pick up .yml files.
  • Various other bug fixes.

0.6 Build #82

  • Requirements code reformat is done, thanks for being patient if you were watching the Jenkins!
  • FINISH command now increments a counter so you can check for a certain number of FINISHes. Use: FINISHED (# of times) [name of script]. The # is optional and will assume 1 if not specified. There's a chance that this broke any recorded FINISHes that may be in your config. Sorry about that. You can manually change them from True to 1 to fix this. New FINISHes will overwrite without any issues.
  • TIME requirement can now check for DAWN and DUSK in addition to DAY and NIGHT.
  • Requirements that use items can now use the #:# (typeId:data) format. So, for gray wool, 35:7. You can still specify just WOOL and any color will do.
  • Script combiner will now only read .yml files, this fixes issues with hidden files in your scripts file corrupting the combined read-only-scripts.yml.
  • NAME, WORLD, PERMISSION, GROUP, POTION_EFFECT can now all use multiple arguments. For example, WORLD world_1 world_2 world_3 world_4 will return true if one of the worlds listed matches. You can use up to 24 arguments.

0.6 Build #71

  • Started code reformat, this will make it easier to extend.
  • Added ability to use multiple scripts! Denizen will read any .yml file in the /plugins/Denizen/scripts/ folder. You will need to place your existing scripts.yml in that folder. Denizen will generate a read-only-scripts.yml to the main Denizen folder. This should be left alone. Also made config.yml generate automatically upon startup.
  • Added config node chat_globally_if_no_chat_triggers


You can see more at the full Denizen changelog.

Known caveats

There are some 'issues' with Denizen that we are aware of, and thought that you should be too. Keep in mind that we're working hard to fix these, as soon as possible.

  • I've been having problems getting the NPCs to WALKTO a bookmarked location that is far away.
  • When close to a Denizen that is RESPAWNing, it sometimes won't actually spawn until you back away from it.
  • Multi-line CHATting loses color codes second line on.

Before using Denizens

Denizens are in BETA! Expect a few bugs here and there! There is little error handling for scripts that contain bad syntax, so if you are getting errors while processing a script, the first thing you should do it check the script syntax. I'm working hard to catch errors, but every once in awhile you'll find one that requires a /reload or server restart. If you do come across any errors beyond bad syntax, please report them to the Github Issues page for Denizens. You can also get assistance with Denizens on the #citizens IRC channel on EsperNET from me (aufdemrand) when available. I'm usually there working hard to add awesome features and squashing bugs.

Denizen is not a drag-and-go type of plugin. In fact, Denizen won't do anything unless you assign and define scripts to NPCs. It's highly customizable and you should expect that to be able to write scripts, it is suggested you read the entirety of this wiki document. I'm always around IRC to help out, but please don't ask about the basics unless you have consulted here first.

Denizens REQUIRES you to have Vault installed. You also should have a Permissions System and and Economy System for best results.

Getting started with Denizen

The easiest way to use Denizen for the first time is to download the Start-up Kit with sample .yml configuration files and scripts. This includes the default config file, sample scripts, and sample assignments to get you started. Denizen relies on a few files to run properly, so let's first go over the file structure.

File Structure

Denizen File Structure

Denizen requires the use of a few different YML files to operate properly. This includes a config.yml, assignments.yml, scripts, and saves.yml.

config.yml

The Denizen config.yml contains nodes to alter the stock behavior and look of Denizen. You'll notice that Denizen does not create its own config.yml. Why is this? Denizen stores its entire config inside memory, so it's not necessary to have a copy inside the Denizen folder unless you need to change the defaults. You can use the config.yml to override those defaults. Not having Denizen write to the config.yml itself (as well as scripts files, and assignments.yml) ensures that upon a /denizen reload, the config.yml, between a save and reload, is never changed when you don't want it to. This also keeps code comments inside the YML files stay intact, exactly the way you left them from last edit allowing you to leave yourself and others detailed notes and ideas.

This file can be reloaded into from disk to Denizen memory at any time by using /denizen reload.

See: Denizen config.yml for a stock copy and explanation of all available options.

assignments.yml

This YML is where you can define all the options and information for your Denizen NPCs. This will be explained further along in this document, but the most common information in this file is [Interact Script Assignments], [Activity Script Schedule], and [Custom Interact Texts].

This file can be reloaded from disk into Denizen memory at any time by using /denizen reload.

See: #A basic assignment for information on how to get started with assignments.

saves.yml

This file is not meant to be edited by hand, Denizen will create and populate this file automatically as needed. It stores important information such as player progression, Denizen location and block bookmarks, active activity script progression and more. If you absolutely need to make changes by hand, it's best to stop the server, edit, and then restart your server, as this file is constantly being written to by Denizen which will overwrite any changes you make.

This file saves periodically, and automatically, upon progression and a server stop.

read-only-scripts.yml

This is another files that Denizen creates and should not be edited by hand. This is a combination of the files contained in the scripts folder that Denizen reads from.

This file is populated on a server restart, or by using the /denizen reload command.

/scripts/ folder

This folder is where Denizen will read all the script information from. Upon a server load or /denizen reload, the files are combined and put into the read-only-scripts.yml for the Denizen to read from. This allows better organization of scripts to be maintained, since the amount of scripts can easily get into the triple digits.

The files in the plugins/Denizen/scripts/ folder can be named whatever you please, as long as they end in .yml. Be sure not to duplicate script names from file to file as this will cause problems.

See: #A basic trigger script for information on how to get started with scripts.

Writing Scripts and Assignments

Still reading? Great! You're on your way to writing some sweet scripts. Let's start out with the basics: Trigger Scripts and Assignments. Denizen needs two things to be functional. A script, and an assignment. Scripts, obviously, hold instructions that are carried out when triggered. Assignments hold information on which scripts should trigger, and when. Bear with me, and keep reading!

A basic trigger script

First, we need a script. The great thing about a Denizen script is that it can be simple or advanced, short or long, thanks to a wide array of commands and functions at your disposal. Scripts can work with, extend, and rely on one another to create rich, interactive gameplay. Each script has at least 2 parts, Requirements and Steps. For now, let's take this very simple script as an example. We'll get more detailed later on.

Remember: Scripts are defined in plugins/Denizen/scripts/ folder. They can be put into any YML file contained in that directory. You may need to create the directory yourself if no scripts yet exist.

'Daytime in the City':   
  Type: Trigger
  Requirements:
    Mode: All
    List:
    - TIME Day
  Steps:
    1:
      Click Trigger:
        Script:
        - CHAT Welcome to the city! Isn't it beautiful in the daytime?

So what just happened there? A quick literal translation: This script is named 'Daytime in the City'. This name is used when assigning Denizen NPCs their scripts to use. When the script is called by a trigger, in this case a 'Click Trigger', for it to activate the Requirements set must be met, more specifically ALL of the requirements set. In this example, the only requirement is TIME DAY which requires the current time in the world to be daytime. If the Requirements are met, the script defined in the 'Click Trigger' is sent to be run. It will have the Denizen NPC chat to the player 'Welcome to the city! Isn't it beautiful in the daytime?'.

But before the script can be triggered, it needs to be assigned.

A basic assignment

In order for a Denizen to be associated with a script, he needs to be assigned to it. The following shows a simple assignment format.

Assignments are defined in the Denizens node found in plugins/Denizen/assignments.yml and must be done by hand. Once you edit the config.yml, immediately save and use /denizen reload in-game.

Denizens:                         
  'Steve':                        
    Interact Scripts:                      
    - 10 Daytime in the City  
    Texts:
      No Requirements Met: 'Come back during the day!'

Let's break this down again. This assignement will work for Denizens named 'Steve'. Triggers that involve this NPC, such as a 'Click Trigger' will call the script named 'Daytime in the City'. The 10 before the name is the script priority, useful when assigning multiple scripts, but we'll get into that next. If no scripts meet requirements (in this case -- if it's NOT daytime when clicking on Steve), the text defined in the Texts: node called 'No Requirements Met' will trigger instead. So to reiterate, if the player clicks on Steve during the daytime, the player will get a chat containing 'Welcome to the city! Isn't it beautiful in the daytime?' If the player clicks during the nighttime, since the script requirements are not met, the player will see a chat containing 'Come back during the day!'. Note that the default No Requirements Met text can be changed in the config.yml.

Multiple Script Assignments

The key to Denizens being dynamic is their ability to handle multiple scripts in different situations. This is done by assigning a priority to script assignments. Let's take this example configs below to see how script priority is handled. The below code references assignments.yml and a script.yml.

---- assignments.yml ----

Denizens:                         
  'Steve':                        
    Interact Scripts:                      
    - 0 Regular Joe
    - 10 Joe the Builder  

---- script.yml ----

'Regular Joe':
  Type: Trigger   
  Requirements:
    Mode: None
  Steps:
    1:
      Click Trigger:
        Script:
        - CHAT Hello <PLAYER>! I supply builders only!

'Joe the Builder':
  Type: Trigger   
  Requirements:
    Mode: All
    List:
    - PERMISSION modifyworld.*
  Steps:
    1:
      Click Trigger:
        Script:
        - ENGAGE
        - CHAT Hello <PLAYER> the Builder! Take this shovel!
        - GIVE WOOD_SPADE 1
        - FINISH
        - DISENGAGE

Denizen Steve has been assigned two scripts. Upon player interaction, each script is checked for met requirements. If only one script has their requirements met, it's clear what script will be returned. But what if both meet requirements? That's where the number before each script assigned comes in. Higher priority always wins. To break down this specific situation, if a player with the 'modifyworld.*' permission clicks on Steve, both scripts meet the requirements, but since the script 'Joe the Builder' has a priority of 10, and 'Regular Joe' only has a priority of 0, 'Joe the Builder' sends its script. 'Regular Joe' is simply ignored. Denizens can be issued as many scripts as you want. If two scripts have the same priority, the first in the list will be the one to trigger, if both scripts meet their requirements.

Things to Note, Thus Far

Denizens with the same name use the same script assignments. The plus to this is the ability to quickly make 'generic NPCs' such as a 'Townsman' or 'Miner'.

All the scripts and configuration nodes are in YAML. Remember! Spacing is CRITICAL when dealing with YAML files. Each parent node and sibling node should follow the spacing and formatting guidelines set forth by the YAML 1.0 standard.

In all the examples used in this guide, 2 spaces are used for indenting. Generally, whatever you choose should be maintained through your YAML document. No tabs are allowed in YAML files.

In the YAML files, nodes are case sensitive! 'Scripts:' will work. 'scripts:' will not! All nodes are first letter capital, rest of the word lowercase. Scripts names follow this rule too!

YAML tutorials can be intimidating, but this small tutorial on the Essentials wiki is pretty useful for basic YAML, which is the extent of which Denizens uses.

Assignments in Detail

Trigger Scripts in detail

The general structure of a script should always include the 'Name', 'Type', 'Requirements', and 'Steps' nodes. These are required.

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.

General layout of a Trigger Script

'Name of script':   # Name Node
  Type: Trigger     # Type Node
  Requirements:     # Requirements Node
    ...:
    ...:
      - ...
      - ...
  Steps:            # Steps Node
    ...:
      - ...
    ...:
  Options:          # Options Node
    ...:

Name Node

This node is pretty self-explanatory, but here are some things to keep in mind.

  • Names, just like nodes are case-sensitive! 'This script name' is different than 'THIS SCRIPT NAME'.
  • Names that contain spaces must have single or double quotes around it. ie: "This script": or 'This script': 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: "John's Script": or 'John''s Script':

Type Node

Let's Denizen know the type of script. For trigger scripts, as explained in this section, use TYPE: TRIGGER.

Requirements Node

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:

  Requirements:
    Mode: All
    List:
    - TIME Night
    - MONEY 1000000
    - STORMY

This would be a difficult script to obtain, for sure. To trigger, the time would have to be after 16000, but before 0, the player would need one million dollars on hand (or whatever economy you use), 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.

Mode Types

[] indicates required field

  • ALL
    Requires all requirements listed to be met.
  • ANY [#]
    Requires the specified number of requirements to be met, out of the total of requirements listed.
  • NONE
    Requires NO requirements to be met.

Requirements Types

[] indicates required field, () indicates an optional field, OR indicates alternative usage.

  • NAME [Player Name] (or this Player Name) ...
    Requires a specific player.
  • ITEM [#:#] (# of that item, or more)
    Requires the player to have an item in their inventory. You can also specify an amount.
  • WEARING [#]
    Requires the player to be wearing a specific piece of armor.
  • HOLDING [#:#] (# of that item, or more)
    Requires the player to have an item in their hand. You can also specify an amount.
  • TIME [Day|Night|Dusk|Dawn] OR TIME [0-23999] [1-24000]
    Requires day or night. Alternatively you can specify a time window.
  • HUNGER [Full|Hungry|Starving]
    Requires a specific hunger state.
  • PRECIPITATION
    Requires a rain or snow.
  • SUNNY
    Requires clear skies. Note: This can still trigger at night as it does not check time.
  • WORLD [World Name] (or this World Name) (or this World Name) ...
    Requires the player to be in a specific world, or worlds. You can check as many as you'd like with one line.
  • PERMISSION [this.permission.node] (or this permission.node) ...
    Requires one of the listed permission nodes. Only one is required. If you require multiple permission nodes, use multiple entries.
  • LEVEL [This Level # or higher] OR LEVEL [At least this Level #] [But no more than this Level #]
    Requires a specific Minecraft XP level, or a range of levels.
  • FINISHED (# of times) [Script Name]
    Requires a specific script to be FINISHed. Remember: Script names are case-sensitive! You can specify a certain number of times, as well. Using this as a negative requirement is a good way to put a limit on how many times a player can do a script.
  • FAILED [Script Name]
    Requires a specific script to be FAILed. Remember: Script names are case-sensitive!
  • GROUP [Name of Group] (or this Group) ...
    Requires the player be a member of a group. Requires a Permissions system that allows groups, such as PermissionsEX.
  • MONEY [Amount of Money, or more]
    Requires the player to have at least a certain amount of money on hand. Requires an economy system, such as iConomy.
  • POTIONEFFECT [POTION_EFFECT]
    Requires the player to be under the influence of a specific potion. You can use 'ANY' to specify the player just be under the influence of a potion, without being specific as to which type.
Negative Requirements Types

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 overlaps, such as '-WEATHER Precipitating' and 'WEATHER Sunny' technically being the same thing. If anything, it can add to script readability.

  Requirements:
    Mode: All
    List:
    - -TIME Night
    - -MONEY 1000000
    - -STORMY

Negative requirements completely change our original example around. For this script to trigger, time needs to be Day, the weather in the current world must NOT be storming, and the player must not have more than 1000000 units of currency on them.

Steps Node

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.

'Welcome to Harbortown':
  Type: Trigger
  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?

The sub-sections below reference this example.

Trigger Types

Steps handle the flow of commands and messages with triggers.

Denizen Triggers trigger from interaction with Denizens. They are defined in the Steps: node.

  • Click Triggers activate when the Denizen is clicked on.
Click Trigger:
  Script:
  - CHAT Scripts are nested as a list.
  - CHAT You can use any command that
    you'd wish.


  • Chat Triggers 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
Chat Trigger:
  '1':
    Trigger: The word needed to /Trigger/ is inside slashes. 
    Script:
    - CHAT Scripts are nested as a list.
    - CHAT You can use any command that
      you'd wish.

For a list of commands, see #Script Commands

Task Scripts in detail

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.

General layout of a Trigger Script

'Name of script':   # Name Node
  Type: Task        # Type Node
  Script:           # Script Node
  - ...
  - ...

Using a Task Script with RUNTASK

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!

'Apple Reward': 
  Type: Task    
  Script:       
  - NARRATE You've received some APPLES. Nice!
  - GIVE APPLE 10
  - FINISH

'Apple Quest 1':
  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

Using a Task Script with PLAYERTASK

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.

'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': 
  Type: Task    
  Script:       
  - NARRATE You are thoroughly spooked out. Maybe you should return to Dave.
  - FINISH

'Graveyard Investigated Complete':
  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!

Script Commands

Note: There are plenty more to come, be patient, more are coming! Have ideas for a good command? Let me know!

[] indicates required field, () indicates an optional field, OR indicates alternative usage.

  • ZAP (Step #)
    Progresses the player through the steps. ZAP used alone will progress to the next step. ZAP with a number following will progress the player to a specific step.
  • FINISH
    Marks the script as completed to check against with the requirement type 'FINISHED'.
  • ENGAGE
    Blocks player interaction from triggering the NPC.
  • DISENGAGE
    Opens the NPC back up to player interaction.
  • PLAYERTASK LOCATION [Location Bookmark] [Duration in seconds] [Block leeway] [Task Script to trigger]
    Starts a player task to the Denizen's location bookmark in which the player must stay within a certain amount of blocks (Block Leeway) for a specific duration. Once accomplished, a Task Script is called.
  • FAIL
    Marks the script as failed to check against with the requirement type 'FAILED'. Note: A script can be both completed and failed!
  • RESET [FINISHED|FAILED] [Name of Script]
    Sets either FINISHED or FAILED of the specified script to False. Remember: Script names are case sensitive!
  • WAIT [# of seconds]
    Will hold a player's Command Que for a specific amount of seconds. You can use this to put delays in your script. All lines of a script after the hold will execute after the time has passed.
  • LOOK [CLOSE|AWAY] or LOOK [Location Bookmark]
    Toggle 'lookclose' on the Denizen. Alternate use specifies a pitch/yaw from a Location bookmark.
  • GIVE [ITEM_NAME] (Quantity)
    Denizen will drop specified items.
  • TAKE [ITEM_NAME|MONEY] (Quantity)
    Takes specific item or money from the player.
  • CHAT [The text to chat.]
    Makes the Denizen talk to the player. Long messages will be formatted for multiple lines automatically.
  • NARRATE [The text to narrate.]
    Sends text to the player without branding the Denizen. Long messages will be formatted for multiple lines automatically.
  • FOLLOW [PLAYER|NOBODY]
    Makes the Denizen follow the player, or stop following the player.
  • WALKTO [Location Bookmark]
    Makes the Denizen walk to a specified location.

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)
    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.
  • RETURN
    Can be used after initiating a WALK command. This will make the denizen return to its previous location.
  • EXECUTE [ASPLAYER|ASNPC|ASSERVER] [command to execute] Ex: EXECUTE ASSERVER toggledownfall
    Executes a command, issues from either the Player, NPC, or Server. No need for a /.
  • STRIKE
    Strikes the player with lightning.
  • WEATHER [Sunny|Stormy|Precipitating]
    Sets the weather for the world.
  • RESPAWN [Location Bookmark]
    Despawns the Denizen and respawns it to a bookmarked location.

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.

  • TELEPORT [Location Bookmark]
    Teleports the player interacting to the Denizen's specified Location Bookmark/
  • SPAWN [ENTITY_TYPE] [AMOUNT] (Location Bookmark)
    Spawns a specified amount of entities. If the location bookmark is missing, they will spawn near the Denizen.
  • PERMISS [permission.node.to.add]
    Gives to the player interacting the specified permission node for the current world.
  • REFUSE [permission.node.to.take]
    Takes from the player interacting the specified permission node for the current world.
  • CAST [POTION_TYPE] [Duration in seconds] [Amplifier]
    Gives the player interacting a potion effect. Note: 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.
  • SWITCH [Block Bookmark]
    If a lever is found at the block location, it will be switched ON or OFF.
  • PRESS [Block Bookmark]
    If a button is found at the block location, it will be pressed. Note: You may need a - WAIT 1 and a 2nd - PRESS [Block Bookmark] or the Denizen will hold the button.

Denizen in-game bukkit commands

/denizen reload|save

  • Reloads|saves the config.yml and scripts.yml. Useful for testing scripts without rebooting your server.

/denizen bookmark location [name]

  • Stores a location to the selected Denizen for use with script commands such as RESPAWN and WALKTO. Note: Names can only be one word, and are unique to the Denizen.

/denizen bookmark block [name]

  • Stores the Player crosshair's block location to the selected Denizen for use with script commands such as SWITCH. Note: Names can only be one word, and are unique to the Denizen.

/denizen adddata|decdata|getdata

  • Nothing to do with Denizens, really, but handy for checking/switching block data. Try it on a tree.

/denizen version

  • Gives you an approximation of what build you are using. I'll probably ask you this if you come to #citizens for any tech support.