XML Attributes in Data Files

From HLKitWiki
Jump to: navigation, search

Context: HL KitKit Reference 

All of the information contained within data files is managed through XML elements, attributes, and PCDATA. Each XML element typically has a number of attributes which dictate the characteristics of that element. Some attributes will be required and some will be optional. When an attribute is optional, it will be clearly designated as such, along with the default value. Unless specified as optional, all attributes are required.

The XML specification allows attributes to represent virtually anything with a text value. However, the Kit differentiates between various types of attributes, each of which has various rules associated with the values it can be assigned. Within the Kit Reference, each attribute’s type will be specified in its description. The following types of attributes are utilized, with the indicated constraints being imposed.

Text Text attributes must always consist of standard ASCII text characters. Unless specified otherwise in the description of the attribute, text attributes have no additional constraints other than those dictated by the use of the attribute’s contents. For example, a text attribute that specifies a file name needs to comply with the naming rules for files, else attempts to use the file name will fail. Any special constraints are indicated within the attribute description.
Integer Integer attributes must specify an integer value. In general, integer attributes will represent positive numbers, although it is valid to specify a negative value when appropriate.
Float Float attributes must specify a floating point value (e.g. 3.14159). In general, only positive values are used, although negative values are sometimes allowed. The attribute description will specify any restrictions.
Boolean Boolean attributes must specify a value of either “yes” or “no”. The name of the Boolean attribute will typically give a clear indication of the meaning of “yes” or “no”. For example, tag groups have a “visible” attribute, where the meanings of “yes” and “no” are clear.
Id Ids represent the unique id of an object. The rules for Unique Ids are outlined separately.
Set Set-based attributes must specify one of an explicit set of values. Boolean attributes are an example of a set-based attribute, wherein the value must be specified as one of the two valid choices: “yes” and “no”. Set-based attributes will specify the valid values and their meanings.

NOTE! Many attributes of type "text" will have an appropriate maximum length specified in their description. It is perfectly valid to specify a value that exceeds the indicated maximum within an XML file, since XML imposes no constraints. However, if you exceed the designated maximum length for a text attribute, HL will either report an error or simply truncate the text to the maximum length allowed (depending on the context). This can potentially yield unintended results, so be careful when specifying text attributes. Some text attributes have no maximum length, in which case HL will utilize whatever you specify for the attribute.