- mcmonkey studios -
Home Page / Pi to one million places / Contact mcmonkey / Donate / Paste Scripts / Denizen Help /
You are browsing as a guest.
Login | Register


Listing Language Explanations...

1: Ungrouped
2: object system
3: object fetcher system
4: script command system
5: comparables
6: script container system
7: useful lists
8: console commands
9: events
10: npc traits
11: merchant trades
12: properties
13: inventory system
14: useful flags
15: entities
16: inventories

Namescript event switches
DescriptionModern script events support the concept of 'switches'.
A switch is a specification of additional requirements in an event line other than what's in the event label it.

A switch consists of a name and a value input, and are can be added anywhere in an event line as "name:<value>"
For example, "on delta time secondly every:5:" is a valid event, where "delta time secondly" is the event itself,
and "every:<#>" is a switch available to the event.

A traditional Denizen 1 event might look like "on <entity> damaged",
where "<entity>" can be filled with "entity" or any entity type (like "player").
A switch-using event would instead take the format "on entity damaged" with switch "type:<entity type>"
meaning you can do "on entity damaged" for any entity, or "on entity damaged type:player:" for players specifically.
This is both more efficient to process and more explicit in what's going on, however it is less
clear/readable to the average user, so it is not often used.
Some events may have switches for less-often specified data, and use the event line for other options.

Namescript event cancellation
DescriptionAny modern ScriptEvent can take a "cancelled:<true/false>" argument and a "ignorecancelled:true" argument.
For example: "on object does something ignorecancelled:true:"
Or, "on object does something cancelled:true:"
If you set 'ignorecancelled:true', the event will fire regardless of whether it was cancelled.
If you set 'cancelled:true', the event will fire /only/ when it was cancelled.
By default, only non-cancelled events will fire. (Effectively acting as if you had set "cancelled:false").

Any modern script event can take the determinations "cancelled" and "cancelled:false".
These determinations will set whether the script event is 'cancelled' in the eyes of following script events,
and, in some cases, can be used to stop the event itself from continuing.
A script event can at any time check the cancellation state of an event by accessing "<context.cancelled>".

Namescript event priority
DescriptionAny modern ScriptEvent can take a "priority:#" argument.
For example: "on object does something priority:3:"
The priority indicates which order the events will fire in.
Lower numbers fire earlier. EG, -1 fires before 0 fires before 1.
Any integer number, within reason, is valid. (IE, -1 is fine, 100000 is fine,
but 200000000000 is not, and 1.5 is not as well)
The default priority is 0.

Namescript event special contexts
DescriptionEvery modern ScriptEvent has some special context tags available.
The most noteworthy is "context.cancelled", which tracks whether the script event has been cancelled.
You can also use "context.event_header", which returns the exact event header text that fired (which may be useful for some types of dynamic script).
That returns, for example, "on player breaks stone".
You can also use "context.event_name", which returns the internal name of the script event that fired (which may be useful for some debugging techniques).
That returns, for example, "PlayerBreaksBlock".

DescriptionA 'tick' is usually referred to as 1/20th of a second, the speed at which CraftBukkit updates
its various server events.

DescriptionMany arguments in Denizen require the use of a 'number', or 'double'. Sometimes referred to as #.# or <number>,
this kind of hint can generally be filled with any reasonable positive or negative number with or without a
decimal point. Numbers can be verified with the 'if' commands' 'matches' functionality.
For example: - if <number> matches double ... will return true if <number> is a valid number.

DescriptionPromotes the usage of a 'percentage' format to be used in applicable arguments. The 'percentage' in Denizen is
much like the 'number', except arguments which utilize percentages instead of numbers can also include a %.
Percentage arguments can generally be filled with any reasonable positive or negative number with or without a
decimal point and/or percentage sign. Argument hints and other usages will typically refer to a percentage as
#.#% or <percentage>. Percentages can be verified with the 'if' commands' 'matches' functionality.
For example: - if <percentage> matches percentage ... will return true if <percentage> is a valid percentage.

Denizen uses the regular expression pattern -?(?:\d+)?(\.\d+)?(%)? for percentage matching.

DescriptionA somewhat vague term used to describe a collection of script entries and other script parts.

For example, 'Hey, check out this script I just wrote!', probably refers to a collection of script entries
that make up some kind of script container. Perhaps it is a NPC Assignment Script Container that provides
waypoint functionality, or a world script that implements and keeps track of a new player stat. 'Script' can
refer to a single container, as well as a collection of containers that share a common theme.

Scripts that contain a collection of containers are typically kept to a single file. Multiple containers are
permitted inside a single file, but it should be noted that container names are stored on a global level. That
is, naming scripts should be done with care to avoid duplicate script names.

Namebukkit event priority
DescriptionScript events that are backed by standard Bukkit events are able to control what underlying Bukkit event priority
they register as.
This can be useful, for example, if a different plugin is cancelling the event at a later priority,
and you're writing a script that needs to un-cancel the event.
This can be done using the "bukkit_priority" switch.
Valid priorities, in order of execution, are: LOWEST, LOW, NORMAL, HIGH, HIGHEST, MONITOR.
Monitor is executed last, and is intended to only be used when reading the results of an event but not changing it.
The default priority is "normal".

DescriptionDurations are a unified and convenient way to get a 'unit of time' throughout Denizen.
Many commands and features that require a duration can be satisfied by specifying a number
and unit of time, especially command arguments that are prefixed 'duration:', etc. The d@
object fetcher notation can also be used, and is encouraged. The unit of time can be specified
by using one of the following: T=ticks, M=minutes, S=seconds, H=hours, D=days, W = Weeks.
Not using a unit will imply seconds. Examples: d@10s, d@50m, d@1d, d@20.

Specifying a range of duration will result in a randomly selected duration that is
in between the range specified. The smaller value should be first. Examples:
d@10s-25s, d@1m-2m.

See 'd@duration' tags for an explanation of duration attributes.

Groupobject system

DescriptionElements are simple objects that contain either a boolean (true/false),
string, or number value. Their main usage is within the replaceable tag
system, often times returned from the use of another tag that isn't returning
a specific object type, such as a location or entity. For example,
<player.name> or <li@item|item2|item3.as_cslist> will both return Elements.

