Group Element (Data)

Context: HL Kit … Kit Reference … Structural File Reference 

The "group" Element

One of the cornerstones of describing objects in the Kit is the tags mechanism. All tags belong to named tag groups, with each tag group having a defined set of valid tag values that can be used. Tag groups also have a number of characteristics which dictate how the tags within that group are handled. Each tag group is specified through the use of a "group" element. The complete list of attributes for this element is below.

id	Id – Specifies the unique id of the tag group. This id is used in all references to the tag group.
dynamic	(Optional) Boolean – Indicates whether the tags for this group can be dynamically defined "on-the-fly" by specifying the tag directly on a thing. If a tag group is not dynamic, then all tags for the group must be defined within the group prior to their use within data files. If a tag group is dynamic, new tags can be defined throughout the data files by simply including the new tag id within a "tag" element on a thing. Dynamic tag groups cannot be assigned "explicit" sequencing. Default: "no".
sequence	(Optional) Set – Designates the sorting sequence to be used for the tags within the group. When you specify the tag group within a sort set, this sequence is used. Must be one of these values: ascii – Sort using ASCII codes (digits, all upper case, all lower case). nocase – Sort ignoring case (digits, upper case A, lower case A, upper B, etc.). textvalue – Treat the name of each tag as a numeric value (if no value, treated as zero for sorting). idvalue – Treat the id of each tag as a numeric value (if no value, treated as zero for sorting). explicit – Sort on the value of the "order" attribute assigned to each tag. id – Sort on the unique id of each tag as if it were text (allows handling of absolutely any situation). Default: "ascii".
minvalue	(Optional) Integer – Specifies the starting value to use for automatically generating value-based tags (see below). Default: "0".
maxvalue	(Optional) Integer – Specifies the starting value to use for automatically generating value-based tags (see below). Default: "0".
autoassign	(Optional) Set – Designates how tags from this group are handled when a thing is copied for use within the Editor. This behavior only applies when the tag group possesses auto-created tags, such as with identity tags. Must be one of the following: yes – Tags from this group are always considered to be auto-assigned and are therefore never copied within the Editor. no – Tags from this group are always copied within the Editor, except for identity tags that reference the thing being copied. This setting enables proper handling of identity tags for other things that are assigned, such as in situations where one things "counts as" another thing. default – Tags from this group are copied within the Editor only when they were not automatically created by the Kit. Default: "default".

NOTE! Tag groups can automatically generate "value" tags for a given integer range via use of the "minvalue" and/or "maxvalue" attributes. Value tags possess a unique id that is simply an integer value, such as "42". Specifying either or both of these attributes as non-zero makes it easy to create a group of tags number X-Y (e.g. 1-42). When value tags are created, the group automatically uses "idvalue" sequencing. You can define explicit tags for the group that are blended with the auto-generated tags, and any author-defined tag takes precedence over whatever would be auto-generated. Lastly, if the group is dynamic, then additional tags can be defined on-the-fly, as needed.

NOTE! Dynamic tags are processed in the order they are encountered when the data files are compiled, and there is no guarantee of the order in which dynamic tags will be processed. If a dynamic tag has already been defined when it is next encountered, the original definition is used. This means that the first definition of a dynamic tag that happens to be encountered during compilation is the one that will be used for all instances of the tag, so you should strive to ensure that all dynamically defined tags have identical specifications.

The "group" element also possesses child elements that define the individual tags of the group. The list of these child elements is below and must appear in the order shown. Click on the link to access the details for each element.

value

Zero or more "value" elements may appear as defined by the given link. This element specifies the tags that exist for the group. NOTE! While it is valid to specify zero tags here, every tag group must have at least one tag defined. You can only specify zero tags here if the group is dynamic and at least one tag is defined directly on a thing.

The "value" Element

The "value" element defines a tag for the containing tag group. The complete list of attributes for this element is below.

id	Id – Specifies the unique id of the tag within the group. This id is used in all references to the tag.
name	(Optional) Text – Name assigned to the tag. If empty, the unique id is used as the name. Maximum length is 100 characters. Default: Empty.
order	(Optional) Integer – Specifies the explicit order value to be used when sorting this tag against others within the tag group. This attribute only applies when the tag group is assigned the "explicit" sequence.

Example

The following example demonstrates what a "group" element might look like. All default values are assumed for optional attributes.

<group id="Equipment" dynamic="yes">
  <value id="Hand" name="Requires one or more hands"/>
  <value id="TwoHand" name="Requires two hands"/>
  <value id="AutoEquip" name="Gear is auto-equipped"/>
  <value id="Natural" name="Natural weapon/armor/etc."/>
  <value id="CustomGear" name="Custom Gear"/>
  </group>