Denizen Script Commands

Commands are always written with a '-' before them, and are the core component of any script, the primary way to cause things to happen.
Learn about how commands work in The Beginner's Guide.

Showing 1 out of 183 commands...
Syntaxyaml [create]/[load:<file>]/[loadtext:<text> raw_format]/[unload]/[savefile:<file>]/[copykey:<source_key> <target_key> (to_id:<name>)]/[set <key>([<#>])(:<action>):<value> (data_type:{string}/integer/double/boolean/auto)] [id:<name>]
Short DescriptionEdits YAML data, especially for YAML files.
Full DescriptionEdits YAML configuration data.

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.
Related Tags<yaml[<idname>].contains[<path>]> Returns true if the file has the specified path. (...)
<yaml[<idname>].read[<path>]> Returns the value from a data key on the YAML document as an ElementTag, ListTag, or MapTag.
<yaml[<idname>].list_keys[<path>]> Returns a ListTag of all the keys at the path (and not sub-keys). (...)
<yaml[<idname>].has_changes> Returns whether this YAML object has had changes since the last save or load.
Usage Example
#Use to create a new YAML file.
- yaml create id:myfile
Usage Example
#Use to load a YAML file from disk.
- ~yaml load:myfile.yml id:myfile
Usage Example
#Use to modify a YAML file similarly to a flag.
- yaml id:myfile set my.key:HelloWorld
Usage Example
#Use to save a YAML file to disk.
- ~yaml savefile:myfile.yml id:myfile
Usage Example
#Use to unload a YAML file from memory.
- yaml unload id:myfile
Usage Example
#Use to modify a YAML file similarly to a flag.
- yaml id:myfile set my.key:+:2
Usage Example
#Use to modify a YAML file similarly to a flag.
- yaml id:myfile set my.key[2]:hello
Usage Example
#Use to modify a copy the contents of one YAML key to a new owning key.
- yaml id:myfile copykey:my.first.key
Usage Example
#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 to_id:myotherfile