Denizen/0.6

DENIZENS are helpful, 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. 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 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.

Timeline: Beta 1 -- All functionality used in the example file. Beta 2 -- Additional functionality of additional behaviors/requirements/triggers listed. 1.0 -- Bug fixes from Beta. 1.5 -- Standalone (Window) script writer. 2.0 -- Profit.

How do denizens work?

There are lots of cool things that the Denizens plugin has to offer, but let's start with the basics. 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 are defined in the Scripts node found in plugins/Denizens/config.yml

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:                      
      - 0 Daytime in the City  
    No Scripts To Trigger:
      - CHAT I have nothing to say to you at this time.

Another literal rundown. 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 0 beforehand is the script priority, useful when assigning multiple scripts. 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.'