Specify "def:<name>" as an input to adjust a definition and automatically save the result back to the definition.

You can optionally adjust a MapTag of mechanisms to values.

To adjust an item in an inventory, use Command:inventory, as '- inventory adjust slot:<#> <mechanism>:<value>'.
Note that that is only for items, not actual inventories.
To adjust an actual InventoryTag mechanism, you should still use the normal 'adjust' command, not 'inventory adjust'.

# Use to set a custom display name on an entity.
- adjust <[some_entity]> custom_name:ANGRY!

# Use to set the skin of every online player.
- adjust <server.online_players> skin:Notch

# Use to modify an item held in a definition.
- adjust def:stick "display_name:Fancy stick"

Input a location or list of locations, and the mechanism to apply.

Use the "no_physics" argument to indicate that the change should not apply a physics update.
If not specified, physics will apply to the block and nearby blocks.

# Use to put snow on the block at the player's feet.
- adjustblock <player.location.below> snowy:true

# Use to switch on the lever that the player is looking at, without actually providing redstone power.
- adjustblock <player.cursor_on> switched:true no_physics

Cooldown requires a type (player or global), a script, and a duration.
It also requires a valid link to a PlayerTag if using a non-global cooldown.

To cooldown non-interact scripts automatically, consider Command:ratelimit.

Cooldown periods are persistent through a server restart as they are saved in the 'saves.yml'.

# Use to keep the current interact script from meeting requirements.
- cooldown 20m

# Use to keep a player from activating a script for a specified duration.
- cooldown 11h script:bonus_script
- cooldown 5s script:hit_indicator

# Use the 'global' argument to indicate the script to be on cooldown for all players.
- cooldown global 24h script:daily_treasure_offering

Input is an ID (the name of your custom event, choose a constant name to use), and an optional MapTag of context data.

Linked data (player, npc, ...) is automatically sent across to the event.

Use with Event:custom event

# Use to call a custom event with path "on custom event id:things_happened:"
- customevent id:things_happened

# Use to call a custom event with path "on custom event id:things_happened:" and supply a context map of basic data.
- customevent id:things_happened context:[a=1;b=2;c=3]

# Use to call a custom event with a path such as "on custom event id:things_happened data:item:stone:" and supply a context map of more interesting data.
- definemap context:
    waffle: hello world
    item: <player.item_in_hand>
- customevent id:things_happened context:<[context]>

# Use to call a custom event and allow cancelling or replacing a value.
- definemap context:
    message: hello world
- customevent id:custom_message context:<[context]> save:event
- if <entry[event].was_cancelled>:
    - stop
- define message <entry[event].determination_list.first.if_null[<[context.message]>]>
- narrate "Final message is: <[message]>"

Outputs plain text debug to the console by default, supporting the 'debug' format type (see Language:Script Formats).

Alternatively, specify one of the following debug types:
DEBUG: standard hideable debug.
HEADER: standard hideable debug inside a header line.
FOOTER: a footer line.
SPACER: a spacer line.
LOG: global output, non-hideable.
APPROVAL: "Okay!" output, non-hideable.
ERROR: "Error!" output, non-hideable. Supports the 'error' format type, see Language:Script Formats.
REPORT: normally used to describe the arguments of a command, requires a name, hideable.
EXCEPTION: outputs a full java stacktrace.
RECORD: Use message 'start' to start recording, 'submit' to submit a recording, or 'cancel' to cancel a recording.

# Use to show an error.
- debug error "Something went wrong!"

# Use to add some information to help your own ability to read debug output from you script.
- debug "Time is currently <[milliseconds].div[1000].round> seconds!"

# Use to record a debug log of a certain script.
# NOTICE: Spamming debug recordings to the official Denizen Paste instance will result in you being blocked from the paste service.
- debug record start
- run myscript
- ~debug record submit save:mylog
- narrate "Recorded log as <entry[mylog].submitted||<red>FAILED>"

This command supports data actions, see Language:data actions.

