- D1 Meta Docs - Denizen Script -
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: script events
2: common terminology
3: object system
4: denizen scripting language
5: script command system
6: comparables
7: script container system
8: tag system
9: useful lists
10: npc traits
11: properties
12: inventory system
13: npc interact scripts
14: denizen magic
15: console commands
16: depenizen object types

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 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.

One of the most common switches across many Denizen events is "in:<area>".
In these switches, 'area' is a world, noted cuboid, or noted ellipsoid.
So for example you might have an event line like "on player breaks block in:space:"
where space is the name of a world or of a noted cuboid.
This also works as "in:cuboid" or "in:ellipsoid" to match for *any* noted cuboid or ellipsoid.

GroupScript Events

NameScript Event After vs On
DescriptionModern ScriptEvents let you choose between "on" and "after".
An "on" event looks like "on player breaks block:" while an "after" event looks like "after player breaks block:".

An "on" event fires *before* the event actually happens in the world. This means some relevant data won't be updated
(for example, "<context.location.material>" would still show the block type that is going to be broken)
and the result of the event can be changed (eg the event can be cancelled to stop it from actually going through).

An "after" event, as the name implies, fires *after* the event actually happens. This means data will be already updated to the new state
(so "<context.location.material>" would now show air) but could potentially contain an arbitrary new state from unrelated changes
(for example "<context.location.material>" might now show a different block type, or the original one, if the event was changed,
or another thing happened right after the event but before the 'after' event ran).
This also means you cannot affect the outcome of the event at all (you can't cancel it or anything else - the "determine" command does nothing).

GroupScript Events

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>".

GroupScript Events

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.

GroupScript Events

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".

GroupScript Events

NameAdvanced Script Event Matching
DescriptionScript event lines often include specific 'matchable' keywords.
For example, while you can write "on player breaks block:" as a script event line,
you can also instead write "on player breaks stone:" to listen to a much more specific event.
This is general in-line matching.
This is made available to avoid needing to do things like "- if <context.material.name> == stone"
just to validate whether an event is even relevant to you.

Of course, there are times when you want to more than one specific thing to be handled by the event, so what do you do?
The Denizen script event system provides a few 'advanced' options to get more detailed matching.

One option is to use wildcards.
For example, there are several 'log' materials, such as 'oak_log', 'birch_log', and more for the rest of the tree types.
So how can you match a player breaking any of these? Use "on player breaks *_log:"
The asterisk is a generic wildcard, it means any text at all will match. So an asterisk followed by '_log' means
any material at all that has a name ending with '_log', including 'birch_log' and the rest.

Note that you can also use multiple wildcards at once, like "on player breaks block with:my_*_script_*:"
That example will work for item scripts named "my_item_script_1" and "my_first_script_of_items" or any similar name.
Note also that wildcards still match for blanks, so "my_item_script_" would still work for that example.

You can also specify lists. For example, if you want an event to work with certain tool types,
the 'on player breaks block:' event supports a switch named 'with', like 'on player breaks block with:iron_pickaxe:'
So lets match multiple tools for our event...
'on player breaks block with:iron_pickaxe|gold_pickaxe|diamond_axe|wood_shovel:'

You can also combine wildcards and lists... note that lists are the 'wider' option.
That is, if you have wildcards and lists together, you will have a list of possible matches, where each entry
may contain wildcards. You do not have a a wildcard match with a list.
As a specific example,
'*_pickaxe|*_axe' will match any pickaxe or any axe.
'*_pickaxe|stone' will match any pickaxe or specifically stone. It will NOT match other types of stone, as it interprets
the match to be a list of "*_pickaxe" and "stone", NOT "*" followed by a list of "pickaxe" or "stone".

Additionally, when you're really desperate for a good matcher, you may use 'regex:'
For example, "on player breaks regex:(?i)\d+_customitem:"
Note that generally regex should be avoided whenever you can, as it's inherently hard to track exactly what it's doing at-a-glance, and may have unexpected edge case errors.

GroupScript Events

NameScript Event Object Matchables
DescriptionScript events have a variety of matchable object inputs, and the range of inputs they accept may not always be obvious.
For example, an event might be "player clicks <block>"... what can "<block>" be filled with?

"<block>" usually indicates that a MaterialTag will be matched against.
This means you can specify any valid block material name, like "stone" or "air".
You can also use "block" or "material" as catch-alls.

"<entity>", "<projectile>", "<vehicle>", etc. are examples of where an EntityTag will be expected.
You can generally specify any potentially relevant entity type, such as "creeper" under "<entity>", or "arrow" for "<projectile>",
but you can also specify "entity" (catch-all), "player" (real players, NOT player-type NPCs), "npc" (Citizens NPC),
"vehicle" (minecarts, boats, horses, etc), "fish" (cod, pufferfish, etc), "projectile" (arrow, trident, etc), "hanging" (painting, item_frame, etc).

"<item>" or similar expects of course an ItemTag.
You can use any valid item material type like "stick", or the name of an item script, or "item" as a catch-all, or "potion" for any potion item.

"<inventory>" or similar expects of course an InventoryTag.
You can use "inventory" as a catch-all, "note" to mean any noted inventory, the name of an inventory script,
the name of an inventory note, or the name of an inventory type (like "chest").

You will also often see match inputs like "<cause>" or "<reason>" or similar,
which will expect the name from an enumeration documented elsewhere in the event meta (usually alongside a "<context.cause>" or similar).

You can also do more advanced multi-matchers in any of these inputs.
For details on that, see language/Advanced Script Event Matching.

GroupScript Events

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".

GroupScript Events

NamePlayer Event Switches
DescriptionThere are a few special switches available to any script event with a linked player.

The "flagged:<flag name>" will limit the event to only fire when the player has the flag with the specified name.
It can be used like "on player breaks block flagged:nobreak:" (that would be used alongside "- flag player nobreak").

The "permission:<perm key>" will limit the event to only fire when the player has the specified permission key.
It can be used like "on player breaks block permission:denizen.my.perm:"

Note that these switches will be ignored for events that do not have a linked player.
Be cautious with events that will only sometimes have a linked player.

For multiple flag or permission requirements, just list them separated by '|' pipes, like "flagged:a|b|c".

GroupScript Events

NameSafety In Events
DescriptionOne of the more common issues in Denizen scripts (particularly ones relating to inventories) is
*event safety*. That is, using commands inside an event that don't get along with the event.

The most common example of this is editing a player's inventory, within an inventory-related event.
Generally speaking, this problem becomes relevant any time an edit is made to something involved with an event,
within the firing of that event.
Take the following examples:
on player clicks in inventory:
take iteminhand
on entity damaged:
remove <context.entity>

In both examples above, something related to the event (the player's inventory, and the entity being damaged)
is being modified within the event itself.
These break due a rather important reason: The event is firing before and/or during the change to the object.
Most events operate this way. A series of changes *to the object* are pending, and will run immediately after
your script does... the problems resultant can range from your changes being lost to situational issues
(eg an inventory suddenly being emptied entirely) to even server crashes!
The second example event also is a good example of another way this can go wrong:
Many scripts and plugins will listen to the entity damage event, in ways that are simply unable to handle
the damaged entity just being gone now (when the event fires, it's *guaranteed* the entity is still present
but that remove command breaks the guarantee!).

The solution to this problem is simple: Use "after" instead of "on".
after player clicks in inventory:
take iteminhand
after entity damaged:
if <context.entity.is_spawned||false>:
  - remove <context.entity>
This will delay the script until *after* the event is complete, and thus outside of the problem area.
And thus should be fine. One limitation you should note is demonstrated in the second example event:
The normal guarantees of the event are no longer present (eg that the entity is still valid) and as such
you should validate these expectations remain true after the event (as seen with the 'if is_spawned' check).

If you need determine changes to the event, you can instead use 'on' but add a 'wait 1t' after the determine but before other script logic.
This allows the risky parts to be after the event and outside the problem area, but still determine changes to the event.
Be sure to use 'passively' to allow the script to run in full.
on player clicks in inventory:
determine passively cancelled
wait 1t
take iteminhand
on entity damaged:
determine passively cancelled
wait 1t
if <context.entity.is_spawned||false>:
  - remove <context.entity>

GroupScript Events

NameNumber and Decimal
DescriptionMany arguments in Denizen require the use of a 'number', or 'decimal'. Sometimes shorthanded to '#' or '#.#',
this kind of input can generally be filled with any reasonable positive or negative number.
'decimal' inputs allow (but don't require) a decimal point in the number.
'number' inputs will be rounded, so avoiding a decimal point is better. For example, '3.1' will be interpreted as just '3'.

GroupCommon Terminology

DescriptionA 'tick' is usually referred to as 1/20th of a second, the speed at which Minecraft servers update
and process everything on them.

GroupCommon Terminology

NameUnique Objects vs Generic Objects
DescriptionThere are a lot of object types in the Denizen object system, and not all of them behave the same way.
It can be useful to separate object types into categories to better understand how objects work, and how Denizen as a whole works.
While there are some hardlined separations, there are also some generalizations that don't necessarily hold exactly, but are still helpful.
One such generalization is the separation between Unique and Generic object types.

A UNIQUE object is the way you might assume all objects are.
Unique objects most notably include EntityTag objects and the derivative NPCTag / PlayerTag objects.
An entity object identifies in a form like 'e@<uuid>', where '<uuid>' is some unique ID that looks something like 'abc123-4d5e6f'.
This ID is randomly generated by the Minecraft server and is used to identify that one entity in the world separately from any other.
'e@abc123' is not "a creeper" to the engine, it is "that specific creeper over there".
An object that is unique must have some way to specify the exact single instance of it in the world, like the UUID used by entities.

A GENERIC object can be said to be a 'description' of a unique object.
A generic form of an EntityTag might look like 'e@creeper'.
Instead of "that specific creeper over there", it is instead "the concept of a creeper mob".
There is no way for the engine to read only the word 'creeper' and find out which specific creeper in the world it came from...
it could be any of them, there's often hundreds of creepers spawned somewhere in the world at any time.
Objects like items and materials are always generic. There is no unique identifier for any item, there is only the description.
An item usually looks something like 'i@stick'.
ItemTag objects can include more detail, like 'i@stick[lore=hi;display_name=My Stick;enchantments=sharpness,5]'...
but this is still just a description, and there could still be many items out there that match this description.

The consequences of this mostly relate to:
- How you adjust an object (eg change the lore of an item, or teleport an entity).
For example: you can't teleport the generic concept of a creeper, but you can certainly teleport a specific single creeper in the world.
- How reliable tags on the object are.
For example: the result of 'ItemTag.lore' on the item 'i@stick[lore=hi]' will always be 'hi' (because ItemTags are generic),
but the result of 'EntityTag.location' on the entity 'e@abc123' will change every tick as the entity moves,
or even become invalid if the entity dies (because that EntityTag is unique).

Here's where the separation gets muddy:
First, as mentioned, an EntityTag can either be unique ('e@abc123', 'n@42', etc.) OR generic ('e@creeper', 'e@zombie[custom_name=Bob]', etc).
Second, some object types exhibit a bit of both.

For example, a LocationTag refers to a unique block in the world (like, 'l@1,2,3,world' is always that specific block at that position),
but also is a generic object in terms of the location object itself - if for example you want to change the angle of a location,
you have to essentially 'create' a new location, that is an exact copy of the previous one but with a new yaw or pitch value.

GroupObject System

NameCustom Objects
DescriptionCustom objects are custom object types. They use a script basis to create an object
similar to the base object types (ListTag, PlayerTags, etc).

Usage of these should generally be avoided, as they can be considered 'over-engineering'...
That is, using a very complicated solution to solve a problem that can be solved much more simply.

These use the object notation "custom@".
The identity format for custom objects is the script name, followed by property syntax listing all fields with their values.

GroupObject System

NameDurationTag Objects
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 unit of time can be specified by using one of the following:
t=ticks, s=seconds, m=minutes, h=hours, d=days, w=weeks.
Not using a unit will imply seconds. Examples: 10s, 50m, 1d, 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:
'10s-25s', '1m-2m'.

The input of 'instant' or 'infinite' will be interpreted as 0 (for use with commands where instant/infinite logic applies).

These use the object notation "d@".
The identity format for DurationTags is the number of seconds, followed by an 's'.

GroupObject System

NameElementTag Objects
DescriptionElementTags are simple objects that contain a simple bit of text.
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 <list[item1|item2|item3].comma_separated> will both return ElementTags.

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

While information fetched from other tags resulting in an ElementTag is often times automatically handled,
it may be desirable to utilize element attributes from text/numbers/etc. that aren't already an element object.
To accomplish this, the standard 'element' tag base can be used for the creation of a new element.
For example: <element[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 (p@, li@, e@, etc.), elements usually do not (except special type-validation circumstances).
They will, however, recognize the object notation "el@" if it is used.

GroupObject System

DescriptionWhen "ElementTag(Boolean)" appears in meta documentation, this means the input/output is an ElementTag
(refer to language/ElementTag Objects) that is a boolean.
Boolean means either a "true" or a "false".

GroupObject System

DescriptionWhen "ElementTag(Number)" appears in meta documentation, this means the input/output is an ElementTag
(refer to language/ElementTag Objects) that is an integer number.
That is, for example: 0, 1, 5, -4, 10002325 or any other number.
This does NOT include decimal numbers (like 1.5). Those will be documented as language/ElementTag(Decimal).

In some cases, this will also be documented as "<#>".

GroupObject System

DescriptionWhen "ElementTag(Decimal)" appears in meta documentation, this means the input/output is an ElementTag
(refer to language/ElementTag Objects) that is a decimal number.
That is, for example: 0, 1, 5, -4, 10002325, 4.2, -18.281241 or any other number.
While this is specifically for decimal numbers, the decimal itself is optional (will be assumed as ".0").

In some cases, this will also be documented as "<#.#>".

GroupObject System

NameListTag Objects
DescriptionA ListTag is a list of any data. It can hold any number of objects in any order.
The objects can be of any basic Denizen object type, including another list
(escaping sub-lists is strongly recommended).

These use the object notation "li@".
The identity format for ListTags is each item, one after the other, in order, separated by a pipe '|' symbol.
For example, for a list of 'taco', 'potatoes', and 'cheese', it would be 'li@taco|potatoes|cheese|'
A list with zero items in it is simply 'li@',
and a list with one item is just the one item and a pipe on the end.

If the pipe symbol "|" appears in a list entry, it will be replaced by "&pipe",
similarly if an ampersand "&" appears in a list entry, it will be replaced by "&amp".
This is a subset of Denizen standard escaping, see language/property escaping.

GroupObject System

NameMapTag Objects
DescriptionA MapTag represents a mapping of keys to values.
Keys are plain text, case-insensitive.
Values can be anything, even lists or maps themselves.

Any given key can only appear in a map once (ie, no duplicate keys).
Values can be duplicated into multiple keys without issue.

Order of keys is preserved. Casing in keys is preserved in the object but ignored for map lookups.

These use the object notation "map@".
The identity format for MapTags is each key/value pair, one after the other, separated by a pipe '|' symbol.
The key/value pair is separated by a slash.
For example, a map of "taco" to "food", "chicken" to "animal", and "bob" to "person" would be "map@taco/food|chicken/animal|bob/person|"
A map with zero items in it is simply 'map@'.

If the pipe symbol "|" appears in a key or value, it will be replaced by "&pipe",
a slash "/" will become "&fs", and an ampersand "&" will become "&amp".
This is a subset of Denizen standard escaping, see language/property escaping.

GroupObject System

NameQueueTag Objects
DescriptionA QueueTag is a single currently running set of script commands.
This is not to be confused with a script path, which is a single set of script commands that can be run.
There can be one, multiple, or zero queues running at any time for any given path.

These use the object notation "q@".
The identity format for queues is simply the queue ID.

GroupObject System

NameScriptTag Objects
DescriptionA ObjectTag that represents a script container. ScriptTags 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 ScriptTag object.

ScriptTags 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 ScriptTag object.

These use the object notation "s@".
The identity format for scripts is simply the script name.

GroupObject System

NameTimeTag Objects
DescriptionA TimeTag represents a real world date/time value.

These use the object notation "time@".
The identity format for TimeTags is "yyyy/mm/dd_hh:mm:ss:mill_offset"
So, for example, 'time@2020/05/23_02:20:31:123_-07:00'

TimeTags can also be constructed from 'yyyy/mm/dd', 'yyyy/mm/dd_hh:mm:ss', or 'yyyy/mm/dd_hh:mm:ss:mill'.
(Meaning: the offset is optional, the milliseconds are optional, and the time-of-day is optional,
but if you exclude an optional part, you must immediately end the input there, without specifying more).

GroupObject System

NameBiomeTag Objects
DescriptionA BiomeTag represents a world biome type.

A list of all valid Bukkit biomes can found be at

These use the object notation "b@".
The identity format for biomes is simply the biome name, as registered in Bukkit, for example: 'desert'.

GroupObject System

NameChunkTag Objects
DescriptionA ChunkTag represents a chunk in the world.

These use the object notation "ch@".
The identity format for chunks is <x>,<z>,<world>
For example, 'ch@5,3,world'.

Note that the X/Z pair are chunk coordinates, not block coordinates.
To convert from block coordinates to chunk coordinates, divide by 16 and round downward.
Note that negative chunks are one unit lower than you might expect.
To understand why, simply look at chunks on a number line...
x      x      x      x      x
-2     -1    b 0 a    1      2
The block 'a' at block position '1' is in chunk '0', but the block 'b' at block position '-1' is in chunk '-1'.
As otherwise (if 'b' was in chunk '0'), chunk '0' would be double-wide (32 blocks wide instead of the standard 16).

For example, block at X,Z 32,67 is in the chunk at X,Z 2,4
And the block at X,Z -32,-67 is in the chunk at X,Z -2,-5

GroupObject System

NameColorTag Objects
DescriptionA ColorTag represents an RGB color code.

Note that a ColorTag is NOT a base dye color (used by wool, etc). That is handled by a separate naming system.

These use the object notation "co@".
The identity format for colors is <red>,<green>,<blue> or the name of a color.
For example, 'co@50,64,128' or 'co@red'.

A list of accepted color names can be found at

Red/green/blue values are each from 0 to 255.

GroupObject System

NameCuboidTag Objects
DescriptionA CuboidTag represents a cuboidal region in the world.

The word 'cuboid' means a less strict cube.
Basically: a "cuboid" is to a 3D "cube" what a "rectangle" is to a 2D "square".

One 'cuboid' consists of two points: the low point and a high point.
a CuboidTag can contain as many cuboids within itself as needed (this allows forming more complex shapes from a single CuboidTag).

These use the object notation "cu@".
The identity format for cuboids is <world>,<x1>,<y1>,<z1>,<x2>,<y2>,<z2>
Multi-member cuboids can simply continue listing x,y,z pairs.
For example, 'cu@space,1,2,3,4,5,6'.

GroupObject System

NameEllipsoidTag Objects
DescriptionAn EllipsoidTag represents an ellipsoidal region in the world.

The word 'ellipsoid' means a less strict sphere.
Basically: an "ellipsoid" is to a 3D "sphere" what an "ellipse" (or "oval") is to a 2D "circle".

These use the object notation "ellipsoid@".
The identity format for ellipsoids is <x>,<y>,<z>,<world>,<x-radius>,<y-radius>,<z-radius>
For example, 'ellipsoid@1,2,3,space,7,7,7'.

GroupObject System

NameEntityTag Objects
DescriptionAn EntityTag represents a spawned entity, or a generic entity type.

Note that players and NPCs are valid EntityTags, but are generally represented by the more specific
PlayerTag and NPCTag objects.

Note that a spawned entity can be a living entity (a player, NPC, or mob) or a nonliving entity (a painting, item frame, etc).

These use the object notation "e@".
The identity format for entities is a spawned entity's UUID, or an entity type.
For example, 'e@abc123' or 'e@zombie'.

GroupObject System

NameInventoryTag Objects
DescriptionAn InventoryTag represents an inventory, generically or attached to some in-the-world object.

Inventories can be generically designed using inventory script containers,
and can be modified using the inventory command.

These use the object notation "in@".
The identity format for inventories is a the classification type of inventory to use. All other data is specified through properties.

Valid inventory type classifications:
"npc", "player", "crafting", "enderchest", "workbench", "entity", "location", "generic"

GroupObject System

NameItemTag Objects
DescriptionAn ItemTag represents a holdable item generically.

ItemTags are temporary objects, to actually modify an item in an inventory you must add the item into that inventory.

ItemTags do NOT remember where they came from. If you read an item from an inventory, changing it
does not change the original item in the original inventory. You must set it back in.

These use the object notation "i@".
The identity format for items is the basic material type name, or an item script name. Other data is specified in properties.
For example, 'i@stick'.

Find a list of valid materials at:
Note that some materials on that list are exclusively for use with blocks, and cannot be held as items.

GroupObject System

NameLocationTag Objects
DescriptionA LocationTag represents a point in the world.

These use the object notation "l@".
Note that 'l' is a lowercase 'L', the first letter in 'location'.
The identity format for locations is <x>,<y>,<z>,<pitch>,<yaw>,<world>
Note that you can leave off the world, and/or pitch and yaw, and/or the z value.
You cannot leave off both the z and the pitch+yaw at the same time.
For example, 'l@1,2.15,3,45,90,space' or 'l@7.5,99,3.2'

GroupObject System

NameMaterialTag Objects
DescriptionA MaterialTag represents a material (a type of block or item).

These use the object notation "m@".
The identity format for materials is the material type name.
For example, 'm@stick'.

Block materials may sometimes also contain property data,
for specific values on the block material such as the growth stage of a plant or the orientation of a stair block.

Material types: url/https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Material.html.

GroupObject System

NameNPCTag Objects
DescriptionAn NPCTag represents an NPC configured through Citizens.

These use the object notation "n@".
The identity format for NPCs is the NPC's id number.
For example, 'n@5'.

GroupObject System

NamePlayerTag Objects
DescriptionA PlayerTag represents a player in the game.

These use the object notation "p@".
The identity format for players is the UUID of the relevant player.

GroupObject System

NamePluginTag Objects
DescriptionA PluginTag represents a Bukkit plugin on the server.

These use the object notation "pl@".
The identity format for plugins is the plugin's registered name.
For example, 'pl@Denizen'.

GroupObject System

NameTradeTag Objects
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.

Trades are represented by TradeTags.

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 command opens a virtual merchant inventory with two merchant trades.
The first trade offers a sponge for two emeralds, 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.
opentrades trade[max_uses=10;inputs=emerald[quantity=2];result=sponge]|trade[result=barrier]

These use the object notation "trade@".
The identity format for trades is just the text 'trade'. All other data is specified through properties.

GroupObject System

NameWorldTag Objects
DescriptionA WorldTag represents a world on the server.

These use the object notation "w@".
The identity format for worlds is the name of the world it should be
associated with. For example, to reference the world named 'world1', use simply 'world1'.
World names are case insensitive.

GroupObject System

DescriptionObjectTags 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 ObjectTags notation
system helps both you and Denizen know what type of objects are being referenced and worked with.

So when should you use ObjectTags? 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!

ObjectTag is a broader term for a 'type' of object that more specifically represents something,
such as a LocationTag or ScriptTag, 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 referenced with their 'ObjectTag 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@.
This notation is automatically generated when directly displaying objects, or saving them into data files.
It should never be manually typed into a script.

Let's take the tag system, for example. It uses the ObjectTags system pretty heavily. For instance,
every time you use <player.name> or <npc.id>, you're using a ObjectTag, which brings us to a simple
clarification: Why <player.name> and not <PlayerTag.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'.
<PlayerTag.name> is instead the format for documentation, with "PlayerTag" simply indicating 'any player object here'.

ObjectTags can be used to CREATE new instances of objects, too! Though not all types allow 'new'
objects to be created, many do, such as ItemTags. 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 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 ObjectTags, so be sure to check out each object type for more
specific information. While all ObjectTags share some features, many contain goodies on top of that!

GroupObject System

NameDiscordBotTag Objects
DescriptionA DiscordBotTag is an object that represents a Discord bot powered by dDiscordBot.

These use the object notation "discord@".
The identity format for Discord bots is the bot ID (as chosen in command/discord).
For example: mybot

NoteThis language requires the plugin(s) dDiscordBot!
GroupObject System

NameDiscordChannelTag Objects
DescriptionA DiscordChannelTag is an object that represents a channel (text or voice) on Discord, either as a generic reference,
or as a bot-specific reference (the relevant guild is inherently linked, and does not need to be specified).

These use the object notation "discordchannel@".
The identity format for Discord channels is the bot ID (optional), followed by the channel ID (required).
For example: 1234
Or: mybot,1234

NoteThis language requires the plugin(s) dDiscordBot!
GroupObject System

NameDiscordEmbedTag Objects
DescriptionA DiscordEmbedTag is an object that represents a Discord embed for use with dDiscordBot.

These use the object notation "discordembed@".
The identity format for Discord embeds is a map of embed data. Do not alter raw embed data, use the with.as tag instead.

NoteThis language requires the plugin(s) dDiscordBot!
GroupObject System

NameDiscordGroupTag Objects
DescriptionA DiscordGroupTag is an object that represents a group on Discord, either as a generic reference,
or as a bot-specific reference.

Note that the correct name for what we call here a 'group' is inconsistent between different people.
The Discord API calls it a "guild" (for historical reasons, not called that by *people* anymore usually),
messages in the Discord app call it a "server" (which is a convenient name but is factually inaccurate, as they are not servers),
many people will simply say "a Discord" (which is awkward for branding and also would be confusing if used in documentation).
So we're going with "group" (which is still confusing because "group" sometimes refers to DM groups, but... it's good enough).

These use the object notation "discordgroup@".
The identity format for Discord groups is the bot ID (optional), followed by the guild ID (required).
For example: 1234
Or: mybot,1234

NoteThis language requires the plugin(s) dDiscordBot!
GroupObject System

NameDiscordRoleTag Objects
DescriptionA DiscordRoleTag is an object that represents a role on Discord, either as a generic reference,
or as a guild-specific reference, or as a bot+guild-specific reference.

These use the object notation "discordrole@".
The identity format for Discord roles  is the bot ID (optional), followed by the guild ID (optional), followed by the role ID (required).
For example: 4321
Or: 1234,4321
Or: mybot,1234,4321

NoteThis language requires the plugin(s) dDiscordBot!
GroupObject System

NameDiscordUserTag Objects
DescriptionA DiscordUserTag is an object that represents a user (human or bot) on Discord, either as a generic reference,
or as a bot-specific reference.

These use the object notation "discorduser@".
The identity format for Discord users is the bot ID (optional), followed by the user ID (required).
For example: 1234
Or: mybot,1234

NoteThis language requires the plugin(s) dDiscordBot!
GroupObject System

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.

GroupDenizen Scripting Language

DescriptionThe overall 'scripting language' that Denizen implements is referred to as 'dScripting', or 'dScript'.
dScripts use the Denizen script syntax and the Denizen Scripting API to parse scripts that are stored as .dsc files.
Scripts go in the 'plugins/Denizen/scripts' folder.

GroupDenizen Scripting Language

NameScript Syntax
DescriptionThe syntax of Denizen is broken into multiple abstraction layers.

At the highest level, Denizen scripts are stored in script files, which use the '.dsc' suffix

Denizen script syntax is approximately based on YAML configuration files,
and is intended to seem generally as easy to edit as a YAML configuration.
However, several key differences exist between the Denizen script syntax and YAML syntax.
In particular, there are several changes made to support looser syntax rules
and avoid some of the issues that would result from writing code directly into a plain YAML file.

Within those 'script files' are 'script containers', which are the actual unit of separating individual 'scripts' apart.
(Whereas putting containers across different files results in no actual difference:
file and folder separation is purely for your own organization, and doesn't matter to the Denizen parser).
Each script container has a 'type' such as 'task' or 'world' that defines how it functions.

Within a script container are individual script paths, such as 'script:' in a 'task' script container,
or 'on player breaks block:' which might be found within the 'events:' section of a 'world' script container.
These paths are the points that might actually be executed at any given time.
When a path is executed, a 'script queue' is formed to process the contents of that script path.

Within any script path is a list of 'script entries', which are the commands to be executed.
These can be raw commands themselves (like 'narrate') with their arguments,
or commands that contain additional commands within their entry (as 'if' and 'foreach' for example both do).

GroupDenizen Scripting Language

NameThe Save Argument
DescriptionThe "save:<name>" argument is a special meta-argument that is available for all commands, but is only useful for some.
It is written like:
- run MyScript save:mysave

When the save argument is used, the results of the command will be saved on the queue, for later usage by the "entry" tag.

The useful entry keys available for any command are listed in the "Tags" documentation section for any command.
For example, the "run" command lists "<entry[saveName].created_queue>".
The "saveName" part should be replaced with whatever name you gave to the "save" argument,
and the "created_queue" part changes between commands.
Some commands have multiple save entry keys, some have just one, most don't have any.

GroupScript Command 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)
An argument that contains a ":" (like "duration:<value>") is a prefix:value pair. The prefix is usually literal and the value dynamic. The prefix and the colon should be kept directly in the final command.

A few examples:
[<location>] is required and non-literal... you might fill it with a notable location, or a tag that returns one like '<player.location>'.
(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 "<[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 command that is "~Waitable" (or "Holdable", or that can be "~waited for") is a command that:
- Might potentially take a while to execute
- Is able to perform a slowed execution (that doesn't freeze the server)
- And so supports the "~" prefix.

This is written, for example, like: - ~run MySlowScript

When a command is ~waited for, the queue it's in will wait for it to complete, but the rest of the server will continue running.
This is of course similar to the "wait" command, but waits for the action to complete instead of simply for a period of time.

Some commands, particularly those related to file operation, when ~waited for will move the file operation off-thread.
Others may need to be on the server thread, and may split the operation into smaller segments spread out over 1 tick each or similar logic.
Some of these commands, when NOT waited for, will freeze the server thread until the operation completes.
Others, however, may still perform the action in a delayed/slow/off-thread manner, but simply not hold the queue.

GroupScript Command System

NameThe Player and NPC Arguments
DescriptionThe "player:<player>" and "npc:<npc>" arguments are special meta-arguments that are available for all commands, but are only useful for some.
They are written like:
- give stick player:<server.flag[some_player]>
- assign set script:MyScript npc:<entry[save].created_npc>

Denizen tracks a "linked player" and a "linked NPC" in queues and the commands within.
Many commands automatically operate on the linked player/NPC or by default or exclusively
(for example, "give" defaults to giving items to the linked player but that can be changed with the "to" argument,
"assign" exclusively changes the assignment of the linked NPC, and that cannot be changed except by the global NPC argument).

When the player argument is used, it sets the linked player for the specific command it's on.
This is only useful for commands that default to operating on the linked player.
This can also be useful with the "run" command to link a specific player to the new queue.

The NPC argument is essentially equivalent to the player argument, but for the linked NPC instead of the linked player.

These arguments will also affect tags (mainly "<player>" and "<npc>") in the same command line (regardless of argument order).
If you need to use the original player/NPC in a tag on the same line, use the define command to track it.

GroupScript Command System

DescriptionA Comparable is a method that the If command, While command, and 'element.is[...].to[...]' tag uses to compare objects.

These are usually written in the format "VALUE OPERATOR VALUE".

For example, if you use ">=" as the operator, and "3" and "5" as the values, you'd write "3 >= 5",
which would return false (as 3 is NOT greater-than-or-equal-to 5).

For a list of valid operators and their usages, 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:
"Equals" is written as "=="
"Does not equal" is written as "!="
"Is more than" is written as ">" or "MORE".
"Is less than" is written as "<" or "LESS".
"Is more than or equal to" is written as ">=" or "OR_MORE".
"Is less than or equal to" is written as "<=" or "OR_LESS".

Note: When using an operator in a replaceable tag (such as <ElementTag.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.

There are also special boolean operators (&&, ||, ...) documented at: command/if


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,
(ScriptTag_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 name:
  type: script_type  <--- script type
    - script entries
    - ...

GroupScript Container System

NameCustom Script Containers
DescriptionCustom script containers are used to define a template type for a custom object.

Custom script containers have no required keys but several optional ones.
Use 'tags' key to define scripted tags,
'mechanisms' to define scripted mechanisms,
'inherit' to define what other custom script to inherit from,
and any other key name to define a default object field.

  type: custom
  # Use 'inherit' to make this custom script container inherit from another custom object.
  inherit: some_object
  # This adds default field 'some_field' with initial value of 'some_value'.
  some_field: some_value
  # List additional fields here...
  # Use 'tags' to define scripted tags on the object.
  # Tags are subject to the same rules as procedure scripts:
  # NEVER change any external state. Just determine a value. Nothing else should change from the script.
    # This would be read like <[my_object].my_tag>
    # Perform any logic here, and 'determine' the result.
    - determine 3
    # list additional tags here...
  # Use 'mechanisms' to define scripted mechanisms on the object.
  # Note that these should only ever determine a new object,
  # with NO CHANGES AT ALL outside the replacement determined object.
  # (Same rules as tags and procedure scripts).
    # This would be used like custom@Custom_Script_Name[my_mech=3]
    - adjust <context.this> true_value:<context.value.mul[2]> save:new_val
    - determine <entry[new_val].result>
    # list additional mechanisms here...

GroupScript Container System

NameData Script Containers
DescriptionData script containers are generic script containers for information that will be referenced by other scripts.

No part of a 'data' script container is ever run as commands.

There are no required keys.

Generally, data is read using the tag/ScriptTag.data_key tag.

  type: data
  # Your data here
  some key: some value
  some list key:
  - some list value
  some map key:
    some subkey: some value

GroupScript Container System

NameProcedure Script Containers
DescriptionProcedure script containers are used to define a script that can be ran through a tag.

Generally called via tag/proc or tag/proc.context.

The only required key is 'script:'.

Note that procedure scripts must NEVER change external state.
That is, a procedure script cannot change anything at all, ONLY determine a value.
Setting a flag, loading a YAML document, placing a block, etc. are all examples of external changes that are NOT allowed.

This restriction comes from two main reasons:
- Tags run in arbitrary conditions. They may be read asynchronously or in other weird circumstances that can result
in applied changes crashing your server or other unexpected side effects.
- Tags can run for a variety of reasons.
If you were to make a proc script 'spawn_entity' that actually spawns an entity into the world,
you would likely end up with a *lot* of unintentional entity spawns.
Some tags will be read multiple times when theoretically ran once,
in some circumstances a tag read might even be based on user input! (Particularly if you ever make use of the '.parsed' tag,
or the list.parse/filter/sort_by_number tags).
Imagine if for example, a tag can be read when users input a specific custom command,
and a clever user finds out they can type "/testcommand 32 <proc[spawn_entity].context[creeper]>"
to spawn a creeper ... that would be a major problem!
In general, maximum caution is the best for situations like this... simply *never* make a procedure
that executes external changes.

  type: procedure
  # Optionally specify definition names to use with the 'context' input of the proc tag.
  definitions: def|names|here
  # Put any logic, then determine the result.
  - determine 5

GroupScript Container System

NameTask Script Containers
DescriptionTask script containers are generic script containers for commands that can be run at
any time by command.

Generally tasks will be ran by command/run or command/inject.

The only required key on a task script container is the 'script:' key.

  type: task
  # When intending to run a task script via the run command with the "def:" argument to pass data through,
  # use this "definitions" key to specify the names of the definitions (in the same order as the "def:" argument will use).
  definitions: name1|name2|...
  - your commands here

GroupScript Container System

NameWorld Script Containers
DescriptionWorld script containers are generic script containers for commands that are automatically
ran when some given event happens in the server.

The only required key is 'events:', within which you can list any events to handle.

  type: world
    # Any event label can be placed here
    # This includes generic labels like 'on entity death:',
    # Specified labels  like 'on player death:',
    # And detailed labels like 'on player death ignorecancelled:true priority:5:'
    some event label:
    # Write any logic that should fire when the event runs.
    # Optionally 'determine' any results to the event.
    - some commands
    # List additional events here

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' 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.
See also language/interact script containers

Basic structure of an assignment script:
  type: assignment
  # | All assignment scripts MUST have this key!
    on <action>:
    - ...
  # | Most assignment scripts should exclude this key, but it's available.
  default constants:
    - ...
  # | MOST assignment scripts should have this key!
  interact scripts:
  - <interact_script_name>

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

Though note that almost always you should include the 'actions:' key, usually with the 'on assignment:' action (if using triggers).
Refer to action/assignment.

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 ItemTag object, and can be fetched
with the Object Fetcher by using the ItemTag constructor book_script_name
Example: - give <player> my_book

  type: book
  # The 'custom name' can be anything you wish.
  # | All book scripts MUST have this key!
  title: custom name
  # The 'custom name' can be anything you wish.
  # | All book scripts MUST have this key!
  author: custom name
  # Defaults to true. Set to false to spawn a 'book and quill' instead of a 'written book'.
  # | Some book scripts might have this key!
  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>.
  # | All book scripts MUST have this key!
  - page
  - ...

GroupScript Container System

NameCommand Script Containers
DescriptionCommand script containers allow you to register your own custom commands to the server.
This also 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 event/on command.

The following is the format for the container.

The required keys are 'name:', 'description:', 'usage:', and 'script:'
All other keys can be excluded if unneeded.
If you are not intentionally setting a specific value for the other keys, it is
strongly recommended that you simply not include them at all.

Please note that 'name:' is the true name of the command (written by users),
and 'usage:' is for documentation in the '/help' command.
These two options should almost always show the same name.

# The name of the script doesn't matter, and will not affect the command in any way.
  type: command
  # The name of the command. This will be the default method for running the command, and will show in '/help'.
  # | All command scripts MUST have this key!
  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.
  # | All command scripts MUST have this key!
  description: My command.
  # Correct usage for the command. This will show in the '/help' command.
  # This is NOT the name of the command, and it is NOT used to control input parsing. It is EXCLUSIVELY for '/help'.
  # | All command scripts MUST have this key!
  usage: /mycmd <&lt>myArg1<&gt>
  # A list of aliases for the command. These will be used as alternative ways to trigger the command, and will show in the '/help' command.
  # | Some command scripts might have this key, but it's optional.
  - 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.
  # Note that you can include multiple permission nodes (a player only needs to have any one permission from the list)
  # by separating them with a semicolon, like: perm.one;perm.two;third.perm
  # | Most command scripts should have this key!
  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.
  # | Most command scripts should NOT have this key, but it's available.
  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).
  # | Most command scripts should NOT have this key, but it's available.
  allowed help:
  - determine <player.has_flag[special_allowed_help_flag]||<context.server>>
  # You can optionally specify tab completions on a per-argument basis.
  # 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.
  # | This key is great to have when used well, but is not required.
  tab completions:
    # This will complete "alpha" and "beta" for the first argument
    1: alpha|beta
    # This will complete any online player name for the second argument
    # This will allow flags "-a", "-b", or "-c" to be entered in the third, fourth, or fifth argument.
    3 4 5: -a|-b|-c
    # Any argument other than the ones explicitly listed will be handled here with a tab complete that just says 'StopTyping'.
    default: StopTyping
  # You can also optionally use the 'tab complete' key to build custom procedure-style tab complete logic
  # if the simply numeric argument basis isn't sufficient.
  # Has the same context available as 'tab completions'.
  # | Most scripts should leave this key off, though it can be useful to some.
  tab complete:
  - determine some|dynamic|logic|here
  # 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.source_type> returns the source of the command. Can be: PLAYER, SERVER, COMMAND_BLOCK, or COMMAND_MINECART.
  # <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 EntityTag of the command minecart (if the command was run from one).
  # | All command scripts MUST have this key!
  - if !<player.is_op||<context.server>>:
    - narrate "<red>You do not have permission for that command."
    - stop
  - narrate Yay!
  - narrate "My command worked!"
  - narrate "And I typed '/<context.alias> <context.raw_args>'!"

GroupScript Container System

NameEconomy Script Containers
DescriptionEconomy script containers

Economy script containers provide a Vault economy, which can be used in scripts by
tag/PlayerTag.money and command/money
and as well by any other plugin that relies on economy functionality (such as shop plugins).

Note that vault economy bank systems are not currently supported.
Per-world economies are also not currently supported.

Note that in most cases, you do not want to have multiple economy providers, as only one will actually be in use.


# The script name will be shown to the economy provider as the name of the economy system.
  type: economy
  # The Bukkit service priority. Priorities are Lowest, Low, Normal, High, Highest.
  priority: normal
  # The name of the currency in the singular (such as "dollar" or "euro").
  name single: scripto
  # The name of the currency in the plural (such as "dollars" or "euros").
  name plural: scriptos
  # How many digits after the decimal to include. For example, '2' means '1.05' is a valid amount, but '1.005' will be rounded.
  digits: 2
  # Format the standard output for the money in human-readable format. Use "<amount>" for the actual amount to display.
  # Fully supports tags.
  format: $<amount>
  # A tag that returns the balance of a linked player. Use a 'proc[]' tag if you need more complex logic.
  # Must return a decimal number.
  # A tag that returns a boolean indicating whether the linked player has the amount specified by auto-tag "<amount>".
  # Use a 'proc[]' tag if you need more complex logic.
  # Must return 'true' or 'false'.
  # A script that removes the amount of money needed from a player.
  # Note that it's generally up to the systems calling this script to verify that the amount can be safely withdrawn, not this script itself.
  # However you may wish to verify that the player has the amount required within this script.
  # The script may determine a failure message if the withdraw was refused. Determine nothing for no error.
  # Use def 'amount' for the amount to withdraw.
  - flag <player> money:-:<[amount]>
  # A script that adds the amount of money needed to a player.
  # The script may determine a failure message if the deposit was refused. Determine nothing for no error.
  # Use def 'amount' for the amount to deposit.
  - flag <player> money:+:<[amount]>

NoteThis language requires the plugin(s) Vault!
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 EntityTag object, and can be fetched with the Object Fetcher by using the
EntityTag constructor of simply the script name. Example: - spawn <player.location> MyEntity

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

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

# The name of the entity script is the same name that you can use to construct a new
# EntityTag based on this entity script. For example, an entity script named 'space_zombie'
# can be referred to as 'space_zombie'.
  type: entity
  # Must be a valid EntityTag (EG 'zombie' or 'pig[age=baby]') See 'EntityTag' for more information.
  # | All entity scripts MUST have this key!
  entity_type: BASE_ENTITY_TYPE_HERE
  # Samples of mechanisms to use (any valid EntityTag mechanisms may be listed like this):
  # Whether the entity has the default AI
  # | Do not copy this line, it is only an example.
  has_ai: true/false
  # What age the entity is
  # | Do not copy this line, it is only an example.
  age: baby/adult/<#>

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

GroupScript Container System

NameFormat Script Containers
DescriptionFormat script containers are very simple script containers used for formatting messages, usually with the 'narrate' command.

  type: format
  # The only key is the format. The format can use '<text>' as a special tag to contain the message being sent.
  # '<name>' is available as a special tag as well for use with the 'on player chats' event to fill the player's name properly.
  # | All format scripts MUST have this key!
  format<name> says <text>

GroupScript Container System

NameInteract Script Containers
DescriptionInteract script containers are used to handle NPC triggers.

Interact scripts must be referenced from an assignment script container to be of any use.
See language/assignment script containers.

The only required key on a task script container is the 'steps:' key.

Within the steps key is a list of steps,
where the first step is '1', 'default', or any step that contains a '*' symbol.
After that, any steps must be 'zapped' to via the zap command: command/zap.

Each step contains a list of trigger types that it handles, and the relevant handling that the given
trigger makes available.

Refer to language/interact script triggers for documentation about the triggers available.
Any triggers used must be enabled in action/assignment by command/trigger.

Note that script commands ran in interact scripts by default have a delay between each command.
To override this delay, set 'speed: 0' on the container or change the relevant config setting.

  type: interact
  # | All interact scripts MUST have this key!
    # The first step
      # Any trigger type here
      click trigger:
        # Handle what happens when the NPC is clicked during step 1
        - some commands
      # Other triggers here
    # other steps here

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 InventoryTag object, and can be fetched with the Object Fetcher by using the
InventoryTag constructor InventoryTag_script_name.

Example: - inventory open d:MyInventoryScript

The following is the format for the container.

The 'inventory:' key is required, other keys vary based on the type.
Some types will require you define either 'size:' or 'slots:' (or both).
'Procedural items:' and 'definitions:' are optional, and should only be defined if needed.

# The name of the script is the same name that you can use to construct a new
# InventoryTag based on this inventory script. For example, an inventory script named 'Super_Cool_Inventory'
# can be referred to as 'Super_Cool_Inventory'.
  type: inventory
  # Must be a valid inventory type.
  # | All inventory scripts MUST have this key!
  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.
  # | MOST inventory scripts should have this key!
  title: custom title
  # The size must be a multiple of 9. It is recommended to not go above 54, as it will not show correctly when a player looks into it.
  # | Some inventory scripts should have this key! Most can exclude it if 'slots' is used.
  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 to be in a definition tag.
  # | Some inventory scripts MAY have this key, but it is optional. Most scripts will just specify items directly.
    my item: ItemTag
    other item: ItemTag
  # Procedural items can be used to specify a list of ItemTags 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.
  # | Most inventory scripts should exclude this key, but it may be useful in some cases.
  procedural items:
    - define list <list[]>
    - foreach <server.online_players>:
      - define item player_head[skull_skin=<[value].name>]
      - define list <[list].include[<[item]>]>
    - determine <[list]>
  # You can specify the items in the slots of the inventory. For empty spaces, simply put an empty "slot" value, like "[]".
  # Note the quotes around the entire lines.
  # | Most inventory scripts SHOULD have this key!
    - [] [] [] [my item] [ItemTag] [] [other item] [] []
    - [my item] [] [] [] [] [ItemTag] [ItemTag] [] []
    - [] [] [] [] [] [] [] [] [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 ItemTag object, and can be fetched with the Object Fetcher by using the
ItemTag constructor ItemTag_script_name. Example: - drop <player.location> 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
# ItemTag based on this item script. For example, an item script named 'sword_of_swiftness'
# can be referred to as simply 'sword_of_swiftness'.
  type: item
  # Must be a valid ItemTag. See 'ItemTag' for more information.
  # | All item scripts MUST have this key!
  material: base_material
  # List any mechanisms you want to apply to the item within
  # | Some item scripts should have this key!
    # An example of a mechanism to apply
    unbreakable: true
  # The 'custom name' can be anything you wish. Use color tags to make colored custom names.
  # | Some item scripts should have this key!
  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.
  # | Some item scripts should have this key!
  - item
  - ...
  # If you want an item to be damaged on creation, you can change its durability.
  # | Most item scripts should exclude this key!
  durability: 12
  # Each line must specify a valid Minecranft enchantment name.
  # | Some item scripts should have this key!
  - enchantment_name:level
  - ...
  # You can optionally add crafting recipes for your item script.
  # Note that recipes won't show in the recipe book when you add a new item script, until you either reconnect or use the "resend_recipes" mechanism.
  # | Most item scripts should exclude this key, unless you're specifically building craftable items.
          # The type can be: shaped, shapeless, stonecutting, furnace, blast, smoker, or campfire.
          type: shaped
          # The recipe can optionally have a custom internal recipe ID (for recipe books).
          # If not specified, will be of the form "<type>_<script.name>_<id>" where ID is the recipe list index (starting at 1, counting up).
          # IDs will always have the namespace "denizen". So, for the below, the full ID is "denizen:my_custom_item_id"
          # Note that most users should not set a custom ID. If you choose to set a custom one, be careful to avoid duplicates or invalid text.
          # Note that the internal rules for Recipe IDs are very strict (limited to "a-z", "0-9", "/", ".", "_", or "-").
          recipe_id: my_custom_item_id
          # You can optional add a group as well. If unspecified, the item will have no group.
          # Groups are used to merge together similar recipes (in particular, multiple recipes for one item).
          group: my_custom_group
          # You can optionally specify the quantity to output. The default is 1 (or whatever the item script's quantity is).
          output_quantity: 4
          # You must specify the input for the recipe. The below is a sample of a 3x3 shaped recipe. Other recipe types have a different format.
          # You are allowed to have non-3x3 shapes (can be any value 1-3 x 1-3, so for example 1x3, 2x1, and 2x2 are fine).
          # For an empty slot, use "air".
          # By default, items require an exact match. For a material-based match, use the format "material:MaterialNameHere" like "material:stick".
          # To make multiple different items match for any slot, just separate them with slashes, like "stick/stone". To match multiple materials, use "material:a/b/c".
          - ItemTag|ItemTag|ItemTag
          - ItemTag|ItemTag|ItemTag
          - ItemTag|ItemTag|ItemTag
     # You can add as many as you want.
          # Sample of the format for a 2x2 recipe
          type: shaped
          - ItemTag|ItemTag
          - ItemTag|ItemTag
         # Shapeless recipes take a list of input items.
         type: shapeless
         input: ItemTag|...
         # Stonecutting recipes take exactly one input item.
         type: stonecutting
         input: ItemTag
         # Furnace, blast, smoker, and campfire recipes take one input and have additional options.
         type: furnace
         # Optionally specify the cook time as a duration (default 2s).
         cook_time: 1s
         # Optionally specify experience reward amount (default 0).
         experience: 5
         input: ItemTag
  # Set to true to not store the scriptID on the item, treating it as an item dropped by any other plugin.
  # | Most item scripts should exclude this key!
  no_id: true/false
  # For colorable items, such as leather armor, you can specify a valid ColorTag to specify the item's appearance.
  # See 'ColorTag' for more information.
  # | Most item scripts should exclude this key!
  color: ColorTag
  # 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.
  # | Most item scripts should exclude this key, though there are certain rare cases it may be useful to.
  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.
  type: map
  # Whether to display the original map below the custom values. Defaults to true.
  # | Some map scripts should have this key!
  original: true/false
  # The 'custom name' can be anything you wish. Use color tags to make colored custom names.
  # | Some map scripts should have this key!
  display name: custom name
  # Whether to constantly update things.
  # | Some map scripts should have this key!
  auto update: true
  # Lists all contained objects.
  # | Most map scripts should have this key!
    # 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 type
      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

A list of cursor types is available through tag/server.map_cursor_types.

GroupScript Container System

NameTag Fallbacks
DescriptionTag fallbacks (AKA "tag alternatives") are a system designed to allow scripters to automatically handle tag errors.

A tag without a fallback might look like "<player.name>".
This tag works fine as long as there's a linked player, but what if a player isn't always available?
Normally, this situation would display an error in the console debug logs, and return plaintext "player.name" in the script.
A fallback can help us handle the problem more gracefully.
That same tag with a fallback would look like "<player.name||Steve>".
Now, when there isn't a player available, there will not be an error, and the tag will simply return "Steve".

This format is the same for basically all tags. "<main.tag.here||Fallback here>".
For another example, "<player.flag[myflag]||0>" returns either the value of the flag, or "0" if the flag is not present (or if there's no player).

This is particularly useful for things like checking whether an object exists / is valid.
What if we want to check if there even is a linked player? We don't have a "<has_player>" tag to do that, so what can we do?
if <player||null> == null:
The above example demonstrates using a fallback to check if a player is valid.
The if block will run only if there is not a player valid (you might, for example, place the "stop" command inside).

We use the word "null" in the above example. This is a common programming term that means "no object is present".
In this case, that term isn't actually a functionality of Denizen, it's just a word we choose for clarity.
You could just as easily do "- if <player||nothing> == nothing:", or for that matter "- if <player||cheese> == cheese:".
A player object takes the form "p@uuid", so it will therefore never exactly match any simple word, so there's no coincidental match edge-case to worry about.
Note that this won't work so perfect for things like a user input or fully dynamic value,
so in those cases you may want to use a more specialized check. For example, with flags, the "has_flag" tag is available for this purpose.

Fallbacks can be tags themselves. So, for example, if we want either a custom flag-based display name, or if not available, the player's base name,
we can do: "<player.flag[display_name]||<player.name>>".
You can as well chain these, though that starts to get ugly pretty fast: "<player.flag[good_name]||<player.flag[bad_name]||<player.name>>>".

Note that fallbacks will *hide errors*. Generally, the only errors you should ever hide are ones you're expecting that are fine.
Don't use a fallback on a "<player.name>" tag, for example, if there should always be a player present when the script runs.
That tag should only ever have a fallback when the script is meant to still work without a player attached.
If you carelessly apply fallbacks to all tags, you might end up not realizing there's a problem in your script until it's affecting real players.
You want to solve errors in testing, not ten months later when a player mentions to you "that shop NPC let me buy things even when I had $0"!

GroupTag 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 sign @ = &at
. = &dot
\ = &bs
' = &sq
" = &quo
! = &exc
/ = &fs
ยง = &ss
# = &ns

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

Note that these are NOT tag names. They are exclusively used by the escaping system.

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: stick[display_name=&ltFancy&spStick&gt]

You can use these escape codes in a tag via tag/ElementTag.escaped and tag/ElementTag.unescaped.

GroupUseful Lists

NameData Actions
DescriptionSeveral commands function as a way to modify data values,
including command/flag, command/yaml, and command/define.
These commands each allow for a set of generic data change operations.

These operations can be used with a syntax like "<key>:<action>:<value>"
For example "mykey:+:5" will add 5 to the value at 'mykey'.

The following actions are available:

Actions that take no input value:
Increment: '++': raises the value numerically up by 1. Example: - define x:++
Decrement: '--': lowers the value numerically down by 1. Example: - define x:--
Clear: '!': removes the value entirely. Example: - define x:!

Actions that take an input value:
Add: '+': adds the input value to the value at the key. Example: - define x:+:5
Subtract: '-': subtracts the input value from the value at the key. Example: - define x:-:5
Multiply: '*': multiplies the value at the key by the input value. Example: - define x:*:5
Divide: '/': divides the value at the key by the input value. Example: - define x:/:5
List insert: '->': adds the input value as a single new entry in the list (see also 'List split'). Example: - define x:->:new_value
List remove: '<-': removes the input value from the list. Example: - define x:<-:old_value
List split: '|': splits the input list and adds each value into an existing list at the key. Example: - define x:|:a|b|c
Split to new: '!|': similar to list split, but removes any existing value at the key first. Example: - define x:!|:a|b|c

Special cases:
In some commands, specifying no action or input value will automatically set the key's value to 'true'.
Setting a '<key>:<value>' without an action will set the key to the exact value. Be careful to not input a list like this, use 'split to new' instead.

Note that the <key> input may take an index input as well.
That is, for example: "mykey[3]:--" will decrement the third item in the list at 'mykey'.
This syntax may also be used to remove the entry at a specified index.

GroupUseful Lists

NameDamage Cause
DescriptionPossible damage causes: url/https://hub.spigotmc.org/javadocs/spigot/org/bukkit/event/entity/EntityDamageEvent.DamageCause.html
These are used in event/entity damage, tag/server.damage_causes, tag/EntityTag.last_damage.cause, ...

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

NameRaw NBT Encoding
DescriptionThe item Raw_NBT property encodes and decodes raw NBT data.
For the sake of inter-compatibility, a special standard format is used to preserve data types.

NBT Tags are encoded as follows:
CompoundTag: (a fully formed MapTag)
ListTag: list:(NBT type-code):(a fully formed ListTag)
ByteArrayTag: byte_array:(a pipe-separated list of numbers)
IntArrayTag: int_array:(a pipe-separated list of numbers)
ByteTag: byte:(#)
ShortTag: short:(#)
IntTag: int:(#)
LongTag: long:(#)
FloatTag: float:(#)
DoubleTag: double:(#)
StringTag: string:(text here)
EndTag: end

GroupUseful Lists

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

- Everything on url/https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Particle.html
- Everything on url/https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Effect.html
- RANDOM (chooses a random visual effect from the Particle list)

GroupUseful Lists

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.

GroupUseful Lists

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.

GroupUseful Lists

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

NameEntity Color Types
DescriptionThis is a quick rundown of the styling information used to handle the coloration of a mob,
in both tag/EntityTag.color and mechanism/EntityTag.color.

For horses, the format is COLOR|STYLE,
For ocelots, the types are BLACK_CAT, RED_CAT, SIAMESE_CAT, or WILD_OCELOT. (NOTE: Deprecated since 1.14 - now 'cat' entity type is separate)
For cats, the format is TYPE|COLOR (see below).
For parrots, the types are BLUE, CYAN, GRAY, GREEN, or RED.
For llamas, the types are CREAMY, WHITE, BROWN, and GRAY.
For mushroom_cows, the types are RED and BROWN.
For foxes, the types are RED and SNOW.
For pandas, the format is MAIN_GENE|HIDDEN_GENE.
         The gene types are NORMAL, LAZY, WORRIED, PLAYFUL, BROWN, WEAK, and AGGRESSIVE.
For villagers, the types are DESERT, JUNGLE, PLAINS, SAVANNA, SNOW, SWAMP, and TAIGA.
For tropical_fish, the input is PATTERN|BODYCOLOR|PATTERNCOLOR, where BodyColor and PatterenColor are both DyeColor (see below),
For sheep, wolf, and shulker entities, the input is a Dye Color.
For Tipped Arrow entities, the input is a ColorTag.

For all places where a DyeColor is needed, the options are:


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 'buttons'.

In Denizen, all noted inventories (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.

Noting is not the only way to create virtual inventories, however.
Using '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,
where 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:generic[size=18;title=<red>My <green>Awesome <blue>Inventory;contents=air|snow_ball]"

GroupInventory System

NameInteract Script Triggers
DescriptionInteract script triggers are the most basic components of standard NPC scripting.
They're very useful for NPCs that give quests or have other very basic interactions with players.
While less powerful that other tools that Denizen provides, they can be very straightforward and clear to use in many simpler cases.

Note that triggers have a default cooldown system built in to prevent users from clicking too rapidly.
However these are very short cooldowns by default - when you need a longer cooldown, use
command/cooldown or command/engage.

Triggers go in language/interact script containers.

The available default trigger types are language/click triggers,
language/damage triggers, language/chat triggers, and language/proximity triggers.

GroupNPC Interact Scripts

NameChat Triggers
DescriptionChat Triggers are triggered when when a player chats to the NPC (usually while standing close to the NPC and facing the NPC).

Interact scripts are allowed to define a list of possible messages a player may type and the scripts triggered in response.

Within any given step, the format is then as follows:
# Some identifier for the trigger, this only serves to make the sub-triggers unique, and sort them (alphabetically).
  # The trigger message written by a player. The text between // must be typed by a player, the other text is filled automatically.
  trigger: /keyword/ othertext
  # Your code here
  - wait 1
  # use "<context.message>" for the exact text written by the player.
  - chat "<context.message> eh?"
# You can list as many as you want
  # You can have multi-option triggers, separated by pipes (the "|" symbol). This example matches if player types 'hi', 'hello', OR 'hey'.
  trigger: /hi|hello|hey/
  - wait 1
  # use "<context.keyword>" for the specific word that was said.
  # this example will respond to players that said 'hi' with "hi there buddy!", 'hello' with "hello there buddy!", etc.
  - chat "<context.keyword> there buddy!"
  # You can have regex triggers. This example matches when the player types any numbers.
  - wait 1
  # use "<context.keyword>" for the text matched by the regex matcher.
  - chat "<context.keyword> eh?"
  # Use '*' as the trigger to match anything at all.
  trigger: /*/
  # Add this line to hide the "[Player -> NPC]: hi" initial trigger message.
  hide trigger message: true
  # If you hide the trigger message, you might want to fill that spot with something else.
  - narrate "[Player -> NPC]: I don't know how to type the right thing"
  - wait 1
  - chat "Well type 'keyword' or any number!"

GroupNPC Interact Scripts

NameClick Triggers
DescriptionClick Triggers are triggered when when a player right clicks the NPC.

These are very basic with no extraneous complexity.

GroupNPC Interact Scripts

NameDamage Triggers
DescriptionDamage Triggers are triggered when when a player left clicks the NPC.
Despite the name, these do not actually require the NPC take any damage, only that the player left clicks the NPC.

In scripts, use <context.damage> to measure how much damage was done to the NPC
(though note that invincible NPCs don't necessarily take any damage even when this is non-zero).

These are very basic with no extraneous complexity.

GroupNPC Interact Scripts

NameProximity Triggers
DescriptionProximity Triggers are triggered when when a player moves in the area around the NPC.

Proximity triggers must have a sub-key identifying what type of proximity trigger to use.
The three types are "entry", "exit", and "move".

Entry and exit do exactly as the names imply: Entry fires when the player walks into range of the NPC, and exit fires when the player walks out of range.

Move is a bit more subtle: it fires very rapidly so long as a player remains within range of the NPC.
This is useful for eg script logic that needs to be constantly updating whenever a player is nearby (eg a combat NPC script needs to constantly update its aim).

The radius that the proximity trigger detects at is set by command/trigger.

GroupNPC Interact Scripts

NameDenizen Text Formatting
DescriptionDenizen provides a variety of special chat format options like "on_hover" and "on_click".
These options exist within Denizen and do not appear in the historical Minecraft legacy chat format that most plugins and systems read.
That legacy system has 16 colors (0-9, A-F) and a few toggleable formats (bold, italic, etc). It does not contain anything that needs more than just an on/off.

Modern Minecraft, however, supports a JSON based "raw" message format that can do click events, hover events, full RGB colors, etc.

Denizen therefore has its own internal system that works like the legacy format system, but also supports the new options normally only available as 'raw JSON'.

Because it is entirely processed within Denizen, these options only work within Denizen, when performing actions that support raw JSON input.
This magic tool exists to let you write messages without having to write the messy JSON.

Be aware that many inputs do not support raw JSON, and as such are limited only the historical Minecraft legacy format.
Also be aware that click events, hover evers, etc. are exclusively limited to the chat bar and the pages of books, as you cannot mouse over anything else.

GroupDenizen Magic

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.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 debugger 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 debugger 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 debugger.
Note: While your server is in 'live production mode', the debugger 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
'-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).
'-p' enables/disables packet debug logging. When enabled, all packets sent to players (from anywhere) will be logged to console.
'-f' enables/disables showing of future warnings. When enabled, future warnings (such as upcoming deprecations) will be displayed in console logs.
'-v' enables/disables advanced verbose log output. This will *flood* your console super hard.
'-o' enables/disables 'override' mode. This will display all script debug, even when 'debug: false' is set for scripts.
'-l' enables/disables script loading information. When enabled, '/ex reload' will produce a potentially large amount of debug output.

GroupConsole Commands

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.

By default, ex command debug output is sent to the player that ran the ex command (if the command was ran by a player).
To avoid this, use '-q' at the start of the ex command.
Like: /ex -q narrate "wow no output"

/ex flag <player> test_flag:!
/ex run npc_walk_script

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:<[aplayer]> 'Your health is <player.health.formatted>.'
/ex walk npc:<[some_npc]> <player.cursor_on>

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

NameAreaShopTag Objects
DescriptionAn AreaShopTag represents an AreaShop shop.

These use the object notation "areashop@".
The identity format for shops is <shop_name>
For example, 'areashop@my_shot'.

NoteThis language requires the plugin(s) Depenizen, AreaShop!
GroupDepenizen Object Types

NameFactionTag Objects
DescriptionA FactionTag represents a Factions faction.

These use the object notation "faction@".
The identity format for factions is <faction_name>
For example, 'faction@my_faction'.

NoteThis language requires the plugin(s) Depenizen, Factions!
GroupDepenizen Object Types

NameNationTag Objects
DescriptionA NationTag represents a Factions nation.

These use the object notation "nation@".
The identity format for nations is <nation_name>
For example, 'nation@my_nation'.

NoteThis language requires the plugin(s) Depenizen, Factions!
GroupDepenizen Object Types

NameGriefPreventionClaimTag Objects
DescriptionA GriefPreventionClaimTag represents a GriefPrevention claim.

These use the object notation "gpclaim@".
The identity format for claims is <claim_id>
For example, 'gpclaim@1234'.

NoteThis language requires the plugin(s) Depenizen, GriefPrevention!
GroupDepenizen Object Types

NameJobsJobTag Objects
DescriptionA JobsJobTag represents a Jobs job.

These use the object notation "job@".
The identity format for jobs is <job_name>
For example, 'job@job_name'.

NoteThis language requires the plugin(s) Depenizen, Jobs!
GroupDepenizen Object Types

NameLibsDisguiseTag Objects
DescriptionA LibsDisguiseTag represents a LibsDisguises disguise type.

These use the object notation "libsdisguise@".
The identity format for disguises is <disguise_name>
For example, 'libsdisguise@zombie'.

NoteThis language requires the plugin(s) Depenizen, LibsDisguises!
GroupDepenizen Object Types

NameLuckPermsTrackTag Objects
DescriptionA LuckPermsTrackTag represents a LuckPerms track.

These use the object notation "luckpermstrack@".
The identity format for tracks is <track_name>
For example, 'luckpermstrack@my_track'.

NoteThis language requires the plugin(s) Depenizen, LuckPerms!
GroupDepenizen Object Types

NamePartyTag Objects
DescriptionA PartyTag represents an McMMO party.

These use the object notation "party@".
The identity format for parties is <party_name>
For example, 'party@my_party'.

NoteThis language requires the plugin(s) Depenizen, McMMO!
GroupDepenizen Object Types

NameMobArenaArenaTag Objects
DescriptionA MobArenaArenaTag represents a mob arena in the world.

These use the object notation "mobarena@".
The identity format for arenas is <arena_name>
For example, 'mobarena@my_arena'.

NoteThis language requires the plugin(s) Depenizen, MobArena!
GroupDepenizen Object Types

NameMythicMobsMobTag Objects
DescriptionA MythicMobsMobTag represents a Mythic mob entity in the world.

These use the object notation "mythicmob@".
The identity format for mythicmobs is <uuid>
For example, 'mythicmob@1234-1234-1234'.

NoteThis language requires the plugin(s) Depenizen, MythicMobs!
GroupDepenizen Object Types

NamePlotSquaredPlotTag Objects
DescriptionA PlotSquaredPlotTag represents a PlotSquared plot in the world.

These use the object notation "plotsquaredplot@".
The identity format for plots is <x>,<z>,<world>
For example, 'plotsquaredplot@5,10,Hub'.

NoteThis language requires the plugin(s) Depenizen, PlotSquared!
GroupDepenizen Object Types

NamePVPArenaArenaTag Objects
DescriptionA PVPArenaArenaTag represents a PvP Arena in the world.

These use the object notation "pvparena@".
The identity format for arenas is <arena_name>
For example, 'pvparena@myarena'.

NoteThis language requires the plugin(s) Depenizen, PvPArena!
GroupDepenizen Object Types

NameResidenceTag Objects
DescriptionA ResidenceTag represents a Residence in the world.

These use the object notation "residence@".
The identity format for residences is <residence_name>
For example, 'residence@myresidence'.

NoteThis language requires the plugin(s) Depenizen, Residence!
GroupDepenizen Object Types

NameShopKeeperTag Objects
DescriptionA ShopKeeperTag represents a ShopKeeper entity in the world.

These use the object notation "shopkeeper@".
The identity format for shopkeepers is <uuid>
For example, 'shopkeeper@1234-1234-1234'.

NoteThis language requires the plugin(s) Depenizen, Shopkeepers!
GroupDepenizen Object Types

NameSkillAPIClassTag Objects
DescriptionA SkillAPIClassTag represents a SkillAPI class.

These use the object notation "skillapiclass@".
The identity format for regions is <class_name>
For example, 'skillapiclass@myclass'.

NoteThis language requires the plugin(s) Depenizen, SkillAPI!
GroupDepenizen Object Types

NameTownTag Objects
DescriptionA TownTag represents a Towny town in the world.

These use the object notation "town@".
The identity format for towns is <town_name>
For example, 'town@mytown'.

NoteThis language requires the plugin(s) Depenizen, Towny!
GroupDepenizen Object Types

NameWorldGuardRegionTag Objects
DescriptionA WorldGuardRegionTag represents a WorldGuard region in the world.

These use the object notation "region@".
The identity format for regions is <region_name>,<world_name>
For example, 'region@spawnland,Hub'.

NoteThis language requires the plugin(s) Depenizen, WorldGuard!
GroupDepenizen Object Types