Denizen
Meta Documentation | Issue Tracker | New Script Repository | Old Script Repository | Tutorial Videos | Forums
Development builds of this project can be acquired at the provided continuous integration server. These builds have not been approved by the BukkitDev staff. Use them at your own risk.
Denizen uses a pasting service provided by its developers to enable recording of debug sessions. This allows an easy and universal way to troubleshoot a script. It is only used on '/denizen submit', however this service is not endorsed by the BukkitDev staff. Use it at your own risk.
HEY!
This project is moved!
Please download from:
https://www.spigotmc.org/resources/denizen.21039/
View resources at:
This Bukkit page won't be updated much!
About
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.
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
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> 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.
Auto Save Event Handler: type: world debug: false events: on 5:00 in 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 Handler: type: world debug: false 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!
So, how do you best get started? This is a question we get all the time. Because of the enormous amount of ways to use and customize Denizen, we suggest that you simply START SMALL! Checking out the videos, scripts, and articles on denizen-docs you're sure to find a comfortable place to start. While scripting, utilize the tools provided, such as the SublimeText2 grammar pack, and the reference and search for meta lookup on this site.
Like any programming language, there is a learning curve with code structure and syntax that will only be overcome by trial and error. While using some user-made scripts can be as easy as dragging-and-dropping, many scripts will likely require at least a basic understanding of the denizen-script structure to fully utilize their features. But don't worry! Denizen is purposefully made to be easy to read and easy to customize! Tags, commands and events are all very verbose, easy to follow. With a little bit of research we know you'll soon be drunken with power, just like us!
Videos
Other useful links
- Denizen Handbook (Outdated kind of, but has some useful information still.)
- User-made beginner's guide
- Citizens2 Wiki
@aufdemrand
I at first considered COOLDOWN but if you think about it, for example lets say you want a global reset of all daily quests at 3am. Now say someone does the quest at 2:30am, now how am I supposed to figured out, and know to unreset it in 30minutes, say where someone else did the quest at 11am, and someone else at 4pm. Theres no way to account for that issue. Otherwise I would use the COOLDOWN =)
EDIT: Just read through the 0.8 tester script. It really seems like a lot of new/powerful features are coming. I am excited. But can I say, I hope that you strongly document all of the changes. As well to, I wouldn't mind if you checked and made sure all of the current info in the Wiki is there, as I am pretty sure some of it is not. And I use that Wiki fairly religiously, but I feel I am not able to fully utilize Denizens because I have to ask questions on the project for things that aren't fully documented.
@XF1taX
0.8 pre-release is imminent. I have one more thing to tackle in it and I will send public builds. Work has put that way behind... but I think it's worth the wait. Huge improvements in in-game usage, assignments, constants, replaceable tags, actions, a few new commands, and an improved flag system and much more powerful if command.
Here's an example 0.8 script that I'm using to test against: http://scripts.citizensnpcs.com/view/t1fc4s
@silentnight18
Use ENGAGE NOW for a truly 'instant' engage.
When specifying a number of times a script has been completed, it should be 'X amount of times or more'...
ie. SCRIPT FINISHED 'SCRIPT:Name' QTY:3
You can use the EXACTLY argument to require EXACTLY 3, for instance.
Have you considered using the COOLDOWN command for daily 'quests'?
As for your other suggestions, I have noted them down and will add them to the list :)
This plugin is great. I was just wondering when 0.8 would come out and the features?
@aufdemrand
It doesn't, I use full ENGAGE DISENGAGE when the NPC is moving and interacting across the world. They must queue multiples before the ENGAGE can kick in. I also use ^ for instant ENGAGE too, but they find a way.
Another question a lot of the documentation is not 100% clear. Under requirements, you can set it to say need to have finished xx script x times. Now is that needed to finish said Script xx or more times? Or exactly x times. Say if i have a requirement of finishing a script 100 times, if they finish it 101 times, will that also flag as true? And would the inverse of that be the opposite of that? say from 0-99 it would return true, 100+ false?
Also, is there any documentation anywhere for the Listeners Scripting? I will gladly test this experimental feature for you, if you have any test builds or anything set up and ready.
Could you add a new requirement/command that can allow you to acquire/check blocks infront/under/above an NPC? Normally you could just check a bookmarked location but I want to make something on a wandering NPC, that checks the block under his feet for a certain block. Also is there a way to get an NPC to place a block/item on a block? I want to basically create an NPC to walk around aimlessly, planting trees.
Also, could you add an ability to run activity scripts on a real time schedule? I know it's possible to allow NPCs to run a script at a certain time ingame. This will be needed for my next suggestion.
Make a Command to allow a mass reset of all Finished script counts of all players from a specific script. This, combined with realtime script scheduling will allow people to make Daily Repeatable quests. At a set realtime, the NPC would run the clear all finished command, allowing daily repeatable quests with a daily reset timer.
Edit #3: Sorry I just keep thinking of ideas. Maybe a way to call the number of times a Player has finished a Script, for chat use. And then maybe a way to call that number as an int and do simple math with it? If you are wondering, yes I do have practical uses for all these ideas.
Sorry for all the Questions/comments lol! I really hope to see some of these features implemented! If you would like help ever on Denizens, I have a lot of my own plugins to maintenance, but I am more than willing to sit down and learn to code and help you out.
@silentnight18
Definitely could.. maybe RESET QUEUE... using ENGAGE should help to keep players from spamming the queue, too.
@aufdemrand
Agreed! I have another question. Is there a way, that you can clear every current script or queued script on a denizen?
Over the last few weeks I have been making a script that takes players on a 10 minute tour of my Server, explaining things ,showing commands, the works. Its finally finished and running, but I am having an issue with one thing. Children love to spam click, so when they are initially starting the script, they are queuing it up an ass load of times. Is there a way to just clear every currently queued script/command? I want to run something like that on the End script I have and just tp them back after.
@Cyborax
Nope :P But I'll add that to the list.
@silentnight18
Still lots to do, too!
@aufdemrand
Ah, needed the arrows, thnx man. And nice work on this, it's really blossomed into something amazing. I remember beta testing this when it was still in it's first planning stages, I saw big things!
Is it possible to spawn MAGMA_CUBE with another size like: Small or Tiny?
@silentnight18
<COLOR> or <&#>
The best and most complex plugin ever. Good job.
Hey, at first glance, I dont know if I overlooked it, but is it possible to do Colored Chat in the CHAT command?
@GnomeffinWay
Don't be! Glad you stepped up :D
@aufdemrand
Ah! Haha well now I guess I've learned something too! Thanks for the clarification and, er, sorry for slightly misleading users :P
@GnomeffinWay
Close, but ^ will actually run the NEXT command instantaniously...
'^' denotes that it will not trigger the delay after running the command.
So, for your example: - CHAT "Hello" - ^CHAT "HEY"
..for them to run similtaniously (without delay).. it should be: - ^CHAT "Hello" - CHAT "Hey"
:D small detail, but your logic is correct. I recommend using ^ on commands that have no 'visible' output to the player.. like FLAG, FINISH, ZAP, etc. Keeping the time a script takes should be kept to the absolute minimum possible.
When you place a "^" in front of a command, it makes that command process without the normal (small) delay the scripting engine has.
For example:
- CHAT "Hello"
- ^CHAT "HEY"
Would have an NPC say both statements almost simultaneously, while
- CHAT "Hello"
- CHAT "HEY"
Would have a minimal wait time before "HEY" is spoken.
This applies more to when you use server commands, like
- EXECUTEASSERVER <something>
- ^EXECUTEASSERVER <something else>
Where you would need something to be carried out almost simultaneously.
Rough German Translation:
Wenn Sie ein "^" legen vor einem Befehl, macht es diesen Befehl Prozess ohne die normalen (kleinen) verzögern die Scripting-Engine verfügt.
Zum Beispiel:
- CHAT "Hallo"
- ^ CHAT "HEY"
Müsste ein NPC sagen beide Aussagen fast gleichzeitig, während
- CHAT "Hallo"
- CHAT "HEY"
Würde ein minimaler Wartezeit haben, bevor "HEY" gesprochen wird.
Dies gilt mehr, wenn Sie Server-Befehle, wie
- EXECUTEASSERVER <irgendwas>
- ^ EXECUTEASSERVER <something else>
Wo würden Sie etwas zu fast gleichzeitig durchgeführt werden müssen.
Hallo, kann mir bitte jemand auf Deutsch erklären, was die Verwendung bzw der Sinn dieses Symbols "^" ist, ich versteh es irgendwie nicht? Danke im Voraus.
I have an understanding problem, can you tell me the use of this ^ symbol please? thanks
@Kiak
No, stick with dev build http://ci.citizensnpcs.com/view/Characters/job/Denizen/546/
@aufdemrand
I'm not ready to update to 1.4 so do i just stick with your last Dev build b4 1.4?
or are the new versions backwards compatible anyway?