Name | Number and Decimal |
Description | Many 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'. |
Group | Common Terminology |
Source | https://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/objects/ArgumentHelper.java#L14 |
Name | Tick |
Description | A 'tick' is usually referred to as 1/20th of a second, the speed at which Minecraft servers update
and process everything on them. |
Group | Common Terminology |
Source | https://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/utilities/CommonRegistries.java#L67 |
Name | Operator |
Description | An operator is a tool for comparing values, used by commands like if, while, waituntil, ... and tags like 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:" "does this object or text match an advanced matcher" is written as "matches". For example, "- if <player.location.below> matches stone:" 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[<<>].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: if |
Group | Comparables |
Source | https://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/scripts/commands/Comparable.java#L14 |
Name | /denizen debug command |
Description | Using 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. or, '--pfilter (filter)' to enable packet debug logging with a string contain filter. '-f' enables/disables showing of future warnings. When enabled, future warnings (such as upcoming deprecations) will be displayed in console logs. '-e' enables/disables extra output. This will spam more information about various internal things. '-v' enables/disables advanced ultra-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. |
Group | Console Commands |
Source | https://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/utilities/command/DenizenCommandHandler.java#L93 |
Name | /denizen submit command |
Description | Use 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.) |
Group | Console Commands |
Source | https://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/utilities/command/DenizenCommandHandler.java#L53 |
Name | /ex command |
Description | The '/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 The Player and NPC Arguments. Examples: /ex narrate player:<[aplayer]> 'Your health is <player.health.formatted>.' /ex walk npc:<[some_npc]> <player.cursor_on> |
Group | Console Commands |
Source | https://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/utilities/command/ExCommandHandler.java#L34 |
Name | /npc constant command |
Description | The /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. |
Group | Console Commands |
Source | https://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/utilities/command/NPCCommandHandler.java#L117 |
Name | /npc pushable command |
Description | The '/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' |
Group | Console Commands |
Source | https://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/utilities/command/NPCCommandHandler.java#L36 |
Name | Denizen Permissions |
Description | The following is a list of all permission nodes Denizen uses within Bukkit.
denizen.clickable # use the 'denizenclickable' command, which is automatically executed when using clickable and for clickable chat triggers 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>" ) |
Group | Console Commands |
Source | https://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/utilities/command/DenizenCommandHandler.java#L30 |
Name | Denizen Text Formatting |
Description | Denizen 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. |
Group | Denizen Magic |
Source | https://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/utilities/FormattedTextHelper.java#L25 |
Name | dScript |
Description | The 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. |
Group | Denizen Scripting Language |
Source | https://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/objects/core/ScriptTag.java#L44 |
Name | Flag System |
Description | The 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 https://guide.denizenscript.com/guides/basics/flags.html. For non-persistent temporary memory, see instead define. For more generic memory options, see yaml or sql. Flags can be sub-mapped with the '.' character, 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 flag, however items are primarily flagged via inventory with the 'flag' argument. Any supported object type, including the 'server' base tag, can use the tags FlaggableObject.flag, FlaggableObject.has_flag, FlaggableObject.flag_expiration, FlaggableObject.list_flags. Additionally, flags be searched for with tags like server.online_players_flagged, server.players_flagged, server.spawned_npcs_flagged, server.npcs_flagged, ... Flags can also be required by script event lines, as explained at Script Event Switches. Item flags can also be used as a requirement in take. Note that some internal flags exist, and are prefixed with '__' to avoid conflict with normal user flags. This includes: - '__raw' and '__clear' which are part of a fake-flag system used for forcibly setting raw data to a flaggable object, - '__scripts', '__time', etc. which is where some object-type flags are stored inside of server flags, - '__interact_step' which is used for interact script steps, related to zap, - '__interact_cooldown' which is used for interact script cooldowns, related to 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 (though 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. As a bonus feature-combo, it is possible to transmit sets of flags exactly in-place and reapply them, this is particular useful for example to synchronize player data across Bungee servers. To do this, you can read raw flag data with the tag FlaggableObject.flag_map and the '__raw' prefix in a flag command. For example:
|
Group | Denizen Scripting Language |
Source | https://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/scripts/commands/core/FlagCommand.java#L34 |
Name | Script |
Description | A 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. |
Group | Denizen Scripting Language |
Source | https://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/objects/core/ScriptTag.java#L28 |
Name | Script Syntax |
Description | The 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). |
Group | Denizen Scripting Language |
Source | https://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/objects/core/ScriptTag.java#L54 |
Name | Image positions |
Description | Some image-related features take in x and y values, which represent a point on the image.
The values are relative to the upper left corner of the image, which acts as 0,0. If the values are meant to represent the position of a larger object (a shape, an image being drawn onto another image, etc.), they represent the position of that object's upper left corner. |
Group | image |
Source | https://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/scripts/commands/core/DrawCommand.java#L57 |
Name | Virtual Inventories |
Description | Virtual 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.
|
Group | Inventory System |
Source | https://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/scripts/commands/item/InventoryCommand.java#L65 |
Name | Display Entity Interpolation |
Description | Display entities can interpolate between different properties, providing a smooth transition.
Interpolation can be started (immediately or with a delay) using EntityTag.interpolation_start, and it's duration can be set using EntityTag.interpolation_duration. The following properties can be interpolated: EntityTag.scale, EntityTag.translation, EntityTag.shadow_radius, EntityTag.shadow_strength, EntityTag.opacity, EntityTag.left_rotation, EntityTag.right_rotation. |
Group | Minecraft Logic |
Source | https://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/objects/properties/entity/EntityInterpolationStart.java#L10 |
Name | Internal Entity Data |
Description | Each entity in Minecraft has a set of data values that get sent to the client, with each data value being a number id -> value pair.
Denizen allows direct control over that data, as it can be useful for things like setting values that would usually be blocked. Because this is such a direct control that's meant to impose less restriction, there's no limitations/verification on the values being set other than basic type checking. Note as well that as these are raw internal values, they are liable to change between minecraft version updates, especially the numeric IDs. For all possible internal entity data values and their respective ids, see https://github.com/DenizenScript/Denizen/blob/dev/v1_20/src/main/java/com/denizenscript/denizen/nms/v1_20/helpers/EntityDataNameMapper.java#L50. Alternatively, you can use the number id directly instead of the names listed there. For a list of all entity data ids and their values, see https://wiki.vg/Entity_metadata (note that it documents the values that eventually get sent to the client, so the input this expects might be slightly different in some cases). You can input the equivalent denizen objects to have them be auto-converted to the internal types. |
Group | Minecraft Logic |
Source | https://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/scripts/commands/entity/FakeInternalDataCommand.java#L24 |
Name | Player Entity Skins (Skin Blobs) |
Description | Player 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 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). |
Group | Minecraft Logic |
Source | https://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/nms/abstracts/ProfileEditor.java#L51 |
Name | Chat Triggers |
Description | Chat Triggers are triggered when a player chats to the NPC (usually while standing close to the NPC and facing the NPC).
They can also be triggered by the command "/denizenclickable chat hello" (where 'hello' is replaced with the chat message). This is used for clickable triggers. This option enforces all the same limitations as chatting directly, but unlike real chat, won't display the message in global chat when there's no match. This requires players have the permission "denizen.clickable". 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:
|
Group | NPC Interact Scripts |
Source | https://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/scripts/triggers/core/ChatTrigger.java#L40 |
Name | Click Triggers |
Description | Click Triggers are triggered when a player right clicks the NPC.
These are very basic with no extraneous complexity.
They can optionally have an item matcher with multiple triggers, for the item in the player's hand. For example:
|
Group | NPC Interact Scripts |
Source | https://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/scripts/triggers/core/ClickTrigger.java#L25 |
Name | Damage Triggers |
Description | Damage 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. |
Group | NPC Interact Scripts |
Source | https://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/scripts/triggers/core/DamageTrigger.java#L30 |
Name | Interact Script Triggers |
Description | Interact 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 cooldown or engage. Triggers go in interact script containers. The available default trigger types are click triggers, damage triggers, chat triggers, and proximity triggers. |
Group | NPC Interact Scripts |
Source | https://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/scripts/containers/core/InteractScriptContainer.java#L67 |
Name | Proximity Triggers |
Description | Proximity 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 trigger. |
Group | NPC Interact Scripts |
Source | https://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/scripts/triggers/core/ProximityTrigger.java#L23 |
Name | Health Trait |
Description | By 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 EntityTag.health EntityTag.formatted_health EntityTag.health_max EntityTag.health_percentage NPCTag.has_trait[health] Related Mechanisms EntityTag.health EntityTag.max_health Related Commands heal health vulnerable Related Actions on damage on damaged on no damage trigger |
Group | NPC Traits |
Source | https://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/npc/traits/HealthTrait.java#L29 |
Name | Invisible Trait |
Description | The invisible trait will allow a NPC to remain invisible, even after a server restart.
It permanently applies the invisible potion effect. Use '/npc 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. |
Group | NPC Traits |
Source | https://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/npc/traits/InvisibleTrait.java#L19 |
Name | Pushable Trait |
Description | By 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'. |
Group | NPC Traits |
Source | https://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/npc/traits/PushableTrait.java#L19 |
Name | Advanced Object Matchables |
Description | Script 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 LocationTag and/or MaterialTag will be matched against. This means you can specify any valid block material name, like "stone" or "air", like "on player clicks stone:" (will only run the event if the player is clicking stone) You can also use a catch-all such as "block", like "on player clicks block:" (will always run the event when the player clicks anything/anywhere) You can also use some more complicated matchables such as "vanilla_tagged:", like "on player clicks vanilla_tagged:mineable/axe:" (will run if the block is mineable with axes) (For more block-related options, refer to the LocationTag and MaterialTag matchers lists.) Many object types can be used for matchables, the valid inputs are unique depending on the object type involved. Some inputs don't refer to any object at all - they're just advanced matchers for some generic plaintext, for example "<cause>" implies an enumeration of causes will be matched against. Many inputs support advanced matchers. For details on that, see Advanced Object Matching. A common matchable type found among different objects is a Flag Matchable. This usually looks like "item_flagged:<flag>" This matches if the object has the specified flag, and fails to match if the object doesn't have that flag. You can specify multiple required flags with '|', like "item_flagged:a|b|c", which will match if-and-only-if the item has ALL the flags named. They can also be used to require the object does NOT have the flag with a "!" like "item_flagged:!<flag>". When using multiple flags with "|", the "!" is per-entry, so "item_flagged:!a|b" requires the item DOES have 'b' but does NOT have 'a'. Note also that in addition to events, tags often also have matchables as input params, usually documented like ".types[<matcher>]", with tag documentation specifying what matcher is used, or like "<material_matcher>" to indicate in this example specifically MaterialTag matchables are allowed. Not all object types have defined matchable options, and those that do list them in their ObjectType meta. For an example of this, check ItemTag. As a special case, "in:<area>" style matchable listings in event conform to the following option set: "biome:<name>": matches if the location is in a given biome, using advanced matchers. "cuboid" plaintext: matches if the location is in any noted cuboid. "ellipsoid" plaintext: matches if the location is in any noted ellipsoid. "polygon" plaintext: matches if the location is in any noted polygon. "chunk_flagged:<flag>": a Flag Matchable for ChunkTag flags. "area_flagged:<flag>": a Flag Matchable for AreaObject flags. Area note name: matches if an AreaObject note that matches the given advanced matcher contains the location. If none of the above are used, uses WorldTag matchers. |
Group | Object System |
Source | https://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/events/BukkitScriptEvent.java#L45 |
Name | Advanced Object Matching |
Description | Script 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|wooden_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. Object types have their own special supported matchable inputs, refer to Advanced Object Matchables. These advanced matchers are also used in some commands and tags, such as ObjectTag.advanced_matches, or in if with the 'matches' operator. |
Group | Object System |
Source | https://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/events/ScriptEvent.java#L905 |
Name | ElementTag(Boolean) |
Description | When "ElementTag(Boolean)" appears in meta documentation, this means the input/output is an ElementTag
(refer to ElementTag) that is a boolean. Boolean means either a "true" or a "false". |
Group | Object System |
Source | https://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/objects/core/ElementTag.java#L66 |
Name | ElementTag(Decimal) |
Description | When "ElementTag(Decimal)" appears in meta documentation, this means the input/output is an ElementTag
(refer to 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 "<#.#>". |
Group | Object System |
Source | https://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/objects/core/ElementTag.java#L87 |
Name | ElementTag(Number) |
Description | When "ElementTag(Number)" appears in meta documentation, this means the input/output is an ElementTag
(refer to 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 ElementTag(Decimal). In some cases, this will also be documented as "<#>". |
Group | Object System |
Source | https://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/objects/core/ElementTag.java#L75 |
Name | ObjectTags |
Description | ObjectTags are a system put into place by Denizen that make working with things, or 'objects',
in Minecraft and Denizen easier. Many parts of scripts will require some kind of object as an argument, identifier/type, or such as in world events, part of an event name. The ObjectTags notation system helps both you and Denizen know what type of objects are being referenced and worked with. So when should you use ObjectTags? In arguments, event names, replaceable tags, configs, flags, and more! If you're just a beginner, you've probably been using them without even realizing it! ObjectTag is a broader term for a 'type' of object that more specifically represents something, such as a LocationTag or ScriptTag, often times just referred to as a 'location' or 'script'. Denizen employs many object types that you should be familiar with. You'll notice that many times objects are referenced with their 'ObjectTag notation' which is in the format of 'x@', the x being the specific notation of an object type. Example: player objects use the p@ notation, and locations use l@. This notation is automatically generated when directly displaying objects, or saving them into data files. It should never be manually typed into a script. Let's take the tag system, for example. It uses the ObjectTags system pretty heavily. For instance, every time you use <player.name> or <npc.id>, you're using a ObjectTag, which brings us to a simple clarification: Why <player.name> and not <PlayerTag.name>? That's because Denizen allows Players, NPCs and other 'in-context objects' to be linked to certain scripts. In short, <player> already contains a reference to a specific player, such as the player that died in a world event 'on player dies'. <PlayerTag.name> is instead the format for documentation, with "PlayerTag" simply indicating 'any player object here'. ObjectTags can be used to CREATE new instances of objects, too! Though not all types allow 'new' objects to be created, many do, such as ItemTags. With the use of tags, it's easy to reference a specific item, say -- an item in the Player's hand -- items are also able to use a constructor to make a new item, and say, drop it in the world. Take the case of the command/usage '- drop diamond_ore'. The item object used is a brand new diamond_ore, which is then dropped by the command to a location of your choice -- just specify an additional location argument. There's a great deal more to learn about ObjectTags, so be sure to check out each object type for more specific information. While all ObjectTags share some features, many contain goodies on top of that! |
Group | Object System |
Source | https://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/utilities/CommonRegistries.java#L29 |
Name | Unique Objects vs Generic Objects |
Description | There are a lot of object types in the Denizen object system, and not all of them behave the same way.
It can be useful to separate object types into categories to better understand how objects work, and how Denizen as a whole works. While there are some hardlined separations, there are also some generalizations that don't necessarily hold exactly, but are still helpful. One such generalization is the separation between Unique and Generic object types. A UNIQUE object is the way you might assume all objects are. Unique objects most notably include EntityTag objects and the derivative NPCTag / PlayerTag objects. An entity object identifies in a form like 'e@<uuid>', where '<uuid>' is some unique ID that looks something like 'abc123-4d5e6f'. This ID is randomly generated by the Minecraft server and is used to identify that one entity in the world separately from any other. 'e@abc123' is not "a creeper" to the engine, it is "that specific creeper over there". An object that is unique must have some way to specify the exact single instance of it in the world, like the UUID used by entities. A GENERIC object can be said to be a 'description' of a unique object. A generic form of an EntityTag might look like 'e@creeper'. Instead of "that specific creeper over there", it is instead "the concept of a creeper mob". There is no way for the engine to read only the word 'creeper' and find out which specific creeper in the world it came from... it could be any of them, there's often hundreds of creepers spawned somewhere in the world at any time. Objects like items and materials are always generic. There is no unique identifier for any item, there is only the description. An item usually looks something like 'i@stick'. ItemTag objects can include more detail, like 'i@stick[lore=hi;display_name=My Stick;enchantments=[sharpness=5]]'... but this is still just a description, and there could still be many items out there that match this description. The consequences of this mostly relate to: - How you adjust an object (eg change the lore of an item, or teleport an entity). For example: you can't teleport the generic concept of a creeper, but you can certainly teleport a specific single creeper in the world. - How reliable tags on the object are. For example: the result of 'ItemTag.lore' on the item 'i@stick[lore=hi]' will always be 'hi' (because ItemTags are generic), but the result of 'EntityTag.location' on the entity 'e@abc123' will change every tick as the entity moves, or even become invalid if the entity dies (because that EntityTag is unique). Here's where the separation gets muddy: First, as mentioned, an EntityTag can either be unique ('e@abc123', 'n@42', etc.) OR generic ('e@creeper', 'e@zombie[custom_name=Bob]', etc). Second, some object types exhibit a bit of both. For example, a LocationTag refers to a unique block in the world (like, 'l@1,2,3,world' is always that specific block at that position), but also is a generic object in terms of the location object itself - if for example you want to change the angle of a location, you have to essentially 'create' a new location, that is an exact copy of the previous one but with a new yaw or pitch value. |
Group | Object System |
Source | https://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/objects/ObjectTag.java#L43 |
Name | Attribute Modifiers |
Description | In 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 EntityTag.attribute_modifiers, ItemTag.attribute_modifiers, EntityTag.has_attribute, EntityTag.attribute_value, EntityTag.attribute_base_value, EntityTag.attribute_default_value, ... These can be modified by such mechanisms as EntityTag.attribute_base_values, EntityTag.attribute_modifiers, EntityTag.add_attribute_modifiers, EntityTag.remove_attribute_modifiers, ItemTag.attribute_modifiers, ItemTag.add_attribute_modifiers, 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 additionally: Before MC 1.21: optional 'name', 'slot', and 'id' keys. The default ID will be randomly generated, the default name will be the attribute name. After MC 1.21: required 'key' key, and optional 'slot'. The 'key' is the attribute's name/identifier in a "namespace:key" format (defaulting to the "minecraft" namespace), which has to be distinct to other modifiers of the same type on the object. Valid operations: ADD_NUMBER, ADD_SCALAR, and MULTIPLY_SCALAR_1 Valid slots (used up to MC 1.20.6): HAND, OFF_HAND, FEET, LEGS, CHEST, HEAD, ANY Valid slot groups (used on MC 1.20.6+): https://hub.spigotmc.org/javadocs/spigot/org/bukkit/inventory/EquipmentSlotGroup.html Valid attribute names are listed at https://hub.spigotmc.org/javadocs/spigot/org/bukkit/attribute/Attribute.html The default slot/slot group is "any". Operation names are based on the Bukkit enum. ADD_NUMBER corresponds to Mojang "ADDITION" - adds on top of the base value. ADD_SCALAR corresponds to Mojang "MULTIPLY_BASE" - adds to the total, multiplied by the base value. MULTIPLY_SCALAR_1 corresponds to Mojang "MULTIPLY_TOTAL", multiplies the final value (after both "add_number" and "add_scaler") by the amount given plus one. They are combined like (pseudo-code):
See also https://minecraft.wiki/w/Attribute#Modifiers For a quick and dirty in-line input, you can do for example: [generic_max_health=<list[<map[key=my_project:add_health;operation=ADD_NUMBER;amount=20;slot=HEAD]>]>] For more clean/proper input, instead do something like:
When pre-defining a custom item, instead of this, simply use an item script: item script containers. That page shows an example of valid attribute modifiers on an item script. |
Group | Properties |
Source | https://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/objects/properties/entity/EntityAttributeModifiers.java#L208 |
Name | Entity Color Types |
Description | This is a quick rundown of the styling information used to handle the coloration of a mob in EntityTag.color.
The list of values can be gotten in-script via 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 and zombie_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 types are BLUE, CYAN, GOLD, LUCY, or WILD. For frogs, the types are TEMPERATE, WARM, or COLD. For boats, type types are ACACIA, BAMBOO, BIRCH, CHERRY, DARK_OAK, JUNGLE, MANGROVE, OAK, or SPRUCE. 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. |
Group | Properties |
Source | https://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/objects/properties/entity/EntityColor.java#L308 |
Name | ~Waitable |
Description | A 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. |
Group | Script Command System |
Source | https://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/scripts/commands/Holdable.java#L9 |
Name | Command Syntax |
Description | Almost 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:
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 noted 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:
|
Group | Script Command System |
Source | https://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/scripts/commands/CommandRegistry.java#L45 |
Name | The Global If Argument |
Description | The "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:
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 objecttag.is.to or elementtag.and or elementtag.or. |
Group | Script Command System |
Source | https://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/scripts/commands/CommandExecutor.java#L50 |
Name | The Player and NPC Arguments |
Description | The "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: - sit 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, "sit" exclusively makes the linked NPC sit, 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. You can also modify the linked player or NPC for an entire queue using the fake-definitions '__player' and '__npc', for example:
|
Group | Script Command System |
Source | https://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/utilities/implementation/DenizenCoreImplementation.java#L104 |
Name | The Save Argument |
Description | The "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. Many users make the mistake of using dynamic save names like "save:<[something]>" - this is almost always wrong. Use a constant name, just like you do for definitions. |
Group | Script Command System |
Source | https://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/scripts/commands/CommandExecutor.java#L31 |
Name | Assignment Script Containers |
Description | Assignment 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 interact script containers Assignments scripts can be automatically disabled by adding "enabled: false" as a root key (supports any load-time-parseable tags). This will disable any "actions" on the script (but not interact scripts steps - disable the interact for that). Basic structure of an assignment script:
Though note that almost always you should include the 'actions:' key, usually with the 'on assignment:' action (if using triggers). Refer to assignment. |
Group | Script Container System |
Source | https://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/scripts/containers/core/AssignmentScriptContainer.java#L13 |
Name | Book Script Containers |
Description | Book 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
|
Group | Script Container System |
Source | https://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/scripts/containers/core/BookScriptContainer.java#L19 |
Name | Command Script Containers |
Description | Command 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 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. Command scripts can be automatically disabled by adding "enabled: false" as a root key (supports any load-time-parseable tags).
|
Group | Script Container System |
Source | https://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/scripts/containers/core/CommandScriptContainer.java#L28 |
Name | Custom Script Containers |
Description | Custom 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.
|
Group | Script Container System |
Source | https://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/scripts/containers/core/CustomScriptContainer.java#L25 |
Name | Data Script Containers |
Description | Data 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 ScriptTag.data_key tag.
|
Group | Script Container System |
Source | https://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/scripts/containers/core/DataScriptContainer.java#L9 |
Name | Enchantment Script Containers |
Description | Enchantment 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. Rarity, Category, and Slots do not apply changes to an already-loaded script until the next restart (except when the script is newly added). Using these may cause unpredictable compatibility issues with external plugins. Enchantment scripts can be automatically disabled by adding "enabled: false" as a root key (supports any load-time-parseable tags).
|
Group | Script Container System |
Source | https://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/scripts/containers/core/EnchantmentScriptContainer.java#L33 |
Name | Entity Script Containers |
Description | Entity 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.
MORE MECHANISM OPTIONS ARE LISTED HERE: https://meta.denizenscript.com/Docs/Mechanisms/entitytag. |
Group | Script Container System |
Source | https://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/scripts/containers/core/EntityScriptContainer.java#L27 |
Name | Format Script Containers |
Description | Format script containers are very simple script containers used for formatting messages, usually with the 'narrate' command.
|
Group | Script Container System |
Source | https://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/scripts/containers/core/FormatScriptContainer.java#L19 |
Name | Interact Script Containers |
Description | Interact script containers are used to handle NPC triggers.
Interact scripts must be referenced from an assignment script container to be of any use. See 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: zap. Each step contains a list of trigger types that it handles, and the relevant handling that the given trigger makes available. Refer to interact script triggers for documentation about the triggers available. Any triggers used must be enabled in assignment by 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 scripts can be automatically disabled by adding "enabled: false" as a root key (supports any load-time-parseable tags).
|
Group | Script Container System |
Source | https://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/scripts/containers/core/InteractScriptContainer.java#L19 |
Name | Inventory Script Containers |
Description | Inventory 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.
|
Group | Script Container System |
Source | https://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/scripts/containers/core/InventoryScriptContainer.java#L26 |
Name | Item Script Containers |
Description | Item 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.
|
Group | Script Container System |
Source | https://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/scripts/containers/core/ItemScriptContainer.java#L30 |
Name | Map Script Containers |
Description | Map scripts allow you define custom in-game map items, for usage with the map command.
The following is the format for the container.
A list of cursor types is available through server.map_cursor_types. |
Group | Script Container System |
Source | https://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/scripts/containers/core/MapScriptContainer.java#L23 |
Name | Procedure Script Containers |
Description | Procedure script containers are used to define a script that can be ran through a tag.
Generally called via proc or 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.
|
Group | Script Container System |
Source | https://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/scripts/containers/core/ProcedureScriptContainer.java#L9 |
Name | Script Container |
Description | Script 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:
And here's a container, put into a more familiar context:
|
Group | Script Container System |
Source | https://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/scripts/containers/ScriptContainer.java#L24 |
Name | Script Name |
Description | Typically 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.
|
Group | Script Container System |
Source | https://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/scripts/containers/ScriptContainer.java#L122 |
Name | Script Type |
Description | The type of container that a script is in. For example, 'task script' is a script type that has some sort of utility.
|
Group | Script Container System |
Source | https://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/scripts/containers/ScriptContainer.java#L191 |
Name | Task Script Containers |
Description | Task script containers are generic script containers for commands that can be run at
any time by command. Generally tasks will be ran by run or inject. The only required key on a task script container is the 'script:' key.
|
Group | Script Container System |
Source | https://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/scripts/containers/core/TaskScriptContainer.java#L15 |
Name | World Script Containers |
Description | World 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 scripts can be automatically disabled by adding "enabled: false" as a root key (supports any load-time-parseable tags).
|
Group | Script Container System |
Source | https://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/scripts/containers/core/WorldScriptContainer.java#L9 |
Name | Economy Script Containers |
Description | Economy script containers
Economy script containers provide a Vault economy, which can be used in scripts by PlayerTag.money and 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. Economy scripts can be automatically disabled by adding "enabled: false" as a root key (supports any load-time-parseable tags).
|
Group | Script Container System |
Requires | Vault |
Source | https://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/scripts/containers/core/EconomyScriptContainer.java#L32 |
Name | Bukkit Event Priority |
Description | Script 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". |
Group | Script Events |
Source | https://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/events/BukkitScriptEvent.java#L526 |
Name | Safety In Events |
Description | One 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:
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".
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). (See also Script Event After vs On) 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.
|
Group | Script Events |
Source | https://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/events/BukkitScriptEvent.java#L934 |
Name | Script Event After vs On |
Description | Modern 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). See also Safety In Events |
Group | Script Events |
Source | https://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/events/ScriptEvent.java#L361 |
Name | Script Event Cancellation |
Description | Any 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>". |
Group | Script Events |
Source | https://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/events/ScriptEvent.java#L556 |
Name | Script Event Priority |
Description | Any 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. |
Group | Script Events |
Source | https://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/events/ScriptEvent.java#L622 |
Name | Script Event Special Contexts |
Description | Every modern ScriptEvent has some special context tags available.
The most noteworthy is "context.cancelled", which tracks whether the script event has been cancelled. That returns, for example, "on player breaks stone". The context 'reflect_event' is available in some events (eg Bukkit events) to get a JavaReflectedObjectTag of the raw internal event. |
Group | Script Events |
Source | https://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/events/ScriptEvent.java#L881 |
Name | Script Event Switches |
Description | Modern 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. This can also be used to require the server does NOT have a flag with "server_flagged:!<flag_name>" "chance:<percent>" is also a globally available switch. For example, "on player breaks diamond_ore chance:25:" will only fire on average one in every four times that a player breaks a diamond ore block. Events that have a player linked have the "flagged" and "permission" switches available. If the switch is specified, and an event doesn't have a linked player, the event will automatically fail to match. The "flagged:<flag_name>" switch 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"). You can also use "flagged:!<flag_name>" to require the player does NOT have the flag, like "on player breaks block flagged:!griefbypass:" 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:" For multiple flag or permission requirements, just list them separated by '|' pipes, like "flagged:a|b|c". This will require all named flags/permissions to be present, not just one. Events that have an NPC linked have the "assigned" switch available. If the switch is specified, and an event doesn't have a linked NPC, the event will automatically fail to match. The "assigned:<script name>" switch will limit the event to only fire when the NPC has an assignment script that matches the given advanced matcher. 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 Advanced 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 script event priority), All Bukkit events have bukkit priority switches (see bukkit event priority), All cancellable script events have cancellation switches (see script event cancellation). See also Advanced Object Matching. |
Group | Script Events |
Source | https://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/events/ScriptEvent.java#L236 |
Name | Tag Fallbacks |
Description | Tag 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?
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:
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 "p@uuid", so it will therefore never exactly match any simple word, so there's no coincidental match edge-case to worry about. Note that this won't work so perfect for things like a user input or fully dynamic value, so in those cases you may want to use 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. |
Group | Tag System |
Source | https://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/tags/Attribute.java#L471 |
Name | Damage Cause |
Description | Possible damage causes: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/event/entity/EntityDamageEvent.DamageCause.html
These are used in entity damage, server.damage_causes, EntityTag.last_damage.cause, ... |
Group | Useful Lists |
Source | https://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/events/entity/EntityDamagedScriptEvent.java#L27 |
Name | Data Actions |
Description | Several commands function as a way to modify data values,
including flag, yaml, and 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]:<-" The index can also be "last" to automatically use the last entry in the list as the target. |
Group | Useful Lists |
Source | https://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/utilities/data/DataActionType.java#L5 |
Name | Denizen Entity Types |
Description | Along with the default EntityTypes 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. |
Group | Useful Lists |
Source | https://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/utilities/entity/DenizenEntityType.java#L39 |
Name | Escaping System |
Description | Sometimes, you need to avoid having symbols that might be misinterpreted in your data.
Denizen provides the tags ElementTag.escaped and 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: (THESE ARE NOT TAG NAMES) | = &pipe < = < > = > newline = &nl & = & ; = &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. |
Group | Useful Lists |
Source | https://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/tags/core/EscapeTagUtil.java#L8 |
Name | Inventory Actions |
Description | Used 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. |
Group | Useful Lists |
Source | https://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/events/player/PlayerClicksInInventoryScriptEvent.java#L20 |
Name | Particle Effects |
Description | All the effects listed here can be used by PlayEffect to display visual effects or play sounds
Effects: - Everything on https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Particle.html - Everything on https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Effect.html - RANDOM (chooses a random visual effect from the Particle list) |
Group | Useful Lists |
Source | https://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/scripts/commands/world/PlayEffectCommand.java#L48 |
Name | Raid Event Data |
Description | Every event related to village raids has a <context.raid> property, a MapTag wrapper around raid data (see https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Raid.html).
These events are player triggers raid, raid finishes, raid spawns wave, and raid stops. The data format is as follows: location: a LocationTag of the raid's center heroes: a list of PlayerTags that have participated in the raid raiders: a list of raider EntityTags that remain in the current wave status: the current status of the raid. See https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Raid.RaidStatus.html age: the raid's age (active time) as a DurationTag level: the Bad Omen level that the raid was started with spawned_groups: the number of raider groups spawned total_groups: the number of groups planned to spawn or already spawned health: the combined health of all current raiders waves: the number of waves in the raid |
Group | Useful Lists |
Source | https://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/events/world/RaidScriptEvent.java#L20 |
Name | Raw NBT Encoding |
Description | Several things in Minecraft use NBT to store data, such as items and entities.
For the sake of inter-compatibility, a special standard format is used in Denizen to preserve data types. This system exists in Denizen primarily for the sake of compatibility with external plugins/systems. 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 |
Group | Useful Lists |
Source | https://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/objects/properties/item/ItemRawNBT.java#L111 |
Name | Slot Inputs |
Description | Whenever 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. |
Group | Useful Lists |
Source | https://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/utilities/inventory/SlotHelper.java#L72 |
Name | Structure lookups |
Description | Structures can be located using LocationTag.find_structure.
It works similarly to the '/locate' command, and has several side effects/edge cases: - The radius is in chunks, but isn't always a set square radius around the origin; certain structures may modify the amounts of chunks checked. For example, woodland mansions can potentially check up to 20,000 blocks away (or more) regardless of the radius used. - Lookups can take a long amount of time (several seconds, over 10 in some cases), especially when looking for unexplored structures, which will cause the server to freeze while searching. - They will not load/generate chunks (but can search not-yet-generated chunks and return a location in them). - They can lead to situations where the server hangs and crashes when trying to find unexplored structures (if there aren't any/any nearby), as it keeps looking further and further out. - The returned location only contains the X and Z values, and will always have a Y value of 0. Tags like LocationTag.highest are available, but note that they require the chunk to be loaded. |
Group | Useful Lists |
Source | https://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/objects/LocationTag.java#L4298 |
Name | Teleport Cause |
Description | Possible player teleport causes: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/event/player/PlayerTeleportEvent.TeleportCause.html
These are used in entity teleports, server.teleport_causes, teleport, ... Note that these causes will only work for player entities. Additionally, Denizen provides two basic teleport causes for non-player entity teleport events: ENTITY_PORTAL and ENTITY_TELEPORT. These additional causes are only for entity teleports, and thus not usable in teleport, and will not show in server.teleport_causes. |
Group | Useful Lists |
Source | https://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/events/entity/EntityTeleportScriptEvent.java#L20 |
Name | MythicMobs Bridge |
Description | In addition to the tags, commands, and events found by searching for "mythicmobs" throughout the meta documentation,
Depenizen adds 4 new Denizen matchers, and additional features to Mythic Mobs: 2 Targeters, and a Condition. Depenizen provides additional EntityTag and ItemTag matchers to match MythicMobs mobs/items: - "mythic_mob" plaintext EntityTag matcher, matches if the entity is a mythic mob. - "mythic_mob:<MythicMobID>" EntityTag matcher, matches if the entity is a mythic mob, and its ID matches the advanced matcher specified. - "mythic_item" plaintext ItemTag matcher, matches if the item is a mythic item. - "mythic_item:<MythicItemID>" ItemTag matcher, matches if the item is a mythic item, and its ID matches the advanced matcher specified. 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 entity-based 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 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>} |
Group | Depenizen Bridges |
Requires | Depenizen, MythicMobs |
Source | https://github.com/DenizenScript/Depenizen/blob/master/src/main/java/com/denizenscript/depenizen/bukkit/utilities/mythicmobs/MythicMobsLoaders.java#L20 |
Name | PlaceholderAPI Bridge |
Description | Using Depenizen with PlaceholderAPI allows you to use placeholder and 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]>% |
Group | Depenizen Bridges |
Requires | Depenizen, PlaceholderAPI |
Source | https://github.com/DenizenScript/Depenizen/blob/master/src/main/java/com/denizenscript/depenizen/bukkit/bridges/PlaceholderAPIBridge.java#L25 |