Denizen Script Language Explanations


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


Showing 17 out of 81 language explanations...
NameAssignment Script Containers
DescriptionAssignment script-containers provide functionality to NPCs by 'assignment' of the container. Assignment
scripts are meant to be used when customizing the normal behavior of NPCs. This can be used on a 'per-NPC' basis,
but the encouraged approach is to design assignment scripts in a way that they can be used for multiple NPCs,
perhaps with the use of constants or flags to determine specific information required by the scripts.

Features unique to assignment script-containers include 'actions' and 'interact script' assignment.
Like any script, the ability to run local utility scripts can be accomplished as well. This allows fully
interactive NPCs to be built purely with Assignment Scripts, and for advanced situations, world scripts and
interact scripts can provide more functionality.
See also Language:interact script containers

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:

Assignment_Script_Name:

    type: assignment

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

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

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


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

NameBook Script Containers
DescriptionBook script containers are similar to item script containers, except they are specifically
for the book items. They work with with the ItemTag object, and can be fetched
with the Object Fetcher by using the ItemTag constructor book_script_name
Example: - give <player> my_book


Book_Script_Name:

    type: book

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

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

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

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

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

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

The following is the format for the container.

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

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


Command scripts can be automatically disabled by adding "enabled: false" as a root key (supports any load-time-parseable tags).


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

    type: command

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

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

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

    # A list of aliases for the command. These will be used as alternative ways to trigger the command, and will show in the '/help' command.
    # | Some command scripts might have this key, but it's optional.
    aliases:
    - myalias
    - mycommand

    # The permission node to check for permissions plugins. This will automatically
    # block players without the permission from accessing the command and help for
    # the command.
    # Note that you can include multiple permission nodes (a player only needs to have any one permission from the list)
    # by separating them with a semicolon, like: perm.one;perm.two;third.perm
    # | Most command scripts should have this key!
    permission: my.permission.node

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

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

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

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

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

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

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

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

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


Custom_Script_Name:

    type: custom

    # Use 'inherit' to make this custom script container inherit from another custom object.
    inherit: some_object

    # This adds default field 'some_field' with initial value of 'some_value'.
    some_field: some_value

    # List additional fields here...

    # Use 'tags' to define scripted tags on the object.
    # Tags are subject to the same rules as procedure scripts:
    # NEVER change any external state. Just determine a value. Nothing else should change from the script.
    tags:

        # This would be read like <[my_object].my_tag>
        my_tag:
        # Perform any logic here, and 'determine' the result.
        - determine 3

        # list additional tags here...

    # Use 'mechanisms' to define scripted mechanisms on the object.
    # Note that these should only ever determine a new object,
    # with NO CHANGES AT ALL outside the replacement determined object.
    # (Same rules as tags and procedure scripts).
    mechanisms:

        # This would be used like custom@Custom_Script_Name[my_mech=3]
        my_mech:
        - adjust <context.this> true_value:<context.value.mul[2]> save:new_val
        - determine <entry[new_val].result>

        # list additional mechanisms here...

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

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

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

There are no required keys.

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


data_script_name:

    type: data

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

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

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

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

It may be beneficial in some cases to restart your server after making changes to enchantments, rather than just reloading scripts.
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).


Enchantment_Script_Name:

    type: enchantment

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


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

    type: entity

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

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

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

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

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

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

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


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

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


Format_Script_Name:

    type: format

    # The only key is the format. The format can use '<[text]>' as a special def to contain the message being sent.
    # '<[name]>' is available as a special def as well for use with the 'on player chats' event to fill the player's name properly.
    # Note that 'special' means special: these tags behave a little funny in certain circumstances.
    # In particular, these can't be used as real tags in some cases, including for example when using a format script as a determine in the 'player chats' event.
    # | All format scripts MUST have this key!
    format: <[name]> says <[text]>
GroupScript Container System
Sourcehttps://github.com/DenizenScript/Denizen/blob/dev/plugin/src/main/java/com/denizenscript/denizen/scripts/containers/core/FormatScriptContainer.java#L19

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

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

The only required key on an interact script container is the 'steps:' key.

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

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

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

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

Interact scripts can be automatically disabled by adding "enabled: false" as a root key (supports any load-time-parseable tags).


Interact_Script_Name:

    type: interact

    # | All interact scripts MUST have this key!
    steps:

        # The first step
        1:
            # Any trigger type here
            click trigger:
                script:
                    # Handle what happens when the NPC is clicked during step 1
                    - some commands
            # Other triggers here
        # other steps here

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

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

Example: - inventory open d:MyInventoryScript