Pluses to the Element system is the ability to utilize its attributes that
can provide a range of functionality that should be familiar from any other
programming language, such as 'to_uppercase', 'split', 'replace', 'contains',
as_int, any many more. See 'element' tags for more information.

While information fetched from other tags resulting in an Element is often
times automatically handled, it may be desirable to utilize element
attributes from strings/numbers/etc. that aren't already an element object.
To accomplish this, the object fetcher can be used to create a new element.
Element has a constructor, el@val[element_value], that will allow the
creation of a new element. For example: <el@val[This_is_a_test.].to_uppercase>
will result in the value 'THIS_IS_A_TEST.' Note that while other objects often
return their object identifier (el@, li@, e@, etc.), elements do not.

Groupobject system

Description1) A dObject that represents a script container. dScripts contain all information inside the script, and can be
used in a variety of commands that require script arguments. For example, run and inject will 'execute'
script entries inside of a script container when given a matching dScript object.

dScripts also provide a way to access attributes accessed by the replaceable tag system by using the object
fetcher or any other entry point to a dScript object. dScript objects have the object identifier of 's@'.
For example: s@script_name

2) The overall 'scripting language' that Denizen implements is referred to as 'dScripting', or 'dScript'.
dScripts use YAML + Denizen's Scripting API to parse scripts that are stored as .yml or .dscript files. Scripts
go in the .../plugins/Denizen/scripts folder.

Groupobject system

DescriptiondObjects are a system put into place by Denizen that make working with things, or 'objects',
in Minecraft and Denizen easier. Many parts of scripts will require some kind of object as an
argument, identifier/type, or such as in world events, part of an event name. The dObjects notation
system helps both you and Denizen know what type of objects are being referenced and worked with.

So when should you use dObjects? In arguments, event names, replaceable tags, configs, flags, and
more! If you're just a beginner, you've probably been using them without even realizing it!

dObject is a broader term for a 'type' of object that more specifically represents something,
such as a dLocation or dScript, often times just referred to as a 'location' or 'script'. Denizen
employs many object types that you should be familiar with. You'll notice that many times objects
are reference with their 'dObject notation' which is in the format of 'x@', the x being the specific
notation of an object type. Example: player objects use the p@ notation, and locations use l@.
The use of this notation is encouraged, but not always required.

Let's take the tag system, for example. It uses the dObjects system pretty heavily. For instance,
every time you use <player.name> or <npc.id>, you're using a dObject, which brings us to a simple
clarification: Why <player.name> and not <p@player.name>? That's because Denizen allows Players,
NPCs and other 'in-context objects' to be linked to certain scripts. In short, <player> already
contains a reference to a specific player, such as the player that died in a world event 'on player dies'.
<p@player.name> would incorrectly reference the player named 'player', however this format is often
used to help with usage of a tag, simply indicating 'any player object'.

dObjects can be used to CREATE new instances of objects, too! Though not all types allow 'new'
objects to be created, many do, such as dItems. With the use of tags, it's easy to reference a specific
item, say -- an item in the Player's hand -- items are also able to use a constructor to make a new item,
and say, drop it in the world. Take the case of the command/usage '- drop i@diamond_ore'. The item object
used is a brand new diamond_ore, which is then dropped by the command to a location of your choice -- just
specify an additional location argument.

There's a great deal more to learn about dObjects, so be sure to check out each object type for more
specific information. While all dObjects share some features, many contain goodies on top of that!

Here's an overview of each object type that is implemented by the Denizen core:

