|
|
| (20 intermediate revisions by the same user not shown) |
| Line 1: |
Line 1: |
| {{CharacterWithExamples
| |
| | PICTURE = Denizen.png
| |
| | AUTHOR = aufdemrand
| |
| | NAME = Denizen
| |
| | VERSION = 0.6 Build #86
| |
| | CITIZENSBUILD = 2.0 dev build (Latest)
| |
| | DEVSTATUS = ALPHA
| |
| | DEPENDS = Vault, a permissions system, and an economy system
| |
| | DOWNLOADLINK = http://ci.citizensnpcs.net/view/Characters/job/Denizen/86/artifact/target/denizen-0.6.jar
| |
| | DOWNLOADEXAMPLESLINK = http://dl.dropbox.com/u/129951/Denizen%20Alpha%20Example%20Configs.zip
| |
| | DESCRIPTION = Scriptable, interactive citizens!
| |
| }}
| |
| <div style="float:right; clear:both; margin-left:0.5em; margin-bottom:2.0em">__TOC__</div>
| |
|
| |
|
| Denizens are a great way to add [http://en.wikipedia.org/wiki/MUD 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 thousands of different ways, from tutorials, to questing, to administrating and more!<br>
| |
|
| |
| == Script Repository ==
| |
| [[File:Script Repository.png]]
| |
|
| |
|
| |
| [http://form.jotform.us/form/21498151597160 Submit your Denizens Scripts here to share.]<br>
| |
| [https://www.dropbox.com/sh/hw6x3f980maa8d9/DNtzAw8cn3 View Shared Scripts]<br>
| |
|
| |
| == Change Log ==
| |
| '''Changelog:'''<br>
| |
|
| |
| '''0.6 Build #82'''
| |
| * Requirements code reformat is done, thanks for being patient if you were watching the Jenkins!
| |
| * FINISH command now increments a counter so you can check for a certain number of FINISHes. Use: <code>FINISHED (# of times) [name of script]</code>. The # is optional and will assume 1 if not specified. There's a chance that this broke any recorded FINISHes that may be in your config. Sorry about that. You can manually change them from True to 1 to fix this. New FINISHes will overwrite without any issues.
| |
| * TIME requirement can now check for DAWN and DUSK in addition to DAY and NIGHT.
| |
| * Requirements that use items can now use the #:# (typeId:data) format. So, for gray wool, 35:7. You can still specify just WOOL and any color will do.
| |
| * Script combiner will now only read .yml files, this fixes issues with hidden files in your scripts file corrupting the combined read-only-scripts.yml.
| |
| * NAME, WORLD, PERMISSION, GROUP, POTION_EFFECT can now all use multiple arguments. For example, <code>WORLD world_1 world_2 world_3 world_4</code> will return true if one of the worlds listed matches. You can use up to 24 arguments.
| |
|
| |
| '''0.6 Build #71'''
| |
| * Started code reformat, this will make it easier to extend.
| |
| * Added ability to use multiple scripts! Denizen will read any .yml file in the /plugins/Denizen/scripts/ folder. You will need to place your existing scripts.yml in that folder. Denizen will generate a read-only-scripts.yml to the main Denizen folder. This should be left alone. Also made config.yml generate automatically upon startup.
| |
| * Added config node chat_globally_if_no_chat_triggers
| |
|
| |
| '''0.5.3 Build #60'''
| |
| * PlayerQue now uses ConcurrentHashMap to avoid ConcurrentModificationException. (Thanks tenowg!)
| |
| * <code>/denizen reload</code> and <code>/denizen save</code> can now be used in the console.
| |
| * Check for interact_delay_in_ticks = 0 and change it to 1. (Thanks Sparta!) Probably a good idea to keep this at least 10, though.
| |
|
| |
| '''0.5.3 Build #56'''
| |
| * Added FAIL command. Sets the script as 'FAILED' for checking with requirements. Note: A script can still be FAILED and FINISHED, they are seperate.
| |
| * Added FAILED requirement. Use FAILED [Name of Script]. Remember: SCRIPT NAMES ARE CaSe SeNsItIvE!
| |
| * Added RESET command. This can be used to reset the FAILED or FINISHED status of a script. Use RESET FAILED|FINISHED [Name of Script].
| |
| * Added small warning on the /denizen help stating that many commands listed there do not yet work -- this is a beta, people, I'm working on them :P
| |
| * Documenting /denizen adddata|decdata|getdata. Nothing to do with Denizens, really, but handy for checking/switching block data. Try it on a tree.
| |
| * Fixed WAIT command. It actually works as intended now.
| |
|
| |
| '''0.5.3 Build #48'''
| |
| * Extended use of LOOK command. Can now specify a location bookmark to set Pitch and Yaw of a Denizen. Note: When making Location Bookmarks, your Pitch and Yaw are recorded along with your XYZ position. Use: LOOK [Location Bookmark]. Existing arguments, CLOSE and AWAY, are still valid. Additional note: LOOK CLOSE will override the set pitch/yaw, so be sure LOOK AWAY is used beforehand, or be sure LOOK CLOSE was not engaged.
| |
| * Fixed issue with RESPAWN command.
| |
| * Fixed issue with talking to Denizens close to one another. Players now only speak to the very closest Denizen.
| |
| * Added TELEPORT command to teleport the player to a Denizen's location bookmark. Use TELEPORT [Location Bookmark].
| |
| * Added REFUSE command to take a permission from the player. Use REFUSE [name.of.permission.node].
| |
|
| |
| It is suggested you use the latest builds of C2.
| |
|
| |
| '''0.5.3 Build #42'''
| |
| * SWITCH now activates redstone. Sorry about that folks.
| |
| * WAIT command added.
| |
| * SPAWN command added.
| |
| * Other code optimizations/cleanup.
| |
|
| |
| Big thanks to the hardworking beta testers in #citizens! Thank you!
| |
|
| |
| '''0.5.3 Build #25'''
| |
| * NARRATE command now replaces <NPC> properly.
| |
| * Denizens no longer requires you to be the owner of the NPC to use commands.
| |
| * Tweaked multi-line engine to accomodate for extra long names.
| |
| * ZAP now uses getName instead of getDisplayName (Sorry if this causes issues with current progress.)
| |
|
| |
| '''0.5.3 Alpha'''
| |
| * Added SWITCH command. Denizens can now flip levers!
| |
| * Added Denizen Project to [http://ci.citizensnpcs.net/job/Denizen/ Citizens Jenkins]!
| |
|
| |
| '''0.5.2 Alpha:'''
| |
| * Fixed requirements WEARING and -TIME. Note: PermissionsBukkit users are still having problems with GROUP.
| |
| * Added FOLLOW, TAKE, NARRATE, and CAST commands.
| |
| Smaller update than I planned, stay tuned for more!
| |
|
| |
| '''0.5.1 Alpha:'''
| |
| * Fixed requirements... they should all work now, except haven't tested requirements which can have an enchantment.
| |
| * Added the ability to give Denizens 'Location Bookmarks'. Use /denizen bookmark location [name].
| |
| * Added WALKTO, PERMISS, FINISH, RESPAWN, WEATHER and EXECUTE commands.
| |
| * Started to flesh out /denizen help
| |
| * Added activity scheduler.
| |
|
| |
|
| |
| == Known caveats ==
| |
|
| |
| * I've been having problems getting the NPCs to WALKTO a bookmarked location that is far away. This seems to be a bug beyond Denizen and Citizens2. I have a possible fix and am looking in to it.
| |
|
| |
|
| |
| == Before using Denizens ==
| |
|
| |
| Denizens are in BETA! Expect bugs! There is very little error handling for scripts that contain bad syntax. If you do come across any errors, please report them to the [http://www.github.com/aufdemrand/Denizen/issues Github Issues page for Denizens]. You can also get assistance with Denizens on the [irc://irc.esper.net #citizens IRC channel on EsperNET] from me (aufdemrand) when available. I'm usually there working hard to add awesome features and squashing bugs.
| |
|
| |
| 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 and you should expect that to be able to write scripts, it is suggested you read the entirety of this wiki document. I'm always around IRC to help out, but please don't ask about the basics unless you have consulted here first.
| |
|
| |
| Denizens '''REQUIRES''' you to have [http://dev.bukkit.org/server-mods/vault/ Vault] installed. You also should have a Permissions System and and Economy System for best results.
| |
|
| |
|
| |
| == Getting started with Denizen ==
| |
|
| |
| The easiest way to use Denizen for the first time is to download the [http://www.dropbox.com/ Start-up Kit] with sample .yml configuration files and scripts.
| |
|
| |
| === File Structure ===
| |
| [[File:Figure 1 - Denizen file structure.png|250px|thumb|right|Denizen File Structure]]
| |
|
| |
| File structure.
| |
|
| |
| == A basic trigger script ==
| |
|
| |
| <span style="word-spacing:3;letter-spacing:2">
| |
| 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 plugins/Denizen/scripts/nameofscript.yml. See the main scripts section for more information.
| |
|
| |
| <pre>
| |
| 'Daytime in the City':
| |
| Type: Trigger
| |
| Requirements:
| |
| Mode: All
| |
| List:
| |
| - TIME Day
| |
| Steps:
| |
| 1:
| |
| Click Trigger:
| |
| Script:
| |
| - CHAT Welcome to the city! Isn't it beautiful in the daytime?
| |
| </pre>
| |
|
| |
| 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.</span>
| |
|
| |
|
| |
| == A basic assignment ==
| |
|
| |
| <span style="word-spacing:3;letter-spacing:2">
| |
| 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/Denizen/config.yml and must be done by hand, for now. Once you edit the config.yml, immediately save and use /denizen reload in-game.
| |
|
| |
| <pre>
| |
| Denizens:
| |
| 'Steve':
| |
| Interact Scripts:
| |
| - 10 Daytime in the City
| |
| Texts:
| |
| No Scripts To Trigger: 'I have nothing to say to you at this time.'
| |
|
| |
| </pre>
| |
|
| |
| 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 ==
| |
|
| |
| <span style="word-spacing:3;letter-spacing:2">
| |
| 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 configs below to see how script priority is handled.
| |
|
| |
| <pre>
| |
| ---- Config.yml ----
| |
|
| |
| Denizens:
| |
| 'Steve':
| |
| Interact Scripts:
| |
| - 0 Regular Joe
| |
| - 10 Joe the Builder
| |
|
| |
| ---- Scripts.yml ----
| |
|
| |
| 'Regular Joe':
| |
| Type: Trigger
| |
| Requirements:
| |
| Mode: None
| |
| Steps:
| |
| 1:
| |
| Click Trigger:
| |
| Script:
| |
| - CHAT Hello <PLAYER>! I supply builders only!
| |
|
| |
| 'Joe the Builder':
| |
| Type: Trigger
| |
| Requirements:
| |
| Mode: All
| |
| List:
| |
| - PERMISSION modifyworld.*
| |
| Steps:
| |
| 1:
| |
| Click Trigger:
| |
| Script:
| |
| - CHAT Hello <PLAYER> the Builder! Take this shovel!
| |
| - GIVE WOOD_SPADE 1
| |
| - FINISH
| |
| </pre>
| |
|
| |
| 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 ==
| |
|
| |
| <span style="word-spacing:3;letter-spacing:2">
| |
| 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'.
| |
|
| |
| 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 [http://wiki.ess3.net/wiki/YAML_Tutorial 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.
| |
|
| |
| <code>
| |
| Denizens:
| |
| 'Steve':
| |
| Interact Scripts:
| |
| - 10 Joe the Builder
| |
| Options:
| |
| <del>Languages: HU EN</del>
| |
| <del>Chat Name: Steve the Master Builder</del>
| |
| <del>Finish Cooldown: 600</del>
| |
| Texts:
| |
| <del>Finish Cooldown:</del>
| |
| No Scripts To Trigger: I have nothing for you at this time!
| |
| <del>Interact Cooldown: That's all I have for now! Come back later!</del>
| |
| </code>
| |
|
| |
|
| |
| == Denizen Options ==
| |
|
| |
| <code>
| |
| * <del>Languages:</del>
| |
| *: </code><del>Adds a spoken/understood language to the Denizen. Languages are defined in the Languages: node. See: [[#Languages]]</del><code>
| |
| * <del>Finish Cooldown:</del>
| |
| *: </code><del>Sets a delay for the speed in which you can trigger scripts between <code>FINISH</code>es. 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, if the script is required! 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 a Finish Cooldown.</del>
| |
| <code>
| |
| * <del>Chat Name:</del>
| |
| *: </code><del>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.</del>
| |
| <code></code>
| |
|
| |
|
| |
| == Denizen Texts ==
| |
| <code>
| |
| * No Scripts To Trigger:
| |
| *: </code>If no scripts meet requirements, this message is CHATted instead.
| |
| <del><code>
| |
| * Cooldown Not Yet Met:
| |
| *: </code>If an <code>Interact Cooldown:</code> is set and not yet satisfied, this message is CHATted instead.
| |
| </del>
| |
|
| |
|
| |
| = 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/scripts/ folder. Any .yml file in that directory will be loaded into Denizen. For example purposes on this website, reference to scripts.yml is made.
| |
|
| |
|
| |
| == General layout of a Script ==
| |
|
| |
| <span style="word-spacing:3;letter-spacing:2">
| |
| <pre>
| |
| 'Name of script': # Name Node
| |
| Type: ... # Type Node
| |
| Requirements: # Requirements Node
| |
| ...:
| |
| ...:
| |
| - ...
| |
| - ...
| |
| Steps: # Steps Node
| |
| ...:
| |
| - ...
| |
| ...:
| |
| Options: # Options Node
| |
| ...:
| |
| </pre>
| |
|
| |
|
| |
| == Name Node ==
| |
|
| |
| <span style="word-spacing:3;letter-spacing:2">
| |
| This node is pretty self-explanatory, but here are some things to keep in mind.
| |
| * Names, just like nodes are case-sensitive! <code>'This script name'</code> is different than <code>'THIS SCRIPT NAME'</code>.
| |
| * Names that contain spaces must have single or double quotes around it. ie: <code>"This script":</code> or <code>'This script':</code> 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: <code>"John's Script":</code> or <code>'John<nowiki>''</nowiki>s Script':</code>
| |
|
| |
|
| |
| == Type Node ==
| |
|
| |
| <span style="word-spacing:3;letter-spacing:2">
| |
| I've been getting questions about the type node. The truth is, while this isn't technically required as of yet, there will soon be a couple more different types of scripts, and for the sake of forward compatibility, I believe this node will be used to easily distinguish between the different types. For the scripts that are explained here, use <code>Type: Trigger</code>. In the near future I have planned Activity type scripts and another types I haven't come up with a good name for, yet :D
| |
|
| |
|
| |
| == Requirements Node ==
| |
|
| |
| <span style="word-spacing:3;letter-spacing:2">
| |
| 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:
| |
|
| |
| <pre>
| |
| Requirements:
| |
| Mode: All
| |
| List:
| |
| - TIME Night
| |
| - MONEY 1000000
| |
| - STORMY
| |
| </pre>
| |
|
| |
| 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 ===
| |
| <code>[] indicates required field
| |
|
| |
| * ALL
| |
| *: </code>Requires all requirements listed to be met.<code>
| |
| * ANY [#]
| |
| *: </code>Requires the specified number of requirements to be met, out of the total of requirements listed.<code>
| |
| * NONE
| |
| *: </code>Requires NO requirements to be met.<code>
| |
| </code>
| |
|
| |
|
| |
| === Requirements Types ===
| |
| <code>[] indicates required field, () indicates an optional field, OR indicates alternative usage.
| |
|
| |
| * NAME [Player Name] (or this Player Name) ...
| |
| *: </code>Requires a specific player.<code>
| |
|
| |
| * ITEM <nowiki>[</nowiki>[[ITEM_NAME|#:#]]<nowiki>]</nowiki> (# of that item, or more)
| |
| *: </code>Requires the player to have an item in their inventory. You can also specify an amount.<code>
| |
|
| |
| * WEARING <nowiki>[</nowiki>[[ITEM_NAME|#]]<nowiki>]</nowiki>
| |
| *: </code>Requires the player to be wearing a specific piece of armor.<code>
| |
|
| |
| * HOLDING <nowiki>[</nowiki>[[ITEM_NAME|#:#]]<nowiki>]</nowiki> (# of that item, or more)
| |
| *: </code>Requires the player to have an item in their hand. You can also specify an amount.<code>
| |
|
| |
| * TIME [Day|Night|Dusk|Dawn] OR TIME [0-23999] [1-24000]
| |
| *: </code>Requires day or night. Alternatively you can specify a time window.<code>
| |
|
| |
| * HUNGER [Full|Hungry|Starving]
| |
| *: </code>Requires a specific hunger state.<code>
| |
|
| |
| * PRECIPITATION
| |
| *: </code>Requires a rain or snow.<code>
| |
|
| |
| * SUNNY
| |
| *: </code>Requires clear skies. Note: This can still trigger at night as it does not check time.<code>
| |
|
| |
| * WORLD [World Name] (or this World Name) (or this World Name) ...
| |
| *: </code>Requires the player to be in a specific world, or worlds. You can check as many as you'd like with one line.<code>
| |
|
| |
| * PERMISSION [this.permission.node] (or this permission.node) ...
| |
| *: </code>Requires one of the listed permission nodes. Only one is required. If you require multiple permission nodes, use multiple entries.<code>
| |
|
| |
| * LEVEL [This Level # or higher] OR LEVEL [At least this Level #] [But no more than this Level #]
| |
| *: </code>Requires a specific Minecraft XP level, or a range of levels.<code>
| |
|
| |
| * FINISHED (# of times) [Script Name]
| |
| *: </code>Requires a specific script to be <code>FINISH</code>ed. Remember: Script names are case-sensitive! You can specify a certain number of times, as well. Using this as a negative requirement is a good way to put a limit on how many times a player can do a script.<code>
| |
|
| |
| * FAILED [Script Name]
| |
| *: </code>Requires a specific script to be <code>FAIL</code>ed. Remember: Script names are case-sensitive!<code>
| |
|
| |
| * GROUP [Name of Group] (or this Group) ...
| |
| *: </code>Requires the player be a member of a group. Requires a Permissions system that allows groups, such as PermissionsEX.<code>
| |
|
| |
| * MONEY [Amount of Money, or more]
| |
| *: </code>Requires the player to have at least a certain amount of money on hand. Requires an economy system, such as iConomy.<code>
| |
|
| |
| * POTIONEFFECT [POTION_EFFECT]
| |
| *: </code>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.
| |
|
| |
| <pre>
| |
| Requirements:
| |
| Mode: All
| |
| List:
| |
| - -TIME Night
| |
| - -MONEY 1000000
| |
| - -STORMY
| |
| </pre>
| |
|
| |
| 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.
| |
|
| |
| <pre>
| |
| 'Welcome to Harbortown':
| |
| Type: Trigger
| |
| Requirements:
| |
| Mode: NONE
| |
| Steps:
| |
| '1':
| |
| Click Trigger:
| |
| Script:
| |
| - CHAT What's your name, stranger?
| |
| - HINT
| |
| Chat Trigger:
| |
| '1':
| |
| Trigger: My name is /<PLAYER>/.
| |
| Script:
| |
| - CHAT Ah ha, your name sounds familiar!
| |
| - CHAT Are you from around this area?
| |
| - ZAP
| |
| '2':
| |
| Click Trigger:
| |
| Script:
| |
| - HINT
| |
| Chat Trigger:
| |
| '1':
| |
| Trigger: /Yes/, I grew up in Harbortown!
| |
| Script:
| |
| - CHAT I thought so, welcome back!
| |
| Have you heard about Tom the Taylor?
| |
| Isn't that just horrible?
| |
| - ZAP 3
| |
| '2':
| |
| Trigger: /No/, you must be mistaken.
| |
| Script:
| |
| - 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 4
| |
| '3':
| |
| Click Trigger:
| |
| Script:
| |
| - CHAT I wonder if Tom the Taylor is doing any better.
| |
| - NARRATE Perhaps you should check on Tom the Taylor.
| |
| '4':
| |
| Click Trigger:
| |
| Script:
| |
| - CHAT Oh, nice to see you again <PLAYER>!
| |
| - CHAT Have you stopped by the bakery?
| |
| </pre>
| |
|
| |
| The sub-sections below reference this example.
| |
|
| |
|
| |
| === Trigger Types ===
| |
|
| |
| Steps handle the flow of commands and messages with triggers.
| |
|
| |
| '''Denizen Triggers''' trigger from interaction with Denizens. They are defined in the Steps: node.
| |
|
| |
| * '''Click Trigger'''s activate when the Denizen is clicked on.
| |
|
| |
| <pre>
| |
| Click Trigger:
| |
| Script:
| |
| - CHAT Scripts are nested as a list.
| |
| - CHAT You can use any command that
| |
| you'd wish.
| |
| </pre>
| |
|
| |
|
| |
| * '''Chat Trigger'''s activate when players chat with Denizens. Players' chat within the configurable range will be directed to the Denizen instead of global chat. Chat also follows the configuration setting <code>
| |
|
| |
| <pre>
| |
| Chat Trigger:
| |
| '1':
| |
| Trigger: The word needed to /Trigger/ is inside slashes.
| |
| Script:
| |
| - CHAT Scripts are nested as a list.
| |
| - CHAT You can use any command that
| |
| you'd wish.
| |
| </pre>
| |
| </code>
| |
|
| |
|
| |
| == Script Commands ==
| |
|
| |
| Note: There are plenty more to come, some I've even used in examples here but aren't in the alpha. Be patient, more are coming!
| |
|
| |
| <code>[] indicates required field, () indicates an optional field, OR indicates alternative usage.
| |
|
| |
| * ZAP (Step #)
| |
| *: </code>Progresses the player through the steps. ZAP used alone will progress to the next step. ZAP with a number following will progress the player to a specific step.<code>
| |
|
| |
| * FINISH
| |
| *: </code>Marks the script as completed to check against with the requirement type 'FINISHED'.<code>
| |
|
| |
| * FAIL
| |
| *: </code>Marks the script as failed to check against with the requirement type 'FAILED'. Note: A script can be both completed and failed!<code>
| |
|
| |
| * RESET [FINISHED|FAILED] [Name of Script]
| |
| *: </code>Sets either FINISHED or FAILED of the specified script to False. Remember: Script names are case sensitive!<code>
| |
|
| |
| * WAIT [# of seconds]
| |
| *: </code>Will hold a player's Command Que for a specific amount of seconds. You can use this to put delays in your script. All lines of a script after the hold will execute after the time has passed.<CODE>
| |
|
| |
| * LOOK [CLOSE|AWAY] or LOOK [Location Bookmark]
| |
| *: </code>Toggle 'lookclose' on the Denizen. Alternate use specifies a pitch/yaw from a Location bookmark.<code>
| |
|
| |
| * GIVE [ITEM_NAME] (Quantity)
| |
| *: </code>Denizen will drop specified items.<CODE>
| |
|
| |
| * TAKE [ITEM_NAME|MONEY] (Quantity)
| |
| *: </code>Takes specific item or money from the player.<CODE>
| |
|
| |
| * CHAT [The text to chat.]
| |
| *: </code>Makes the Denizen talk to the player. Long messages will be formatted for multiple lines automatically.<code>
| |
|
| |
| * NARRATE [The text to narrate.]
| |
| *: </code>Sends text to the player without branding the Denizen. Long messages will be formatted for multiple lines automatically.<code>
| |
|
| |
| * FOLLOW [PLAYER|NOBODY]
| |
| *: </code>Makes the Denizen follow the player, or stop following the player.<code>
| |
|
| |
| * WALKTO [Location Bookmark]
| |
| *: </code>Makes the Denizen walk to a specified location.<code>
| |
| Note: I've been having problems getting the NPCs to WALKTO a bookmarked location that is far away, perhaps in a different chunk? Working on it with the C2 team. I may have another workaround as well.
| |
|
| |
| * WALK [Z] [X] [Y] Note: Z(-NORTH(2)/+SOUTH(0)) X(-WEST(1)/+EAST(3)) Y (+UP/-DOWN)
| |
| *: </code>Makes the Denizen walk. This is not for making the Denizen to specific coordinates. The values for X Y and Z will get added or subtracted from the Denizen's current location.<code>
| |
|
| |
| * RETURN
| |
| *: </code>Can be used after initiating a WALK command. This will make the denizen return to its previous location.<code>
| |
|
| |
| * EXECUTE [ASPLAYER|ASNPC|ASSERVER] [command to execute] Ex: EXECUTE ASSERVER toggledownfall
| |
| *: </code>Executes a command, issues from either the Player, NPC, or Server. No need for a /.<code>
| |
|
| |
| * STRIKE
| |
| *: </code>Strikes the player with lightning.<CODE>
| |
|
| |
| * WEATHER [Sunny|Stormy|Precipitating]
| |
| *: </code>Sets the weather for the world.<CODE>
| |
|
| |
| * RESPAWN [Location Bookmark]
| |
| *: </code>Despawns the Denizen and respawns it to a bookmarked location.<CODE>
| |
| Note: There is something funny going on with NPCs spawning to a location you are very near to. You sometimes have to back away before they show up. This seems to be an issue with Craftbukkit and/or Minecraft Server.
| |
|
| |
| * TELEPORT [Location Bookmark]
| |
| *: </code>Teleports the player interacting to the Denizen's specified Location Bookmark/ <code>
| |
|
| |
| * SPAWN [ENTITY_TYPE] [AMOUNT] (Location Bookmark)
| |
| *: </code>Spawns a specified amount of entities. If the location bookmark is missing, they will spawn near the Denizen.<CODE>
| |
|
| |
| * PERMISS [permission.node.to.add]
| |
| *: </code>Gives to the player interacting the specified permission node for the current world.<CODE>
| |
|
| |
| * REFUSE [permission.node.to.take]
| |
| *: </code>Takes from the player interacting the specified permission node for the current world.<CODE>
| |
|
| |
| * CAST [POTION_TYPE] [Duration in seconds] [Amplifier]
| |
| *: </code>Gives the player interacting a potion effect. Note: [[Alchemist#Valid_Effects | Valid potion types are the same as the Alchemist's.]] Amplifier specifies 'level, strength, or duration', depending on the type of potion effect. Try 1-5 for most types.<CODE>
| |
|
| |
| * SWITCH [Block Bookmark] [ON|OFF]
| |
| *: </code>If a lever is found at the block location, it will be switched ON or OFF.<CODE>
| |
| * PRESS [Block Bookmark]
| |
| *: </code>If a button is found at the block location, it will be pressed. Note: You may need a - WAIT 1 and a 2nd - PRESS [Block Bookmark] or the Denizen will hold the button until the interact timeout.<CODE>
| |
| </code>
| |
|
| |
| = Denizen in-game bukkit commands =
| |
|
| |
| <code>/denizen reload|save</code>
| |
| * Reloads|saves the config.yml and scripts.yml. Useful for testing scripts without rebooting your server.
| |
|
| |
| <code>/denizen bookmark location [name]</code>
| |
| * Stores a location to the selected Denizen for use with script commands such as RESPAWN and WALKTO. Note: Names can only be one word, and are unique to the Denizen.
| |
|
| |
| <code>/denizen bookmark block [name]</code>
| |
| * Stores the Player crosshair's block location to the selected Denizen for use with script commands such as SWITCH. Note: Names can only be one word, and are unique to the Denizen.
| |
|
| |
| <code>/denizen adddata|decdata|getdata</code>
| |
| * Nothing to do with Denizens, really, but handy for checking/switching block data. Try it on a tree.
| |