- 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




Search:

Listing Language Explanations...

Categories:
1: script events
2: common terminology
3: object system
4: object fetcher system
5: denizen scripting language
6: script command system
7: comparables
8: script container system
9: useful lists
10: console commands
11: events
12: npc traits
13: properties
14: inventory system
15: npc interact scripts
16: useful flags
17: entities
18: inventories
19: depenizen object types
20: depenizen object fetcher types




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

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

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

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.

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

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

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 an example.
Take the following examples:
on player clicks in inventory:
take <player.item_in_hand>
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: Just wait a tick. Literally.
on player clicks in inventory:
wait 1t
take <player.item_in_hand>
on entity damaged:
wait 1t
if <context.entity.is_spawned||false>:
  - remove <context.entity>

By waiting a tick, you cause your script to run *after* the event, 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).


GroupScript Events



Top
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 avoided a decimal point is better. For example, '3.1' will be interpreted as just '3'.
Numbers can be verified with the 'if' commands' 'matches' functionality.
For example: "- if <number> matches number" ... will return true if <number> is a valid number.

GroupCommon Terminology

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

Generally it's best to not include the '%' symbol, and some percentage inputs will actually not accept a '%'.

While most things explicitly labeled as being a percentage scale from zero to one hundred (0 - 100)
others may go from zero to one (0.0 - 1.0).
To translate between the two formats, you only need to multiply or divide by one hundred (100).


GroupCommon Terminology

NameTick
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



