Denizen/0.7/Before Using Denizen: Difference between revisions

From Citizens Wiki

< Denizen‎ | 0.7

No edit summary
No edit summary
 
(5 intermediate revisions by 3 users not shown)
Line 1: Line 1:
<div style="font-family:camingodos-web;">
<div style="float:right;margin-left:2.0em; padding:10px; font-family:camingodos-web; font-size:110%; ">__TOC__</div>


<div style="margin-right:2.0em; margin-top:35px; padding:10px; font-family:camingodos-web; font-size:110%;">
For more up-to-date information and full details on specific features (individual commands or tags, for example), check the [https://one.denizenscript.com/denizen/cmds/ Meta Documentation].
<span style="font-family:natalya-alternate-one; font-size:650%; margin-right:-7px; margin-left:-10px;">W</span>elcome to Denizen! Grand adventure awaits, but let's get the basics out of the way first. On this page you will find instructions for installing Denizen, description of what the various files are used for, and a brief overview of what this is all about.
</div>


===Getting Started===
If you want a full tutorial to help get you set up, check out the [https://one.denizenscript.com/denizen/cmds/denizen/vids Tutorial Videos] on youtube or the [https://guide.denizenscript.com/ Beginner's Guide] text website.
<div style="margin-right:2.0em; padding:10px; font-family:camingodos-web; font-size:110%;">Denizen is in BETA! Expect a few bugs here and there! If you are having problems, [[Denizen/In_Game_Commands#Debug_Mode|<code>/denizen debug</code>]] is your friend! We're always willing to help out in [irc://irc.esper.net #denizen-dev on EsperNET] as well. If you do come across any errors beyond bad command syntax, please  report them to the [http://www.github.com/aufdemrand/Denizen/issues Github Issues page for Denizens].


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. With the new [http://scripts.citizensnpcs.com|Script Repository] in development, we hope there will be a wide array of par-baked scripts that you can easily download and customize to your server, but perhaps the most exciting part of Denizen is the ability to write your own scripts. In order to write awesome scripts, you will probably need to read the entirety of this wiki page and think outside the box! Someone is always around IRC to help out and provide suggestions, but please don't ask about the basics unless you have consulted here first.
If you need quick help, visit our [https://discord.gg/Q6pZGSR Discord group].


Some Denizen commands and requirements '''REQUIRE''' you to have other plugins, such as [http://dev.bukkit.org/server-mods/vault/ Vault], installed with a compatible Permissions System and and Economy System. If the commands deals with money or permissions, chances are you will need Vault in order to utilize it. We're also getting ready to release command/requirement packs for Heroes and mcMMO, so stay tuned!
<br><br><br>


The easiest way to use Denizen for the first time is to download the [[Denizen/Start-up kit|Start-up Kit]]. This includes the default config file, sample scripts, and sample assignments to get you started. It is still recommended that you read as much of the wiki as you can take in to properly utilize Denizen's power and flexibility.
<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>
</div>




<div style="margin-right:2.0em; padding:10px; font-family:camingodos-web; font-size:110%;">
<s>
===How it works===


Denizen is an extension of Citizens2 that adds an incredible amount of interactivity and automation to NPCs and Players with some of these major features:
<div style="font-family:camingodos-web;">
<div style="float:right;margin-left:2.0em; padding:10px; font-family:camingodos-web; font-size:110%; ">__TOC__</div>


* '''The Script Engine''' carries out and sends all the commands to be executed in an orderly and predictable fashion; this is the backbone of Denizen. Currently has 3 queues, one for the Player, one for Denizens, and one for Tasks. There's not much to see on the outside, this is the interworkings of Denizen, but rest assured that this is high performance machine behind the scenes!
<div style="margin-right:2.0em; margin-top:35px; padding:10px; font-family:camingodos-web; font-size:110%;">
* '''Interact Scripts''' are the meat of Denizen, allowing Players and NPCs to interact with each other and the world. These are highly customizable with 20+ requirement types, 40+ script commands, and thousands of different ways to use them together. This with the Denizen Script Engine also allows commands to help control the rest of Denizen with script flow commands and such.
<span style="font-family:natalya-alternate-one; font-size:650%; margin-right:-7px; margin-left:-10px;">W</span>elcome to Denizen! Grand adventure awaits, but let's get the basics out of the way first. On this page you will find instructions for installing Denizen, description of what the various files are used for, and a brief overview of what this is all about.
* '''Activity Scripts''' are exciting. Imagine Johnny Appleseed planting trees, on his own, or simple villagers wandering around and socializing. Activities, of course, work with the rest of Denizen's other functions and features, allowing hundreds of ways to use Activities to add automation and liveliness to your world.
* '''Activity Scheduler''' takes Activity Scripts one step further, allowing Denizen NPCs to have daily schedules, based on the Minecraft day, to allow certain functionality to different times of the day. This also enables certain Script Commands to be executed and carried out, as well.
* '''Task Scripts''' are simple scripts that can be carried out in a variety of different ways. These can be used along side both Activity and Interact Scripts, but perhaps the most powerful way to use them is by allowing your plugin to utilize them, if you're a developer, or using other plugins that harness the ability to run a Denizen Task Script as well.
* '''Listeners''' are currently in and 'experimental phase', but are already allowing control over minecraft and bukkit events like nothing other. This already allows scripts to keep track of and assign 'quest-like' objectives, such as a 'kill quest', if you're familiar with the C1 Quester. But whereas many quest plugins are limited to this feature alone, Denizen, of course, allows you to use this in addition and along side the rest of the plugin, making room for extremely dynamic and intricate 'quest scripts'.
* '''Flag System''' is the key to Denizen being dynamic. An intricate, yet easy to learn 'Flag/Variable' system has been implemented into Denizen to help keep track of events, items, numbers, players, and more. The new Flag System is still getting more powerful each and every day.. it's the key to a spectacular script is sure to have a flag or two.
* '''Extensible Commands/Requirements/Activities and more''' make it easy to add-on to Denizen with very little Java knowledge. This also makes it extremely easy to let users utilize your plugin with script commands. Denizen also has API Events to use.
* '''Denizen Debugger'''' is an extremely friendly and informative way to test out scripts and interactions. Commands, events, and interactions are all logged in an easy to read format to show the exact progression of a script and its surroundings. No more guessing! Less headaches!
 
 
Seem overwhelming? Stop! Start small! Denizen is easy, Denizen is simple. But. Denizen is hard, Denizen is complex. Simply put: Denizen is what you make it! Our advice? Start small, and build upon what you have. Read the wiki articles, watch the youtube videos, test our your scripts, and test out some of the sample scripts! Before you know it, you'll be a Denizen poweruser, drunken with power, just like us!
</div>
</div>


===Getting Started===
<div style="margin-right:2.0em; padding:10px; font-family:camingodos-web; font-size:110%;">Denizen is in BETA! Expect a few bugs here and there! If you are having problems, [[Denizen/0.7/In_Game_Commands#Debug_Mode|<code>/denizen debug</code>]] is your friend! We're always willing to help out in [irc://irc.esper.net #denizen-dev on EsperNET] as well. If you do come across any errors beyond bad command syntax, please  report them to the [http://www.github.com/aufdemrand/Denizen/issues Github Issues page for Denizens].


=== File Structure ===
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. With the new [http://scripts.citizensnpcs.com|Script Repository] in development, we hope there will be a wide array of par-baked scripts that you can easily download and customize to your server, but perhaps the most exciting part of Denizen is the ability to write your own scripts. In order to write awesome scripts, you will probably need to read the entirety of this wiki page and think outside the box! Someone is always around IRC to help out and provide suggestions, but please don't ask about the basics unless you have consulted here first.
[[File:Figure 1 - Denizen file structure.png|right|Denizen File Structure]]
<div style="margin-right:2.0em; padding:10px; font-family:camingodos-web; font-size:110%;">Denizen requires the use of a few different YML files to operate properly, so let's first go over the file structure. See below for more details about each file. This section may seem bloated, but please read it to get a good understanding of the file structure since you will be using these a lot!
</div>


==== denizen.jar ====
Some Denizen commands and requirements '''REQUIRE''' you to have other plugins, such as [http://dev.bukkit.org/server-mods/vault/ Vault], installed with a compatible Permissions System and and Economy System. If the commands deals with money or permissions, chances are you will need Vault in order to utilize it. We're also getting ready to release command/requirement packs for Heroes and mcMMO, so stay tuned!
<div style="margin-right:2.0em; padding:10px; font-family:camingodos-web; font-size:110%;">We have gotten a few questions about where to place the Denizen JAR file, especially from former users of Citizens 1.2, where Citizens-types went in a special folder. This is not the case for Citizens2 or Denizen. It should be treated like any other bukkit plugin and be placed in your craftbukkit/plugins/ folder. Please note that while a lot of plugins will automatically generate a folder to go along with it, Denizen does not, and this should be either created by hand and populated, or generated by copying the [[Denizen/Start-up kit|Start-up Kit]] with sample .yml configuration files and scripts.
</div>
 
==== config.yml ====
<div style="margin-right:2.0em; padding:10px; font-family:camingodos-web; font-size:110%;">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) ensures that upon a <tt>/denizen reload</tt>, 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 from disk to Denizen memory at any time by using <tt>/denizen reload</tt>. Some changes in the config.yml may require a restart of the server. This includes <tt>interact_delay_in_ticks</tt>, but is not limited to that config node.
 
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; font-family:camingodos-web; font-size:110%;">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 <code>/denizen reload</code>
 
</div>


===={{color|red|white|saves.yml}}====
The easiest way to use Denizen for the first time is to download the [[Denizen/0.7/Start-up kit|Start-up Kit]]. This includes the default config file, sample scripts, and sample assignments to get you started. It is still recommended that you read as much of the wiki as you can take in to properly utilize Denizen's power and flexibility.
<div style="margin-right:2.0em; padding:10px; font-family:camingodos-web; font-size:110%;">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, flags, 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.
 
To reiterate: This file saves periodically, and automatically, upon progression and a server stop, and should only be edited by hand when the server is off or Denizen is disabled.
</div>
 
===={{color|red|white|read-only-scripts.yml}}====
<div style="margin-right:2.0em; padding:10px; font-family:camingodos-web; font-size:110%;">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 <code>/denizen reload</code> command.
</div>
 
==== /scripts/ folder ====
<div style="margin-right:2.0em; padding:10px; font-family:camingodos-web; font-size:110%;">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.  
 
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. All scripts in the scripts folder are merged into <code>read-only-scripts.yml</code>, so there will be an issue if two scripts are named the same.
</div>
</div>


Line 82: Line 33:
=== Down and dirty ===
=== Down and dirty ===
<div style="margin-right:2.0em; padding:10px; font-family:camingodos-web; font-size:110%;">
<div style="margin-right:2.0em; padding:10px; font-family:camingodos-web; font-size:110%;">
By now, you probably just want to see how to add custom content, right? Here's a quick, down-and-dirty walk-through to get your first custom NPC up and going. First you should have the [[Denizen/Start-up kit|Start-up Kit]], or at least an existing assignments.yml and script.yml. These are the files that you will be adding to in this walkthrough. Remember: The files should be placed in your server folder so that it resembles the format mentioned in [[#File Structure|File Structure]]. Once everything is in place, start up your server.
By now, you probably just want to see how to add custom content, right? Here's a quick, down-and-dirty walk-through to get your first custom NPC up and going. First you should have the [[Denizen/0.7/Start-up kit|Start-up Kit]], or at least an existing assignments.yml and script.yml. These are the files that you will be adding to in this walkthrough. Remember: The files should be placed in your server folder so that it resembles the format mentioned in [[#File Structure|File Structure]]. Once everything is in place, start up your server.




Line 90: Line 41:




'''2:''' Create a script for Notch. See also: [[Denizen/Writing_Scripts|Writing Denizen Scripts]]. <br>
'''2:''' Create a script for Notch. See also: [[Denizen/0.7/Writing_Scripts|Writing Denizen Scripts]]. <br>
Create a new file in <tt>plugins/Denizen/scripts/</tt> named <tt>Notch Cookies.yml</tt>. Next, copy the contents of the small script below. This script gives a small random greeting to Notch with an 'easter egg' surprise if you know the secret word.
Create a new file in <tt>plugins/Denizen/scripts/</tt> named <tt>Notch Cookies.yml</tt>. Next, copy the contents of the small script below. This script gives a small random greeting to Notch with an 'easter egg' surprise if you know the secret word.


Line 121: Line 72:




'''3:''' Assign notch some scripts. See also: [[Denizen/Assigning_Scripts|Assigning Denizen Scripts]]. <br>
'''3:''' Assign notch some scripts. See also: [[Denizen/0.7/Assigning_Scripts|Assigning Denizen Scripts]]. <br>
Open your assignments.yml. If none exists, create it in your <tt>/plugins/Denizen</tt> folder. Insert the following into your YML file. If <tt>Denizens:</tt> is not at the top of this document, create it.
Open your assignments.yml. If none exists, create it in your <tt>/plugins/Denizen</tt> folder. Insert the following into your YML file. If <tt>Denizens:</tt> is not at the top of this document, create it.


Line 130: Line 81:
   Notch:
   Notch:
     Interact Scripts:
     Interact Scripts:
     - 10 Notch Cookies
     - 10 Notch Greeting
     Texts:
     Texts:
       No Click Trigger: Stop poking me!
       No Click Trigger: Stop poking me!
Line 140: Line 91:




'''4:''' Reload Denizen. See also: [[Denizen/In_Game_Commands#Denizen_Reload|Denizen Reload]]. <br>
'''4:''' Reload Denizen. See also: [[Denizen/0.7/In_Game_Commands#Denizen_Reload|Denizen Reload]]. <br>
This will ensure that the information has taken. First, in the console or your minecraft client, type <tt>/denizen reload</tt>. This will reload assignments.yml, config.yml, saves.yml, re-concantenate scripts, and perform some cleaning up of objects and such. This is a good time to check the console for any errors. If found, head on over to [[Denizen/Troubleshooting|Troubleshooting]].
This will ensure that the information has taken. First, in the console or your minecraft client, type <tt>/denizen reload</tt>. This will reload assignments.yml, config.yml, saves.yml, re-concantenate scripts, and perform some cleaning up of objects and such. This is a good time to check the console for any errors. If found, head on over to [[Denizen/0.7/Troubleshooting|Troubleshooting]].




'''5:''' Check Denizen NPC status. See also: [[Denizen/In_Game_Commands#Info-Click|Info-Click]]. <br>
'''5:''' Check Denizen NPC status. See also: [[Denizen/0.7/In_Game_Commands#Info-Click|Info-Click]]. <br>
Info-Click your Denizen NPC by crouching and right-clicking it. This will output a couple of pages of information showing Citizens2 NPC stats, current Interact scripts, Trigger status, Bookmarks, and more. In the case of our example, Notch should have a single entry under Interact Scripts for <tt>Notch Cookies</tt>.
Info-Click your Denizen NPC by crouching and right-clicking it. This will output a couple of pages of information showing Citizens2 NPC stats, current Interact scripts, Trigger status, Bookmarks, and more. In the case of our example, Notch should have a single entry under Interact Scripts for <tt>Notch Cookies</tt>.


Line 151: Line 102:




''Note:'' This seems like as good of time as any to mention that if any interact script you are using have a 'proximity', 'location', or 'damage trigger', these must be turned on, per NPC. They are off by default as to keep performance as high as possible. See [[Denizen/In_Game_Commands|In Game Commands]] for more info.
''Note:'' This seems like as good of time as any to mention that if any interact script you are using have a 'proximity', 'location', or 'damage trigger', these must be turned on, per NPC. They are off by default as to keep performance as high as possible. See [[Denizen/0.7/In_Game_Commands|In Game Commands]] for more info.


Ready to dive deeper? start with either [[Denizen/Interact_Scripts]] or [[Denizen/Activity_Scripts]]
Ready to dive deeper? start with either [[Denizen/0.7/Interact_Scripts]] or [[Denizen/0.7/Activity_Scripts]]
</div>
</div>
</div>
</div>
[[Category:Denizen 0.7]]</s>

Latest revision as of 16:10, 24 March 2020

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 Tutorial Videos on youtube or 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!


Welcome to Denizen! Grand adventure awaits, but let's get the basics out of the way first. On this page you will find instructions for installing Denizen, description of what the various files are used for, and a brief overview of what this is all about.

Getting Started

Denizen is in BETA! Expect a few bugs here and there! If you are having problems, /denizen debug is your friend! We're always willing to help out in #denizen-dev on EsperNET as well. If you do come across any errors beyond bad command syntax, please report them to the Github Issues page for Denizens.

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. With the new Repository in development, we hope there will be a wide array of par-baked scripts that you can easily download and customize to your server, but perhaps the most exciting part of Denizen is the ability to write your own scripts. In order to write awesome scripts, you will probably need to read the entirety of this wiki page and think outside the box! Someone is always around IRC to help out and provide suggestions, but please don't ask about the basics unless you have consulted here first.

Some Denizen commands and requirements REQUIRE you to have other plugins, such as Vault, installed with a compatible Permissions System and and Economy System. If the commands deals with money or permissions, chances are you will need Vault in order to utilize it. We're also getting ready to release command/requirement packs for Heroes and mcMMO, so stay tuned!

The easiest way to use Denizen for the first time is to download the Start-up Kit. This includes the default config file, sample scripts, and sample assignments to get you started. It is still recommended that you read as much of the wiki as you can take in to properly utilize Denizen's power and flexibility.


Down and dirty

By now, you probably just want to see how to add custom content, right? Here's a quick, down-and-dirty walk-through to get your first custom NPC up and going. First you should have the Start-up Kit, or at least an existing assignments.yml and script.yml. These are the files that you will be adding to in this walkthrough. Remember: The files should be placed in your server folder so that it resembles the format mentioned in File Structure. Once everything is in place, start up your server.


1: Make a NPC by using C2 commands to create a new NPC, and assign a trait. We will use Notch in this example. See also: /NPC Commands.

/npc create Notch --trait denizen

Note: You could alternatively use /trait denizen if working with an existing NPC.


2: Create a script for Notch. See also: Writing Denizen Scripts.
Create a new file in plugins/Denizen/scripts/ named Notch Cookies.yml. Next, copy the contents of the small script below. This script gives a small random greeting to Notch with an 'easter egg' surprise if you know the secret word.

'Notch Greeting':
  Type: Interact
  Requirements:
    Mode: None
  Steps:
    1:
      Click Trigger:
        Script:
        - RANDOM 3
        - CHAT 'I Like Cookies!'
        - CHAT 'MMmm.. cookies are my favorite!'
        - CHAT 'Cocoa and Wheat make me freak!'
      Chat Trigger:
        1:
          Trigger: 'I love /cookie/s!'
          Script: 
          - CHAT 'Me too!'
          - EMOTE 'gives <PLAYER> some cookies.'
          - GIVE COOKIE QTY:6
          - ZAP 2
    2:
      Click Trigger:
        Script:
        - CHAT 'How were the cookies?'


3: Assign notch some scripts. See also: Assigning Denizen Scripts.
Open your assignments.yml. If none exists, create it in your /plugins/Denizen folder. Insert the following into your YML file. If Denizens: is not at the top of this document, create it.

Denizens:
  # ...
    # ...
  Notch:
    Interact Scripts:
    - 10 Notch Greeting
    Texts:
      No Click Trigger: Stop poking me!
      Denizen Unavailable: Sorry! Busy eating cookies!
      No Chat Trigger: I only understand cookies.

This text gives Notch some simple messages for specified circumstances. It also assigns the Notch Cookies script that we just wrote in the section above.


4: Reload Denizen. See also: Denizen Reload.
This will ensure that the information has taken. First, in the console or your minecraft client, type /denizen reload. This will reload assignments.yml, config.yml, saves.yml, re-concantenate scripts, and perform some cleaning up of objects and such. This is a good time to check the console for any errors. If found, head on over to Troubleshooting.


5: Check Denizen NPC status. See also: Info-Click.
Info-Click your Denizen NPC by crouching and right-clicking it. This will output a couple of pages of information showing Citizens2 NPC stats, current Interact scripts, Trigger status, Bookmarks, and more. In the case of our example, Notch should have a single entry under Interact Scripts for Notch Cookies.


6: Click on Notch! Play out the script. It's that easy! Go up to Notch and chat 'cookie' for the super secret special surprise.


Note: This seems like as good of time as any to mention that if any interact script you are using have a 'proximity', 'location', or 'damage trigger', these must be turned on, per NPC. They are off by default as to keep performance as high as possible. See In Game Commands for more info.

Ready to dive deeper? start with either Denizen/0.7/Interact_Scripts or Denizen/0.7/Activity_Scripts