Home

Hey there! Thanks for using Denizen for Bukkit and Citizens2. Looking for a quick starting guide? Here's the place!

**So, what is Denizen?** It's is best classified as a scripting platform. _Denizen for Bukkit and Citizens2_ utilizes the scripting, and various other components provided by DenizenAPI. The scripting component of Denizen features easy to use _script containers_, _replaceable tags_, _commands_, and a _queue system_. Built aside is a slew of components that deal with many kinds of _event handlers_, many additional NPC features, a fully-featured _variable system_ (we call them 'flags'), and a rich _object-oriented_ set of features. I encourage users to start small when first getting into Denizen, but rest assured there are _tons of features to explore_.
**Denizen NPCs?** Yep, that's right. Denizen is probably best known as a way to create scripted Citizen NPCs. In fact, this whole project started out as an extension to Citizens2. You can use it to make interactive NPCs with the use of _Assignment Scripts_ and _Interact Scripts_. This is pretty easy to do, and there's a bunch of cool NPC specific (among many other) commands and tags that you can utilize as well.

Here's a small example I call 'cookies'. I normally like to comment my scripts, but this one below is presented without any as to show the flow. We'll of course go over the basics of this all in this wiki, just look at the other pages.

Cookies:
  type: assignment

  interact scripts:
  - 100 Cookie Handler


Cookie Handler:
  type: interact

  steps:
    'Spreading the Word*':
      click trigger:
        script:
        - random 3
        - chat 'I like cookies!'
        - chat 'MMmm.. cookies are favorite!'
        - chat 'Cocoa and wheat me freak!'

      chat trigger:
        'Cookies':
          trigger: 'I love /cookie/s!'
          script: 
          - chat 'Me too!'
          - narrate "<npc.name> gives 
            you some cookies."
          - give i@cookie qty:6
          - zap 'step:Cookies given'

  'Cookies given':
        click trigger:
            script:
            - chat 'How were the cookies?'
            - zap 'step:Spreading the Word'

It's a simple 2-step, multi-trigger script that creates a _cookie loving_ NPC. For some reason I think it's funny to name the NPC 'Notch'. Making a NPC use this script couldn't be easier, either. Simply use a bukkit command while having the NPC selected. It looks like this:

/npc assignment --set cookies

Now clicking on your NPC will use Denizen Triggers to activate the script above. An instant Denizen NPC! Cookies is funny, but hardly useful, and it's my personal philosophy that NPCs should be useful. How 'bout a simple healer? This NPC will heal you, but only when you're seriously injured.

Basic Healer:
  type: assignment

  interact scripts:
  - 100 heal me, bro!


Heal me, bro!:
  type: interact

  steps:

    "Need a heal?*":
      click trigger:
        script:
        - if '<player.health>' < '<m:<player.health.max> / 2>' {
            - look <player.location>
            - chat 'Woah dude, you are <player.health.formatted>! You could use a heal!'
            - chat 'Just give me another click to get some power!'
            - zap "Healin'" duration:30s
          } else {
            - look <player.location>
            - chat 'Nice an healthy. Keep it up!' 
          }

    "Healin'":
      click trigger:
        script:
        - ^zap 'need a heal?'
        - ^engage
        - chat "Here goes nothin'!"
        - playeffect instant_spell <npc.location> qty:25
        - playeffect heart <player.location> qty:25 offset:1
        - heal <player>
        - disengage

But, but, but... how do you make a Healer NPC with this script? You guess it! Just select that NPC, and type:

/npc assignment --set 'basic healer'

**It's not just for NPCs.** I guess I already told you that, but Denizen has some other script types that open up possibilities that extend far beyond it's core functionality of utilizing NPCs. One of my favorite 'simple scripts' that I like to show people is one that my friend Blankiito showed me. The one below is slightly modified, but basically it enables a 'rogue-like feature' that makes a player invisible when sneaking. It's a simple concept, but perfectly illustrates the flow of a Denizen Script.

Rogue:
  type: world
  debug: false

  events:
    on player starts sneaking:
    - playeffect <p.location> effect:magic_crit qty:10
    - invisible player state:true

    on player stops sneaking:
    - invisible player state:false

Even small scripts can be incredibly useful for your server. Sometimes scripts can replace entire bukkit plugins, and since the 'code' is in Denizen Script, the end result is often times more flexible to you, the server operator. Have a plugin that run some commands every once in awhile? Replace it with a simple Denizen script.

Autosave Command:
  type: world

  events:
    on 5:00 in w@world:
    - announce 'Autosaving...'
    - execute as_server 'denizen save'
    - execute as_server 'citizens save'
    - execute as_server 'save-all'

Use Denizen to solve problems, or to make features easier to use. Example: If you're familiar with Citizens, you may have realized that WorldGuard's /butcher command is not friendly to mob-type NPCs. It removes them, too, which can be a pain! Why not write your own /butcher command?

Safer Butcher:
  type: world

  events:
    on sbutcher command:
    - narrate 'Removing all mob entities within 15 blocks... your NPCs are safe!'
    - foreach <player.location.find.entities.within[15]> {
        - if <%value%.is_mob>
          remove %value%
      }

Denizen Quests are the best quests. If you're like me, this whole thing started by using the Quester for Citizens1. It featured a fairly simple questing structure to implement things like 'kill quests' and 'collection quests'. When Citizens went to version 2, that functionality was no longer 'core', but no worries Denizen can help! By utilizing Denizen's Player Listeners, simple questing can be done easily, and it's more robust because you can use all the other features implemented by Denizen, too!