The following is the format for the container.

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


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

    type: inventory

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

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

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

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

    # You can use definitions to define items to use in the slots. These are not like normal script definitions, and do not need to be in a definition tag.
    # | Some inventory scripts MAY have this key, but it is optional. Most scripts will just specify items directly.
    definitions:
        my item: ItemTag
        other item: ItemTag

    # Procedural items can be used to specify a list of ItemTags for the empty slots to be filled with.
    # Each item in the list represents the next available empty slot.
    # When the inventory has no more empty slots, it will discard any remaining items in the list.
    # A slot is considered empty when it has no value specified in the slots section.
    # If the slot is filled with air, it will no longer count as being empty.
    # | Most inventory scripts should exclude this key, but it may be useful in some cases.
    procedural items:
    - define list <list>
    - foreach <server.online_players>:
        # Insert some form of complex doesn't-fit-in-just-a-tag logic here
        - define item <[value].skull_item>
        - define list:->:<[item]>
    - determine <[list]>

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

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

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


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

    type: item

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

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

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

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

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

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

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

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

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

       7:
           # Brewing recipes take one base item and one ingredient item.
           # | Brewing recipes are only available on Paper versions 1.18 and up.
           # | Brewing recipes also have a special input option on 1.20 and above: "matcher:<item matcher>", to allow advanced matchers on the input/ingredient items.
           type: brewing
           input: ItemTag
           ingredient: ItemTag

    # Set to true to not store the scriptID on the item, treating it as an item dropped by any other plugin.
    # NOTE: THIS IS NOT RECOMMENDED UNLESS YOU HAVE A SPECIFIC REASON TO USE IT.
    # | Most item scripts should exclude this key!
    no_id: true/false

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

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

The following is the format for the container.


# The name of the map script is used by the map command.
Map_Script_Name:

    type: map

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

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

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

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

        # The first object...
        1:
            # Specify the object type
            # Type can be IMAGE, TEXT, CURSOR, or DOT.
            type: image
            # Specify an HTTP url or file path within Denizen/images/ for the image. Supports animated .gif!
            image: my_image.png
            # Optionally add width/height numbers.
            width: 128
            height: 128
            # Specify a tag to show or hide custom content! Valid for all objects.
            # Note that all inputs other than 'type' for all objects support tags that will be dynamically reparsed per-player each time the map updates.
            visible: <player.name.contains_text[bob].not>

        2:
            type: text
            # Specify any text to display. Color codes not permitted (unless you know how to format CraftMapCanvas byte-ID color codes).
            text: Hello <player.name>
            # Specify the color of the text as any valid ColorTag.
            color: red
            # | Optionally, specify the following additional options:
            # Specify a font to use, which allows using special characters/other languages the default font may not support.
            font: arial
            # Specify a text size (only available with a custom font).
            size: 18
            # Specify a style, as a list that contains either "bold", "italic", or both (only available with a custom font).
            style: bold|italic
        3:
            type: cursor
            # Specify a cursor type
            cursor: red_marker
            # Optionally, specify a cursor direction. '180' seems to display as up-right usually.
            direction: 180
            # Supported on all objects: x/y positions, and whether to use worldly or map coordinates.
            x: 5
            # If 'world_coordinates' is set to 'true', the 'y' value corresponds to the 'z' value of a location.
            y: 5
            # If true: uses world coordinates. If false: uses map local coordinates. (Defaults to false).
            world_coordinates: false
            # If true: when the object goes past the edge, will stay in view at the corner. If false: disappears past the edge (defaults to false).
            show_past_edge: false

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



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

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

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

The only required key is 'script:'.

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

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


Proc_Script_Name:

    type: procedure

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

    script:

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

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

NameScript Container
DescriptionScript Containers are the basic structure that Denizen uses inside its YAML-based scripting files found in your
plugins/Denizen/scripts/ folder. Regardless of type, all script containers have basic parts that can usually be
described as keys, list keys, parent keys, child keys, values, and list values. While specific container types
probably have more specific names, just remember that no matter how complicated a script, this basic structure
still applies.

It's important to keep in mind that all child keys, including all the main keys of the script, must line up with
one another, hierarchically. If you are familiar with YAML, great, because all script containers use it at the
core. Every value, in one way or another, belongs to some kind of 'key'. To define a key, use a string value plus
a colon (:). Keys can have a single value, a list value, or own another key:


script name:
    key: value
    list key:
        - list value
        - ...
    parent key:
        child key: value


And here's a container, put into a more familiar context:


a haiku script:
    type: task
    script:
      - narrate "A simple script,"
      - narrate "with a key value relationship."
      - narrate "Oh look, a list!"
GroupScript Container System
Sourcehttps://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/scripts/containers/ScriptContainer.java#L24

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

Generally tasks will be ran by Command:run or Command:inject.

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


Task_Script_Name:

    type: task

    # When intending to run a task script via the run command with the "def:" argument to pass data through,
    # use this "definitions" key to specify the names of the definitions (in the same order as the "def:" argument will use).
    # You can optionally document a definition with [square brackets]
    definitions: name1|name2[description here]|...

    script:

    - your commands here

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

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

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

World scripts can be automatically disabled by adding "enabled: false" as a root key (supports any load-time-parseable tags).


World_Script_Name:

    type: world

    events:

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

        # List additional events here

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

NameEconomy Script Containers
DescriptionEconomy script containers

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

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

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

ALL SCRIPT KEYS ARE REQUIRED.

Economy scripts can be automatically disabled by adding "enabled: false" as a root key (supports any load-time-parseable tags).


# The script name will be shown to the economy provider as the name of the economy system.
Economy_Script_Name:

    type: economy

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

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