YAML Basics: Part 1
YAML, which stands for YAML Ain't Markup Language, is a file format that describes data in a human-friendly way. Using a YAML file specifies information about your DragonRealms character through the use of variables, lists, and arrays - although you don't need to know what those are to create your own YAML.
While looking through example YAMLs in the Lich profile directory (or in the profiles section of the repository) can be a quick and informative way of understanding the usefulness of the YAML format, doing so can be overwhelming. We will begin with basic concepts, increasing in complexity over the course of this documentation.
N.B. This document assumes a certain level of game knowledge. If you have questions pertaining to the game itself, please see Elanthipedia and specifically the new player guide for your chosen guild.
Due to the formatting requirements articulated in the next section, you will likely require a more robust and YAML-friendly text editor over Notepad or Microsoft Word. Unless you are at least a hobby programmer with your own preference in code editors, we highly recommend Visual Studio Code along with installing the Red Hat YAML Plugin.
Building a YAML file is one of the larger barriers to entry for new users of Lich, and like all computer code, proper formatting, including spacing and indentation, is absolutely critical to the proper functioning of the YAML. Visual Studio Code, with the specified plugin, will set you up for success by visually identifying many common formatting errors within the file.
Within Visual Studio Code, we also recommend you convert tabs to two spaces. In VSC go to File -> Preferences -> Settings. A window will come up. In the search bar, search for Tab Size, then specify 2 in the box, so all tab indentations equal 2 spaces.
YAML files begin with the document header: --- (three dashes, no spaces, on their own line).
YAML uses whitespace (spaces, not tabs!) indentation to denote structure. Structural information in YAML files is case-sensitive. Comments begin with #. A list element begins with a - and space: - something is an element named 'something' that is part of a list.
Example:
# hunting zone information
hunting_info:
- :zone: rats
args:
- d0
- r3
:duration: 60
# hunting zone information - A comment. Comments are ignored by the YAML parser. They can be used to explain a particular line or separate your document into sections.
hunting_info: - The start of a section called "hunting_info". Note that "hunting_info" is not the same as "Hunting info" or "Hunting_Info"!
- :zone: rats - Indicates that the zone we wish to hunt in is named "rats"
args: - Note the two spaces used for indentation. This means this "args" section modifies the - :zone: rats section. What follows will be a list of "args", or arguments.
- d0 - d0 means "dance threshold of 0". This means "dance with zero creatures". Or, "kill everything". For comparison,
- d1 would mean "dance threshold of 1", meaning "dance with one creature" or "kill everything until one remains". - d4 would mean "kill everything until 5 remain", but since you can only have 4 engaged creatures you would never attack
(useful for Empaths)
- r3 - r3 means "retreat threshold of 3". This means "retreat when three creatures are in the room". This will utilize ranged and/or spells while remaining in missile range.
:duration: 60 - How long, in minutes, you wish to hunt.
Breaking down a YAML into sections often makes handling the information more manageable.
Any attribute left blank or removed entirely will default to false or off or whatever is contextually sensible.
How would I know what is a valid :zone: for hunting_info? How would I know that d# means dance threshold, or that such a thing even exists?
Most systems are documented in a manner that allows a user to find his or her own answers. With dr-scripts and Lich for DragonRealms, most information can be found in pre-existing YAML files under your Lich install profile directory. Viewing any of these files should provide meaningful information to help build out your own YAMLs. A brief list of useful YAMLs follows.
lich/data/base-hunting.yaml - There are two main sections in this file: escort_zones and hunting_zones. Ignore escort_zones for the moment. Under hunting_zones you will find a series of entries labeled by each zone name, followed by a list of rooms using the dash-space format. For example, to set your YAML to hunt in louts, set :zone: louts. The scripts will use the listed numbers (which are room numbers) to move you to your hunting area.
lich/data/base-spells.yaml - This file lists all supported prep and cast messaging, as well as khri, rituals, and other forms of magic. Note that you can edit your copy of these files if you feel a message is missing. Please file an issue with any missing messages, however, so that everyone can use your changes!
lich/profiles/base.yaml - This document lists nearly all supported values for a YAML. Browsing base.yaml will provide useful examples of how a YAML should be setup, and what can be added or changed.
Individual script documentation exists at the Lich script repository on Elanthipedia. Simply expand a particular script's section to see detailed (in progress) documentation. In our example so far, documentation for dance and retreat thresholds will be under combat-trainer.
You may notice that the provided guild example YAMLs (see section 5) do not include every value that is listed in base.yaml. Only values you want to change should be included in your Character-setup.yaml. For example, in base.yaml stop_pick_on_mindlock is set to true. If you want your character to simply pick through all boxes in your possession, in your Character-setup.yaml you would change that to stop_pick_on_mindlock: false. Again, only values you wish to change should be detailed in your character-specific YAML.
If you took the time to browse the Lich script repository and expanded a few script sections (e.g., combat-trainer, crossing-training, crossing-repair) you might notice that the script-specific arguments appear in YAML files. This point is key:
Your YAML stores all settings for all scripts used by Lich.
So while a complete YAML might seem overwhelming, it is merely a collection of much smaller sections.