Denizen Script Language Explanations


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


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

"<block>" usually indicates that a 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 below.)

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 Language:Advanced Script Event 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.

Primary matchable types:

MaterialTag matchers, sometimes identified as "<material>", associated with "<block>":
"material" plaintext: always matches.
"block" plaintext: matches if the material is a block-type material.
"item" plaintext: matches if the material is an item-type material.
"material_flagged:<flag>": a Flag Matchable for MaterialTag flags.
"vanilla_tagged:<tag_name>": matches if the given vanilla tag applies to the material. Allows advanced matchers, for example: "vanilla_tagged:mineable*".
If none of the above are used, uses an advanced matcher for the material name, like "stick".

LocationTag matchers, sometimes identified as "<location>" or "<block>":
"location" plaintext: always matches.
"block_flagged:<flag>": a Flag Matchable for location flags at the given block location.
"location_in:<area>": runs AreaObject checks, as defined below.
If none of the above are used, and the location is at a real block, a MaterialTag matchable is used. Refer to MaterialTag matchable list above.

AreaObject matchers (applies to CuboidTag, EllipsoidTag, PolygonTag, ...), sometimes identified as "<area>": (Note: this is internally always sourced from a LocationTag instance, not a raw area object!)
"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.

WorldTag matchers, sometimes identified as "<world>":
"world" plaintext: always matches.
World name: matches if the world has the given world name, using advanced matchers.
"world_flagged:<flag>": a Flag Matchable for WorldTag flags.

ItemTag matchers, sometimes identified as "<item>", often seen as "with:<item>":
"potion": plaintext: matches if the item is any form of potion item.
"item_flagged:<flag>": A Flag Matcher for item flags.
"item_enchanted:<enchantment>": matches if the item is enchanted with the given enchantment name. Allows advanced matchers.
"raw_exact:<item>": matches based on exact raw item data comparison (almost always a bad idea to use).
Item script names: matches if the item is a script item with the given item script name, using advanced matchers.
If none of the above are used, uses MaterialTag matchables. Refer to MaterialTag matchable list above.
Note that "item" plaintext is always true.

EntityTag matchers, sometimes identified as "<entity>", "<projectile>", or "<vehicle>":
"entity" plaintext: always matches.
"player" plaintext: matches any real player (not NPCs).
"npc" plaintext: matches any Citizens NPC.
"vehicle" plaintext: matches for any vehicle type (minecarts, boats, horses, etc).
"fish" plaintext: matches for any fish type (cod, pufferfish, etc).
"projectile" plaintext: matches for any projectile type (arrow, trident, fish hook, snowball, etc).
"hanging" plaintext: matches for any hanging type (painting, item_frame, etc).
"monster" plaintext: matches for any monster type (creepers, zombies, etc).
"animal" plaintext: matches for any animal type (pigs, cows, etc).
"mob" plaintext: matches for any mob type (creepers, pigs, etc).
"living" plaintext: matches for any living type (players, pigs, creepers, etc).
"entity_flagged:<flag>": a Flag Matchable for EntityTag flags.
"player_flagged:<flag>": a Flag Matchable for PlayerTag flags (will never match non-players).
"npc_flagged:<flag>": a Flag Matchable for NPCTag flags (will never match non-NPCs).
Any entity type name: matches if the entity is of the given type, using advanced matchers.

InventoryTag matchers, sometimes identified as "<inventory>":
"inventory" plaintext: always matches.
"note" plaintext: matches if the inventory is noted.
Inventory script name: matches if the inventory comes from an inventory script of the given name, using advanced matchers.
Inventory note name: matches if the inventory is noted with the given name, using advanced matchers.
Inventory type: matches if the inventory is of a given type, using advanced matchers.
"inventory_flagged:<flag>": a Flag Matchable for InventoryTag flags.
GroupScript Events
Sourcehttps://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/events/BukkitScriptEvent.java#L41