Top
NameCustom Objects
DescriptionCustom objects are custom object types. They use a script basis to create an object
similar to the base object types (dLists, 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.


GroupObject System

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

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

For format info, see language/d@

GroupObject System

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

Pluses to the ElementTag system is the ability to utilize its attributes that
can provide a range of functionality that should be familiar from any other
programming language, such as 'to_uppercase', 'split', 'replace', 'contains',
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 (el@, li@, e@, etc.), elements do not.

For format info, see language/el@

GroupObject System

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

For format info, see language/li@


GroupObject System

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

For format info, see language/q@


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. ScriptTag objects have the object identifier of 's@'.
For example: ScriptTag_name

For format info, see language/s@


GroupObject System

NameObjectTags
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@.
The use of this notation is encouraged, but not always required.

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> would incorrectly reference the player named 'player', however this format is often
used to help with usage of a tag, simply indicating 'any player object'.

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!

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

+ ----- PlayerTag ----- +
| object notation: p@    can reference unique objects: yes    can be notable: no
| constructors: ( <>'s represent non-static information and are not literal)
|   p@<UUID> - fetches an online or offline player with the specified UUID

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

+ ----- CustomObjectTag ------+
| object notation: custom@   can reference unique objects: no      can be notable: no
| constructors: ( <>'s represent non-static information and are not literal)
|   custom@<custom_script_name> - fetches a custom object of the specified base custom script.


GroupObject System

NameBiomeTag
DescriptionA BiomeTag represents a world biome type.

A list of all valid Bukkit biomes can found be at
url/https://hub.spigotmc.org/javadocs/spigot/org/bukkit/block/Biome.html

For format info, see language/b@


GroupObject System

NameChunkTag
DescriptionA ChunkTag represents a chunk in the world.

For format info, see language/ch@


GroupObject System

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

For format info, see language/co@


GroupObject System

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

For format info, see language/cu@


GroupObject System

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

For format info, see language/ellipsoid@


GroupObject System

NameEntityTag
DescriptionA EntityTag represents a spawned entity, or a generic entity type.

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

For format info, see language/e@


GroupObject System

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

For format info, see language/in@


GroupObject System

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

For format info, see language/i@


GroupObject System

NameLocationTag
DescriptionA LocationTag represents a point in the world.

For format info, see language/l@


GroupObject System

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

For format info, see language/m@


GroupObject System

NameNPCTag
DescriptionA NPCTag represents an NPC configured through Citizens.

For format info, see language/n@


GroupObject System

NamePlayerTag
DescriptionA PlayerTag represents a player in the game.

For format info, see language/p@


GroupObject System

NamePluginTag
DescriptionA PluginTag represents a Bukkit plugin on the server.

For format info, see language/pl@


GroupObject System

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

Trades are represented by TradeTags.

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

result=<item>
input=<item>(|<item>)
uses=<number of uses>
max_uses=<maximum number of uses>
has_xp=<true/false>

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

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

For format info, see language/trade@

GroupObject System

NameWorldTag
DescriptionA WorldTag represents a world on the server.

For format info, see language/w@


GroupObject System

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

For format info, see language/discord@


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

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

For format info, see language/discordchannel@


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

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

For format info, see language/discordgroup@


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

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

For format info, see language/discordrole@


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

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

For format info, see language/discorduser@


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



Top
Namecustom@
Descriptioncustom@ refers to the 'object identifier' of a Custom Object. The 'custom@' is notation for Denizen's Object
Fetcher. The constructor for an Custom Object is the name of the custom script, with any relevant properties specified.

GroupObject Fetcher System

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

For general info, see language/Duration

GroupObject Fetcher System

Nameel@
Descriptionel@ refers to the 'object identifier' of an Element. The 'el@' is notation for Denizen's Object
Fetcher. The constructor for an ElementTag is just any text.

For example 'el@hello' forms an element with text 'hello'.

Elements do not output with 'el@' visible. The 'el@' is only for use as a shorthanded constructor.
If you need an element constructor, consider using the '<element[text here]>' tag base instead.

For general info, see language/Element

GroupObject Fetcher System

Nameli@
Descriptionli@ refers to the 'object identifier' of a ListTag. The 'li@' is notation for Denizen's Object
Fetcher. The constructor for a ListTag is the content items of a list separated by a pipe '|' symbol.
For example, if I had a list of 'taco', 'potatoes', and 'cheese', I would use
'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 no pipes.

For general info, see language/ListTag

GroupObject Fetcher System

Nameq@
Descriptionq@ refers to the 'object identifier' of a QueueTag. The 'q@' is notation for Denizen's Object
Fetcher. The constructor for a QueueTag is the queue ID.

For general info, see language/QueueTag


GroupObject Fetcher System

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

For general info, see language/ScriptTag

GroupObject Fetcher System

Nameb@
Descriptionb@ refers to the 'object identifier' of a BiomeTag. The 'b@' is notation for Denizen's Object
Fetcher. The constructor for a BiomeTag is the name of a valid biome (in Bukkit).
For example, 'b@desert'.

For general info, see language/BiomeTag


GroupObject Fetcher System

Namech@
Descriptionch@ refers to the 'object identifier' of a ChunkTag. The 'ch@' is notation for Denizen's Object
Fetcher. The constructor for a ChunkTag 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

For general info, see language/ChunkTag


GroupObject Fetcher System

Nameco@
Descriptionco@ refers to the 'object identifier' of a ColorTag. The 'co@' is notation for Denizen's Object
Fetcher. The constructor for a ColorTag 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
url/https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Color.html

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

For general info, see language/ColorTag


GroupObject Fetcher System

Namecu@
Descriptioncu@ refers to the 'object identifier' of a CuboidTag. The 'cu@' is notation for Denizen's Object
Fetcher. The constructor for a CuboidTag is <x>,<y>,<z>,<world>|...
For example, 'cu@1,2,3,space|4,5,6,space'.

For general info, see language/CuboidTag


GroupObject Fetcher System

Nameellipsoid@
Descriptionellipsoid@ refers to the 'object identifier' of a EllipsoidTag. The 'ellipsoid@' is notation for Denizen's Object
Fetcher. The constructor for a EllipsoidTag is <x>,<y>,<z>,<world>,<x-radius>,<y-radius>,<z-radius>
For example, 'ellipsoid@1,2,3,space,7,7,7'.

For general info, see language/EllipsoidTag


GroupObject Fetcher System

Namee@
Descriptione@ refers to the 'object identifier' of a EntityTag. The 'e@' is notation for Denizen's Object
Fetcher. The constructor for a EntityTag is a spawned entity's UUID, or an entity type.
For example, 'e@zombie'.

For general info, see language/EntityTag


GroupObject Fetcher System

Namein@
Descriptionin@ refers to the 'object identifier' of a InventoryTag. The 'in@' is notation for Denizen's Object
Fetcher. The constructor for a InventoryTag 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"

For general info, see language/InventoryTag


GroupObject Fetcher System

Namei@
Descriptioni@ refers to the 'object identifier' of a ItemTag. The 'i@' is notation for Denizen's Object
Fetcher. The constructor for a ItemTag 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:
url/https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Material.html
Note that some materials on that list are exclusively for use with blocks, and cannot be held as items.

For general info, see language/ItemTag


GroupObject Fetcher System

Namel@
Descriptionl@ refers to the 'object identifier' of a LocationTag. The 'l@' is notation for Denizen's Object
Fetcher. Note that 'l' is a lowercase 'L', the first letter in 'location'.
The full constructor for a LocationTag is: 'l@<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'

For general info, see language/LocationTag


GroupObject Fetcher System

Namem@
Descriptionm@ refers to the 'object identifier' of a MaterialTag. The 'm@' is notation for Denizen's Object
Fetcher. The constructor for a MaterialTag is the material type name.
For example, 'm@stick'.

For general info, see language/MaterialTag


GroupObject Fetcher System

Namen@
Descriptionn@ refers to the 'object identifier' of a NPCTag. The 'n@' is notation for Denizen's Object
Fetcher. The constructor for a NPCTag is the NPC's id number.
For example, 'n@5'.

For general info, see language/NPCTag


GroupObject Fetcher System

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

For general info, see language/PlayerTag


GroupObject Fetcher System

Namepl@
Descriptionpl@ refers to the 'object identifier' of a PluginTag. The 'pl@' is notation for Denizen's Object
Fetcher. The constructor for a PluginTag is the plugin's registered name.
For example, 'pl@Denizen'.

For general info, see language/PluginTag


GroupObject Fetcher System

Nametrade@
Descriptiontrade@ refers to the 'object identifier' of a TradeTag. The 'trade@' is notation for Denizen's Object
Fetcher. The constructor for a TradeTag is just the text 'trade'. All other data is specified through properties.

For general info, see language/Merchant Trades


GroupObject Fetcher System

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

For general info, see language/WorldTag

GroupObject Fetcher System

Namediscord@
Descriptiondiscord@ refers to the 'object identifier' of a DiscordBotTag. The 'discord@' is notation for Denizen's Object
Fetcher. The constructor for a DiscordBotTag is the bot ID (as chosen in command/discord).
For example: mybot

For general info, see language/DiscordBotTag

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

Namediscordchannel@
Descriptiondiscordchannel@ refers to the 'object identifier' of a DiscordChannelTag. The 'discordchannel@' is notation for Denizen's Object
Fetcher. The constructor for a DiscordChannelTag is the bot ID (optional), followed by the channel ID (required).
For example: 1234
Or: mybot,1234

For general info, see language/DiscordChannelTag

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

Namediscordgroup@
Descriptiondiscordgroup@ refers to the 'object identifier' of a DiscordGroupTag. The 'discordgroup@' is notation for Denizen's Object
Fetcher. The constructor for a DiscordGroupTag is the bot ID (optional), followed by the guild ID (required).
For example: 1234
Or: mybot,1234

For general info, see language/DiscordGroupTag

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

Namediscordrole@
Descriptiondiscordrole@ refers to the 'object identifier' of a DiscordRoleTag. The 'discordrole@' is notation for Denizen's Object
Fetcher. The constructor for a DiscordRoleTag 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

For general info, see language/DiscordRoleTag

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

Namediscorduser@
Descriptiondiscorduser@ refers to the 'object identifier' of a DiscordUserTag. The 'discorduser@' is notation for Denizen's Object
Fetcher. The constructor for a DiscordUserTag is the bot ID (optional), followed by the user ID (required).
For example: 1234
Or: mybot,1234

For general info, see language/DiscordUserTag

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



Top
NameScript
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

NamedScript
DescriptionThe overall 'scripting language' that Denizen implements is referred to as 'dScripting', or 'dScript'.
dScripts use a YAML-styled layout + Denizen's Scripting API to parse scripts that are stored as .yml 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 YAML-like files, which use the '.yml' suffix but do not
fully conform to the YAML specification. 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 YAML files are 'script containers', which is 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



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

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

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

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

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

Highly specific note: <commands> means a block of commands wrapped in braces or as a sub-block... EG:
repeat 3:
  - narrate "<[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



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

GroupComparables

NameOperator
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 (==), OR_MORE (>=), OR_LESS (<=), MORE (>), and LESS (<).

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

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

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.


GroupComparables



Top
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
  script:
  - 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 or

script name:
  type: script_type  <--- script type
  script:
    - 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.

Custom_Script_Name:
 
  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.
  tags:
 
    # This would be read like <[my_object].my_tag>
    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).
  mechanisms:
 
    # This would be used like custom@Custom_Script_Name[my_mech=3]
    my_mech:
    - adjust <context.this> true_value:<context.value.mul[2]> save:new_val
    - determine <entry[new_val].result>
 
    # list additional mechanisms here...
 


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 the 'proc' tag.

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 'parse:' 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.

Proc_Script_Name:
 
  type: procedure
 
  script:
 
  # 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.

Task_Script_Name:
 
  type: task
 
  script:
 
  - 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.

World_Script_Name:
 
  type: world
 
  events:
 
    # 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

NameYaml Data Script Containers
DescriptionYaml Data script containers are generic script containers for information
that will be referenced by other scripts.

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

There are no required keys.

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

Yaml_Data_Script_Name:
 
  type: yaml data
 
  # Your data 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:
Assignment_Script_Name:
  type: assignment
 
  actions:
    on <action>:
    - ...
 
  default constants:
    <constant_name><value>
    <constant_list>:
    - ...
 
  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

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


GroupScript Container System

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

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


GroupScript Container System

NameEconomy Script Containers
DescriptionEconomy script containers

Economy script containers provide a Vault economy, which can be used in scripts by
tag/PlayerTag.money and mechanism/PlayerTag.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.

All script keys are required.

# The script name will be shown to the economy provider as the name of the economy system.
Economy_Script_Name:
 
  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.
  balance<player.flag[money]>
  # 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'.
  has<player.flag[money].is[or_more].than[<amount>]>
  # 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.
  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.
  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 e@EntityScriptName. Example: - spawn <player.location> e@MyEntity

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

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

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

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


GroupScript Container System

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, put a '^' in front of each command name, or set 'speed: 0' on the container.

Interact_Script_Name:
 
  type: interact
 
  steps:
 
    # The first step
    1:
      # Any trigger type here
      click trigger:
        script:
        # 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:in@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 'in@Super Cool Inventory'.
Inventory Script Name:
 
  type: inventory
 
  # Must be a valid inventory type.
  # Valid inventory types: BREWING, CHEST, DISPENSER, ENCHANTING, ENDER_CHEST, HOPPER, PLAYER, WORKBENCH
  inventory: inventory type
 
  # The title can be anything you wish. Use color tags to make colored titles.
  # Note that titles only work for some inventory types, including CHEST, DISPENSER, FURNACE, ENCHANTING, and HOPPER.
  title: custom title
 
  # The size must be a multiple of 9. It is recommended not to go above 54, as it will not show
  # correctly when a player looks into it. Tags are allowed for advanced usage.
  size: 27
 
  # You can use definitions to define items to use in the slots. These are not like normal
  # script definitions, and do not need %'s around them.
  definitions:
    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.
  procedural items:
    - define list li@
    - foreach <server.list_online_players>:
      - define item human_skull[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". Note the quotes around the entire lines.
  slots:
    - "[] [] [] [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 'sword of swiftness'.
Item Script Name:
 
  type: item
 
  # Must be a valid ItemTag (EG red_wool or potion,8226) See 'ItemTag' for more information.
  material: base_material
 
  # List any mechanisms you want to apply to the item within
  mechanisms:
    # 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.
  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.
  lore:
  - item
  - ...
 
  # If you want an item to be damaged on creation, you can change its durability.
  durability: 12
 
  # Each line must specify a valid Bukkit enchantment. See 'enchantments' for more information.
  enchantments:
  - enchantment_name:level
  - ...
 
  # You can specify the items required to craft your item. For an empty slot, use "air".
  # 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).
  # Recipe internal IDs will be of the form "denizen:shaped_recipe_<script.name>_<id>" where ID is the recipe list index (starting at 1, counting up).
  recipes:
      1:
      - ItemTag|ItemTag|ItemTag
      - ItemTag|ItemTag|ItemTag
      - ItemTag|ItemTag|ItemTag
      # Format of a 2x2 recipe
      2:
      - ItemTag|ItemTag
      - ItemTag|ItemTag
      # Format of a 1x1 recipe
      3:
      - ItemTag
      # Add more recipes if you want.
      4:
      - ...
 
  # You can specify a list of materials that make up a shapeless recipe.
  # Note: This can overwrite existing shapeless recipes.
  # Recipe internal IDs will be of the form "denizen:shapeless_recipe_<script.name>_<id>" where ID is the recipe list index (starting at 1, counting up).
  shapeless_recipes:
     1: ItemTag|...
     # Add more shapeless recipes if you want.
     2: ...
 
  # You can specify a list of materials that make up a stonecutting recipe.
  # Recipe internal IDs will be of the form "denizen:stonecutting_recipe_<script.name>_<id>" where ID is the recipe list index (starting at 1, counting up).
  stonecutting_recipes:
     1: ItemTag|...
     # Add more stonecutting recipes if you want.
     2: ...
 
  # You can specify a material that can be smelted into your item.
  # Note: This can overwrite existing furnace recipes.
  # Recipe internal IDs will be of the form "denizen:furnace_recipe_<script.name>_<id>" where ID is the recipe list index (starting at 1, counting up).
  furnace_recipes:
     1:
         # The input item
         input: ItemTag
         # The furnace type. Can be: Furnace (default), Blast, Smoker, or Campfire.
         type: furnace
         # The cook time (as a duration)
         cook_time: 1s
         # The experience reward amount (if any)
         experience: 5
     # Add more furnace recipes if you want.
     2: ...
 
  # Set to true to not store the scriptID on the item, treating it as an item dropped by any other plugin.
  # NOTE: THIS IS NOT RECOMMENDED UNLESS YOU HAVE A SPECIFIC REASON TO USE IT.
  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.
  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.
  book: book_script_name


GroupScript Container System

NameMap Script Containers
DescriptionMap scripts allow you define custom in-game map items, for usage with the map command.

The following is the format for the container.

# The name of the map script is used by the map command.
Item Script Name:
 
  type: map
 
  # Whether to display the original map below the custom values.
  original: true/false
 
  # The 'custom name' can be anything you wish. Use color tags to make colored custom names.
  display name: custom name
 
  # Whether to constantly update things.
  auto update: true
 
  # Lists all contained objects.
  objects:
 
    # The first object...
    1:
      # 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.
 
    2:
      type: text
      # Specify any text, with tags.
      text: Hello <player.name>
      # Specify a tag to show or hide custom content! Valid for all objects.
      visible<player.name.contains[bob].not>
 
    3:
      type: cursor
      # Specify a cursor - ?a href="/tags/server.list_map_cursor_types"?tag/server.list_map_cursor_types?/a?
      cursor: red_marker
      # Supported on all objects: x/y positions, and whether to use worldly or map coordinates.
      x: 5
      y: 5
      world_coordinates: false


GroupScript Container System

NameVersion Script Containers
DescriptionVersion script containers are used to identify a public script's version, author, and etc. basic information.

These are primarily for use with the public script repository, and as such generally contain
an 'ID:' key identifying the script repo ID of the script.

Version_Script_Name:
 
  type: version
 
  # This is sample information, for script repository script number zero, 'dSentry'.
  id: 0
  version: 0.7.3
  name: dSentry
  author: mcmonkey
 


GroupScript Container System



Top
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.
Decrement: '--': lowers the value numerically down by 1.
Clear: '!': removes the value entirely.

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

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

NameInventory Actions
DescriptionUsed by some inventory world events to describe the action of the inventory event.

Actions, as described by the bukkit javadocs:
CLONE_STACK
A max-size stack of the clicked item is put on the cursor.
COLLECT_TO_CURSOR
The inventory is searched for the same material, and they are put on the cursor up to
     MaterialTag.max_stack_size.
DROP_ALL_CURSOR
The entire cursor item is dropped.
DROP_ALL_SLOT
The entire clicked slot is dropped.
DROP_ONE_CURSOR
One item is dropped from the cursor.
DROP_ONE_SLOT
One item is dropped from the clicked slot.
HOTBAR_MOVE_AND_READD
The clicked item is moved to the hotbar, and the item currently there is re-added to the
     player's inventory.
HOTBAR_SWAP
The clicked slot and the picked hotbar slot are swapped.
MOVE_TO_OTHER_INVENTORY
The item is moved to the opposite inventory if a space is found.
NOTHING
Nothing will happen from the click.
PICKUP_ALL
All of the items on the clicked slot are moved to the cursor.
PICKUP_HALF
Half of the items on the clicked slot are moved to the cursor.
PICKUP_ONE
One of the items on the clicked slot are moved to the cursor.
PICKUP_SOME
Some of the items on the clicked slot are moved to the cursor.
PLACE_ALL
All of the items on the cursor are moved to the clicked slot.
PLACE_ONE
A single item from the cursor is moved to the clicked slot.
PLACE_SOME
Some of the items from the cursor are moved to the clicked slot (usually up to the max stack size).
SWAP_WITH_CURSOR
The clicked item and the cursor are exchanged.
UNKNOWN
An unrecognized ClickType.


GroupUseful Lists

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

Effects:
- iconcrack_[item] (item break effect - examples: iconcrack_stone, iconcrack_grass)
- blockcrack_[material] (block break effect - examples: blockcrack_stone, blockcrack_grass)
- blockdust_[material] (block break effect - examples: blockdust_stone, blockdust_grass)
- 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 list starting with 'huge_explosion')

GroupUseful Lists



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

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

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

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

GroupConsole Commands

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

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

Additionally:
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
'-e' enables/disables world event timings. While enabled, the debugger will show all triggered events.
'-s' enables/disables stacktraces generated by Denizen. We might ask you to enable this when problems arise.
'-b' enables/disables the ScriptBuilder debug. When enabled, Denizen will show info on script and argument creation.
     Warning: Can be spammy.
'-n' enables/disables debug trimming. When enabled, messages longer than 512 characters will be 'snipped'.
'-i' enables/disables source information. When enabled, debug will show where it came from (when possible).
'-p' enables/disables packet debug logging. When enabled, all packets sent to players (from anywhere) will be logged to console.

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


GroupConsole Commands

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

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

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

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

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

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

See also: 'pushable trait'

GroupConsole Commands

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

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

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

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

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

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

GroupConsole Commands



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

GroupEvents



Top
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
tag/NPCTag.health
tag/NPCTag.health.formatted
tag/NPCTag.health.max
tag/NPCTag.health.percentage
tag/NPCTag.has_trait[health]

Related Mechanisms
mechanism/health
mechanism/max_health

Related Commands
command/heal
command/health
command/vulnerable

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



Top
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,
         where COLOR is BLACK, BROWN, CHESTNUT, CREAMY, DARK_BROWN, GRAY, or WHITE.
         and where STYLE is WHITE, WHITE_DOTS, WHITEFIELD, BLACK_DOTS, or NONE.
For rabbits, the types are BROWN, WHITE, BLACK, BLACK_AND_WHITE, GOLD, SALT_AND_PEPPER, or THE_KILLER_BUNNY.
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).
         The types are TABBY, BLACK, RED, SIAMESE, BRITISH_SHORTHAIR, CALICO, PERSIAN, RAGDOLL, WHITE, JELLIE, and ALL_BLACK.
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 tropical_fish, the input is PATTERN|BODYCOLOR|PATTERNCOLOR, where BodyColor and PatterenColor are both DyeColor (see below),
         and PATTERN is KOB, SUNSTREAK, SNOOPER, DASHER, BRINELY, SPOTTY, FLOPPER, STRIPEY, GLITTER, BLOCKFISH, BETTY, is CLAYFISH.
For sheep, wolf, and shulker entities, the input is a Dye Color.

For all places where a DyeColor is needed, the options are:
BLACK, BLUE, BROWN, CYAN, GRAY, GREEN, LIGHT_BLUE, LIGHT_GRAY, LIME, MAGENTA, ORANGE, PINK, PURPLE, RED, WHITE, or YELLOW.

GroupProperties



Top
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 Notable dInventories (saved by the Note command) are automatically converted into a
virtual copy of the saved inventory. This enables you to open and edit the items inside freely, with automatic
saving, as if it were a normal inventory.

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

size=<size>
contents=<item>|...
title=<title>
holder=<inventory type>

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


GroupInventory System



Top
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).
1:
  # 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
  script:
  # 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