Flags by default are added permanently (or for the lifetime of the object they're attached to).
You can optionally specify a system time the flag will expire at, using either a DurationTag or a TimeTag.
If a DurationTag is used, it will be equivalent to: <util.time_now.add[<your_duration_here>]>

# Use to create or set a flag on a player.
- flag <player> playstyle:aggressive

# Use to set a temporary flag for five minutes on a player.
- flag <player> just_did_something expire:5m

# Use to flag an npc with a given tag value.
- flag <npc> location:<npc.location>

# Use to apply mathematical changes to a flag's value on a unique object.
- flag <context.damager> damage_dealt:+:<context.damage>

# Use to add an item to a server flag as a new value without removing existing values.
- flag server cool_people:->:<[player]>

# Use to add multiple items as individual new values to a server flag that is already a list.
- flag server cool_people:|:<[player]>|<[someplayer]>

# Use to remove an entry from a server flag.
- flag server cool_people:<-:<[someplayer]>

# Use to completely remove a flag.
- flag server cool_people:!

# Use to modify a specific index in a list flag.
- flag server myflag[3]:HelloWorld

MongoDB is a NoSQL database which uses concepts such as Documents and Collections to store data. MongoDB uses a form of JSON to represent its data.
It can interact with localhost connections as well as hosted connections (such as MongoDB's Atlas) via a connection URI.
Store your connection URI in the Denizen secrets file at 'plugins/Denizen/secrets.secret'. Refer to ObjectType:SecretTag for usage info.

Mongo works as a document-oriented database, where data is stored in Documents. Documents are stored inside Collections. Collections can contain many Documents. Collections are then stored inside Databases.

Usage of the mongo command should almost always be used as ~waitable (see Language:~waitable), as large queries and insertions can take a while to retrieve or send.

You can open a mongo connection with connect:<uri>. You must specify a database and collection to connect to with the database:<database> and collection:<collection> options.
You can change the database or collection you are connected to with use_database:<database> and use_collection:<collection>
If a Database or Collection you connect to does not exist, once you insert some data then the Database or Collection will be created automatically.

To insert Documents, use insert:<map>.
To find a specific document from fragments of data, use find:<map>. You can include MongoDB's special query filters to further refine your query. If you want to search by a Document's ID, use by_id:id.

To update a Document's data, use update:<update> with the old data, and new:<new> for the new data being updated. This will update every Document matched with the provided data.
You can also include the upsert flag, to create a new Document if the Document you are trying to update does not already exist.

As MongoDB offers a variety of commands, to run a command not wrapped here you can use command:<map>.

TODO: When opening a connection, Mongo will output a lot of data to the console. There currently is not a way to turn this off.

The mongo command is merely a wrapper, and further usage details should be gathered from an official MongoDB command reference rather than from Denizen command help.
You can view the official mongo documentation here: 🔗https://www.mongodb.com/docs/manual/introduction/.
You can view a list of commands that MongoDB supports here: 🔗https://www.mongodb.com/docs/manual/reference/command/.

# Use to connect to a Mongo instance.
- ~mongo id:name connect:<secret[uri]>

# Use to disconnect from a Mongo instance.
- mongo id:name disconnect

# Run a simple command.
- ~mongo id:name command:[dbStats=1]

# Run more complex commands.
- definemap commands:
     count: my_collection
     skip: 4
 - ~mongo id:name command:<[commands]>

# Simple find query.
- ~mongo id:name find:[name=Bob]

# Complex find query with query filters.
- definemap filters:
     $and:
         - number_greater_than:
             $gt: 2
         - number_less_than:
             $lt: 5
- ~mongo id:name find:<[filters]>

# Insert data into a Collection.
- definemap data:
     name: Pluto
     order_from_sun: 9
     has_rings: false
     main_atmosphere:
         - N2
         - CH4
         - CO
- ~mongo id:name insert:<[data]> save:mg

# Update data.
- definemap old_data:
     name: Pluto
- definemap new_data:
     $set:
         name: Pluto (A Dwarf Planet)
- ~mongo id:name update:<[old_data]> new:<[new_data]>

# Change Databases.
- ~mongo id:name use_database:my_new_database

# Change Collections.
- ~mongo id:name use_collection:my_new_collection

Notable object types: CuboidTag, EllipsoidTag, PolygonTag, LocationTag, InventoryTag

# Use to note a cuboid.
- note <[some_cuboid]> as:mycuboid

# Use to remove a noted cuboid.
- note remove as:mycuboid

# Use to note a location.
- note <context.location> as:mylocation

Redis is a simple key/value data store that is typically used for caching and sending data between servers.
The redis server runs in memory, meaning requests are insanely fast. If you run redis locally, you can expect responses to take under a millisecond.
It is normally advised to run commands as ~waitable (see Language:~waitable), but because of the usual fast responses when the server is on localhost, you can also run commands without ~waiting.

When running commands, make sure to escape unpredictable values such as player input.
Alternatively, include the main redis command as the 'command' input and further arguments as a ListTag input for 'args'.

This command supports subscribing to pub/sub redis channels. This allows you to listen to published messages to redis from any source, including other servers.
When you subscribe to a channel, matching messages sent to the channel will trigger the Event:redis pubsub message event.
Connections that are subscribed to channels get tied up listening for messages and are unavailable to run redis commands.
The channels you subscribe to support wildcard (*) matchers and other patterns, defined by the redis docs: 🔗https://redis.io/commands/psubscribe

Note: Make sure there are at least a few ticks between opening a subscription and closing it, otherwise strange behavior will occur.

You can publish messages to listening subscribers via publish:<channel> message:<message>.
Note that this has to be done on a separate redis connection if it is already subscribed.
Saving the result of this call returns the number of connected subscribers the message was sent to.

The redis command is merely a wrapper, and further usage details should be gathered from an official redis command reference rather than from Denizen command help.
You can view the official redis documentation and the supported commands here: 🔗https://redis.io/

# Use to connect to a Redis server.
- ~redis id:name connect:localhost

# Use to connect to a Redis server with a secret auth key.
- ~redis id:name connect:localhost auth:<secret[my_redis_secret]>

# Use to connect to a Redis server over ssl.
- ~redis id:name connect:localhost port:6380 ssl:true

# Set a key/value pair in the Redis server.
- ~redis id:name "command:set my_key my_value"

# Delete the "foo" key.
- ~redis id:name "command:del my_key"

# Set a key that auto-expires in 60 seconds.
- ~redis id:name "command:setex my_key 60 'value with spaces'"

# Run a command with unpredictable input.
- ~redis id:name command:set args:<list[my_key].include_single[<context.message>]>

# Get a key's value.
- ~redis id:name "command:get my_key" save:result

# Get a key's value in the background via a waitable.
- ~redis id:name "command:get my_key" save:result

# Append values to the front or back of a redis list.
- ~redis id:name "command:rpush my_list a"
- ~redis id:name "command:rpush my_list b"
- ~redis id:name "command:lpush my_list c"

# Retrieve a ListTag of the members stored in a redis list (0 is the start of the list, -1 is the end).
- ~redis id:name "command:lrange my_list 0 -1"

# Subscribe to a redis channel. This will match published messages to channel_1, channel_foo, etc.
- ~redis id:name subscribe:channel_*

# Subscribe to multiple redis channels. Supports wildcards for any list entry.
- ~redis id:name subscribe:a|b*|c|d

# Publish a message to a redis channel. This will trigger the <@link event redis pubsub message> event for any subscribed connections for any server.
- ~redis id:name publish:channel_1 "message:hey look something happened"

# Unsubscribe from a redis channel. Leaves the connection intact.
- redis id:name unsubscribe

# Disconnect from redis.
- redis id:name disconnect

Uses reflection to set, and so can bypass 'private' or 'final' field limits if permitted by config.

If the value is fed as a general ObjectTag, automatic conversion will be attempted.
If automatic conversion is not possible, you must pass a ObjectType:JavaReflectedObjectTag with the appropriate type as the value.

Requires config setting "Reflection.Allow set command".

# Use to change Bukkit's reference to a world's environment to the_end.
- narrate <world[world].environment>
- define obj <world[world].reflected_internal_object>
- narrate <[obj].reflect_field[environment].interpret>
- reflectionset object:<[obj]> field:environment value:the_end
- narrate <world[world].environment>
- narrate <[obj].reflect_field[environment].interpret>

By default, reloads scripts in a way that may delay a few ticks to avoid interrupting the server on large reloads.

Optionally, specify "scripts_now" to force a locked reload (server freezes until reloaded).

You can specify "config", "saves", or "notes" to reload that data instead of scripts.

When using 'scripts' (default), the reload command is ~waitable. Refer to Language:~waitable.

# Use to reload scripts automatically
- reload

The "cooldown" argument removes the player's cooldown for a specific script,
as set by Command:cooldown.

The "global_cooldown" argument removes all cooldowns for the specified script (not player-specific).

# Use to reset all cooldowns for a script when an event that limits usage completes.
- reset global_cooldown MyScriptName

This commands exists primarily for interoperability with pre-existing databases and external services.
It should never be used for storing data that only Denizen needs to use. Consider instead using Command:flag.

The general usage order is connect -> update/query -> disconnect.
It is not required that you disconnect right after using, and in fact encouraged that you keep a connection open where possible.

When connecting, the server format is IP:Port/Database, EG 'localhost:3306/test'.
You can also append options to the end, like 'localhost:3306/test?autoReconnect=true'
Store your password in the Denizen secrets file at 'plugins/Denizen/secrets.secret'. Refer to ObjectType:SecretTag for usage info.

You can switch whether SSL is used for the connection (defaults to false).

Note that when using tag, it is recommended you escape unusual inputs to avoid SQL injection.

The SQL command is merely a wrapper for SQL queries, and further usage details should be gathered from an official MySQL query reference rather than from Denizen command help.

SQL connections are not instant - they can take several seconds, or just never connect at all.
It is recommended you hold the command by doing "- ~sql ..." rather than just "- sql ..."
as this will delay the commands following the SQL command until after the SQL operation is complete.

If you have an SQL database server other than MySQL, be sure to include the driver prefix (defaults to "mysql://" when unspecified).

# Use to connect to an SQL server.
- ~sql id:name connect:localhost:3306/test username:space password:<secret[sql_pw]>

# Use to connect to an SQL server over an SSL connection.
- ~sql id:name connect:localhost:3306/test username:space password:<secret[sql_pw]> ssl:true

# Use to connect to an SQL server with a UTF8 text encoding.
- ~sql id:name connect:localhost:3306/test?characterEncoding=utf8 username:space password:<secret[sql_pw]>

# Use to update an SQL server.
- ~sql id:name "update:CREATE table things(id int,column_name1 varchar(255),column_name2 varchar(255));"

# Use to update an SQL server.
- ~sql id:name "update:INSERT INTO things VALUES (3, 'hello', 'space');"

# Use to query an SQL server.
- ~sql id:name "query:SELECT id,column_name1,column_name2 FROM things;" save:saveName
- narrate <entry[saveName].result_list>

# Use to query an SQL server.
- ~sql id:name "query:SELECT id,column_name1,column_name2 FROM things WHERE id=3;" save:saveName2
- narrate <entry[saveName2].result_list>

# Use to disconnect from an SQL server.
- sql disconnect id:name

This should almost always be ~waited for. Refer to Language:~waitable.

Note that while this will replace URL spaces to %20, you are responsible for any other necessary URL encoding.
You may want to use the Tag:ElementTag.url_encode tag for this.

Optionally, use "data:<data>" to specify a set of data to send to the server (changes the default method from GET to POST).
A BinaryTag input will be used directly - any other input will be treated as a String and encoded as UTF-8.

Optionally, use "method:<method>" to specify the HTTP method to use in your request.
Can be: GET, POST, HEAD, OPTIONS, PUT, DELETE, TRACE, PATCH.

Optionally, use "headers:" to specify a MapTag of headers.

Optionally, use "savefile:" to specify a path to save the retrieved file to.
This will remove the 'result' entry savedata.
Path is relative to server base directory.

Optionally, specify the "timeout:" to set how long the command should wait for a webpage to load before giving up. Defaults to 10 seconds.

Optionally, specify 'hide_failure' to indicate that connection errors are acceptable and shouldn't display in logs.

This command accepts secret inputs via ObjectType:SecretTag as the URL or as the value of any header.
Note that you cannot mix secret with non-secret - meaning, "webget <secret[my_secret]>" and "webget https://example.com" are both valid, but "webget https://example.com/<secret[my_secret]>" is not.
Similarly, for headers, each individual header value can either be a secret or not a secret.

# Use to download the google home page.
- ~webget https://google.com save:google
- narrate <entry[google].result>

# Use to save a webpage to your server's base directory
- ~webget https://google.com savefile:google.html

# Use to post data to a server.
- ~webget https://api.mojang.com/orders/statistics 'data:{"metricKeys":["item_sold_minecraft"]}' headers:<map.with[Content-Type].as[application/json]> save:request
- narrate <entry[request].result>

# Use to retrieve and load an API response into yaml.
- ~webget https://api.mojang.com/users/profiles/minecraft/<player.name> save:request
- yaml loadtext:<entry[request].result> id:player_data

The server does not provide SSL (HTTPS) security or functionality.
The server does not provide active abuse-prevention or routing control or etc.

If your webserver is meant for public connection, it is very strongly recommended you put the webserver behind a reverse-proxy server, such as Nginx or Apache2.

The port, if unspecified, defaults to 8080. You should usually manually specify a port.

The "ignore_errors" option can be enabled to silence basic connection errors that might otherwise spam your console logs.

You can only exactly one webserver per port.
If you use multiple ports, you can thus have multiple webservers.

When using the stop instruction, you must specify the same port you used when starting.

The webserver only does anything if you properly handle Event:webserver web request

Most webserver processing is done in the event, and thus is synchronous with the minecraft thread, and thus may induce lag if not done with care.
Note per the event's meta, "file:" is handled async, and "cached_file:" only runs sync once per file.

This command must be enabled in the Denizen/config.yml before it can be used.

# Use to start a webserver on port 8081.
- webserver start port:8081

# Use to stop the webserver on port 8081.
- webserver stop port:8081

The step name input should match the name of a step in the interact script.
The step name can be '*' to automatically zap to the default step.

If used inside an interact script, will default to the current interact script.
If used elsewhere, but there is a linked NPC with an assignment and interact, that NPC's interact script will be used.
For anywhere else, you must specify the script by name.

Optionally specify a duration. When the duration is up, the script will zap back to the step it was previously on.
If any zap commands are used during the duration, that duration will be discarded.

The command's name was inspired by a command in the language "ZZT-OOP", from a 1991 DOS game enjoyed by the original developer of Denizen.

# Use to change the step to 2.
- zap 2

# Use to return to the default step.
- zap *

# Use to change the step to 3 in a script called Interact_Example.
- zap 3 Interact_Example

# Use to change the step to 1 for the defined player in a script called InteractScript.
- zap 1 InteractScript player:<[player]>

# Use to make an ageable entity a permanant baby.
- age <[some_entity]> baby lock

# ...or a mature adult.
- age <[some_entity]> adult lock

# Use to make a baby entity an adult.
- age <[some_npc]> adult

# Use to mature some animals so that they are old enough to breed.
- age <player.location.find_entities.within[20]> adult

You must specify the entity or list of entities to be attached.
You must specify the entity that they will be attached to, or 'cancel' to end attachment.

Optionally, specify an offset location vector to be a positional offset. This can include a yaw/pitch to offset those as well.
Note that setting an offset of 0,0,0 will produce slightly different visual results from not setting any offset.

Optionally, specify 'relative' to indicate that the offset vector should rotate with the target entity.
If relative is used, optionally specify yaw_offset and/or pitch_offset to add an offset to rotation of the target entity when calculating the attachment offset.

Optionally, specify 'for' with a player or list of players to only sync motion for those players.
If unspecified, will sync for everyone.

Optionally, specify 'sync_server' to keep the serverside position of the attached entities near the target entity.
This can reduce some visual artifacts (such as entity unloading at distance), but may produce unintended functional artifacts.
Note that you should generally only use 'sync_server' when you exclude the 'for' argument.

Optionally specify 'no_rotate' to retain the attached entity's own rotation and ignore the target rotation.
Optionally instead specify 'no_pitch' to retain the attached entity's own pitch, but use the target yaw.

Note that attaches involving a player will not be properly visible to that player, but will still be visible to *other* players.

It may be ideal to change setting "Packets.Auto init" in the Denizen config to "true" to guarantee this command functions as expected.

# Use to attach random NPC to the air 3 blocks above a linked NPC.
- attach <server.list_npcs.random> to:<npc> offset:0,3,0

This technically can be used on an NPC, but it will trigger the Citizens internal punching-pathfinder.
This attack mode doesn't work well. If you want NPC combat, consider using Sentinel instead: 🔗https://github.com/mcmonkeyprojects/Sentinel/blob/master/README.md.

To cancel an attack, use the 'cancel' argument instead of specifying a target.

# Use to make the player's target entity attack a nearby entity.
- attack <player.target> target:<npc.location.find.living_entities.within[10].random>

# Use to make a random nearby entity attack a player.
- attack <player.location.find.living_entities.within[10].random> target:<player>

# Use to stop an entity from attacking.
- attack <[entity]> cancel

# Use to set an entity on fire.
- burn <player> duration:10s

# Use to cancel fire on entities.
- burn <player.location.find.living_entities.within[10]> duration:0

The effect type must be from 🔗https://hub.spigotmc.org/javadocs/spigot/org/bukkit/potion/PotionEffectType.html.

If you don't specify a duration, it defaults to 60 seconds.
An infinite duration will apply an infinite duration potion effect, refer to ObjectType:DurationTag for more details.

The amplifier is how many levels to *add* over the normal level 1.
If you don't specify an amplifier level, it defaults to 1, meaning an effect of level 2 (this is for historical compatibility reasons).
Specify "amplifier:0" to have no amplifier applied (ie effect level 1).

If no entity is specified, the command will target the linked player.
If there isn't one, the command will target the linked NPC. If there isn't one either, the command will error.

Optionally, specify "no_ambient" to hide some translucent additional particles, while still rendering the main particles.
"Ambient" effects in vanilla come from a beacon, while non-ambient come from a potion.

Optionally, specify "hide_particles" to remove the particle effects entirely.

Optionally, specify "no_icon" to hide the effect icon in the corner of your screen.

Optionally use "no_clear" to prevent clearing any previous effect instance before adding the new one.

# Use to cast a level 1 effect onto the linked player or NPC for 50 seconds.
- cast speed duration:50s amplifier:0

# Use to cast an effect onto the linked player or NPC for an infinite duration with an amplifier of 3 (effect level 4).
- cast jump duration:infinite amplifier:3

# Use to remove an effect from a specific entity.
- cast jump remove <[entity]>

# Use to equip a stone block on the player's head.
- equip <player> head:stone

# Use to equip an iron helmet on two defined players.
- equip <[player]>|<[someplayer]> head:iron_helmet

# Use to unequip all armor off the player.
- equip <player> head:air chest:air legs:air boots:air

# Use to equip a saddle on the horse the player is riding.
- equip <player.vehicle> saddle:saddle

# Use to equip a saddle on all nearby pigs.
- equip <player.location.find_entities[pig].within[10]> saddle:saddle

# Use to equip a horse with iron horse armor.
- equip <[horse]> body:iron_horse_armor

The change doesn't happen on-server, and no armor effects will happen from it.

The equipment can only be seen by certain players. By default, the linked player is used.

The changes will remain in place for as long as the duration is specified (even if the real equipment is changed).
The changes can be manually reset early by using the 'reset' argument.
If you do not provide a duration, the fake equipment will last until manually reset.
This does not persist across server restarts.

Set the item to 'air' to unequip any slot.

# Use to fake-equip a stone block on the player's head.
- fakeequip <player> head:stone duration:10s

# Use to fake-equip an iron helmet on two defined players.
- fakeequip <[player]>|<[someplayer]> head:iron_helmet duration:1m

# Use to fake-unequip all armor off the player.
- fakeequip <player> head:air chest:air legs:air boots:air duration:5s

# Use to make all players within 30 blocks of an entity see it permanently equip a shield.
- fakeequip <[entity]> offhand:shield for:<[entity].find_players_within[30]> duration:0

The input to 'data:' is a list of ObjectType:MapTags, with each map being a frame to send; see Language:Internal Entity Data for more information.

Optionally specify a list of players to fake the data for, defaults to the linked player.

'speed:' is the amount of time between each frame getting sent, supporting sub-tick delays.
Note that this is the delay between each frame, regardless of their content (see examples).

# Animates an item display entity's item for the linked player, and slowly scales it up.
- fakeinternaldata entity:<[item_display]> data:[item=iron_ingot;scale=0.6,0.6,0.6]|[item=gold_ingot;scale=0.8,0.8,0.8]|[item=netherite_ingot;scale=1,1,1] speed:0.5s

# Changes an item display's item, then its scale a second later, then its item again another second later.
- fakeinternaldata entity:<[item_display]> data:[item=stone]|[scale=2,2,2]|[item=waxed_weathered_cut_copper_slab] speed:1s

# Animates a rainbow glow on a display entity for all online players.
- define color <color[red]>
- repeat 256 from:0 as:hue:
  - define frames:->:[glow_color=<[color].with_hue[<[hue]>].argb_integer>]
- fakeinternaldata entity:<[display]> data:<[frames]> for:<server.online_players> speed:0.01s

By default targets the player attached to the script queue and feeds a full amount.

Accepts the 'amount:' argument, which is in half bar increments, up to a total of 20 food points.
The amount may be negative, to cause hunger instead of satiating it.

You can optionally also specify an amount to change the saturation by.
By default, the saturation change will be the same as the food level change.
This is also up to a total of 20 points. This value may also be negative.

Also accepts the 'target:<entity>' argument to specify the entity which will be fed the amount.

# Use to feed the player for 5 foodpoints (or 2.5 bars).
- feed amount:5

# Use to feed an NPC for 10 foodpoints (or 5 bars).
- feed <npc> amount:10

# Use to feed a player from a definition fully without refilling saturation.
- feed <[player]> saturation:0

Optionally specify a list of "destinations" to make it move through a series of checkpoints (disabling the "controller" functionality).

Optionally specify an "origin" location where the entities should teleport to at the start.

Optionally specify the "speed" argument to set how fast the entity should fly.

Optionally specify the "rotationthreshold" to set the minimum threshold (in degrees) before the entity should forcibly rotate to the correct direction.

Use the "cancel" argument to stop an existing flight.

# Use to make a player ride+fly a newly spawned dragon.
- fly <player>|ender_dragon

Specify the list of followers or just one. If no follower is specified, will use the linked NPC.

Specify either the target to follow, or 'stop'. If no target is specified, will use the linked player.

Use 'speed' to set the movement speed multiplier.
Use 'lead' to set how far away the follower will remain from the target (ie, it won't try to get closer than the 'lead' distance).
Use 'max' to set the maximum distance between the follower and the target before the follower will automatically start teleporting to keep up.
Use 'no_teleport' to disable teleporting when the entity is out of range (instead, the entity will simply give up).
Use 'allow_wander' to allow the entity to wander randomly.

The 'max' and 'allow_wander' arguments can only be used on non-NPC entities.

# To make an NPC follow the player in an interact script.
- follow

# To make an NPC stop following.
- follow stop

# To explicitly make an NPC follow the player.
- follow followers:<npc> target:<player>

# To make an NPC follow the player, slowly and at distance.
- follow speed:0.7 lead:10

Optionally specify 'for:' with a list of players to fake the entities' glow state for these players.
When using 'toggle' with the 'for:' argument, the glow state will be toggled for each player separately.
If unspecified, will be set globally.
'for:' players remain tracked even when offline/reconnecting, but are forgotten after server restart.

When not using 'for:', the glow is global / on the real entity, which will persist in that entity's data until changed.

To reset an entity's fake glow use the 'reset' state.
A reset is global by default, use the 'for:' argument to reset specific players.

# Use to make the linked player (or NPC, if there isn't one) glow.
- glow

# Use to toggle whether the linked NPC is glowing.
- glow <npc> toggle

# Use to make an entity glow for specific players, without changing the way other players see it.
- glow <[entity]> for:<[player1]>|<[player2]>

# Use to reset an entity's fake glow state for the linked player.
- glow <[entity]> reset for:<player>

If no amount is specified it will heal the specified player(s)/entity(s) fully.

# Use to fully heal a player.
- heal

# Use to heal a player 5 hearts.
- heal 10

# Use to heal a defined player fully.
- heal <[someplayer]>

If the target is an NPC, you can use the 'state' argument to enable, disable, or toggle the Health trait
(which is used to track the NPC's health, and handle actions such as 'on death').
The Health trait will be enabled by default.

By default, this command will target the linked NPC but can be set to target any other living entity, such as a player or mob.

Optionally specify the 'heal' argument to automatically heal the entity to the new health value.
If not specified, the entity's health will remain wherever it was
(so for example a change from 20 max to 50 max will leave an entity with 20 health out of 50 max).

Additionally, you may input a list of entities, each one will calculate the effects explained above.

# Use to set the NPC's maximum health to 50.
- health 50

# Use to disable tracking of health value on the NPC.
- health state:false

# Use to change a player's health limit and current health both to 50.
- health <player> 50 heal

# Use to change a list of entities' health limits all to 50.
- health <player.location.find.living_entities.within[10]> 50

If no entities are specified: if there is a linked player, the command targets that. If there is no linked
player but there is a linked NPC, the command targets the NPC. If neither is available, the command will error.

Does a specified amount of damage usually, but, if no damage is specified, does precisely 1HP worth of damage (half a heart).

Optionally, specify (source:<entity>) to make the system treat that entity as the attacker.
If using a block-type cause such as "contact", you *must* specify (source:<location>) to set that block location as the attacker. The block can be any block, even just "<player.location>" (as long as the player in inside a world).

You may also specify a damage cause to fire a proper damage event with the given cause, only doing the damage if the event wasn't cancelled.
Calculates the 'final damage' rather than using the raw damage input number. See Language:damage cause for damage causes.

Using a valid 'cause' value is best when trying to replicate natural damage, excluding it is best when trying to force the raw damage through.
Note that using invalid or impossible causes may lead to bugs

# Use to hurt the player for 1 HP.
- hurt

# Use to hurt the NPC for 5 HP.
- hurt 5 <npc>

# Use to cause the player to hurt the NPC for all its health (if unarmored).
- hurt <npc.health> <npc> cause:CUSTOM source:<player>

Optionally specify 'for:' with a list of players to fake the entities' visibility state for these players.
When using 'toggle' with the 'for:' argument, the visibility state will be toggled for each player separately.
If unspecified, will be set globally.
'for:' players remain tracked even when offline/reconnecting, but are forgotten after server restart.
Note that using the 'for:' argument won't apply the 'invisible' trait to NPCs.

When not using 'for:', the effect is global / on the real entity, which will persist in that entity's data until changed.

To reset an entity's fake visibility use the 'reset' state.
A reset is global by default, use the 'for:' argument to reset specific players.

NPCs can't be made invisible if not added to the playerlist (the invisible trait adds the NPC to the playerlist when set).
See Language:invisible trait

# Use to make the linked player (or NPC, if there isn't one) invisible.
- invisible

# Use to make the linked NPC visible if previously invisible, and invisible if not.
- invisible <npc> toggle

# Use to make an entity visible for specific players, without changing the way other players see it.
- invisible <[entity]> false for:<[player1]>|<[player2]>

# Use to reset an entity's fake visibility state for the linked player.
- invisible <[entity]> reset for:<player>

If no entities are specified, the command targets the linked player.
If there is no linked player, the command targets the linked NPC.
If neither is available, the command errors.

# Use to kill the linked player.
- kill

# Use to kill the linked NPC.
- kill <npc>

# Use to kill all monsters within 10 blocks of the linked player.
- kill <player.location.find_entities[monster].within[10]>

Non-player NPCs can be leashed if '/npc leashable' is enabled.

# Use to attach a leash to the player's target.
- leash <player.target> holder:<player>

# Use to attach the closest cow in 10 blocks to the fence the player is looking at.
- leash <player.location.find_entities[cow].within[10].first> holder:<player.cursor_on>

# Use to release the target entity.
- leash cancel <player.target>

You can specify either a target location, or a yaw and pitch.

Can be used on players.

If a duration is set, the entity cannot look away from the location until the duration has expired.
Use the cancel argument to end the duration earlier.

Optionally, you can use the "offthread_repeat:" option alongside "yaw:" and "pitch:"
to cause a player's rotation to be smoothed out with a specified number of extra async rotation packets within a single tick.

# Use to point an NPC towards a spot.
- look <npc> <player.location>

# Use to force a player to stare at a spot for some time.
- look <player> <npc.location> duration:10s

# Use to mount an NPC on top of a player.
- mount <npc>|<player>

# Use to spawn a mutant pile of mobs.
- mount cow|pig|sheep|chicken

# Use to place a diamond block above a player's head.
- mount falling_block,diamond_block|<player>

# Use to force an entity in a vehicle.
- mount <player>|boat

You must specify an entity to be pushed.

Usually, you should specify the origin and the destination. If unspecified, they will be assumed from contextual data.

You can specify the script to be run with the (script:<name>) argument,
and optionally specify definitions to be available in this script with the (def:<element>|...) argument.

Using the 'no_damage' argument causes the entity to receive no damage when they stop moving.

Optionally use the "ignore_collision" argument to ignore block collisions.

Optionally use "speed:#" to set how fast it should be pushed.

Optionally use "force_along" to cause the entity to teleport through any blockage.

Optionally use "no_rotate" to prevent entities being rotated at the start of the push.

Optionally use "duration:#" to set the max length of time to continue pushing.

The push command is ~waitable. Refer to Language:~waitable.

# Use to launch an arrow straight towards a target.
- push arrow destination:<player.location>

# Use to launch an entity into the air.
- push cow

Any NPC removed this way is completely removed, as if by '/npc remove'.
For temporary NPC removal, see Command:despawn.

If a generic entity name is given (like 'zombie'), this will remove all entities of that type from the given world.
Optionally, you may specify a world to target.
(Defaults to the world of the player running the command)

# Use to remove the entity the player is looking at.
- remove <player.target>

# Use to remove all nearby entities around the player, excluding the player itself.
- remove <player.location.find_entities.within[10].exclude[<player>]>

# Use to remove all dropped items in the world called cookies.
- remove dropped_item world:cookies

Can rename a spawned or unspawned NPC to any name up to 256 characters.

Can rename a vanilla entity to any name up to 256 characters, and will automatically make the nameplate visible.

Can rename a player to any name up to 16 characters. This will affect only the player's nameplate.

Optionally specify 'per_player' to reprocess the input tags for each player when renaming a vanilla entity
(meaning, if you use "- rename <player.name> t:<[someent]> per_player", every player will see their own name on that entity).
A per_player rename will remain active until the entity is renamed again or the server is restarted.
Rename to "cancel" per_player to intentionally end a per_player rename.
Optionally specify "for:" a list of players when using per_player.

Optionally specify 'list_name_only' to only change the tab list name for a player. Works with 'per_player'.

# Use to rename the linked NPC to 'Bob'.
- rename Bob

# Use to rename a different NPC to 'Bob'.
- rename Bob t:<[some_npc]>

# Use to make an entity show players their own name for 10 seconds.
- rename <green><player.name> t:<[some_entity]> per_player
- wait 10s
- rename cancel t:<[some_entity]> per_player

The yaw and pitch arguments specify how much the entity will rotate each step. Default to 10 and 0 respectively.

The frequency argument specifies how long it takes between each rotation step. Defaults to 1t.

The duration argument specifies how long the whole rotation process will last. Defaults to 1s.
Alternatively, use "infinite" if you want the entity to spin forever.

You can use "cancel" to prematurely stop the ongoing rotation (useful when set to infinite)

The rotate command is ~waitable. Refer to Language:~waitable.

# Use to rotate the player's yaw by 10 every tick for 3 seconds total
- rotate <player> duration:3s

# Use to rotate the player's pitch by 20 every 5 ticks for a second total
- rotate <player> yaw:0.0 pitch:20.0 frequency:5t

# Use to prematurely stop the player's rotation
- rotate cancel <player>

The launch has three modes: arc, lead, and direct.

The "arc" mode calculates a launch arc to exactly hit the target location.
If you want to use this, specify the "height" argument as how high the arc should go, in blocks.
Do not specify "speed" or "lead".
You can optionally specify a custom "gravity" (hidden from syntax line intentionally) if you know what you're doing and really need to.

The "lead" mode calculates a modified arc intended to hit a target based on a lead factor (usually the entity's velocity).
To use, specify the "lead" argument as a vector and "speed" as a launch speed.
Do not specify "height".

Generally, most users should prefer direct mode: it just launches straight in the direction of the destination, at the speed you specify.
To use this, just input the "speed" argument, and don't specify "height" or "lead".

If the origin is not an entity, you can specify a "shooter" so the damage handling code knows who to assume shot the projectile.

Normally, a list of entities will spawn mounted on top of each other. To have them instead fire separately and spread out,
specify the "spread" argument with a decimal number indicating how wide to spread the entities.

Optionally, add "no_rotate" to prevent the shoot command from rotating launched entities.

Use the "script:<name>" argument to run a task script when the projectiles land.
When that script runs, the following definitions will be available:
<[shot_entities]> for all shot entities (as in, the projectiles),
<[last_entity]> for the last one (The controlling entity),
<[location]> for the last known location of the last shot entity, and
<[hit_entities]> for a list of any entities that were hit by fired projectiles.

The shoot command is ~waitable. Refer to Language:~waitable.

Note that for ~waiting or the "script" arg, tracking is only accurate for projectile entities (such as arrows). This will be inaccurately estimated for other entity types.

# Use to shoot an arrow from the NPC to perfectly hit the player.
- shoot arrow origin:<npc> destination:<player.location>

# Use to shoot an arrow out of the player with a given speed.
- shoot arrow origin:<player> speed:2

Can optionally use the 'fake' argument to apply a fake sneak using packets, either globally or for specific players.
Use 'stopfake' to disable faking of sneak.
A fake sneak only affects the name plate, not the entity's pose.

Note: using this command on a player will only show to other players. You cannot alter a player in their own view.
Note that Property:EntityTag.is_sneaking is also available.

# Make the linked NPC start sneaking.
- sneak <npc>

# Make the linked NPC stop sneaking.
- sneak <npc> stop

Accepts the 'target:<entity>' argument which will cause all spawned entities to follow and attack the targeted entity.

If the persistent argument is present, the entity will not despawn when no players are within range, causing the entity to remain until killed.

Optionally specify 'reason:<reason>' (Paper only) to specify the reason an entity is spawning for the 'entity spawns' event,
using any reason from 🔗https://hub.spigotmc.org/javadocs/spigot/org/bukkit/event/entity/CreatureSpawnEvent.SpawnReason.html

If the location isn't specified, will use either the linked NPC's location, or the linked player's location.

# Use to spawn a spider at the player's location.
- spawn spider <player.location>

# Use to spawn a spider at the player's location which will automatically target the player.
- spawn spider <player.location> target:<player>

# Use to spawn a swarm of creepers around the npc, which will not despawn until killed.
- spawn creeper|creeper|creeper|creeper|creeper <npc.location> persistent

Instead of a valid entity, an unspawned NPC or an offline player may also be used.

Optionally specify "relative" to use relative teleportation (Paper only). This is primarily useful only for players, but available for all entities.
Relative teleports are smoother for the client when teleporting over short distances.
Optionally, you may use "relative_axes:" to specify a set of axes to move relative on (and other axes will be treated as absolute), as any of "X", "Y", "Z", "YAW", "PITCH".
Optionally, you may use "offthread_repeat:" with the relative arg when teleporting a player to smooth out the teleport with a specified number of extra async packets sent within a single tick.
Optionally, specify "offthread_yaw" or "offthread_pitch" while using offthread_repeat to smooth the player's yaw/pitch to the new location's yaw/pitch.

Optionally, specify additional teleport options using the 'entity_options:' arguments (Paper only).
This allows things like retaining an open inventory when teleporting - see the links below for more information.
See 🔗https://jd.papermc.io/paper/1.19/io/papermc/paper/entity/TeleportFlag.EntityState.html for all possible options.
Note that the API this is based on is marked as experimental in Paper, and so may change in the future.

# Use to teleport a player to the location their cursor is pointing at.
- teleport <player> <player.cursor_on>

# Use to teleport a player high above.
- teleport <player> <player.location.above[200]>

# Use to teleport to a random online player.
- teleport <player> <server.online_players.random.location>

# Use to teleport all players to your location.
- teleport <server.online_players> <player.location>

# Use to teleport the NPC to a location that was noted with the <@link command note> command.
- teleport <npc> my_prenoted_location

# Use to teleport a player to some location, and inform events that it was caused by a nether portal.
- teleport <player> <server.flag[nether_hub_location]> cause:nether_portal

# Use to teleport the player without closing their currently open inventory.
- teleport <player> <player.location.below[5]> entity_options:retain_open_inventory

Specify a destination location to walk to, or 'stop' to stop all walking.

Optionally, specify a "speed:<#.#>" argument to control the speed of the NPCs.

Optionally, specify "auto_range" to automatically set the path range for the walk instruction
(if not specified, an NPC will not be able to walk to a location outside of its existing path range, by default 25 blocks).
(Does not apply to non-NPC entities).

Note that in most cases, the walk command should not be used for paths longer than 100 blocks.
For ideal performance, keep it below 25.

Optionally, specify a list of entities to give them all the same walk instruction at the same time.
If the list is of NPCs, optionally specify a "radius:<#.#>" argument to change the flocking radius.
('Radius' does not apply to non-NPC entities).

Optionally, specify "lookat:<location>" to cause the NPCs to stare at a specific location while walking (as opposed to straight ahead).
('Radius' does not apply to non-NPC entities).

The walk command is ~waitable. Refer to Language:~waitable.

# Use to make the NPC walk to an anchored position.
- walk <npc> <npc.anchor[spot1]>

# Use to make the NPC walk to an anchored position that may be far away.
- walk <npc> <npc.anchor[spot2]> auto_range

# Use to make the NPC walk to an anchored position while looking backwards.
- walk <npc> <npc.anchor[spot3]> lookat:<npc.anchor[spot2]>

# Use to make the NPC walk to an anchored position, and then say something after arrival, using ~waitable syntax.
- ~walk <npc> <npc.anchor[spot4]>
- chat "I'm here!"

# Use to make a list of NPCs stored in a flag all move together, with a flocking radius based on the number of NPCs included.
- walk <player.flag[squad]> radius:<player.flag[squad].size> <player.location>

Player animations require a Player-type entity or NPC. Available player animations include:
ARM_SWING, HURT, CRIT, MAGIC_CRIT, SIT, SLEEP, SNEAK, STOP_SITTING, STOP_SLEEPING, STOP_SNEAKING,
START_USE_MAINHAND_ITEM, START_USE_OFFHAND_ITEM, STOP_USE_ITEM, EAT_FOOD, ARM_SWING_OFFHAND

All entities also have available Bukkit's entity effect list:
🔗https://hub.spigotmc.org/javadocs/spigot/org/bukkit/EntityEffect.html
These EntityEffect options can optionally be played only for specific players with the "for:" argument input.

In addition, Denizen adds a few new entity animations:
SKELETON_START_SWING_ARM, SKELETON_STOP_SWING_ARM,
POLAR_BEAR_START_STANDING, POLAR_BEAR_STOP_STANDING,
HORSE_BUCK, HORSE_START_STANDING, HORSE_STOP_STANDING,
IRON_GOLEM_ATTACK,
VILLAGER_SHAKE_HEAD,
SWING_MAIN_HAND, SWING_OFF_HAND

Note that the above list only applies where logical, EG 'WOLF_' animations only apply to wolves.

In versions 1.20+, to specify the direction of damage for the HURT animation, use Mechanism:EntityTag.play_hurt_animation

# Use to make a player appear to get hurt.
- animate <player> animation:hurt

# Use to make a wolf NPC shake.
- animate <npc> animation:wolf_shake

The starting directory is server/plugins/Denizen.

May overwrite existing copies of files.

Note that in most cases this command should be ~waited for (like "- ~filecopy ..."). Refer to Language:~waitable.

This command can be disabled by setting Denizen config option "Commands.Filecopy.Allow copying files" to false.

# Use to copy a custom YAML data file to a backup folder, overwriting any old backup of it that exists.
- ~filecopy o:data/custom.yml d:data/backup.yml overwrite save:copy
- narrate "Copy success<&co> <entry[copy].success>"

The starting directory is server/plugins/Denizen.

Note that in most cases this command should be ~waited for (like "- ~fileread ..."). Refer to Language:~waitable.

This command must be enabled by setting Denizen config option "Commands.File.Allow read" to true.

# Use to read 'myfile' and narrate the text content.
- ~fileread path:data/myfile.dat save:read
- narrate "Read data: <entry[read].data.utf8_decode>"

Will overwrite any existing file at the path.

The starting directory is server/plugins/Denizen.

Directories will automatically be generated as-needed.

Note that in most cases this command should be ~waited for (like "- ~filewrite ..."). Refer to Language:~waitable.

This command must be enabled by setting Denizen config option "Commands.File.Allow write" to true.

# Use to write some simple text to 'myfile'
- ~filewrite path:data/myfile.dat data:<element[Hello].utf8_encode>

You just input a file name and some text, and it will store that information in the file with a date/time stamp and the chosen type ('INFO' by default).
If you don't want the date/time stamp and type, you can set the type to 'none' and it will only add the message text.

Regardless of type, each usage of the log command will add a new line to the file, you can't just keep adding to one line.

You might choose to use this to record some important things,
for example, every time a player uses a dangerous command you might log the player's name and their location, so you'll know who to blame if you find something damaged.

Remember that the file location is inside the server's primary folder. You most likely want to prefix file names with a folder name, For example: 'file:logs/security.log'

If the file or folder path you input do not already exist, they will be automatically created.

Warning: Remember that file operations are dangerous! A typo in the filename could ruin your server.
It's recommended you use this command minimally.

This command can be disabled by setting Denizen config option "Commands.Log.Allow logging" to false.

This should almost always be ~waited for. Refer to Language:~waitable.

# Use to log some information to a file.
- ~log "Security breach on level 3!" type:severe file:securitylog.txt

# Use to log a player's name and location when they did something dangerous.
- ~log "<player.name> used the '/EXPLODE' command at <player.location.simple>!" type:warning file:security.log

# Use to write information directly to a file.
- ~log "This won't have a date or type" type:none file:example.log

# Use to clear a log file and write some text at the start.
- ~log "// Log File Generated by my Denizen script, do not edit!" type:clear file:myfile.log

# Use to clear a log file entirely.
- ~log "" type:clear file:myfile.log

This commands exists primarily for interoperability with pre-existing data files and other plugins.
It should never be used for storing data that only Denizen needs to use. Consider instead using Command:flag.

Use waitable syntax ("- ~yaml load:...") with load or savefile actions to avoid locking up the server during file IO.
Refer to Language:~waitable.

For loading and saving, the starting path is within 'plugins/Denizen'.
The file path follows standard system file path rules. That means '/' separators folders,
and '..' as a folder name means go-up-one folder, for example '../WorldGuard/config.yml' would load the WorldGuard plugin config.
Also be aware that some servers (Linux/Mac based) have case sensitive file systems while others (Windows based) don't.
Generally, when using existing paths, make sure your casing is correct. When creating new paths, prefer all-lowercase to reduce risk of issues.

Please note that all usages of the YAML command except for "load" and "savefile" arguments are purely in memory.
That means, if you use "set" to make changes, those changes will not be saved to any file, until you use "savefile".
Similarly, "create" does not create any file, instead it only creates a YAML object in RAM.

When loading, optionally specify 'raw_format' to indicate that this YAML file needs to maintain compatibility with some external system using raw YAML data
(for example, when altering YAML data files used by external plugins).
Note that this can have side effects of custom data disappearing (for example, the value "yes" gets magically converted to "true") or strange data parsing in.

In-memory changes to a loaded YAML object will mark that object as having changes. Before saving,
you can check whether the YAML object needs to be written to disk with the has_changes tag.

Note that the '.yml' extension is not automatically appended, and you will have to include that in filenames.

All usages of the YAML command must include the "id:" argument. This is any arbitrary name, as plaintext or from a tag,
to uniquely and globally identify the YAML object in memory. This ID can only be used by one YAML object at a time.
IDs are stored when "create" or "load" arguments are used, and only removed when "unload" is used.
If, for example, you have a unique YAML data container per-player, you might use something like "id:myscript_<player>".

For ways to use the "set" argument, refer to Language:data actions.

When setting a value directly, you can optionally specify "data_type" as "string", "integer", "double", "boolean", or "auto",
to force the input to a specific data type, which may be needed for compatibility with some external YAML files.
Only applicable when setting a single value, not lists/maps/etc.
'Auto' will attempt to choose the best type for the value.

# Use to create a new YAML file.
- yaml create id:myfile

# Use to load a YAML file from disk.
- ~yaml load:myfile.yml id:myfile

# Use to modify a YAML file similarly to a flag.
- yaml id:myfile set my.key:HelloWorld

# Use to save a YAML file to disk.
- ~yaml savefile:myfile.yml id:myfile

# Use to unload a YAML file from memory.
- yaml unload id:myfile

# Use to modify a YAML file similarly to a flag.
- yaml id:myfile set my.key:+:2

# Use to modify a YAML file similarly to a flag.
- yaml id:myfile set my.key[2]:hello

# Use to modify a copy the contents of one YAML key to a new owning key.
- yaml id:myfile copykey:my.first.key my.new.key

# Use to modify a copy the contents of one YAML key to a new owning key on a different YAML file.
- yaml id:myfile copykey:my.first.key my.new.key to_id:myotherfile

"id:" - the id of the image to draw on, see Command:Image.
"x:" and "y:" - the position that should be drawn on, see Language:Image positions.

For pixels or shapes:
"color:" - a ObjectType:ColorTag of the color to draw in.

For non-pixel shapes:
"width:" and "height:" - the size of the shape being drawn, required.
"filled" - whether the shape should be filled or just a border. optional, defaults to false.

And for images:
"image:" - the image to draw, required.
"width:" and "height:" - the size to rescale the image being drawn to, optional.

# Use to draw a single red pixel in the top left corner of an image.
- draw id:image pixel x:0 y:0 color:red

# Use to draw a purple 100x100 filled circle in the top left of an image.
- draw id:image oval x:0 y:0 width:100 height:100 color:purple filled