Denizen Script Language Explanations


Language Explanations explain components of Denizen in a more direct and technical way than The Beginner's Guide.


Showing all 75 language explanations...

Categories:

Common Terminology | Comparables | Console Commands | Denizen Magic | Denizen Scripting Language | Inventory System | Minecraft Logic | NPC Interact Scripts | NPC Traits | Object System | Properties | Script Command System | Script Container System | Script Events | Tag System | Useful Lists | Depenizen Bridges


Category: Common Terminology


NameNumber and Decimal
DescriptionMany arguments in Denizen require the use of a 'number', or 'decimal'. Sometimes shorthanded to '#' or '#.#',
this kind of input can generally be filled with any reasonable positive or negative number.
'decimal' inputs allow (but don't require) a decimal point in the number.
'number' inputs will be rounded, so avoiding a decimal point is better. For example, '3.1' will be interpreted as just '3'.
GroupCommon Terminology
Sourcehttps://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/objects/ArgumentHelper.java#L11

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
Sourcehttps://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/utilities/CommonRegistries.java#L66



Category: Comparables


NameOperator
DescriptionAn operator is a tool for comparing values, used by commands like Command:if, Command:while, Command:waituntil, ... and tags like Tag:ObjectTag.is.than

Available Operators include:
"Equals" is written as "==" or "equals".
"Does not equal" is written as "!=".
"Is more than" is written as ">" or "more".
"Is less than" is written as "<" or "less".
"Is more than or equal to" is written as ">=" or "or_more".
"Is less than or equal to" is written as "<=" or "or_less".
"does this list or map contain" is written as "contains". For example, "- if a|b|c contains b:" or "- if [a=1;b=2] contains b:"
"is this in the list or map" is written as "in". For example, "- if b in a|b|c:", or "- if [a=1;b=2] contains b:"

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

There are also special boolean operators (&&, ||, ...) documented at: Command:if
GroupComparables
Sourcehttps://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/scripts/commands/Comparable.java#L15



Category: Console 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: you should almost NEVER disable debug entirely. Instead, always disable it on a per-script basis.
If debug is globally disabled, that will hide important error messages, not just normal debug output.

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

'-c' enables/disables color. This is sometimes useful when debugging with a non-color console.
'-r' enables recording mode. See also: /denizen submit command
'-s' enables/disables stacktraces generated by Denizen. We might ask you to enable this when problems arise.
'-b' enables/disables the ScriptBuilder debug. When enabled, Denizen will show info on script and argument creation. Warning: Can be spammy.
'-n' enables/disables debug trimming. When enabled, messages longer than 1024 characters will be 'snipped'.
'-i' enables/disables source information. When enabled, debug will show where it came from (when possible).
'-p' enables/disables packet debug logging. When enabled, all packets sent to players (from anywhere) will be logged to console.
'-f' enables/disables showing of future warnings. When enabled, future warnings (such as upcoming deprecations) will be displayed in console logs.
'-v' enables/disables advanced verbose log output. This will *flood* your console super hard.
'-o' enables/disables 'override' mode. This will display all script debug, even when 'debug: false' is set for scripts.
'-l' enables/disables script loading information. When enabled, '/ex reload' will produce a potentially large amount of debug output.
GroupConsole Commands
Sourcehttps://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/utilities/command/DenizenCommandHandler.java#L87

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
Sourcehttps://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/utilities/command/DenizenCommandHandler.java#L50

Name/ex command
DescriptionThe '/ex' command is an easy way to run a single denizen script command in-game.
'Ex' is short for 'Execute'.
Its syntax, aside from '/ex' is exactly the same as any other Denizen script 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"

The '/ex' command creates a new queue each time it's run,
meaning for example '/ex define' would do nothing, as the definition will be lost immediately.

If you need to sustain a queue between multiple executions, use '/exs' ("Execute Sustained").
A sustained queue will use the same queue on every execution until the queue stops (normally due to '/exs stop').
Be warned that waits will block the sustained queue - eg '/exs wait 10m' will make '/exs' effectively unusable for 10 minutes.

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

Need to '/ex' a command as a different player or NPC? Use Language:The Player and NPC Arguments.

Examples:
/ex narrate player:<[aplayer]> 'Your health is <player.health.formatted>.'
/ex walk npc:<[some_npc]> <player.cursor_on>
GroupConsole Commands
Sourcehttps://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/utilities/command/ExCommandHandler.java#L42

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
Sourcehttps://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/utilities/command/NPCCommandHandler.java#L119

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
Sourcehttps://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/utilities/command/NPCCommandHandler.java#L33

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

denizen.clickable # use the 'denizenclickable' command, which is automatically executed when using Command:clickable
denizen.basic # use the basics of the /denizen command
denizen.ex # use the /ex command
denizen.debug # use the /denizen debug command
denizen.submit # use the /denizen submit command

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
Sourcehttps://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/utilities/command/DenizenCommandHandler.java#L27



Category: Denizen Magic


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

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

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

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

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

Also note that RGB colors use a format that Spigot invented, meaning they will work in places that use Spigot's parser OR Denizen's version, but nowhere that uses the vanilla format still.

Thanks to Paper's implementation of component APIs where Spigot was too lazy to, Paper servers have advanced text formatting available in more areas.
GroupDenizen Magic
Sourcehttps://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/utilities/FormattedTextHelper.java#L17



Category: Denizen Scripting Language


NamedScript
DescriptionThe overall 'scripting language' that Denizen implements is referred to as 'dScripting', or 'dScript'.
dScripts use the Denizen script syntax and the Denizen Scripting API to parse scripts that are stored as .dsc files.
Scripts go in the 'plugins/Denizen/scripts' folder.
GroupDenizen Scripting Language
Sourcehttps://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/objects/core/ScriptTag.java#L38

NameFlag System
DescriptionThe flag system is a core feature of Denizen, that allows for persistent data storage linked to objects.

"Persistent" means the data is still around even after a server restart or anything else, and is only removed when you choose for it to be removed.
"Linked to objects" means rather than purely global values, flags are associated with a player, or an NPC, or a block, or whatever else.

See also the guide page at URL:https://guide.denizenscript.com/guides/basics/flags.html.

For non-persistent temporary memory, see instead Command:define.
For more generic memory options, see Command:yaml or Command:sql.

Flags can be sub-mapped with the '.' key, meaning a flag named 'x.y.z' is actually a flag 'x' as a MapTag with key 'y' as a MapTag with key 'z' as the final flag value.
In other words, "<server.flag[a.b.c]>" is equivalent to "<server.flag[a].get[b].get[c]>"

Server flags can be set by specifying 'server' as the object, essentially a global flag target, that will store data in the file "plugins/Denizen/server_flags.dat"

Most unique object types are flaggable - refer to any given object type's language documentation for details.

Most flag sets are handled by Command:flag, however items are primarily flagged via Command:inventory with the 'flag' argument.
Any supported object type, including the 'server' base tag, can use the tags
Tag:FlaggableObject.flag, Tag:FlaggableObject.has_flag, Tag:FlaggableObject.flag_expiration, Tag:FlaggableObject.list_flags.

Additionally, flags be searched for with tags like Tag:server.online_players_flagged, Tag:server.players_flagged, Tag:server.spawned_npcs_flagged, Tag:server.npcs_flagged, ...
Flags can also be required by script event lines, as explained at Language:Script Event Switches.
Item flags can also be used as a requirement in Command:take.

Note that some internal flags exist, and are prefixed with '__' to avoid conflict with normal user flags.
This includes '__scripts' which is where script flags are stored inside of server flags,
and '__interact_step' which is used for interact script steps, related to Command:zap,
and '__interact_cooldown' which is used for interact script cooldowns, related to Command:cooldown.

Flags have an expiration system, which is used by specifying a time at which they should expire (or via a duration which internally calculates the date/time of expiration by adding the duration input to the current date/time).
Expirations are then *checked for* in flag tags - meaning, the flag tags will internally compare a stored date/time against the real current date/time,
and if the flag's expiration time is in the past, the flag tag will return values equivalent to if the flag doesn't exist.
There is no system actively monitoring for flag expirations or applying them. There is no event for expirations occurring, as they don't "occur" per se.
In other words, it is correct to say a flag "is expired" or a flag "is not expired",
but it is incorrect to say a flag "expires", as it is not an active action (those this wording can be convenient when speaking informally).
Expired flags are sometimes 'cleaned up' (meaning, any expired flags get actually removed from internal storage), usually when a flag save file is loaded into the server.
GroupDenizen Scripting Language
Sourcehttps://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/scripts/commands/core/FlagCommand.java#L31

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
Sourcehttps://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/objects/core/ScriptTag.java#L22

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

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

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

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

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

Within any script path is a list of 'script entries', which are the commands to be executed.
These can be raw commands themselves (like 'narrate') with their arguments,
or commands that contain additional commands within their entry (as 'if' and 'foreach' for example both do).
GroupDenizen Scripting Language
Sourcehttps://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/objects/core/ScriptTag.java#L48



Category: Inventory System


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

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

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

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

For example, the following task script opens a virtual inventory with 18 slots,
where the second slot is a snowball, all the rest are empty, and the title is "My Awesome Inventory" with some colors in it.

open random inventory:
  type: task
  script:
  - inventory open "d:generic[size=18;title=<red>My <green>Awesome <blue>Inventory;contents=air|snow_ball]"
GroupInventory System
Sourcehttps://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/scripts/commands/item/InventoryCommand.java#L38



Category: Minecraft Logic


NamePlayer Entity Skins (Skin Blobs)
DescriptionPlayer entities (that is, both real players and player-type NPCs), in addition to Player_Head items,
use something called a "skin blob" to determine what skin to show.
A skin blob consists of an identifier (usually the player's UUID, sometimes the name), a "texture", and a "signature".

The "texture" portion, despite the name, does not contain actual texture data - it contains a Base64 encoding of a JSON section that contains outlinks to real skin data.
That might be a bit confusing, so here's an example:

The raw "texture" data for "mcmonkey4eva"'s skin is:
eyJ0aW1lc3RhbXAiOjE1NjU1NjUyNDA4NTMsInByb2ZpbGVJZCI6IjQ2MGU5NmI5N2EwZTQxNmRiMmMzNDUwODE2NGI4YjFiIiwicHJvZmlsZU5hbWUiOiJtY21vbmtleTRldmEiLCJzaWduYXR1cmVSZXF1aXJlZCI6dHJ1ZSwidGV4dH
VyZXMiOnsiU0tJTiI6eyJ1cmwiOiJodHRwOi8vdGV4dHVyZXMubWluZWNyYWZ0Lm5ldC90ZXh0dXJlL2ZkMzRiM2UyN2EzZmU1MzgyN2IzN2FkNTk1NmFjY2EwOGYyODYzYzY5MjZjYzk3MTE2ZGRhMzM0ODY5N2E1YTkifX19

This is base64 encoding, which is just a way of controlling the format of binary data. When passed through a Base64 decoder, that says:
{"timestamp":1565565240853,"profileId":"460e96b97a0e416db2c34508164b8b1b","profileName":"mcmonkey4eva","signatureRequired":true,
"textures":{"SKIN":{"url":"http://textures.minecraft.net/texture/fd34b3e27a3fe53827b37ad5956acca08f2863c6926cc97116dda3348697a5a9"}}}

As you can see, it contains: the timestamp of when the skin was added, the UUID and name, and a link to the actual skin file on Mojang's servers.

The "signature" portion is a digitally encrypted signature that is used to verify a skin really was generated by Mojang.
It is also represented as Base64, but cannot be decoded to anything readable.
The "signature" is required for Player entity skins, but can generally be left off from Player_Head items (meaning, you can generate your own Player_Head items by base64 encoding your own JSON).

The website URL:https://mineskin.org/ can be used to generate full texture+signature data from any skin file
(it does this by automatically uploading the skin image to Mojang's servers for processing and signing, using a donated Minecraft account).

In terms of general actual usage, skin blobs are generally meant to be read from tags and applied with mechanisms, never directly written out or read by a human, due to their complexity.

A skin_blob always represents a single actual skin, as opposed to a player name/uuid, where the account owner might choose to change their skin.

It should be noted that any time a skin is applied to a Player, NPC, Or Player_Head item using just a name or UUID, the server must contact Mojang's servers to requst the skin blob for that given name/uuid.
With a skin blob, however, the server does not need to make any remote calls, and can apply the skin directly (However note that the client will still download the image from Mojang's servers).
GroupMinecraft Logic
Sourcehttps://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/nms/abstracts/ProfileEditor.java#L48



Category: NPC 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
  # Add this line to show the player chat message in the normal chat.
  show as normal chat: true
  script:
  # If you hide the trigger message but not show as normal chat, 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
Sourcehttps://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/scripts/triggers/core/ChatTrigger.java#L40

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
Sourcehttps://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/scripts/triggers/core/ClickTrigger.java#L22

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
Sourcehttps://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/scripts/triggers/core/DamageTrigger.java#L28

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
Sourcehttps://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/scripts/containers/core/InteractScriptContainer.java#L64

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

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

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

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

The radius that the proximity trigger detects at is set by Command:trigger.
GroupNPC Interact Scripts
Sourcehttps://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/scripts/triggers/core/ProximityTrigger.java#L21



Category: NPC Traits


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:EntityTag.health
Tag:EntityTag.formatted_health
Tag:EntityTag.health_max
Tag:EntityTag.health_percentage
Tag:NPCTag.has_trait[health]

Related Mechanisms
Mechanism:EntityTag.health
Mechanism:EntityTag.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
Sourcehttps://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/npc/traits/HealthTrait.java#L29

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
Sourcehttps://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/npc/traits/InvisibleTrait.java#L18

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
Sourcehttps://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/npc/traits/PushableTrait.java#L18



Category: Object System


NameElementTag(Boolean)
DescriptionWhen "ElementTag(Boolean)" appears in meta documentation, this means the input/output is an ElementTag
(refer to Language:ElementTag) that is a boolean.
Boolean means either a "true" or a "false".
GroupObject System
Sourcehttps://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/objects/core/ElementTag.java#L56

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

In some cases, this will also be documented as "<#.#>".
GroupObject System
Sourcehttps://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/objects/core/ElementTag.java#L77

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

In some cases, this will also be documented as "<#>".
GroupObject System
Sourcehttps://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/objects/core/ElementTag.java#L65

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 '[email protected]', the x being the specific
notation of an object type. Example: player objects use the [email protected] notation, and locations use [email protected]
This notation is automatically generated when directly displaying objects, or saving them into data files.
It should never be manually typed into a script.

Let's take the tag system, for example. It uses the ObjectTags system pretty heavily. For instance,
every time you use <player.name> or <npc.id>, you're using a ObjectTag, which brings us to a simple
clarification: Why <player.name> and not <PlayerTag.name>? That's because Denizen allows Players,
NPCs and other 'in-context objects' to be linked to certain scripts. In short, <player> already
contains a reference to a specific player, such as the player that died in a world event 'on player dies'.
<PlayerTag.name> is instead the format for documentation, with "PlayerTag" simply indicating 'any player object here'.

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

There's a great deal more to learn about ObjectTags, so be sure to check out each object type for more
specific information. While all ObjectTags share some features, many contain goodies on top of that!
GroupObject System
Sourcehttps://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/utilities/CommonRegistries.java#L28

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

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

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

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

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

For example, a LocationTag refers to a unique block in the world (like, '[email protected],2,3,world' is always that specific block at that position),
but also is a generic object in terms of the location object itself - if for example you want to change the angle of a location,
you have to essentially 'create' a new location, that is an exact copy of the previous one but with a new yaw or pitch value.
GroupObject System
Sourcehttps://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/objects/ObjectTag.java#L77



Category: Properties


NameAttribute Modifiers
DescriptionIn minecraft, the "attributes" system defined certain core numerical values on entities, such as max health or attack damage.
The value of an "attribute" is determined by its "base value" modified mathematically by each of its "attribute modififers".
"Attribute modifiers" can be added either directly to the entity, or onto items - when on an item, an entity can equip it into the correct slot to automatically apply the modifier.

These can be read via such tags as Tag:EntityTag.attribute_modifiers, Tag:ItemTag.attribute_modifiers,
Tag:EntityTag.has_attribute, Tag:EntityTag.attribute_value, Tag:EntityTag.attribute_base_value, Tag:EntityTag.attribute_default_value, ...

These can be modified by such mechanisms as Mechanism:EntityTag.attribute_base_values, Mechanism:EntityTag.attribute_modifiers, Mechanism:EntityTag.add_attribute_modifiers,
Mechanism:EntityTag.remove_attribute_modifiers, Mechanism:ItemTag.attribute_modifiers, Mechanism:ItemTag.add_attribute_modifiers, Mechanism:ItemTag.remove_attribute_modifiers, ...

The input format of each of the 'add' and set mechanisms is slightly complicated: a MapTag where the keys are attribute names, and values are a ListTag of modifiers,
where each modifier is itself a MapTag with required keys 'operation' and 'amount', and optional keys 'name', 'slot', and 'id'.

Valid operations: ADD_NUMBER, ADD_SCALAR, and MULTIPLY_SCALAR_1
Valid slots: HAND, OFF_HAND, FEET, LEGS, CHEST, HEAD, ANY
Valid attribute names are listed at URL:https://hub.spigotmc.org/javadocs/spigot/org/bukkit/attribute/Attribute.html
The default ID will be randomly generated, the default name will be the attribute name, the default slot is any.

For a quick and dirty in-line input, you can do for example: [generic_max_health=<list[<map[operation=ADD_NUMBER;amount=20;slot=HEAD]>]>]

For more clean/proper input, instead do something like:

- definemap attributes:
    generic_max_health:
        1:
            operation: ADD_NUMBER
            amount: 20
            slot: head
- inventory adjust slot:head add_attribute_modifiers:<[attributes]>


When pre-defining a custom item, instead of any of this, simply use an item script: Language:item script containers. That page shows an example of valid attribute modifiers on an item script.
GroupProperties
Sourcehttps://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/objects/properties/entity/EntityAttributeModifiers.java#L169

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.
The list of values can be gotten in-script via Tag:EntityTag.allowed_colors.

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 cats (not ocelots), 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 villagers, the types are DESERT, JUNGLE, PLAINS, SAVANNA, SNOW, SWAMP, and TAIGA.
For tropical_fish, the input is PATTERN|BODYCOLOR|PATTERNCOLOR, where BodyColor and PatterenColor are both DyeColor (see below),
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 Tipped Arrow entities, the input is a ColorTag.
For goats, the input is SCREAMING or NORMAL.
For axolotl, the input is BLUE, CYAN, GOLD, LUCY, or WILD.

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
Sourcehttps://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/objects/properties/entity/EntityColor.java#L206



Category: Script Command System


Name~Waitable
DescriptionA command that is "~Waitable" (or "Holdable", or that can be "~waited for") is a command that:
- Might potentially take a while to execute
- Is able to perform a slowed execution (that doesn't freeze the server)
- And so supports the "~" prefix.

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

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

Some commands, particularly those related to file operation, when ~waited for will move the file operation off-thread.
Others may need to be on the server thread, and may split the operation into smaller segments spread out over 1 tick each or similar logic.
Some of these commands, when NOT waited for, will freeze the server thread until the operation completes.
Others, however, may still perform the action in a delayed/slow/off-thread manner, but simply not hold the queue.
GroupScript Command System
Sourcehttps://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/scripts/commands/Holdable.java#L9

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

You merely need to look at the command's usage/syntax info.
Let's take for example:

- animatechest [<location>] ({open}/close) (sound:{true}/false)

Obviously, the command is 'animatechest'... but what does the rest of it mean?

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

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

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

Highly specific note: <commands> means a block of commands wrapped in braces or as a sub-block... EG:

- repeat 3:
  - narrate "<[value]>"
  - narrate "everything spaced out as a sub-block (these two narrates) following a ":" ended command (that repeat) is for the <commands> input!"
GroupScript Command System
Sourcehttps://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/scripts/commands/CommandRegistry.java#L47

NameThe Global If Argument
DescriptionThe "if:<boolean>" argument is a special meta-argument that is available for all commands, but is more useful for some than others.
It is written like:

- stop if:<player.has_flag[forbidden]>
# Equivalent to
- if <player.has_flag[forbidden]>:
  - stop


When the if argument is used, the command will only run if the value of the argument is 'true'.

The most useful place to have this is a 'stop' command, to quickly stop a script if a condition is true (a player has a flag, lacks a permission, is outside a region, or whatever else).

If you need more complex matching, especially using '&&', '||', '==', etc. you should probably just do an 'if' command rather than using the argument.
Though if you really want to, you can use tags here like Tag:objecttag.is.to or Tag:elementtag.and or Tag:elementtag.or.
GroupScript Command System
Sourcehttps://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/scripts/commands/CommandExecutor.java#L57

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

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

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

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

These arguments will also affect tags (mainly "<player>" and "<npc>") in the same command line (regardless of argument order).
If you need to use the original player/NPC in a tag on the same line, use the define command to track it.
GroupScript Command System
Sourcehttps://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/utilities/implementation/DenizenCoreImplementation.java#L186

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

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

The useful entry keys available for any command are listed in the "Tags" documentation section for any command.
For example, the "run" command lists "<entry[saveName].created_queue>".
The "saveName" part should be replaced with whatever name you gave to the "save" argument,
and the "created_queue" part changes between commands.
Some commands have multiple save entry keys, some have just one, most don't have any.
GroupScript Command System
Sourcehttps://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/scripts/commands/CommandExecutor.java#L40



Category: Script 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

  # | All assignment scripts MUST have this key!
  actions:
    on <action>:
    - ...

  # | Most assignment scripts should exclude this key, but it's available.
  default constants:
    <constant_name>: <value>
    <constant_list>:
    - ...

  # | MOST assignment scripts should have this key!
  interact scripts:
  - <interact_script_name>


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

Though note that almost always you should include the 'actions:' key, usually with the 'on assignment:' action (if using triggers).
Refer to Action:assignment.
GroupScript Container System
Sourcehttps://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/scripts/containers/core/AssignmentScriptContainer.java#L9

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.
  # | All book scripts MUST have this key!
  title: custom name

  # The 'custom name' can be anything you wish.
  # | All book scripts MUST have this key!
  author: custom name

  # Defaults to true. Set to false to spawn a 'book and quill' instead of a 'written book'.
  # | Some book scripts might have this key!
  signed: true/false

  # Each -line in the text section represents an entire page.
  # To create a newline, use the tag <n>. To create a paragraph, use <p>.
  # | All book scripts MUST have this key!
  text:
  - page
  - ...
GroupScript Container System
Sourcehttps://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/scripts/containers/core/BookScriptContainer.java#L19

NameCommand Script Containers
DescriptionCommand script containers allow you to register your own custom commands to the server.
This also allows the command to show up in the '/help' command, with some info on the command.

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

The following is the format for the container.

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

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


# The name of the script doesn't matter, and will not affect the command in any way.
Command_Script_Name:

  type: command

  # The name of the command. This will be the default method for running the command, and will show in '/help'.
  # | All command scripts MUST have this key!
  name: mycmd

  # The description of the command. This will be shown in the '/help' command.
  # Multiple lines are acceptable, via <&nl> (the tag for a new line), but you should
  # make the first line a brief summary of what your command does.
  # | All command scripts MUST have this key!
  description: My command.

  # Correct usage for the command. This will show in the '/help' command.
  # This is NOT the name of the command, and it is NOT used to control input parsing. It is EXCLUSIVELY for '/help'.
  # | All command scripts MUST have this key!
  usage: /mycmd <&lt>myArg1<&gt>

  # A list of aliases for the command. These will be used as alternative ways to trigger the command, and will show in the '/help' command.
  # | Some command scripts might have this key, but it's optional.
  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.
  # Note that you can include multiple permission nodes (a player only needs to have any one permission from the list)
  # by separating them with a semicolon, like: perm.one;perm.two;third.perm
  # | Most command scripts should have this key!
  permission: my.permission.node

  # The message to send to the player when they try to use the command without
  # permission. If this is not specified, the default Bukkit message will be sent.
  # | Most command scripts should NOT have this key, but it's available.
  permission message: Sorry, <player.name>, you can't use my command because you don't have the permission '<permission>'!

  # The procedure-based script that will be checked when a player or the console
  # is trying to view help for this command. This must always be determined true
  # or false. If there is no script, it's assumed that all players and the console
  # should be allowed to view the help for this command.
  # Available context: <context.server> returns whether the server is viewing the help (a player if false).
  # | Most command scripts should NOT have this key, but it's available.
  allowed help:
  - determine <player.has_flag[special_allowed_help_flag]||<context.server>>

  # You can optionally specify tab completions on a per-argument basis.
  # Available context:
  # <context.args> returns a list of input arguments.
  # <context.raw_args> returns all the arguments as raw text.
  # <context.server> returns whether the server is using tab completion (a player if false).
  # <context.alias> returns the command alias being used.
  # | This key is great to have when used well, but is not required.
  tab completions:
    # This will complete "alpha" and "beta" for the first argument
    1: alpha|beta
    # This will complete any online player name for the second argument
    2: <server.online_players.parse[name]>
    # This will allow flags "-a", "-b", or "-c" to be entered in the third, fourth, or fifth argument.
    3 4 5: -a|-b|-c
    # Any argument other than the ones explicitly listed will be handled here with a tab complete that just says 'StopTyping'.
    default: StopTyping

  # You can also optionally use the 'tab complete' key to build custom procedure-style tab complete logic
  # if the simply numeric argument basis isn't sufficient.
  # Has the same context available as 'tab completions'.
  # | Most scripts should leave this key off, though it can be useful to some.
  tab complete:
  - determine some|dynamic|logic|here

  # The script that will run when the command is executed.
  # No, you do not need '- determine fulfilled' or anything of the sort, since the command is fully registered.
  # Available context:
  # <context.args> returns a list of input arguments.
  # <context.raw_args> returns all the arguments as raw text.
  # <context.source_type> returns the source of the command. Can be: PLAYER, SERVER, COMMAND_BLOCK, or COMMAND_MINECART.
  # <context.alias> returns the command alias being used.
  # <context.command_block_location> returns the command block's location (if the command was run from one).
  # <context.command_minecart> returns the EntityTag of the command minecart (if the command was run from one).
  # | All command scripts MUST have this key!
  script:
  - narrate Yay!
  - narrate "My command worked!"
  - narrate "And I typed '/<context.alias> <context.raw_args>'!"
GroupScript Container System
Sourcehttps://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/scripts/containers/core/CommandScriptContainer.java#L28

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

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.

Custom objects exist for experimental reasons. Use at your own risk.

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 [email protected]_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
Sourcehttps://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/scripts/containers/core/CustomScriptContainer.java#L25

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

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

There are no required keys.

Generally, data is read using the Tag:ScriptTag.data_key tag.


data_script_name:

  type: data

  # Your data here
  some_key: some value
  some_list_key:
  - some list value
  some_map_key:
    some_subkey: some value

GroupScript Container System
Sourcehttps://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/scripts/containers/core/DataScriptContainer.java#L9

NameEnchantment Script Containers
DescriptionEnchantment script containers allow you to register custom item enchantments.
For the most part, they work similarly to vanilla enchantments, albeit with some limitations.
These can be attached to enchanted books and used in anvils,
and can be generated by the enchanting table (requires discoverable: true and treasure_only: false).

In current implementation, custom enchantments do not appear in lore on their own, and will need fake lore added in their place.
This might be fixed in the future.

It may be beneficial in some cases to restart your server after making changes to enchantments, rather than just reloading scripts.

Using these may cause unpredictable compatibility issues with external plugins.


Enchantment_Script_Name:

  type: enchantment

  # The ID is used as the internal registration key, and for lookups with things like the 'enchantments' mechanism.
  # If unspecified, will use the script name.
  # Limited to A-Z or _.
  # | Most enchantment scripts should have this key!
  id: my_id

  # A list of slots this enchantment is valid in.
  # | ALL enchantment scripts MUST have this key!
  slots:
  # Can be any of: mainhand, offhand, feet, legs, chest, head
  - mainhand

  # The rarity level of this enchantment. Can be any of: COMMON, UNCOMMON, RARE, VERY_RARE
  # If unspecified, will use COMMON.
  # | Most enchantment scripts should have this key!
  rarity: common

  # The category/type of this enchantment. Can be any of: ARMOR, ARMOR_FEET, ARMOR_LEGS, ARMOR_CHEST, ARMOR_HEAD,
  # WEAPON, DIGGER, FISHING_ROD, TRIDENT, BREAKABLE, BOW, WEARABLE, CROSSBOW, VANISHABLE
  # This is used internally by the enchanting table to determine which items to offer the enchantment for.
  # If unspecified, will use WEAPON.
  # | Most enchantment scripts should have this key!
  category: weapon

  # The per-level full name of this enchantment. Does not appear in lore automatically (but might in the future?).
  # Can make use of "<context.level>" for the applicable level.
  # | Most enchantment scripts should have this key!
  full_name: My Enchantment <context.level>

  # The minimum level of this enchantment.
  # If unspecified, will use 1.
  # | Most enchantment scripts can exclude this key.
  min_level: 1

  # The maximum level of this enchantment.
  # If unspecified, will use 1.
  # | Some enchantment scripts should have this key.
  max_level: 1

  # The per-level minimum XP cost of enchanting.
  # Can make use of "<context.level>" for the applicable level.
  # | Most enchantment scripts should have this key!
  min_cost: <context.level.mul[1]>

  # The per-level maximum XP cost of enchanting.
  # Can make use of "<context.level>" for the applicable level.
  # | Most enchantment scripts should have this key!
  max_cost: <context.level.mul[1]>

  # Whether this enchantment is only considered to be treasure. Treasure enchantments do not show in the enchanting table.
  # If unspecified, will be false.
  # | Most enchantment scripts can exclude this key.
  treasure_only: false

  # Whether this enchantment is only considered to be a curse. Curses are removed at grindstones, and spread from crafting table repairs.
  # If unspecified, will be false.
  # | Most enchantment scripts can exclude this key.
  is_curse: false

  # Whether this enchantment is only considered to be tradable. Villagers won't trade this enchantment if set to false.
  # If unspecified, will be true.
  # | Most enchantment scripts can exclude this key.
  is_tradable: true

  # Whether this enchantment is only considered to be discoverable.
  # If true, this will spawn from vanilla sources like the enchanting table. If false, it can only be given directly by script.
  # If unspecified, will be true.
  # | Most enchantment scripts can exclude this key.
  is_discoverable: true

  # A tag that returns a boolean indicating whether this enchantment is compatible with another.
  # Can make use of "<context.enchantment_key>" for the applicable enchantment's key, like "minecraft:sharpness".
  # This is used internally by the enchanting table and the anvil to determine if this enchantment can be given alongside another.
  # If unspecified, will default to always true.
  # | Most enchantment scripts can exclude this key.
  is_compatible: <context.enchantment_key.advanced_matches[minecraft:lure|minecraft:luck*]>

  # A tag that returns a boolean indicating whether this enchantment can enchant a specific item.
  # Can make use of "<context.item>" for the applicable ItemTag.
  # This is used internally to decide whether survival players can copy the enchantment between items on an anvil, as well as for commands like "/enchant".
  # If unspecified, will default to always true.
  # | Most enchantment scripts can exclude this key.
  can_enchant: <context.item.advanced_matches[*_sword|*_axe]>

  # A tag that returns a decimal number indicating how much extra damage this item should deal.
  # Can make use of "<context.level>" for the enchantment level,
  # and "<context.type>" for the type of monster being fought: ARTHROPOD, ILLAGER, WATER, UNDEAD, or UNDEFINED
  # If unspecified, will default to 0.0.
  # | Most enchantment scripts can exclude this key.
  damage_bonus: 0.0

  # A tag that returns an integer number indicating how much this item should protection against damage.
  # Can make use of "<context.level>" for the enchantment level, and "<context.cause>" for the applicable damage cause, using internal cause names (different from Spigot Damage Causes).
  # Internal cause names: inFire, lightningBolt, onFire, lava, hotFloor, inWall, cramming, drown, starve, cactus, fall, flyIntoWall,
  # outOfWorld, generic, magic, wither, anvil, fallingBlock, dragonBreath, dryout, sweetBerryBush, freeze, fallingStalactite, stalagmite
  # Also "<context.attacker>" as an EntityTag if the cause has an attacker specified.
  # If unspecified, will default to 0.
  # | Most enchantment scripts can exclude this key.
  damage_protection: 0

  # Triggered after an enchanted weapon is used to attack an entity.
  # Has <context.attacker> (EntityTag), <context.victim> (EntityTag), and <context.level>.
  # May fire rapidly or multiple times per hit. Use a ratelimit to prevent this.
  # | Some enchantment scripts should have this key.
  after attack:
  - narrate "You attacked <context.victim.name> with a <context.level> enchantment!"

  # Triggered after an enchanted armor is used to defend against an attack.
  # Also fires if an entity is holding a weapon with this enchantment while being hit.
  # Has <context.attacker> (EntityTag), <context.victim> (EntityTag), and <context.level>.
  # | Some enchantment scripts should have this key.
  after hurt:
  - narrate "You got hurt by <context.attacker.name> and protected by a level <context.level> enchantment!"
GroupScript Container System
Sourcehttps://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/scripts/containers/core/EnchantmentScriptContainer.java#L33

NameEntity Script Containers
DescriptionEntity script containers are an easy way to pre-define custom entities for use within scripts. Entity
scripts work with the EntityTag object, and can be fetched with the Object Fetcher by using the
EntityTag constructor of simply the script name. Example: - spawn <player.location> MyEntity

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

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


# The name of the entity script is the same name that you can use to construct a new
# EntityTag based on this entity script. For example, an entity script named 'space_zombie'
# can be referred to as 'space_zombie'.
Entity_Script_Name:

  type: entity

  # Must be a valid EntityTag (EG 'zombie' or 'pig[age=baby]') See 'EntityTag' for more information.
  # | All entity scripts MUST have this key!
  entity_type: BASE_ENTITY_TYPE_HERE

  # If you want custom data that won't be parsed, use the 'data' root key.
  # | Some entity scripts should have this key!
  data:
    example_key: example value

  # You can set flags on the entity when it spawns.
  # | Some entity scripts should have this key!
  flags:
    my_flag: my value

  # Specify any mechanisms to apply the entity when it spawns.
  # | Some entity scripts should have this key!
  mechanisms:

    # Samples of mechanisms to use (any valid EntityTag mechanisms may be listed like this):

    # Whether the entity has the default AI
    # | Do not copy this line, it is only an example.
    has_ai: true/false

    # What age the entity is
    # | Do not copy this line, it is only an example.
    age: baby/adult/<#>


MORE MECHANISM OPTIONS ARE LISTED HERE: URL:https://meta.denizenscript.com/Docs/Mechanisms/entitytag.
GroupScript Container System
Sourcehttps://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/scripts/containers/core/EntityScriptContainer.java#L26

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


Format_Script_Name:

  type: format

  # The only key is the format. The format can use '<text>' as a special tag to contain the message being sent.
  # '<name>' is available as a special tag as well for use with the 'on player chats' event to fill the player's name properly.
  # | All format scripts MUST have this key!
  format: <name> says <text>
GroupScript Container System
Sourcehttps://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/scripts/containers/core/FormatScriptContainer.java#L16

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 an interact script container is the 'steps:' key.

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

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

Refer to Language:interact script triggers for documentation about the triggers available.
Any triggers used must be enabled in Action:assignment by Command:trigger.

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


Interact_Script_Name:

  type: interact

  # | All interact scripts MUST have this key!
  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
Sourcehttps://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/scripts/containers/core/InteractScriptContainer.java#L18

NameInventory Script Containers
DescriptionInventory script containers are an easy way to pre-define custom inventories for use within scripts.
Inventory scripts work with the InventoryTag object, and can be fetched with the Object Fetcher by using the
InventoryTag constructor InventoryTag_script_name.

Example: - inventory open d:MyInventoryScript

The following is the format for the container.

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


# The name of the script is the same name that you can use to construct a new
# InventoryTag based on this inventory script. For example, an inventory script named 'Super_Cool_Inventory'
# can be referred to as 'Super_Cool_Inventory'.
Inventory_Script_Name:

  type: inventory

  # Must be a valid inventory type.
  # Valid inventory types: BREWING, CHEST, DISPENSER, ENCHANTING, ENDER_CHEST, HOPPER, WORKBENCH
  # | All inventory scripts MUST have this key!
  inventory: inventory type

  # The title can be anything you wish. Use color tags to make colored titles.
  # Note that titles only work for some inventory types, including CHEST, DISPENSER, FURNACE, ENCHANTING, and HOPPER.
  # | MOST inventory scripts should have this key!
  title: custom title

  # The size must be a multiple of 9. It is recommended to not go above 54, as it will not show correctly when a player looks into it.
  # | Some inventory scripts should have this key! Most can exclude it if 'slots' is used.
  size: 27

  # Set 'gui' to 'true' to indicate that the inventory is a GUI, meaning it's a set of buttons to be clicked, not a container of items.
  # This will prevent players from taking items out of or putting items into the inventory.
  # | SOME inventory scripts should have this key!
  gui: true

  # You can use definitions to define items to use in the slots. These are not like normal script definitions, and do not need to be in a definition tag.
  # | Some inventory scripts MAY have this key, but it is optional. Most scripts will just specify items directly.
  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.
  # | Most inventory scripts should exclude this key, but it may be useful in some cases.
  procedural items:
    - define list <list>
    - foreach <server.online_players>:
      # Insert some form of complex doesn't-fit-in-just-a-tag logic here
      - define item <[value].skull_item>
      - define list:->:<[item]>
    - determine <[list]>

  # You can specify the items in the slots of the inventory. For empty spaces, simply put an empty "slot" value, like "[]".
  # Note the quotes around the entire lines.
  # | Most inventory scripts SHOULD have this key!
  slots:
    - [] [] [] [my item] [ItemTag] [] [other item] [] []
    - [my item] [] [] [] [] [ItemTag] [ItemTag] [] []
    - [] [] [] [] [] [] [] [] [other item]
GroupScript Container System
Sourcehttps://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/scripts/containers/core/InventoryScriptContainer.java#L25

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

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


# The name of the item script is the same name that you can use to construct a new
# ItemTag based on this item script. For example, an item script named 'sword_of_swiftness'
# can be referred to as simply 'sword_of_swiftness'.
Item_Script_Name:

  type: item

  # Must be a valid ItemTag. See 'ItemTag' for more information.
  # | All item scripts MUST have this key!
  material: base_material

  # List any mechanisms you want to apply to the item within
  # | Some item scripts should have this key!
  mechanisms:
    # An example of a mechanism to apply
    unbreakable: true
    # Other common example
    custom_model_data: 5
    # This demonstrates how to add a custom attribute modifier.
    attribute_modifiers:
        # One subkey for each attribute you want to modify.
        # Valid attribute names are listed at https://hub.spigotmc.org/javadocs/spigot/org/bukkit/attribute/Attribute.html
        generic_armor:
            # Each attribute can have a list of modifiers, using numbered keys. They will be applied in numeric order, low to high.
            1:
                # Each modifier requires keys 'operation' and 'amount', and can optionally have keys 'name', 'slot', and 'id'.
                # Operations can be: ADD_NUMBER, ADD_SCALAR, and MULTIPLY_SCALAR_1
                operation: add_number
                amount: 5
                # Slots can be: HAND, OFF_HAND, FEET, LEGS, CHEST, HEAD, ANY
                slot: head
                # ID is a UUID used to uniquely identify modifiers. If unspecified the ID will be randomly generated.
                # Items with modifiers that lack IDs cannot be stacked due to the random generation.
                id: 10000000-1000-1000-1000-100000000000

  # The 'custom name' can be anything you wish. Use color tags to make colored custom names.
  # | Some item scripts should have this key!
  display name: custom name

  # Lore lines can make items extra unique. This is a list, so multiple entries will result in multiple lores.
  # If using a replaceable tag, they are filled in when the item script is given/created/dropped/etc.
  # | Some item scripts should have this key!
  lore:
  - item
  - ...

  # If you want an item to be damaged on creation, you can change its durability.
  # | Most item scripts should exclude this key!
  durability: 12

  # Each line must specify a valid enchantment name.
  # | Some item scripts should have this key!
  enchantments:
  - enchantment_name:level
  - ...

  # Set this to 'true' to allow the item script item to be used in material-based recipe (eg most vanilla recipes).
  # Defaults to false if unspecified.
  # | Most item scripts should exclude this key!
  allow in material recipes: false

  # You can specify flags to be added to the item.
  flags:
    # Each line within the flags section should be a flag name as a key, and the flag value as the value.
    # You can use lists or maps here the way you would expect them to work.
    my_flag: my value

  # You can optionally add crafting recipes for your item script.
  # Note that recipes won't show in the recipe book when you add a new item script, until you either reconnect or use the "resend_recipes" mechanism.
  # | Most item scripts should exclude this key, unless you're specifically building craftable items.
  recipes:
      1:
          # The type can be: shaped, shapeless, stonecutting, furnace, blast, smoker, or campfire.
          # | All recipes must include this key!
          type: shaped
          # The recipe can optionally have a custom internal recipe ID (for recipe books).
          # If not specified, will be of the form "<type>_<script.name>_<id>" where ID is the recipe list index (starting at 1, counting up).
          # IDs will always have the namespace "denizen". So, for the below, the full ID is "denizen:my_custom_item_id"
          # Note that most users should not set a custom ID. If you choose to set a custom one, be careful to avoid duplicates or invalid text.
          # Note that the internal rules for Recipe IDs are very strict (limited to "a-z", "0-9", "/", ".", "_", or "-").
          # | Most recipes should exclude this key.
          recipe_id: my_custom_item_id
          # You can optional add a group as well. If unspecified, the item will have no group.
          # Groups are used to merge together similar recipes in the recipe book (in particular, multiple recipes for one item).
          # | Most recipes should exclude this key.
          group: my_custom_group
          # You can optionally specify the quantity to output. The default is 1 (or whatever the item script's quantity is).
          # | Only some recipes should have this key.
          output_quantity: 4
          # You must specify the input for the recipe. The below is a sample of a 3x3 shaped recipe. Other recipe types have a different format.
          # You are allowed to have non-3x3 shapes (can be any value 1-3 x 1-3, so for example 1x3, 2x1, and 2x2 are fine).
          # For an empty slot, use "air".
          # By default, items require an exact match. For a material-based match, use the format "material:MaterialNameHere" like "material:stick".
          # To make multiple different items match for any slot, just separate them with slashes, like "stick/stone".
          # To match multiple materials, use "material:a/b/c".
          # You can also make a dynamic matcher using '*', like "material:*_log" to match any log block,
          # or 'test_*' to match any item script that has name starting with 'test_'.
          # Note that to require multiple of an item as an input, the only option is to use multiple slots.
          # A single slot cannot require a quantity of items, as that is not part of the minecraft recipe system.
          # | All recipes must include this key!
          input:
          - ItemTag|ItemTag|ItemTag
          - ItemTag|ItemTag|ItemTag
          - ItemTag|ItemTag|ItemTag
     # You can add as many as you want.
     2:
          # Sample of the format for a 2x2 recipe
          type: shaped
          input:
          - ItemTag|ItemTag
          - ItemTag|ItemTag
     3:
         # Shapeless recipes take a list of input items.
         type: shapeless
         input: ItemTag|...
     4:
         # Stonecutting recipes take exactly one input item.
         type: stonecutting
         input: ItemTag
     5:
         # Furnace, blast, smoker, and campfire recipes take one input and have additional options.
         type: furnace
         # Optionally specify the cook time as a duration (default 2s).
          # | Only some recipes should have this key.
         cook_time: 1s
         # Optionally specify experience reward amount (default 0).
          # | Only some recipes should have this key.
         experience: 5
         input: ItemTag
     6:
         # Smithing recipes take one base item and one upgrade item.
         type: smithing
         base: ItemTag
         upgrade: ItemTag

  # 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.
  # | Most item scripts should exclude this key!
  no_id: true/false

  # If your material is a 'written_book', you can specify a book script to automatically scribe your item
  # upon creation. See 'book script containers' for more information.
  # | Most item scripts should exclude this key, though there are certain rare cases it may be useful to.
  book: book_script_name
GroupScript Container System
Sourcehttps://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/scripts/containers/core/ItemScriptContainer.java#L29

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

  type: map

  # Whether to display the original map below the custom values. Defaults to true.
  # | Some map scripts should have this key!
  original: true/false

  # Whether to constantly update things. Defaults to true.
  # | Some map scripts should have this key!
  auto update: true

  # Whether this map script renders uniquely per-player. Defaults to true.
  # | Some map scripts should have this key!
  contextual: true

  # Lists all contained objects.
  # | Most map scripts should have this key!
  objects:

    # The first object...
    1:
      # Specify the object type
      # Type can be IMAGE, TEXT, CURSOR, or DOT.
      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.
      width: 128
      height: 128

    2:
      type: text
      # Specify any text to display. Color codes not permitted (unless you know how to format CraftMapCanvas byte-ID color codes).
      text: Hello <player.name>
      # Specify the color of the text as any valid ColorTag.
      color: red
      # Specify a tag to show or hide custom content! Valid for all objects.
      # Note that all inputs other than 'type' for all objects support tags that will be dynamically reparsed per-player each time the map updates.
      visible: <player.name.contains[bob].not>

    3:
      type: cursor
      # Specify a cursor type
      cursor: red_marker
      # Optionally, specify a cursor direction. '180' seems to display as up-right usually.
      direction: 180
      # Supported on all objects: x/y positions, and whether to use worldly or map coordinates.
      x: 5
      # If 'world_coordinates' is set to 'true', the 'y' value corresponds to the 'z' value of a location.
      y: 5
      # If true: uses world coordinates. If false: uses map local coordinates. (Defaults to false).
      world_coordinates: false
      # If true: when the object goes past the edge, will stay in view at the corner. If false: disappears past the edge (defaults to false).
      show_past_edge: false

    4:
      type: dot
      # Specify the radius of the dot.
      radius: 1
      # Specify the color of the dot as any valid ColorTag.
      color: red



A list of cursor types is available through Tag:server.map_cursor_types.
GroupScript Container System
Sourcehttps://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/scripts/containers/core/MapScriptContainer.java#L22

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

Generally called via Tag:proc or Tag:proc.context.

The only required key is 'script:'.

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

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


Proc_Script_Name:

  type: procedure

  # Optionally specify definition names to use with the 'context' input of the proc tag.
  definitions: def|names|here

  script:

  # Put any logic, then determine the result.
  - determine 5

GroupScript Container System
Sourcehttps://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/scripts/containers/core/ProcedureScriptContainer.java#L8

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
Sourcehttps://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/scripts/containers/ScriptContainer.java#L18

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
Sourcehttps://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/scripts/containers/ScriptContainer.java#L89

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


script name:
  type: script_type  <--- script type
  script:
    - script entries
    - ...
GroupScript Container System
Sourcehttps://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/scripts/containers/ScriptContainer.java#L154

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

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

  script:

  - your commands here

GroupScript Container System
Sourcehttps://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/scripts/containers/core/TaskScriptContainer.java#L14

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
Sourcehttps://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/scripts/containers/core/WorldScriptContainer.java#L10

NameEconomy Script Containers
DescriptionEconomy script containers

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

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

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

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

GroupScript Container System
RequiresVault
Sourcehttps://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/scripts/containers/core/EconomyScriptContainer.java#L30



Category: Script Events


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

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

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

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

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

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

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

If you want to match anything *except* a specific value, just prefix the matcher with '!'
For example, on player breaks !stone:" will fire for a player breaking any block type OTHER THAN stone.
This can be combined with other match modes, like "on player breaks !*wood|*planks|*log:" will fire for any block break other than any wood variant.

See also Language:script event object matchables.

These advanced matchers are also used in some commands and tags.
GroupScript Events
Sourcehttps://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/events/ScriptEvent.java#L527

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
Sourcehttps://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/events/BukkitScriptEvent.java#L453

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

The most common example of this is editing a player's inventory, within an inventory-related event.
Generally speaking, this problem becomes relevant any time an edit is made to something involved with an event,
within the firing of that event.
Take the following examples:

on player clicks in inventory:
- take iteminhand
on entity damaged:
- remove <context.entity>


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

The solution to this problem is simple: Use "after" instead of "on".

after player clicks in inventory:
- take iteminhand
after entity damaged:
- if <context.entity.is_spawned||false>:
  - remove <context.entity>

This will delay the script until *after* the event is complete, and thus outside of the problem area.
And thus should be fine. One limitation you should note is demonstrated in the second example event:
The normal guarantees of the event are no longer present (eg that the entity is still valid) and as such
you should validate these expectations remain true after the event (as seen with the 'if is_spawned' check).

If you need determine changes to the event, you can instead use 'on' but add a 'wait 1t' after the determine but before other script logic.
This allows the risky parts to be after the event and outside the problem area, but still determine changes to the event.
Be sure to use 'passively' to allow the script to run in full.

on player clicks in inventory:
- determine passively cancelled
- wait 1t
- take iteminhand
on entity damaged:
- determine passively cancelled
- wait 1t
- if <context.entity.is_spawned||false>:
  - remove <context.entity>
GroupScript Events
Sourcehttps://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/events/BukkitScriptEvent.java#L841

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

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

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

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
Sourcehttps://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/events/ScriptEvent.java#L313

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

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

"<item>" or similar expects of course an ItemTag.
You can use any valid item material type like "stick", or the name of an item script, or "item" as a catch-all, or "potion" for any potion item.
Items can also be used with an "item_flagged" secondary prefix, so for an event that has "with:<item>", you can also do "with:item_flagged:<flag name>".
For item matchers that aren't switches, this works similarly, like "on player consumes item_flagged:myflag:" (note that this is not a switch).
You can also use "vanilla_tagged:<vanilla_tag_name>" to check vanilla tags, or "item_enchanted:<enchantment>" to check enchantments.
You can also use "raw_exact:<item>" to do an exact raw item data comparison (almost always a bad idea to use).

"<entity>", "<projectile>", "<vehicle>", etc. are examples of where an EntityTag will be expected.
You can generally specify any potentially relevant entity type, such as "creeper" under "<entity>", or "arrow" for "<projectile>",
but you can also specify "entity" (catch-all), "player" (real players, NOT player-type NPCs), "npc" (Citizens NPC),
"vehicle" (minecarts, boats, horses, etc), "fish" (cod, pufferfish, etc), "projectile" (arrow, trident, fish hook, snowball, etc), "hanging" (painting, item_frame, etc),
"monster" (creepers, zombies, etc), "animals" (pigs, cows, etc), "mob" (creepers, pigs, etc), "living" (players, pigs, creepers, etc),
"entity_flagged:<flag_name>", "npc_flagged:<flag_name>", "player_flagged:<flag_name>" (all three work similar to 'item_flagged').

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

"<world>" or similar expects of course a WorldTag.
You can use "world" as a catch-all, a world name, or "world_flagged:<flag_name>" (works similar to 'item_flagged').

"<area>" or similar refers to any area-defining tag type, including WorldTag, CuboidTag, EllipsoidTag, and PolygonTag.
You can specify the name of any world, the name of any noted area, "world_flagged:<flag_name>", "chunk_flagged:<flag_name>", "area_flagged:<flag_name>" (all work similar to 'item_flagged'),
"biome:<name> to match based on the location's biome,
"cuboid" for any noted cuboid, "ellipsoid" for any noted ellipsoid, or "polygon" for any noted polygon.

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

You can also do more advanced multi-matchers in any of these inputs.
For details on that, see Language:Advanced Script Event Matching.
GroupScript Events
Sourcehttps://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/events/BukkitScriptEvent.java#L40

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
Sourcehttps://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/events/ScriptEvent.java#L353

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
Sourcehttps://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/events/ScriptEvent.java#L497

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

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

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

There are also some standard switches available to every script event, and some available to an entire category of script events.

One switch available to every event is "server_flagged:<flag name>", which requires that there be a server flag under the given name.
For example, "on console output server_flagged:recording:" will only run the handler for console output when the "recording" flag is set on the server.

Events that have a player linked have the "flagged" and "permission" switches available.
Will always fail if the event doesn't have a linked player.
The "flagged:<flag name>" will limit the event to only fire when the player has the flag with the specified name.
It can be used like "on player breaks block flagged:nobreak:" (that would be used alongside "- flag player nobreak").
The "permission:<perm key>" will limit the event to only fire when the player has the specified permission key.
It can be used like "on player breaks block permission:denizen.my.perm:"
As with any advanced switch, for multiple flag or permission requirements, just list them separated by '|' pipes, like "flagged:a|b|c".

Events that occur at a specific location have the "in:<area>" and "location_flagged" switches.
This switches will be ignored (not counted one way or the other) for events that don't have a known location.
For "in:<area>" switches, 'area' is any area-defining tag type - refer to Language:Script Event Object Matchables.
"location_flagged:<flag name>" works just like "server_flagged" or the player "flagged" switches, but for locations.

All script events have priority switches (see Language:script event priority),
All Bukkit events have bukkit priority switches (see Language:bukkit event priority),
All cancellable script events have cancellation switches (see Language:script event cancellation).

See also Language:advanced script event matching.
GroupScript Events
Sourcehttps://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/events/ScriptEvent.java#L100



Category: Tag System


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

Fallbacks are implemented as special "magic tags" that look like any other tag-part, but override the error handler. These are "if_null", "exists", and "is_truthy".

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

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

The "exists" fallback-tag is available for checking whether an object exists and is valid.
What if we want to check if there even is a linked player? We don't have a "<has_player>" tag to do that, so what can we do?

- if <player.exists>:

The above example demonstrates using a fallback to check if a player is valid.
The if block will run only if there is not a player valid (you might, for example, place the "stop" command inside).

"Exists" is useful when you *only* need a check, however you often need to grab a value and verify it after.
Consider the following example, often found in command scripts:

- define target <server.match_player[<context.args.get[1]>].if_null[null]>
- if <[target]> == null:
    - narrate "<&[error]>Invalid player!"
    - stop
- narrate "<&[base]>You chose <&[emphasis]><[target].name><&[base]>!"


We use the word "null" in the above example, as well as in the tag name itself. This is a common programming term that means "no object is present".
"if_null" is the actual tag name, however the input value of "null" isn't actually a functionality of Denizen, it's just a word we choose for clarity.
You could just as easily do "- if <player.if_null[nothing]> == nothing:", or for that matter "- if <player.if_null[cheese]> == cheese:".
A player object takes the form "[email protected]", so it will therefore never exactly match any simple word, so there's no coincidental match edge-case to worry about.
Note that this won't work so perfect for things like a user input or fully dynamic value,
so in those cases you may want to use the "exists" tag explicitly to guarantee no potential conflict.

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

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

Prior to Denizen 1.2.0, fallbacks exclusively worked with a special "||" syntax, like "- if <player||null> == null:"
This syntax is still fully supported at time of writing, however the newer tag-based format is considered clearer and easier to learn.
GroupTag System
Sourcehttps://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/tags/Attribute.java#L342



Category: Useful Lists


NameDamage Cause
DescriptionPossible damage causes: URL:https://hub.spigotmc.org/javadocs/spigot/org/bukkit/event/entity/EntityDamageEvent.DamageCause.html
These are used in Event:entity damage, Tag:server.damage_causes, Tag:EntityTag.last_damage.cause, ...
GroupUseful Lists
Sourcehttps://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/events/entity/EntityDamagedScriptEvent.java#L20

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

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

The following actions are available:

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

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

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, for example "mykey[3]:value".
This also works with most actions.
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, for example "mykey[3]:<-"
GroupUseful Lists
Sourcehttps://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/utilities/data/DataActionType.java#L5

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.
GroupUseful Lists
Sourcehttps://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/utilities/entity/DenizenEntityType.java#L39

NameEscaping System
DescriptionSometimes, you need to avoid having symbols that might be misinterpreted in your data.
Denizen provides the tags Tag:ElementTag.escaped and Tag:ElementTag.unescaped to help deal with that.
Escaped replaces symbols with the relevant escape-code, and unescaped replaces the escape-codes with the real symbols.

Some older style tags and mechanisms may automatically use this same escaping system.

The mapping of symbols to escape codes is as follows:

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

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.
GroupUseful Lists
Sourcehttps://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/tags/core/EscapeTagBase.java#L30

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
Sourcehttps://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/events/player/PlayerClicksInInventoryScriptEvent.java#L21

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

Effects:
- Everything on URL:https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Particle.html
- Everything on URL:https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Effect.html
- RANDOM (chooses a random visual effect from the Particle list)
GroupUseful Lists
Sourcehttps://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/scripts/commands/world/PlayEffectCommand.java#L35

NameRaw NBT Encoding
DescriptionThe item Raw_NBT property encodes and decodes raw NBT data.
For the sake of inter-compatibility, a special standard format is used to preserve data types.
This system exists in Denizen primarily for the sake of compatibility with external plugins.
It should not be used in any scripts that don't rely on data from external plugins.

NBT Tags are encoded as follows:
CompoundTag: (a fully formed MapTag)
ListTag: list:(NBT type-code):(a fully formed ListTag)
ByteArrayTag: byte_array:(a pipe-separated list of numbers)
IntArrayTag: int_array:(a pipe-separated list of numbers)
ByteTag: byte:(#)
ShortTag: short:(#)
IntTag: int:(#)
LongTag: long:(#)
FloatTag: float:(#)
DoubleTag: double:(#)
StringTag: string:(text here)
EndTag: end
GroupUseful Lists
Sourcehttps://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/objects/properties/item/ItemRawNBT.java#L115

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.)
If the slot given is 'hand', for a player the held item slot will be used, for any other entity the slot will be 1.
OR you can give the following names (valid for player inventories only):
BOOTS: equivalent to 37
LEGGINGS: equivalent to 38
CHESTPLATE: equivalent to 39
HELMET: equivalent to 40
OFFHAND: equivalent to 41

Note that some common alternate spellings may be automatically accepted as well.
GroupUseful Lists
Sourcehttps://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/utilities/inventory/SlotHelper.java#L66



Category: Depenizen Bridges


NameMythicMobs Bridge
DescriptionIn addition to the the tags, commands, and events found by searching for "mythicmobs" throughout the meta documentation,
Depenizen adds additional features to Mythic Mobs: 2 Targeters, and a Condition.

Depenizen provides two additional targeters via the MythicMobs API: @DenizenEntity is an entity-based targeter, @DenizenLocation is a location-based targeter.
Both targeters can parse tags; they accept input of either an EntityTag or LocationTag respectively.
Both targeters also support returning ListTags containing their respective tag types.
Both targeters provide <context.entity> as an EntityTag of the caster.

Conditions provide different contexts depending on their usage.
The syntax for calling a Denizen tag as a condition is DenizenCondition.
The tag should return an ElementTag of a boolean value (true or false).
<context.location> is available for location-based checks,
<context.entity> is available for for entity- and caster-based checks,
and <context.target> is available for target-based checks.
NOTE: TriggerConditions are NOT currently supported.

Note as well that many parts of MythicMobs configurations allow usage of PlaceholderAPI, which means you can use the "denizen_" placeholder to read tags in any such parts,
refer to Language:PlaceholderAPI Bridge for more information.

Usage Examples

Example 1: @DenizenEntity{tag=<context.entity.location.find.players.within[30].filter[has_flag[marked]]>}

Example 2: @DenizenLocation{tag=<context.entity.location.find.surface_blocks.within[30].random[5]>}

Example 3: @DenizenEntity{tag=<proc[SomeProcScript]>}

Conditions:
- denizencondition{tag=<context.entity.location.find.players.within[30].is_empty.not>}
GroupDepenizen Bridges
RequiresDepenizen, MythicMobs
Sourcehttps://github.com/DenizenScript/Depenizen/blob/master/src/main/java/com/denizenscript/depenizen/bukkit/utilities/mythicmobs/MythicMobsLoaders.java#L19

NamePlaceholderAPI Bridge
DescriptionUsing Depenizen with PlaceholderAPI allows you to use Tag:placeholder and Tag:placeholder.player,
and also allows you to read Denizen tags from any PAPI placeholder location, written in the format: %denizen_<tag-here>%
For example: %denizen_<player.flag[MyFlag]>%
GroupDepenizen Bridges
RequiresDepenizen, PlaceholderAPI
Sourcehttps://github.com/DenizenScript/Depenizen/blob/master/src/main/java/com/denizenscript/depenizen/bukkit/bridges/PlaceholderAPIBridge.java#L20