2:
  # 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/
  script:
  - 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!"
3:
  # You can have regex triggers. This example matches when the player types any numbers.
  trigger/regex:\d+/
  script:
  - wait 1
  # use "<context.keyword>" for the text matched by the regex matcher.
  - chat "<context.keyword> eh?"
4:
  # 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
  script:
  # 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 NPC walks into range of the NPC, and exit fires when the NPC 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



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

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


GroupUseful flags



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

GroupEntities



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

Groupinventories



Top
NameAreaShopTag
DescriptionA AreaShopTag represents an AreaShop shop.

For format info, see language/areashop@


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

NameFactionTag
DescriptionA FactionTag represents a Factions faction.

For format info, see language/faction@


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

NameGriefPreventionClaimTag
DescriptionA GriefPreventionClaimTag represents a GriefPrevention claim.

For format info, see language/gpclaim@


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

NameJobsJobTag
DescriptionA JobsJobTag represents a Jobs job.

For format info, see language/job@


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

NameLibsDisguiseTag
DescriptionA LibsDisguiseTag represents a LibsDisguises disguise type.

For format info, see language/libsdisguise@


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

NameLuckPermsTrackTag
DescriptionA LuckPermsTrackTag represents a LuckPerms track.

For format info, see language/luckpermstrack@


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