+ ----- dPlayer ----- +
| object notation: p@    can reference unique objects: yes    can be notable: no
| constructors: ( <>'s represent non-static information and are not literal)
|   p@<UUID> - fetches an online or offline player with the specified UUID
|   p@<player_name> - Outdated constructor for back-support, fetches by name instead of UUID

+ ----- dNPC ---------+
| object notation: n@    can reference unique objects: yes    can be notable: no
| constructors: ( <>'s represent non-static information and are not literal)
|   n@<npc_id> - fetches the NPC with the specified ID
|   n@<npc_name> - fetches the first NPC found with the specified name

+ ----- dLocation ----+
| object notation: l@    can reference unique objects: no     can be notable: yes
| constructors: ( <>'s represent non-static information and are not literal)
|   l@<x>,<y>,<z>,<world_name> - fetches a specific location
|   l@<x>,<y>,<z>,<pitch>,<yaw>,<world_name> - fetches a specific location and direction
|   l@<notable_location_name> - fetches the location that has been 'noted' with the specified ID

+ ----- dEntity ------+
| object notation: e@    can reference unique objects: yes    can be notable: no
| constructors: ( <>'s represent non-static information and are not literal)
|   e@<entity_type> - fetches a new entity with the specified type as implemented by Bukkit's entity type enumeration
|   e@<entity_type>,<setting> - fetches a new entity of the specified type with a custom setting unique to the type
|   e@<entity_script_name> - fetches a new custom entity as specified by the referenced entity script (soon)
|   e@<entity_id> - fetches the entity that has the (temporary) entity ID set by Bukkit
|   e@random - fetches a new, random entity

+ ----- dItem --------+
| object notation: i@    can reference unique objects: no     can be notable: yes
| constructors: ( <>'s represent non-static information and are not literal)
|   i@<material_name> - fetches a new item of the specified material
|   i@<material_name>,<data> - fetches a new item with the specified data
|   i@<item_script_name> - fetches a new custom item as specified by the referenced item script
|   i@<notable_name> - fetches the item that has been noted with the specified ID

+ ----- dWorld -------+
| object notation: w@    can reference unique objects: yes     can be notable: no
| constructors: ( <>'s represent non-static information and are not literal)
|   w@<world_name> - fetches the world with the specified name

+ ----- dColor -------+
| object notation: co@    can reference unique objects: no      can be notable: soon
| constructors: ( <>'s represent non-static information and are not literal)
|   co@<color_name> - fetches a named color, as implemented by Bukkit's color enumeration
|   co@<r>,<g>,<b> - fetches a color made of the specified Red,Green,Blue value
|   co@random - fetches a random color

+ ----- dCuboid ------+
| object notation: cu@   can reference unique objects: no      can be notable: yes
| constructors: ( <>'s represent non-static information and are not literal)
|   cu@<position_1>|<position_2>|... - fetches a new cuboid encompassing a region from position 1 to 2, from 3 to 4, ...
|   cu@<notable_name> - fetches the cuboid that has been noted with the specified ID

+ ----- dEllipsoid ------+
| object notation: ellipsoid@   can reference unique objects: no      can be notable: yes
| constructors: ( <>'s represent non-static information and are not literal)
|   ellipsoid@<x>,<y>,<z>,<world>,<xrad>,<yrad>,<zrad> - fetches a new ellispoid at the position with the given radius
|   ellipsoid@<notable_name> - fetches the ellipsoid that has been noted with the specified ID

+ ----- dChunk ------+
| object notation: ch@   can reference unique objects: yes      can be notable: no
| constructors: ( <>'s represent non-static information and are not literal)
|   ch@<x>,<y>,<world> - fetches a chunk at the given chunk location

+ ----- dInventory ---+
| object notation: in@   can reference unique objects: yes     can be notable: yes
| constructors: ( <>'s represent non-static information and are not literal)
|   in@player[holder=<player>] - fetches the specified Player's inventory (Works for offline players)
|   in@enderchest[holder=<player>] - fetches the specified Player's enderchest inventory (Works for offline players)
|   in@npc[holder=<npc>] - fetches the specified NPC's inventory
|   in@entity[holder=<entity>] - fetches the specified object's inventory, such as a Player, NPC, or Mule
|   in@location[holder=<location>] - fetches the contents of a chest or other 'inventory' block
|   in@<notable_inventory_name> - fetches the inventory that has been 'noted' with the specified ID
|   in@<inventory_script_name> - fetches a new custom inventory as specified by the referenced inventory script
|   in@generic - represents a generic, customizable virtual inventory to be used with inventory properties (See language/Virtual Inventories)

+ ----- dMaterial ----+
| object notation: m@    can reference unique objects: no      can be notable: no
| constructors: ( <>'s represent non-static information and are not literal)
|   m@<material_name> - fetches the material as specified by Bukkit's material enumeration
|   m@<material_name>,<data> - fetches the material as specified by Bukkit's material enumeration with specified data
|   m@<data_variety_material> - fetches the material specified by Denizen's 'data variety' dMaterials
|   m@random - fetches a random material

+ ----- dTrade -----+
| object notation: trade@    can reference unique objects: no      can be notable: no
|   trade@trade - represents a generic, customizable merchant trade to be used with merchant trade properties (See language/Merchant Trades)

+ ----- dList -------+
| object notation: li@  can reference unique objects: yes  can be notable: no
| constructors: ( <>'s represent non-static information and are not literal)
|   li@<items|...> - fetches a new list with the elements specified, separated by a pipe (|) character

+ ----- dScript -------+
| object notation: s@    can reference unique objects: yes     can be notable: no
| constructors: ( <>'s represent non-static information and are not literal)
|   s@<script_container_name> - fetches the script container with the specified name

+ ----- Duration ------+
| object notation: d@    can reference unique objects: no      can be notable: no
| constructors: ( <>'s represent non-static information and are not literal)
|   d@<duration> - fetches a duration object with the specified amount of time
|   d@<low>-<high> - fetches a duration that is randomly selected between the specified 'low' and 'high'

+ ----- dPlugin -------+
| object notation: pl@    can reference unique objects: yes     can be notable: no
| constructors: ( <>'s represent non-static information and are not literal)
|   pl@<plugin_name> - fetches the plugin with the specified name

+ ----- Element ------+
| object notation: el@   can reference unique objects: no      can be notable: no
| constructors: ( <>'s represent non-static information and are not literal)
|   el@<value> - fetches an element with the specified value
|   el@val[<value>] - slightly more verbose, but tag friendly way to fetch a new element (allows periods)

+ ----- Queue ------+
| object notation: q@   can reference unique objects: yes      can be notable: no
| constructors: ( <>'s represent non-static information and are not literal)
|   q@<id> - fetches the queue with the given ID

Groupobject system

Descriptiond@ refers to the 'object identifier' of a 'Duration'. The 'd@' is notation for Denizen's Object
Fetcher. Durations must be a positive number or range of numbers followed optionally by
a unit of time, and prefixed by d@. Examples: d@3s, d@1d, d@10s-20s.

See also 'Duration'

Groupobject fetcher system

Descriptions@ refers to the 'object identifier' of a dScript. The 's@' is notation for Denizen's Object
Fetcher. The only valid constructor for a dScript is the name of the script container that it should be
associated with. For example, if my script container is called 'cool_script', the dScript object for that script
would be able to be referenced (fetched) with s@cool_script.

Groupobject fetcher system

Descriptionp@ refers to the 'object identifier' of a dPlayer. The 'p@' is notation for Denizen's Object
Fetcher. The only valid constructor for a dPlayer is the UUID of the player the object should be
associated with.

Groupobject fetcher system

Descriptionw@ refers to the 'object identifier' of a dWorld. The 'w@' is notation for Denizen's Object
Fetcher. The only valid constructor for a dWorld is the name of the world it should be
associated with. For example, to reference the world named 'world1', use w@world1.
World names are case insensitive.

Groupobject fetcher system

Namecommand syntax
DescriptionAlmost every Denizen command and requirement has arguments after the command itself.
These arguments are just snippets of text showing what exactly the command should do,
like what the chat command should say, or where the look command should point.
But how do you know what to put in the arguments?

You merely need to look at the command's usage/syntax info.
Let's take for example:
animatechest [<location>] ({open}/close) (sound:{true}/false)
Obviously, the command is 'animatechest'... but what does the rest of it mean?

Anything in [brackets] is required... you MUST put it there.
Anything in (parenthesis) is optional... you only need to put it there if you want to.
Anything in {braces} is default... the command will just assume this if no argument is actually typed.
Anything in <> is non-literal... you must change what is inside of it.
Anything outside of <> is literal... you must put it exactly as-is.
<#> represents a number without a decimal, and <#.#> represents a number with a decimal
Lastly, input that ends with "|..." (EG, [<entity>|...] ) can take a list of the input indicated before it (In that example, a list of entities)

A few examples:
[<location>] is required and non-literal... you might fill it with 'l@1,2,3,world' which is a valid location object.
(sound:{true}/false) is optional and has a default value of true... you can put sound:false to prevent sound, or leave it blank to allow sound.
(repeats:<#>) is optional, has no clear default, and is a number. You can put repeats:3 to repeat three times, or leave it blank to not repeat.
Note: Optional arguments without a default usually have a secret default... EG, the (repeats:<#>) above has a secret default of '0'.

Also, you should never directly type in [], (), {}, or <> even though they are in the syntax info.
The only exception is in a replaceable tag (EG: <npc.has_trait[<traitname>]> will take <npc.has_trait[mytrait]> as a valid actual usage)

Highly specific note: <commands> means a block of commands wrapped in braces or as a sub-block... EG:
repeat 3:
  - narrate "<def[value]>"
  - narrate "everything spaced out as a sub-block (these two narrates) following a ":" ended command (that repeat) is for the <commands> input!"

Groupscript command system

DescriptionA Comparable is a method that the IF command and Element dObject uses to compare objects.
(This lang is TODO! )
See language/operator


DescriptionAn operator is the type of comparison that a comparable will check. Not all types of
comparables are compatible with all operators. See language/comparable for more information.

Available Operators include:

Operators which have a symbol alternative (as marked by parenthesis) can be referred to by either
their name or symbol. Using a '!' in front of the operator will also reverse logic, effectively
turning 'EQUALS' into 'DOES NOT EQUAL', for example.

== <= >= > < all compare arguments as text or numbers.

CONTAINS checks whether a list contains an element, or an element contains another element.

IS_EMPTY checks whether a list is empty. (This exists for back-support).

MATCHES checks whether the first element matches a given type.
For example: "if 1 matches number" or "if p@bob matches player".
Match types: location, material, materiallist, script, entity, spawnedentity, entitytype,
npc, player, offlineplayer, onlineplayer, item, pose, duration, cuboid, decimal,
number, even number, odd number, boolean.

Note: When using an operator in a replaceable tag (such as <el@element.is[...].than[...]>),
keep in mind that < and >, and even >= and <= must be either escaped, or referred to by name.
Example: "<player.health.is[<&lt>].than[10]>" or "<player.health.is[LESS].than[10]>",
but <player.health.is[<].than[10]> will produce undesired results. <>'s must be escaped or replaced since
they are normally notation for a replaceable tag. Escaping is not necessary when the argument
contains no replaceable tags.


Namescript container
DescriptionScript Containers are the basic structure that Denizen uses inside its YAML-based scripting files found in your
plugins/Denizen/scripts/ folder. Regardless of type, all script containers have basic parts that can usually be
described as keys, list keys, parent keys, child keys, values, and list values. While specific container types
probably have more specific names, just remember that no matter how complicated a script, this basic structure
still applies.

It's important to keep in mind that all child keys, including all the main keys of the script, must line up with
one another, hierarchically. If you are familiar with YAML, great, because all script containers use it at the
core. Every value, in one way or another, belongs to some kind of 'key'. To define a key, use a string value plus
a colon (:). Keys can have a single value, a list value, or own another key:

script name:
  key: value
  list key:
    - list value
    - ...
  parent key:
    child key: value

And here's a container, put into a more familiar context:

a haiku script:
  type: task
  - narrate "A simple script,"
  - narrate "with a key value relationship."
  - narrate "Oh look, a list!"

Groupscript container system

Namescript name
DescriptionTypically refers to the name of a script container. When using the object fetcher with dScript objects,
(s@script_name), the script_name referred to is the name of the container.

script name:         <--- script name
  type: script_type
  script:            <--- base script
    - script entries
    - ...
  local script:      <--- local script path
    - script entries
    - ...

Groupscript container system

Namescript type
DescriptionThe type of container that a script is in. For example, 'task script' is a script type that has some sort of
utility script or

script name:
  type: script_type  <--- script type
    - script entries
    - ...

Groupscript container system

Nameassignment script containers
DescriptionAssignment script-containers provide functionality to NPCs by 'assignment' of the container. Assignment
scripts are meant to be used when customizing the normal behavior of NPCs. This can be used on a 'per-NPC' basis,
but the encouraged approach is to design assignment scripts in a way that they can be used for multiple NPCs,
perhaps with the use of constants or flags to determine specific information required by the scripts.
Features unique to assignment script-containers include 'actions', 'constants', and 'interact script' assignment.
Like any script, the ability to run local utility scripts can be accomplished as well. This allows fully
interactive NPCs to be built purely with Assignment Scripts, and for advanced situations, world scripts and
interact scripts can provide more functionality.
Basic structure of an assignment script:
Assignment script container name:
  type: assignment
    on <action>:
    - ...
  default constants:
    - ...
  interact scripts:
  - <priority> <interact_script_name>
  - ...

Unlike other script containers, all part of an assignment script are optional. The three features provided can be
used together, but do not require one another.

Groupscript container system

Namebook script containers
DescriptionBook script containers are similar to item script containers, except they are specifically
for the book items. They work with with the dItem object, and can be fetched
with the Object Fetcher by using the dItem constructor i@book_script_name
Example: - give <player> i@my_book

Book Script Name:
  type: book
  # The 'custom name' can be anything you wish.
  title: custom name
  # The 'custom name' can be anything you wish.
  author: custom name
  # Defaults to true. Set to false to spawn a 'book and quill' instead of a 'written book'.
  signed: true/false
  # Each -line in the text section represents an entire page.
  # To create a newline, use the tag <n>. To create a paragraph, use <p>.
  - page
  - ...

Groupscript container system

Namecommand script containers
DescriptionCommand script containers allow you to register commands with CraftBukkit via magic.
This, in turn, allows the command to show up in the '/help' command, with some info
on the command.

Note that existing names or aliases from other plugins will be overridden.
If you want to run a script at the same time as an existing command, see example/on command event tutorial.

The following is the format for the container.
Note that everything is optional except for "name" and "script".

# The name of the script doesn't matter, and will not affect the command in any way.
Command Script Name:
  type: command
  # The name of the command. This will show up in the default list in the '/help' command
  # and will be the default method for running the command.
  name: mycmd
  # The description of the command. This will be shown in the '/help' command.
  # Multiple lines are acceptable, via <&nl> (the tag for a new line), but you should
  # make the first line a brief summary of what your command does.
  description: My command.
  # Correct usage for the command. This will show in the '/help' command.
  usage: /mycmd <&lt>myArg1<&gt>
  # A list of aliases for the command. These will show in the '/help' command, and
  # are alternatives to the default name.
  - myalias
  - mycommand
  # The permission node to check for permissions plugins. This will automatically
  # block players without the permission from accessing the command and help for
  # the command.
  permission: my.permission.node
  # The message to send to the player when they try to use the command without
  # permission. If this is not specified, the default Bukkit message will be sent.
  permission message: Sorry, <player.name>, you can't use my command because you don't have the permission '<permission>'!
  # The procedure-based script that will be checked when a player or the console
  # is trying to view help for this command. This must always be determined true
  # or false. If there is no script, it's assumed that all players and the console
  # should be allowed to view the help for this command.
  # Available context: <context.server> returns whether the server is viewing the help (a player if false).
  allowed help:
  - determine <player.is_op||<context.server>>
  # The procedure-based script that will run when a player uses tab completion to
  # predict words. This should return a dList of words that the player can tab through,
  # based on the arguments they have already typed. Leaving this node out will result
  # in using Bukkit's built-in tab completion.
  # Available context:  <context.args> returns a list of input arguments.
  # <context.raw_args> returns all the arguments as raw text.
  # <context.server> returns whether the server is using tab completion (a player if false).
  # <context.alias> returns the command alias being used.
  tab complete:
  - if !<player.is_op||<context.server>> queue clear
  - determine <server.list_online_players.parse[name].include[pizza|potato|anchovy].filter[starts_with[<context.args.last>]]>
  # The script that will run when the command is executed.
  # No, you do not need '- determine fulfilled' or anything of the sort, since
  # the command is fully registered.
  # Available context: <context.args> returns a list of input arguments.
  # <context.raw_args> returns all the arguments as raw text.
  # <context.server> returns whether the server is running the command (a player if false).
  # <context.alias> returns the command alias being used.
  # <context.command_block_location> returns the command block's location (if the command was run from one).
  # <context.command_minecart> returns the dEntity of the command minecart (if the command was run from one).
  - if !<player.is_op||<context.server>> {
    - narrate "<red>You do not have permission for that command."
    - queue clear
  - narrate "Yay!"
  - narrate "My command worked!"
  - narrate "And I typed '<context.raw_args>'!"

Groupscript container system

Nameentity script containers
DescriptionEntity script containers are an easy way to pre-define custom entities for use within scripts. Entity
scripts work with the dEntity object, and can be fetched with the Object Fetcher by using the
dEntity constructor e@EntityScriptName. Example: - spawn <player.location> e@MyEntity

The following is the format for the container. Except for the 'entity_type' key (and the dScript
required 'type' key), all other keys are optional.

You can also include a 'custom' key to hold any custom yaml data attached to the script.

# The name of the entity script is the same name that you can use to construct a new
# dEntity based on this entity script. For example, an entity script named 'space zombie'
# can be referred to as 'e@space zombie'.
Entity Script Name:
  type: entity
  # Must be a valid dEntity (EG e@zombie or e@pig[age=baby]) See 'dEntity' for more information.
  entity_type: e@base_entity
  # Samples of mechanisms to use (any valid dEntity mechanisms may be listed like this):
  # Whether the entity has the default AI
  has_ai: true/false
  # What age the entity is
  age: baby/adult/<#>

MORE OPTIONS ARE LISTED HERE: url//denizen/mecs/dentity.

Groupscript container system

Nameinventory script containers
DescriptionInventory script containers are an easy way to pre-define custom inventories for use within scripts.
Inventory scripts work with the dInventory object, and can be fetched with the Object Fetcher by using the
dInventory constructor in@inventory_script_name.

Example: - inventory open d:in@MyInventoryScript

The following is the format for the container. They all are optional, but you have to have at least one
of them.

# The name of the script is the same name that you can use to construct a new
# dInventory based on this inventory script. For example, an inventory script named 'Super Cool Inventory'
# can be referred to as 'in@Super Cool Inventory'.
Inventory Script Name:
  type: inventory
  # Must be a valid inventory type.
  inventory: inventory type
  # The title can be anything you wish. Use color tags to make colored titles.
  # Note that titles only work for some inventory types, including CHEST, DISPENSER, FURNACE, ENCHANTING, and HOPPER.
  title: custom title
  # The size must be a multiple of 9. It is recommended not to go above 54, as it will not show
  # correctly when a player looks into it. Tags are allowed for advanced usage.
  size: 27
  # You can use definitions to define items to use in the slots. These are not like normal
  # script definitions, and do not need %'s around them.
    my item: i@item
    other item: i@item
  # Procedural items can be used to specify a list of dItems for the empty slots to be filled with.
  # Each item in the list represents the next available empty slot.
  # When the inventory has no more empty slots, it will discard any remaining items in the list.
  # A slot is considered empty when it has no value specified in the slots section.
  # If the slot is filled with air, it will no longer count as being empty.
  procedural items:
    - define list li@
    - foreach <server.list_online_players>:
      - define item i@human_skull[skull_skin=<def[value].name>]
      - define list <def[list].include[<def[item]>]>
    - determine <def[list]>
  # You can specify the items in the slots of the inventory. For empty spaces, simply put
  # an empty "slot". Note the quotes around the entire lines.
    - "[] [] [] [my item] [i@item] [] [other item] [] []"
    - "[my item] [] [] [] [] [i@item] [i@item] [] []"
    - "[] [] [] [] [] [] [] [] [other item]"

Groupscript container system

Nameitem script containers
DescriptionItem script containers are an easy way to pre-define custom items for use within scripts. Item
scripts work with the dItem object, and can be fetched with the Object Fetcher by using the
dItem constructor i@item_script_name. Example: - drop <player.location> i@super_dooper_diamond

The following is the format for the container. Except for the 'material' key (and the dScript
required 'type' key), all other keys are optional.

# The name of the item script is the same name that you can use to construct a new
# dItem based on this item script. For example, an item script named 'sword of swiftness'
# can be referred to as 'i@sword of swiftness'.
Item Script Name:
  type: item
  # Must be a valid dItem (EG i@red_wool or i@potion,8226) See 'dItem' for more information.
  material: i@base_material
  # The 'custom name' can be anything you wish. Use color tags to make colored custom names.
  display name: custom name
  # Lore lines can make items extra unique. This is a list, so multiple entries will result in multiple lores.
  # If using a replaceable tag, they are filled in when the item script is given/created/dropped/etc.
  - item
  - ...
  # If you want an item to be damaged on creation, you can change its durability.
  durability: 12
  # Each line must specify a valid Bukkit enchantment. See 'enchantments' for more information.
  - enchantment_name:level
  - ...
  # You can specify the items required to craft your item. For an empty slot, use i@air.
  - i@item|i@item|i@item
  - i@item|i@item|i@item
  - i@item|i@item|i@item
  # You can specify a material that can be smelted into your item.
  # Note: This can overwrite existing furnace recipes.
  # If no_id is specified, only the material/data pair will be validated.
  # This might misbehave with some smelting systems, as the Minecraft smelting logic may refuse
  # To continue smelting items in some cases when the script validator gets in the way.
  furnace_recipe: i@item
  # You can specify a list of materials that make up a shapeless recipe.
  # Note: This can overwrite existing shapeless recipes.
  shapeless_recipe: i@item|...
  # Set to true to not store the scriptID on the item, treating it as an item dropped by any other plugin.
  no_id: true/false
  # For colorable items, such as leather armor, you can specify a valid dColor to specify the item's appearance.
  # See 'dColor' for more information.
  color: co@color
  # If your material is a 'm@written_book', you can specify a book script to automatically scribe your item
  # upon creation. See 'book script containers' for more information.
  book: book_script_name

Groupscript container system

Namemap script containers
DescriptionMap scripts allow you define custom in-game map items, for usage with the map command.

The following is the format for the container.

# The name of the map script is used by the map command.
Item Script Name:
  type: map
  # Whether to display the original map below the custom values.
  original: true/false
  # The 'custom name' can be anything you wish. Use color tags to make colored custom names.
  display name: custom name
  # Whether to constantly update things.
  auto update: true
  # Lists all contained objects.
    # The first object...
      # Specify the object type
      type: image
      # Specify an HTTP url or file path within Denizen/images/ for the image. Supports animated .gif!
      image: my_image.png
      # Optionally add width/height numbers.
      type: text
      # Specify any text, with tags.
      text: Hello <player.name>
      # Specify a tag to show or hide custom content! Valid for all objects.
      type: cursor
      # Specify a cursor - ?a href="/tags/server.list_map_cursor_types"?tag/server.list_map_cursor_types?/a?
      cursor: red_marker
      # Supported on all objects: x/y positions, and whether to use worldly or map coordinates.
      x: 5
      y: 5
      world_coordinates: false

Groupscript container system

Nameproperty escaping
DescriptionSome item properties (and corresponding mechanisms) need to escape their
text output/input to prevent players using them to cheat the system
(EG, if a player set the display name of an item to:
     'name;enchantments=damage_all,3', they would get a free enchantment!)
These are the escape codes used to prevent that:

| = &pipe
< = &lt
> = &gt
newline = &nl
& = &amp
; = &sc
[ = &lb
] = &rb
: = &co
@ = &at
. = &dot
\ = &bs
' = &sq
" = &quo
! = &exc
/ = &fs
ยง = &ss
# = &ns

Also, you can input a non-breaking space via &sp

These symbols are automatically used by the internal system, if you are
writing your own property string and need to escape some symbols, you
can just directly type them in, EG: i@stick[display_name=&ltFancy&spStick&gt]

Groupuseful lists

Nameparticle effects
DescriptionAll of the effects listed here can be used by command/PlayEffect to display visual effects or play sounds

- iconcrack_[item] (item break effect - examples: iconcrack_stone, iconcrack_grass)
- blockcrack_[material] (block break effect - examples: blockcrack_stone, blockcrack_grass)
- blockdust_[material] (block break effect - examples: blockdust_stone, blockdust_grass)
TODO: split the above list between sounds, visual effects, and particles?

- RANDOM (chooses a random visual effect from the list starting with 'huge_explosion')

Groupuseful lists

Nameinventory actions
DescriptionUsed by some inventory world events to describe the action of the inventory event.

Actions, as described by the bukkit javadocs:
A max-size stack of the clicked item is put on the cursor.
The inventory is searched for the same material, and they are put on the cursor up to
The entire cursor item is dropped.
The entire clicked slot is dropped.
One item is dropped from the cursor.
One item is dropped from the clicked slot.
The clicked item is moved to the hotbar, and the item currently there is re-added to the
     player's inventory.
The clicked slot and the picked hotbar slot are swapped.
The item is moved to the opposite inventory if a space is found.
Nothing will happen from the click.
All of the items on the clicked slot are moved to the cursor.
Half of the items on the clicked slot are moved to the cursor.
One of the items on the clicked slot are moved to the cursor.
Some of the items on the clicked slot are moved to the cursor.
All of the items on the cursor are moved to the clicked slot.
A single item from the cursor is moved to the clicked slot.
Some of the items from the cursor are moved to the clicked slot (usually up to the max stack size).
The clicked item and the cursor are exchanged.
An unrecognized ClickType.

Groupuseful lists

Name/ex command
DescriptionThe '/ex' command is an easy way to run a single denizen script command in-game. Its syntax,
aside from '/ex' is exactly the same as any other command. When running a command, some context
is also supplied, such as '<player>' if being run by a player (versus the console), as well as
'<npc>' if a NPC is selected by using the '/npc sel' command.

/ex flag <player> test_flag:!
/ex run 's@npc walk script' as:<npc>

Need to '/ex' a command as a different player or NPC? No problem. Just use the 'npc' and 'player'
value arguments, or utilize the object fetcher.

/ex narrate player:p@NLBlackEagle 'Your health is <player.health.formatted>.'
/ex walk npc:n@fred <player.location.cursor_on>

Groupconsole commands

Namedenizen permissions
DescriptionThe following is a list of all permission nodes Denizen uses within Bukkit.

denizen.basic         # use the basics of the /denizen command
denizen.notable       # use the /notable command
denizen.notable.basic # functionality within the /notable command, such as add or list
denizen.ex            # use the /ex command
denizen.debug         # use the /denizen debug command
denizen.submit        # use the /denizen submit command

denizen.npc.health, denizen.npc.sneak,
denizen.npc.effect, denizen.npc.fish, denizen.npc.sleep, denizen.npc.stand,
denizen.npc.sit, denizen.npc.nameplate, denizen.npc.nickname, denizen.npc.trigger,
denizen.npc.assign, denizen.npc.constants, denizen.npc.pushable

However, we recommend just giving op to whoever needs to access Denizen - they can
op themselves through Denizen anyway, why not save the trouble?
( EG, /ex execute as_server "op <player.name>" )

Groupconsole commands

Name/denizen submit command
DescriptionUse the '/denizen submit' command with '/denizen debug -r' to record debug output and post
it online for assisting developers to see.

To begin recording, simply use '/denizen debug -r'. After that, any debug output sent to the
console and any player chat will be added to an internal record. Once enabled, you should then
fire off scripts and events that aren't working fully. Finally, you use the '/denizen submit'
command to take all the recording information and paste it to an online pastebin hosted by
the Denizen team. It will give you back a direct link to the full debug output, which you
can view yourself and send to other helpers without trouble.

There is no limit to the recording size, to prevent any important information from being trimmed
away. Be careful not to leave debug recording enabled by accident, as it may eventually begin
using up large amounts of memory. (The submit command will automatically disable recording,
or you can instead just use '/denizen debug -r' again.)

Groupconsole commands

Name/denizen debug command
DescriptionUsing the /denizen debug command interfaces with Denizen's dBugger to allow control
over debug messages.

To enable debugging mode, simply type '/denizen debug'. While debug is enabled, all debuggable
scripts, and any invoked actions, will output information to the console as they are executed.
By default, all scripts are debuggable while the dBugger is enabled. To disable a script
specifically from debugging, simply add the 'debug:' node with a value of 'false' to your script
container. This is typically used to silence particularly spammy scripts. Any kind of script
container can be silenced using this method.

To stop debugging, simply type the '/denizen debug' command again. This must be used without
any additional options. A message will be sent to show the current status of the dBugger.
Note: While your server is in 'live production mode', the dBugger should be disabled as your
server will run slower while outputting debug information.

There are also several options to further help debugging. To use an option, simply attach them
to the /denizen debug command. One option, or multiple options can be used. For example: /denizen debug -ce

'-c' enables/disables color. This is sometimes useful when debugging with a non-color console.
'-r' enables recording mode. See also: /denizen submit command
'-e' enables/disables world event timings. While enabled, the dBugger will show all triggered events.
'-s' enables/disables stacktraces generated by Denizen. We might ask you to enable this when problems arise.
'-b' enables/disables the ScriptBuilder debug. When enabled, Denizen will show info on script and argument creation.
     Warning: Can be spammy.
'-n' enables/disables debug trimming. When enabled, messages longer than 512 characters will be 'snipped'.
'-i' enables/disables source information. When enabled, debug will show where it came from (when possible).

The dBugger also allows the targeting of specific scripts by using the '--filter script_name' argument. For
example: /denizen debug --filter 'my script|my other script' will instruct the dBugger to only debug the
scripts named 'my script' and 'my other script'. Multiple scripts should be separated by a pipe character (|).
The --filter argument is cumulative, that is, scripts specified are added to the filter. To add more scripts,
simply use the command again. To clear the filter, use the -x option. Example: /denizen debug -x

Groupconsole commands

Name/npc pushable command
DescriptionThe '/npc pushable' command controls a NPCs Pushable Trait. When a NPC is 'pushable', the NPC
will move out of the way when colliding with another LivingEntity.

Pushable NPCs have 3 different settings available: Toggled, Returnable, and Delay.

When an NPCs Pushable Trait is toggled off, it will not function. Entities which
collide may occupy the same space. To toggle pushable on or off, use the Bukkit command:
/npc pushable -t

Setting the NPC as 'returnable' will automatically navigate the NPC back to
its original location after a specified delay. If not returnable, NPCs will retain
their position after being moved.
/npc pushable -r

To change the delay of a returnable NPC, use the following Bukkit Command,
specifying the number of seconds in which the delay should be.
/npc pushable --delay #
It is possible to use multiple arguments at once. For example:
/npc pushable -t -r --delay 10

Note: If allowed to move in undesirable areas, the NPC may be un-returnable
if the navigator cancels navigation due to being stuck. Care should be taken
to ensure a safe area around the NPC.

See also: 'pushable trait'

Groupconsole commands

Name/npc constant command
DescriptionThe /npc constants command configures a NPC's constants. Uses Denizen's ConstantTrait to keep track of
NPC-specific constants. This provides seamless integration with an assignment script's 'Default Constants' in
which text variables can be stored and retrieved with the use of 'replaceable tags', or API. Constants set at
the NPC level override any constants from the NPC's assignment script.

Constants may be used in several ways: Setting, Removing, and Viewing

To set a constant, all that is required is a name and value. Use the Bukkit command in the
following manner: (Note the use of quotes on multi world values)
/npc constant --set constant_name --value 'multi word value'

Removing a constant from an NPC only requires a name. Note: It is not possible to remove a
constant set by the NPCs Assignment Script, except by modifying the script itself.
/npc constant --remove constant_name

Viewing constants is easy, just use '/npc constant #', specifying a page number. Constants which
have been overridden by the NPC are formatted with a strike-through to indicate this case.

To reference a constant value, use the replaceable tag to get the NPCs 'constant' attribute. For example:
<npc.constant[constant_name]>. Constants may also have other tags in their value, which will be replaced
whenever the constant is used, allowing the use of dynamic information.

Groupconsole commands

Namedamage cause
DescriptionPossible damage causes
See list in Spigot source here: url/https://hub.spigotmc.org/javadocs/spigot/org/bukkit/event/entity/EntityDamageEvent.DamageCause.html


Namehealth trait
DescriptionBy default, NPCs are invulnerable, unable to be damaged. If you want your NPC
to be able to take damage, or use the left click as an interaction, it must
have the health trait. The Health trait is automatically enabled if you set
the damage trigger state to true.

You can use the denizen vulnerable command to make your NPCs react to left
click, but not take damage. - vulnerable state:false

Enable Damage trigger via dScript: - trigger name:damage state:true
Enable Health trait via dScript: - trait state:true health
Enable Health trait via npc command: /npc health --set # (-r)

Enable automatic respawn (default delay 300t): /npc health --respawndelay [delay as a duration]
Set respawn location: - flag <npc> respawn_location:<location>

Related Tags

Related Mechanisms

Related Commands

Related Actions
action/on damage
action/on damaged
action/on no damage trigger

Groupnpc traits

Nameinvisible trait
DescriptionThe invisible trait will allow a NPC to remain invisible, even after a server restart. It permanently applies
the invisible potion effect. Use '/trait invisible' or the 'invisible' script command to toggle this trait.

Note that player-type NPCs must have '/npc playerlist' toggled to be turned invisible.
Once invisible, the player-type NPCs can be taken off the playerlist.
This only applies specifically to player-type NPCs.
Playerlist will be enabled automatically if not set in advance, but not automatically removed.

Groupnpc traits

Namepushable trait
DescriptionBy default, NPCs created will allow players to 'noclip' them, or go right through. This is to
avoid NPCs moving from their set location, but often times, this behavior may be undesired.
The pushable trait allows NPCs to move when collided with, and optionally return to their
original location after a specified amount of time.

To enable the trait, use the '/npc pushable' command on any selected NPC. Once the trait is
enabled, the '-r' option can be used to toggle returnable, and the '--delay #' option can be
used to specify the number of seconds before the npc returns.

Care should be taken when allowing NPCs to be pushable. Allowing NPCs to be pushed around
complex structures can result in stuck NPCs. If the NPC is stuck, it may not return. Keeping
a small delay, in situations like this, can be a good trade-off. Typically the lower the
delay, the shorter distance a Player is able to push the NPC. The default delay is 2 seconds.

The pushable trait also implements some actions that can be used in assignment scripts.
This includes 'on push' and 'on push return'.

Groupnpc traits

DescriptionTraits are abilities and functions that are specific to NPCs. The trait system is
implemented by Citizens2, but heavily utilized for NPC features throughout Denizen.

Groupnpc traits

Namemerchant trades
DescriptionMerchant trades are the parts of a special merchant inventory that is typically viewed by right clicking
a villager entity. Any number of trades can fit in a single merchant inventory.

The properties that can be used to customize a merchant trade are:

uses=<number of uses>
max_uses=<maximum number of uses>

For example, the following task script opens a virtual merchant inventory with two merchant trades. The
first trade offers a sponge for two emeralds for a sponge, can be used up to 10 times, and offers XP upon a
successful transaction. The second trade has zero maximum uses and displays a barrier.

open two trades:
    type: task
    - opentrades li@trade@trade[max_uses=10;inputs=i@emerald[quantity=2];result=i@sponge|trade@trade[result=i@barrier]

Groupmerchant trades

Namehorse types
DescriptionThis is a quick rundown of the styling information used to create a horse,
used for both tag/e@entity.color and mechanism/e@entity.color.

The output/input is formatted as COLOR|STYLE(|VARIANT)
Where color is:
and where style is:
and where variant is:


Namerabbit types
DescriptionDenizen includes its own user-friendly list of rabbit type names, instead
of relying on Bukkit names which did not exist at the time of writing.

Types currently available:

Note: The KILLER rabbit type is a hostile rabbit type. It will attempt to kill
      nearby players and wolves. Use at your own risk.


Namevirtual inventories
DescriptionVirtual inventories are inventories that have no attachment to anything within the world of Minecraft. They can
be used for a wide range of purposes - from looting fallen enemies to serving as interactive menus with item

In Denizen, all Notable dInventories (saved by the Note command) are automatically converted into a
virtual copy of the saved inventory. This enables you to open and edit the items inside freely, with automatic
saving, as if it were a normal inventory.

Notables are not the only way to create virtual inventories, however. Using in@generic along with inventory
properties will allow you to create temporary custom inventories to do with as you please. The properties that
can be used like this are:

holder=<inventory type>

For example, the following task script opens a virtual inventory with 18 slots, of which the second slot is a
snowball, all the rest are empty, and the title is "My Awesome Inventory" with some colors in it.
open random inventory:
  type: task
  - inventory open "d:in@generic[size=18;title=<red>My <green>Awesome <blue>Inventory;contents=li@i@air|i@snow_ball]"

Groupinventory system

Name'show_command_reports' player flag
DescriptionGiving a player the flag 'show_command_reports' will tell the Denizen dBugger to output
command reports to the player involved with the ScriptEntry. This can be useful for
script debugging, though it not an all-inclusive view of debugging information.

To turn on and turn off the flag, just use:
/ex flag <player> show_command_reports
/ex flag <player> show_command_reports:!

Groupuseful flags

Namedenizen entity types
DescriptionAlong with the default EntityTypes url/https://hub.spigotmc.org/javadocs/spigot/org/bukkit/entity/EntityType.html,
Denizen also adds in a few altered entities:
- FAKE_ARROW: For use when you want an arrow to stay spawned at a location for any reason.
- FAKE_PLAYER: Spawns a fake player (non-Citizens NPC).
  Use with the mechanisms "name" and "skin" to alter the respective properties.
- ITEM_PROJECTILE: Use this when you want to fire any item as if it were a normal projectile.
  It will have the same physics (although sometimes not clientside) as arrows, and will fire the
  projectile hit event.


Nameslot inputs
DescriptionWhenever a script component requires a slot ID (such as the take command, when using '- take slot:#')
you can give the slot ID input as either a number of the 1-based index (where the first slot is 1, the second is 2, etc.)
OR you can give the following names (valid for player inventories only):
BOOTS: equivalent to 37
LEGGINGS: equivalent to 38
CHESTPLATE: equivalent to 39
HELMET: equivalent to 40
OFFHAND: equivalent to 41

Note that some common alternate spellings may be automatically accepted as well.