Denizen/0.6

External Character Type!
This page is about a type of NPC that is not developed supported by the Citizens development team. Don't ask for support from them, or on the forums/IRC, as we won't be able to help you. Instead, look at the BukkitDev link of the InfoBox to the right for information on how to get support for this character type.

Denizen Author aufdemrand Version 0.5 Citizens build 2.0 Newest Dev Development status InDev Download [ Link] BukkitDev [ Link] Source Link Issues Link Description: Denizens are helpful, interactive Citizens! Installing Character Types

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!

Denizens are in BETA! Expect bugs, and if you would be so kind, please report them to the 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.

Timeline:

• Beta 1 -- All functionality used in the example config files.
  
• Beta 2 -- Additional functionality additional content pre-documented in this wiki.
  
• 1.0 -- Bug fixes from Beta plus your ideas and contributions.
  
• 1.5 -- Online script writer/manager.
  
• 2.0 -- Profit???
  

What does Denizens have to offer?

There are lots of cool things that the Denizens plugin has to offer, such as:

• YAML scripted NPCs (Denizens) with a multitude of flexibility.
• Triggered scripts on click, chat, die, location, and more!
• MUD-like chat interface. You say to the Denizen, 'Very RPG!'
• In game language support. Now players can learn the language of the Ender!
• Completely customizable user experience let's you keep Denizens within your theme.
• Location and Achievement Notables -- the achievement system you've been waiting for!

All these features are documented here, and it is recommended you read the entire document when using Denizens. First, let's get into the basics of scripted NPCs.

A basic script

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.

Scripts: 
  'Daytime in the City':   
    Requirements:
      Mode: All
      List:
        - TIME Day
    Steps:
      0:
        Click Trigger:
          - 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 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?'.

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/Denizens/config.yml

Denizens:                         
  'Steve':                        
    Scripts:                      
      - 10 Daytime in the City  
    No Scripts To Trigger:
      - CHAT I have nothing to say to you at this time.

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 next. 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.'

Multiple Scripts

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.

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

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

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

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.

Some other basic things to note

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

Scripts are defined in the Scripts node found in plugins/Denizens/config.yml

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.

YAML Ain't Markup Lanugage

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.

From the official 1.0 YAML Specs, this is section 4.2.1 on Indentation:

YAML streams use lines and spaces to convey structure. This requires special processing rules for white space (space and tab).

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.

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.

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.

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.

Denizens Node in detail

In addition to handling the script assignments, there are also a few other things that are declared in the Denizens node. Let's take this example to show the different options. Note: Some of the functionality in this has not yet been discussed, you may need to read further.

Denizens:                         
  'Steve':                        
    Scripts:                      
      - 10 Joe the Builder  
    Options:
      Languages: HU EN
      Interact Cooldown: 600 
      Chat Name: Steve the Master Builder
    No Scripts To Trigger:
      - CHAT I have nothing for you at this time!
    Cooldown Not Yet Met:
      - CHAT That's all I have for now! Come back later!

Denizen Options

• Languages:

  Adds a spoken/understood language to the Denizen. Languages are defined in the Languages: node. See: #Languages

• Interact Cooldown:

  Sets a delay for the speed in which you can trigger scripts between FINISHes. If the selected script only has a simple reward, this is a way to control how fast the player can re-trigger the NPC. In the above example, clicking on Steve will trigger the script 'Joe the Builder' in which he hands over a Shovel. With an interact cooldown specified, it keeps the player from getting a shovel every click. Instead, the player must wait 600 seconds. This will also delay any other script from triggering! Useful scenario: Script 1 gives a wood shovel, Script 2 gives a wood sword, but requires Script 1 to be complete first. To keep the player from redeeming Script 2 right away, use an Interact Cooldown.

• Chat Name:

  Allows you to expand on a Denizens name, or completely change it. If this is set, all chat heard from the Denizen will use this 'Chat Name' instead of the actual NPCs name, which can only be one word. Note: On Human NPCs, this will NOT change the name above them in-game. For now, that is coded into the Minecraft client, which this plugin can not modify.

• No Scripts To Trigger:

  If no scripts meet requirements, this script is triggered instead. See: #Script Commands

• Cooldown Not Yet Met:

  If an Interact Cooldown: is set and not yet satisfied, this script will trigger instead. See: #Script Commands

Scripts Node in detail

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.

Scripts are defined in the plugins/Denizen/config.yml under the Scripts: node.

General layout of a Script

Scripts:              # Scripts Node
  'Name of script':   # Name 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':

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) (or this Player Name..) (Etc..)

  Requires a specific player.

• WEARING [ITEM_NAME] (ENCHANTMENT_TYPE)

  Requires the player to be wearing a specific piece of armor.

• INVINCIBLE

  Requires the player to be under the effect of a golden apple.

• ITEM [ITEM_NAME] (# of that item, or more) (ENCHANTMENT_TYPE)

  Requires the player to have an item in their inventory. You can also specify an amount and enchantment.

• HOLDING [ITEM_NAME] (# of that item, or more) (ENCHANTMENT_TYPE)

  Requires the player to have an item in their hand. You can also specify an amount and enchantment.

• TIME [Day|Night] 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.

• WEATHER [Precipitating|Storming|Sunny]

  Requires a specific weather state. Note: STORMING is not the same as PRECIPITATING, though it does rain while storming. Also, SUNNY does not check time, so it technically could be night and still trigger.

• WORLD [World Name] (or this World Name) (or this World Name..) (Etc..)

  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..) (Etc..)

  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 level, or a range of levels.

• SCRIPT [Script Name] (Number of times completed, or more)

  Requires a specific script to be FINISHed, x amount of times or more. If no number is provided, 1 time is assumed.

• NOTABLE [Name of Notable] (or this Notable) (or this Notable..) (Etc..)

  Requires a Notable to be achieved by the player. See: Notables in Denizens

• GROUP [Name of Group] (or this Group) (or this Group..) (Etc..)

  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] (or this POTION_EFFECT..) (Etc..)

  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.

Scripts:
  'Welcome to Harbortown':
    Requirements:
      Mode: NONE
    Steps:
      '0':
        Proximity Trigger:
          - CHAT Hello stranger! Welcome to Harbortown!
        Click Trigger:
          - CHAT What's your name, stranger?
          - HINT
        Chat Trigger:
          - My name is /<player>/.
            - CHAT Ah ha, your name sounds familiar! 
            - CHAT Are you from around this area?
            - ZAP
      '1':
        Click Trigger:
          - HINT
        Chat Trigger:
          - /Yes/, I grew up in Harbortown!
            - CHAT I thought so, welcome back! 
              Have you heard about Tom the Taylor? 
              Isn't that just horrible?
            - ZAP 2 
          - /No/, you must be mistaken. 
            - 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 3
      '2':
        Click Trigger:
          - CHAT I wonder if Tom the Taylor is doing any better.
          - NARRATE Perhaps you should check on Tom the Taylor.
      '3':
        Click Trigger:
          - CHAT Oh, nice to see you again <player>!
          - CHAT Have you stopped by the bakery?

The sub-sections below reference this example.