NamePartyTag
DescriptionA PartyTag represents an McMMO party.

For format info, see language/party@


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

NameMobArenaArenaTag
DescriptionA MobArenaArenaTag represents a mob arena in the world.

For format info, see language/mobarena@


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

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

For format info, see language/mythicmob@


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

NamePlotSquaredPlotTag
DescriptionA PlotSquaredPlotTag represents a PlotSquared plot in the world.

For format info, see language/plotsquaredplot@


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

NamePVPArenaArenaTag
DescriptionA PVPArenaArenaTag represents a PvP Arena in the world.

For format info, see language/pvparena@


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

NameResidenceTag
DescriptionA ResidenceTag represents a Residence in the world.

For format info, see language/residence@


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

NameShopKeeperTag
DescriptionA ShopKeeperTag represents a ShopKeeper entity in the world.

For format info, see language/shopkeeper@


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

NameSkillAPIClassTag
DescriptionA SkillAPIClassTag represents a SkillAPI class.

For format info, see language/skillapiclass@


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

NameTownTag
DescriptionA TownTag represents a Towny town in the world.

For format info, see language/town@


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

NameWorldGuardRegionTag
DescriptionA WorldGuardRegionTag represents a WorldGuard region in the world.

For format info, see language/region@


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



Top
Nameareashop@
Descriptionareashop@ refers to the 'object identifier' of a AreaShopTag. The 'areashop@' is notation for Denizen's Object
Fetcher. The constructor for a AreaShopTag is <shop_name>
For example, 'areashop@my_shot'.

