Throughout this document I'm going to be using some terms which may be confusing. I will try to explain them in context, but you may be jumping straight to the one document that you need to fix your character for the game tomorrow, so you don't have time to read the whole thing. I'm also using some shorthand throughout that is going to be specific to the Hero Lab data system, so even if you know what you are doing, some of it may be confusing.


HL Hero Lab. I'm using this or HeroLab as a substitute for the program's name and the company that makes it.

<thing> All of the data that lives in <thing> code. That is to say, a catch-all for Races, Powers, Feats, Items, Features, Languages, Sourcebooks, etc, etc, etc.

<thing>s Plural <thing>. Also my English major wife and English teacher mother probably feel like I'm stabbing them in the spleen every time this abomination is written down.

bootstrap This is both the code and what it does. <bootstrap thing=...> grabs the <thing> being bootstrapped when the primary <thing> is loaded. See "Race" for an extensive description of the use.

tag(s) I'm using this poorly. Some of the time I mean Element. The start tag is the part that begins an element, the end tag is the part that ends it: <thing...> and </thing>. The whole thing, is an element. Each bit of code inside it with a start and end tag is also an element: <fieldval field="racInt" Value="9"/> (notice the element has an end tag /> instead of a closing the opening tag and then having a separate end tag). I call them tags because of how they work in my mind, which is a terrible way to build a tutorial. I'm sorry about that. Also some of the elements are litterally <tag> elements.

Fluff/Fluffy Text or information that doesn't have any actual rules need. Specifically in this case, it's text that doesn't affect HL's math or anything "real". Think italicized text on Magic cards.

Crunchy Information that is actual rules. Specifically code that makes HL do something, like bootstrapping or math.

User Also "end user". This is shorthand for "The person who is making a character with Hero Lab."

Whitespace Spaces, hard line breaks, etc.



When I'm showing actual code in the tutorial, I will be using a monospace font to make it stand out:

<thing id="rXXXX" name="XXXX" description="XXXXXXXXXXXX" compset="Race" uniqueness="unique">

In some other cases I may use code without standing it off, but everything in the monospace font (each letter/number/space/etc is the same width) will be code.

Further, in some code I will use placeholders. XXXXXXX (or any other number of Capital Xs) denotes an area where the text changes, and is usually letters. For example, the "rXXXX" above means that the ID for that thing starts with an "r" and ends with whatever additional text. Maybe "rElf" or "rUnicorn" and so on. Numbers are designated by "9", and usually the number of 9s denotes the length of the commonly included number. A racial bonus to intelligence, for example, would be shown as Value="9" even though the actual number is never going to be that large, to show that it is usually 1 number (not, say, +20 to int). A number between 1 and 100 would be shown as "999". I can't think of a place where the actual size of the number is actually restricted (maybe there is a hardcoded chart for attribute bonuses), so in most places the number of 9s is more of a hint than a requirement. You will not need to pad a "999" with 0s if you only want to put in "2" (you don't need to do "002").

If a 9 is used as placeholder, it will only take numbers. If it is an X placeholder, you may put in almost anything. Most will not allow spaces, punctuation, and non-english letters. This is not particularly limiting because mostly these are fields that the end user will never see, and are only used for reference within the program. The description field is more open, but it has its own issues (appostrophes are the most common issue) but these will be examined as needed.

Finally, whitespace. XML doesn't need whitespace. If you want to put everything in a single line with no spaces, you can. It will be the most catastrphically difficult thing to read and edit, and it will be extremely easy to accidentally drop a tag and therefore make the whole thing invalid, but you could do it. I say that, but there is one space you have to keep. The opening tag of each element -- <thing <fieldval <bootstrap, etc -- all need a space between them and the first attribute -- <thing id= -- in order to designate that the element name is. Without the space it starts thinking the first element is part of the open tag, and then it stops being the same as the end tag - plus HL will not recognize it as a <thing> if it becomes a <thingid=> or whatever.

That said, whitespace is extremely useful in writing readable and modifiable code. The normal system (for HL at least) is to use two spaces as an indent. Each nested level should be indented, and everything inside that indent should be indented two more (note this is not the real code):

<document>
  <thing>
    <fieldval />
    <bootstrap>
      </bootstrap>
    </thing>
  </document>

As you can see, the first tag <document> starts at the far left. This shows that it is the thing that holds everything. It is easy to see where it ends too, because it is the last thing that is indented once. The <thing> tag starts the second layer, and everything contained by it is indented twice. You can see that <fieldval /> is its own thing because it includes a close tag within the primary element, so we don't have to look for a close tag. <bootstrap>, however, has an open and a close tag, so we have to look for the last thing that is indented 3 times within that 2 indent section. In this case it's easy because it's the next line, but in some cases there can be pages of code making it hard to track the close tag. Then there is the </thing>, which is indented twice to show that it is the end of the two indent code elements. At that point a new <thing> could be opened at 1 indent, and it is easy to see where each one starts and ends. You can indent however you want, but if you don't use two spaces and your code gets merged into the authoritative repository, it will look strange, and it will make me go "Ugh, why did they break the pattern?" If that doesn't bother you, then you can do what you want, and you are a bad person (just kidding (not really)).

Using a program like Notepad++ aids in legibility as well. You will have to specifiy that the language of the document is XML (Language > XML) but once you do that, it becomes colored and easier to see each part of the code. Further, if you select an open tag, it will highlight the close tag (and vise versa).