For general info, see language/AreaShopTag


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

Namefaction@
Descriptionfaction@ refers to the 'object identifier' of a FactionTag. The 'faction@' is notation for Denizen's Object
Fetcher. The constructor for a FactionTag is <faction_name>
For example, 'faction@my_faction'.

For general info, see language/FactionTag


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

Namegpclaim@
Descriptiongpclaim@ refers to the 'object identifier' of a GriefPreventionClaimTag. The 'gpclaim@' is notation for Denizen's Object
Fetcher. The constructor for a GriefPreventionClaimTag is <claim_id>
For example, 'gpclaim@1234'.

For general info, see language/GriefPreventionClaimTag


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

Namejob@
Descriptionjob@ refers to the 'object identifier' of a JobsJobTag. The 'job@' is notation for Denizen's Object
Fetcher. The constructor for a JobsJobTag is <job_name>
For example, 'job@job_name'.

For general info, see language/JobsJobTag


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

Namelibsdisguise@
Descriptionlibsdisguise@ refers to the 'object identifier' of a LibsDisguiseTag. The 'libsdisguise@' is notation for Denizen's Object
Fetcher. The constructor for a LibsDisguiseTag is <disguise_name>
For example, 'libsdisguise@zombie'.

For general info, see language/LibsDisguiseTag


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

Nameluckpermstrack@
Descriptionluckpermstrack@ refers to the 'object identifier' of a LuckPermsTrackTag. The 'luckpermstrack@' is notation for Denizen's Object
Fetcher. The constructor for a LuckPermsTrackTag is <track_name>
For example, 'luckpermstrack@my_track'.

For general info, see language/LuckPermsTrackTag


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

Nameparty@
Descriptionparty@ refers to the 'object identifier' of a PartyTag. The 'party@' is notation for Denizen's Object
Fetcher. The constructor for a PartyTag is <party_name>
For example, 'party@my_party'.

For general info, see language/PartyTag


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

Namemobarena@
Descriptionmobarena@ refers to the 'object identifier' of a MobArenaArenaTag. The 'mobarena@' is notation for Denizen's Object
Fetcher. The constructor for a MobArenaArenaTag is <arena_name>
For example, 'mobarena@my_arena'.

For general info, see language/MobArenaArenaTag


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

Namemythicmob@
Descriptionmythicmob@ refers to the 'object identifier' of a MythicMobsMobTag. The 'mythicmob@' is notation for Denizen's Object
Fetcher. The constructor for a MythicMobsMobTag is <uuid>
For example, 'mythicmob@1234-1234-1234'.

For general info, see language/MythicMobsMobTag


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

Nameplotsquaredplot@
Descriptionplotsquaredplot@ refers to the 'object identifier' of a PlotSquaredPlotTag. The 'plotsquaredplot@' is notation for Denizen's Object
Fetcher. The constructor for a PlotSquaredPlotTag is <x>,<z>,<world>
For example, 'plotsquaredplot@5,10,Hub'.

For general info, see language/PlotSquaredPlotTag


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

Namepvparena@
Descriptionpvparena@ refers to the 'object identifier' of a PVPArenaArenaTag. The 'pvparena@' is notation for Denizen's Object
Fetcher. The constructor for a PVPArenaArenaTag is <arena_name>
For example, 'pvparena@myarena'.

For general info, see language/PVPArenaArenaTag


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

Nameresidence@
Descriptionresidence@ refers to the 'object identifier' of a ResidenceTag. The 'residence@' is notation for Denizen's Object
Fetcher. The constructor for a ResidenceTag is <residence_name>
For example, 'residence@myresidence'.

For general info, see language/ResidenceTag


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

Nameshopkeeper@
Descriptionshopkeeper@ refers to the 'object identifier' of a ShopKeeperTag. The 'shopkeeper@' is notation for Denizen's Object
Fetcher. The constructor for a ShopKeeperTag is <uuid>
For example, 'shopkeeper@1234-1234-1234'.

For general info, see language/ShopKeeperTag


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

Nameskillapiclass@
Descriptionskillapiclass@ refers to the 'object identifier' of a SkillAPIClassTag. The 'skillapiclass@' is notation for Denizen's Object
Fetcher. The constructor for a SkillAPIClassTag is <class_name>
For example, 'skillapiclass@myclass'.

For general info, see language/SkillAPIClassTag


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

Nametown@
Descriptiontown@ refers to the 'object identifier' of a TownTag. The 'town@' is notation for Denizen's Object
Fetcher. The constructor for a TownTag is <town_name>
For example, 'town@mytown'.

For general info, see language/TownTag


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

Nameregion@
Descriptionregion@ refers to the 'object identifier' of a WorldGuardRegionTag. The 'region@' is notation for Denizen's Object
Fetcher. The constructor for a WorldGuardRegionTag is <region_name>,<world_name>
For example, 'region@spawnland,Hub'.

For general info, see language/WorldGuardRegionTag


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