DivNull Software
Home
Download
Docs
Using
Making Lists
License
Credits
Omnihedron

Creating Lists

This documentation was released June 6, 2003 and describes the behavior found in Omnihedron version 1.0b3.

  1. Introduction
  2. Where Lists Live
  3. List Files
  4. Variations
    1. Ranges
    2. Subtables
    3. Hidden Lists
    4. Sequences
    5. Others
  5. Tag Reference
    1. rolllists
    2. rolllist
      1. id attribute
      2. visible attribute
      3. edge attribute
    3. name
    4. dice
    5. author
    6. url
    7. comment
    8. items
    9. item
      1. roll attribute
      2. end attribute
      3. repeat attribute
    10. sub
      1. modifier attribute
      2. repeat attribute
      3. delimiter attribute
      4. unique attribute
      5. sort attribute
      6. store attribute
    11. random
    12. variable
      1. name attribute
      2. modifier attribute
    13. score
      1. name attribute
      2. value attribute
      3. action attribute
    14. store
      1. name attribute
      2. value attribute
      3. action attribute
  6. Predefined Variables
  7. Formatting Output

1.0: Introduction

Anyone can build lists for Omnihedron. If you have ever used XML before, building a list should be easy. If you haven't, or don't even know what XML is, it will be somewhat harder, but is really quite simple. This document should tell you everything you need to know about how to define your own lists for use with Omnihedron.

2.0: Where Lists Live

Omnidron populates its list window on startup based on the files it finds in the list directory. The list directory can be anywhere, and is set in the preferences dialog. When first installed, Omnihedron uses a directory called "Lists" that is installed in the same directory as the application itself. When Omnihedron launches, it searches the list directory for files with the *.xml extension. (Sub-directories of the list directory are not searched, just the directory itself.) It attempts to load the XML file as a list. If the XML is defined properly as a list (as described below), the list described by the file is added to the list window.

3.0 List Files

Lists are defined in XML files. An XML file is just a simple text file that follows particular formatting rules. You can use any text editor (like Notepad) to create and edit XML files, although many specialized editors for XML files can be downloaded. An XML file always ends with a ".xml" extension.

The XML format specific to Omnihedron lists is best shown by example. Suppose we want to create a list that rolls a four-sided die to randomly select one of the cardinal directions (i.e. north, south, east or west). We create a file called, say, "Compass.xml" in the list directory. Each line in the file will be explained in more detail later on, but for now study the contents of our new file:

   <?xml version="1.0" encoding="iso-8859-1" ?>
   <!DOCTYPE rolllists SYSTEM "rolllist.dtd">

   <rolllists>
   <rolllist id="test:compass">
   <name>Random Direction</name>
   <dice>d4</dice>
   <author>Usario Clave</author>
   <comment>Rolls a random compass direction<comment>
   <items>
      <item roll="1">North</item>
      <item roll="2">East</item>
      <item roll="3">South</item>
      <item roll="4">West</item>
   </items>
   </rolllist>
   </rolllists>

The first two lines of the file will be the same for every list you create. The first line is a standard XML line that defines the file as an XML file, declares which version of XML is being used, and indicates the encoding system for the file. If you find this confusing, don't worry about it. You can just copy the first line exactly in all your lists.

The second line can also be copied for all your lists. This line indicates the exact kind of XML document this file is, in this case an Omnihedron list file. It identifies the main object type (a "rolllist") and the document template definition file (DTD) used, defining the format of the file. The DTD used in this case is "rolllist.dtd" which is installed in the default list directory. You should make sure you have a copy of it in your list directory. Again, if you find this confusing, don't worry about it. Just remember that all list files need this line.

The rest of the file is much more interesting. You can see that it consists of a set of matched tags, such as <name> and </name>. The tag with just the field name (e.g. "<name>") is called the open tag, and the tag with that same field name preceded by a slash (e.g. "</name>") is called the close tag. The text in-between a set of matched tags defines the data for the list. You can probably guess what a lot of the tags do just by reading their names and the data in-between them. Note that some tag pairs (e.g. <items>) contain sets of other tags.

There a few more tags than are shown in this example, and most of the tags can be much more complex than they appear above. Each tag is formally defined below, but for now, let's walk quickly through the example.

The <rolllists> tag opens the file. Inside the <rolllists> can be one or more <rolllist> tags (note the difference between <rolllists> and <rolllist>).

The <rolllist> tag opens the list. In fact, everything inside <rolllist> and </rolllist> is the list. Some tags can be given attributes. Attributes are specified within open tags, and are of the style name=value, where "name" is the name of the attribute, and "value" is the value of that attribute. The <rolllist> tag has an id attribute, and it is required. The format of the id attribute is very specific, but we will gloss over it here (it is described in more detail further down). The important thing to know is that this attribute gives the list a unique identifier.

The data in the <name> tag defines the string used to display the list in the list window.

The data in the <dice> tag defines the kind of dice that is rolled for this list. Dice strings have a specific format (described in detail below), but are similar to dice descriptions you have probably seen in books (e.g. 3d6, d4+1, etc.).

The <author> tag is optional, listing the name of the person who developed the list. Your name should go here.

The <comment> tag is optional, too. It is usually used to describe what the list does.

Things get a bit interesting with the <items> tag. It describes the start of a list of lines which describe each entry in the table. It is merely a list of matched <item> pairs, one after the other. The <items> tag means nothing by itself. It is just a way to collect a bunch of <item> tags.

The <item> tags list the entries in the table. Each one has a roll attribute. When a roll is made on the list, the roll is matched to this attribute and the data of that item is returned.

4.0: Variations

4.1: Ranges

You can go very far with just the example above to guide you, but Omnihedron is much more powerful than that.

You might have already wondered, for example about a table with some entries that match to a range of rolls. Let's update our direction table to illustrate how this works. Lets say that most of the time, you want our random direction table to return a cardinal direction (e.g. north, south, etc.) but occasionally (maybe about one-fifth as much) you want it to return one of the "in-between" directions (e.g. northeast, southwest, etc.). You could change the dice type to d8 and add extra items, but that would give an equal chance for every direction.

Instead, you want to roll a d20, and on a 1 to 4 choose north, but on a 5 choose northeast (and so on). Omnihedron does this with a attribute in the tag called end. It looks like this:

   <?xml version="1.0" encoding="iso-8859-1" ?>
   <!DOCTYPE rolllist SYSTEM "rolllist.dtd">

   <rolllists>
   <rolllist id="test:compass2">
   <name>Random Direction</name>
   <dice>d20</dice>
   <author>Usario Clave</author>
   <comment>Rolls a random compass direction<comment>
   <items>
      <item roll="1" end="4">North</item>
      <item roll="5">Northeast</item>
      <item roll="6" end="9">East</item>
      <item roll="10">Southeast</item>
      <item roll="11" end="14">South</item>
      <item roll="15">Southwest</item>
      <item roll="16" end="19">West</item>
      <item roll="20">Northwest</item>
   </items>
   </rolllist>
   </rolllists>

4.2: Subtables

One of the most powerful features of Omnihedron is the <sub> tag. The subtable tag allows you set an item such that if it is rolled on the list, the item will return the result of another roll, made on a different table. For example, say you have a table that rolls a color. Most of the time (say, 75%) you want it to return a primary color like "blue", but 25% of the time you want it to return one of a hundred really odd colors like "electric flamingo". Your list might look like this:

   <?xml version="1.0" encoding="iso-8859-1" ?>
   <!DOCTYPE rolllist SYSTEM "rolllist.dtd">

   <rolllists>
   <rolllist id="test:color">
   <name>Random Color</name>
   <dice>d4</dice>
   <author>Usario Clave</author>
   <comment>Rolls a random color<comment>
   <items>
      <item roll="1">red</item>
      <item roll="2">blue</item>
      <item roll="3">green</item>
      <item roll="4"><sub>test:wildcolor</sub></item>
   </items>
   </rolllist>

   <rolllists>
   <rolllist id="test:wildcolor">
   <name>Wild Color</name>
   <dice>d200</dice>
   <items>
      <item roll="1">mauve</item>
      <item roll="2">chartruese</item>
      <item roll="3">plaid</item>
       ... etc ...
      <item roll="200">electric flamingo</item>
   </items>
   </rolllist>

   </rolllists>
The value of the <sub> tag must be the unique id of another list. That is, it must match the id attribute in the <rolllist> tag of some other list. Altering the Wild Color list to include hundreds of wild colors is left as exercise to the reader.

4.3: Hidden Lists

The ability to define subtables has one drawback: you must define the subtable as a list, but you might not want that subtable to show up in Omnihedron's list window.

Fear not. The <rolllist> tag has an optional attribute named visible. If you set this equal to "false", the list will not be displayed in the list window.

4.4: Sequences

Another powerful feature of Omnihedron is the idea of a sequence. Up to now, we have given examples of lists that were tables. That is, you rolled some dice and returned an item in the list. But what if you want to initiate a sequence of connected rolls?

Omnihedron supports this as well. If you eliminate the <dice> tag in your list, the items in your list are treated as a sequence and executed one after another. Usually, this is done in combination with subtables, where each item rolls on a subtable.

The "Random Human" table that is installed with Omnihedron illustrates the power of the sequence concept. The file defining this table is called "Human.xml". Take a look at how it works.

4.5: Others

A number of other features are available as well, such as items that repeat a random number of times and a number of output formatting features. Rather than list examples for all of these, the best way to see these features is by reading the documentation for each tag. Then, tinker around!

5.0: Tag Reference

Tags and attributes are required unless otherwise indicated.

5.1: rolllists

The top-level tag in a file. The <rolllists> (note the "s" at the end) tag can contain any number of <rolllist> tags. This allows a single file to contain any number of lists. Only one of <rolllists> tag is allowed per file.

5.2: rolllist

The main tag to define a list.

5.2.1: id attribute

Defines the unique identifier for the list. The format of the id string must be creator:label, where creator is a four character code representing the list's creator, and label is a descriptive id of the list.

The idea of formatting ids like this is to solve the following problem: if each list needs a unique id, but anyone can create and post a list, how do you prevent "collisions" of ids without a massive effort to "register" ids?

The creator code helps mitigate this problem. The idea is that everyone who makes lists defines a creator code for himself or herself. Every list that person makes uses that creator code. The creator is responsible for making sure that each of his or her own lists has a unique label. When you combine the code and the label, it is much more a unique string will result.

Naturally, two different people might choose the same creator code, which could generate duplicate list ids. If this happens, it is assumed that the two people can work together to agree on unique codes.

Codes must be four characters (letters, numbers or any other printable ASCII character) and are considered case insensitive. That is, the code "abcd" is the same as "ABCD" or "aBcD". The codes "div0" and "test" are reserved for use by DivNull Software. Codes that might represent a trademarked game or gaming company (e.g. "adnd", "srun") are reserved for use by the owners of those trademarks. Do not choose codes meant to indicate a specific game. Instead, choose a code that represents you as an individual.

5.1.2: visible attribute

Optional. If missing or set to "true", the list is displayed in the list window. If set to "false", the list is hidden.

5.2.1: edge attribute

Optional. This attribute controls what happens if a number is made on the list that is either less than the minimum roll on the list or greater than the maximum roll on the list (in other words, rolls that go off the "edge" of the list in either direction). This is needed because of the modifier attribute of the <sub> tag. For example, say you have a list that rolls a d6, and it has items defined for rolls one through six. You might think, then, that it would never be possible to roll a undefined number; however, say a <sub> tag indicates to make a roll on this table with a modifier of -1. In this case, there is a good chance that the modified roll will be zero, which is not defined on the list. A rollllist's edge attribute tells Omnihedron what to do in this case.

If the edge attribute is missing or set to "bind", the roll is "snapped" to the nearest valid number. In the d6-1 case above, a roll of zero would turn into a roll of one. Most lists work like this, but this case will bias the list, making the items on the egde more likely to be rolled. Sometimes this is desireable and other times it is not.

If set to "wrap", rolls off the edge will "wrap around". For example, if a list has ten items, and a 13 is rolled, it would be equivalent to rolling a three.

If set to "reroll", any time an edge case is generated, it is discarded and a new roll is generated. Note that you, the list author, has a bit of responsibility when using this tag, because you can generate impossible situations. For example, if you call a d6 list with a modifier of +100, it is never possible to generate a valid roll. To avoid ininite loops, Omnihedron will only attempt to reroll 20 times. If a valid roll cannot be made, the roll is set to 0.

5.3: name

The common name of the list. This name shows up in the list window. Names do not have to be unique. In fact, lists with the same name can be displayed in the list window simultaneously.

5.4: dice

If present, defines the dice rolled for the list. As Omnihedron uses the RollPlay Dice Library to handle such strings, any legal RollPlay string may be used. Should the string listed in this tag not be a legal RollPlay dice string, the list file is ignored.

If the dice tag is missing, the items in the list are executed in sequence. Such lists are referred to as "sequence lists" or "sequences".

5.5: author

Optional. The name of the list's author. This name shows up when the user gets information about the list in the list window.

5.6: url

Optional. A URL referencing the author's web page. A link to this URL shows up when the user gets information about the list in the list window.

5.7: comment

Optional. Intended as a description of the lists purpose. This comment shows up when the user gets information about the list in the list window.

5.8: items

Contains the item list. Must contain at least one <item> tag.

5.9: item

Defines a single item in the list. This tag can contain <sub>, <random>, <variable> and <score> tags, as well as text.

5.9.1: roll attribute

Optional. Defines the lower bound of the roll that outputs the item. This item must be an integer. If it is not, the result is undefined.

If the roll attribute is not specified for a list with a <dice> tag, the system will attempt to calculate the correct roll, but this is not guaranteed. For example, if your list rolls a d20, and your item list has 20 items with no roll attributes, the system will correctly assign one number to each item. More complex situations are not recommended, as the results are not defined.

The convention is for items to be listed in the order of their roll attribute, but this is not required.

The roll attribute is ignored for sequence lists.

5.9.2: end attribute

Optional. The upper range of the roll the outputs the item. This item must be an integer. If not, or if an end attribute is specified for an item without a roll tag, the result is undefined.

5.9.3: repeat attribute

Optional. Defines the number of times the item should be executed. The value must be a valid dice string. (Note, constant numbers are considered valid dice strings.) If the item is executed (either by the main table roll or the as a step in a sequence), the dice string indicated by this attribute is rolled, and the item executed a number of times equal to the result.

5.10: sub

Optional. Allowable only inside an <item> tag. Defines the subtable to invoke if the item containing it is rolled. The contents of this tag must be the id attribute of a list's <rollitem> tag. This defines the specific table to roll. The result of the subtable roll will be output into the position in the item's text occupied by the tag.

Note, it is possible for a list to invoke itself as a subtable. This can, however, result in infinite recursion situations and should be used with caution. Combined with the repeat attribute, this feature can be used to implement the "roll twice more on this table" item featured in many games. A simple table that would do this looks like so (note the use of the edge attribute as well which, combined with the modifier, prevents the reroll twice from rolling itself again):

   <rolllist id="test:rolltwice" edge="reroll">
   <name>A table with reroll</name>
   <dice>d4</dice>
   <items>
      <item>Item 1</item>
      <item>Item 2</item>
      <item>Item 3</item>
      <item><sub repeat="2" modifier="-1" delimiter="&newline;">test:rolltwice</sub></item>
   </items>
   </rolllist>

5.10.1: modifier attribute

Optional. Defines a modifier to pass to a subtable. This can be an integer, dice string or variable name. If combined with a repeat attribute, the modifier is determined once, then used for all repeats. For example, if the modifier is "d6", the d6 is rolled once, and passed to all repeats.

5.9.4: repeat attribute

Optional. Defines the number of times the item should be executed. The value must be a valid dice string. (Note, constant numbers are considered valid dice strings.) If the item is executed (either by the main table roll or the as a step in a sequence), the dice string indicated by this attribute is rolled, and the item executed a number of times equal to the result.

Note that this attribute does much the same thing as the repeat attribute of the item tag. The two are not generally used at the same time, as this would cause repeats of repeats. Using the <sub> tag's repeat gives a bit more control, especially in cases where a single item contains multiple subs, but you only want one to repeat.

5.10.3: delimiter attribute

Optional. If a sub is repeated using the <sub> tag's repeat attribute, the text supplied in this tag will separate the results of each repeat. If missing, no delimiter is used.

To use a line break as a delimiter, use the "&newline;" keyword.

5.10.4: unique attribute

Optional. If this attribute is set to "true" and the <sub> tag has a repeat attribute, each repeat will return a unique result. Note that it is possible to set up impossible situations using this attribute. For example, a table with 10 items will never be able to return 20 unique results. To guard against this, Omnihedron will test for a unique roll only 20 times for each repeat. If a unique item is not found, the result will repeat normally.

If this attribute is missing, set to "false", used in a <sub> tag without a repeat attribute, or used on a sequence table, this attribute is ignored.

5.10.5: sort attribute

Optional. If this attribute is set to "true" and the <sub> tag has a repeat attribute, the repeated results will be sorted in the output.

If this attribute is missing, set to "false", used in a <sub> tag without a repeat attribute, or used on a sequence table, this attribute is ignored.

5.10.6: store attribute

Optional. If this attribute is supplied, its value will define a variable into which the output from this list will be stored. If supplied, no output will be written to screen, just into the variable.

5.11: random

Optional. A random number to output for the item. The value of the parameter must be a valid dice string. When the item is executed, the dice string is rolled and the result output in the place in the item stream occupied by the random tag.

This attribute is useful to output a random quantity of things without having to roll on a subtable.

5.12: variable

Optional. When a <variable> tag appears in an item, Omnihedron will replace the value of that variable when outputting the item result. Variables are generally set in earlier items, using the score tag.

Variables can only have integer values. Variables only exist within the life of a roll on a list chosen from the list window. When the main roll finishes, the variables are cleared. Variables will persist, however, over any subtables the main roll may invoke. Usually, one subtable will set a variable that another subtable will use as a modifier.

5.12.1: name attribute

The name of the variable to use. This can be either the name of a variable previously set by a score tag or a predefined variables. If the name used has not been defined, a value of zero is returned.

Names are case insensitive, meaning that "VarTest", "vartest" and "VaRtEsT" are considered to name the same varible.

5.12.1: modifier attribute

Optional. When present, the output of the variable is altered. This does not alter the variable itself, just the output. This attribute can be set to a number, a valid dice string or the name of another variable.

The modifier is evaluated each time the variable is used. For example, if the modifier is set to "d6", and the variable is used in an item that is repeated, the d6 will be rolled on each repeat.

5.13: score

A <score> tag is used to give a name to a numeric value that can be recalled later by a <variable> tag. Unlike a <store> tag, a <score> can only remember integer values. It also has more flexible options for adjusting numeric variables.

Zero or more <score> tags can be embedded in any item tag. Each <score> tag defines an alteration that is made to a variable when the item that contains it is rolled. All <score> tags are evaluated before any sublists in an item are rolled. The body of a <score> tag is empty.

5.13.1: name attribute

This defines the name of the vairble to alter. Variable names are case-insesitive. If a variable with the given name does not already exist, it is created. Otherwise, the existing variable is altered as dictated by the action attribute.

5.13.2: value attribute

This attribute defines the numeric value used to alter the variable. It can be either a number, a valid dice string, or variable name. If set to a variable name, the variable is looked up immediately. If this variable is a number, the value is set to that number. If the variable contains a dice string, or the value attribute itself is set to a dice string, the dice string is rolled immediately and the value is set to the resulting roll.

5.13.3: action attribute

Optional. This attribute defines how the variable is altered. If not provided or set to "set", the setting given in the value attribute replaces the value of the named variable. If, instead, this attribute is set to "add", the value attribute is added to the existing value of the variable. Other simple math can also be done, such as "subtract", "multiply" and "divide". If a "divide" action is done when the value attribute evaluates to zero, the variable is set to zero.

If a <score> tag uses the name of a variable that has previously been set by a <store> tag, the previous value of the variable is overwritten and the variable becomes a numeric variable.

5.14: store

A <store> tag is used to give a name to a text value that can be recalled later by a <variable> tag. Unlike a <score> tag, a <store> remembers only text based values. Variables set by a <store> tag may, however, be evaluated when used by other tags, such as a <score> tag's value attribute.

Zero or more <store> tags can be embedded in any item tag. Each <store> tag defines an alteration that is made to a variable when the item that contains it is rolled. All <store> tags are evaluated before any sublists in an item are rolled. The body of a <store> tag is empty.

5.14.1: name attribute

This defines the name of the vairble to alter. Variable names are case-insesitive. If a variable with the given name does not already exist, it is created. Otherwise, the existing variable is altered as dictated by the action attribute.

5.14.2: value attribute

This attribute defines the text value used to alter the variable. It can be either a text string, a variable name or a valid dice string. Using dice strings with a <store> tag can be useful to set variables that other tags (such as the <score> tag's value attribute) can use. If the value is a variable name, the <store> tag will set the variable to be the contents of the variable at the time the item containing the <store> is rolled.

5.14.3: action attribute

Optional. This attribute defines how the variable is altered. If not provided or set to "set", the setting given in the value attribute replaces the value of the named variable. If, instead, this attribute is set to "add", the value attribute is appended to the existing value of the variable.

If a <store> tag uses the name of a variable that has previously been set by a <score> tag, the previous value of the variable is overwritten and the variable becomes a text variable.

6.0: Predefined Variables

Omnihedron uses some variables internally. These are given predefined names that can be used by list authors. List authors should avoid using predefined variables in score tags, however, using the predefined variables "read-only".

6.1: count

When an <item> tag uses its repeat attribute, the repeats are counted in a variable called "count". During the processing of a repeated item, count starts at one and is incremented by one for each repeat.

Like all variables, you can use a modifier with count in the <variable> tag to display the counter as starting from something other than one. For example, say you have a table that generates a character's age by rolling 2d6 and adding the result to 16. Further, say that you want to generate a random event for each year over 16. You can do this with the following table:

   <rolllist id="test:agegen">
   <name>Random Events</name>
   <items>
      <item><score name="VarAge" value="2d6"/></item>
      <item>Age: <variable name="VarAge" modifier="16"/></item>
      <item>Events</item>
      <item>Age 16: <sub name="test:event"/></item>
      <item repeat="VarAge">Age <variable name="count" modifier="16"/>: <sub name="test:event"/></item>
   </items>
   </rolllist>

Assume that the "test:event" subtable has been defined, and that the 2d6 in the first <score> tag rolls a 4. The output of the above sequence list would be:

Age: 20
Events
Age 16: <results of roll on "test:event" table>
Age 17: <results of roll on "test:event" table>
Age 18: <results of roll on "test:event" table>
Age 19: <results of roll on "test:event" table>
Age 20: <results of roll on "test:event" table>

7.0: Formatting Output

Lists are output to an HTML view, which means that you can make your list output look reasonably good. Unfortunately, embedding HTML data inside of XML documents is a bit tricky, as the < and > symbols are reserved in XML.

The DTD for lists defines a number of entities that can be used to embed HTML tags in the output of the list. You can use an entity in the author, comment or item tag. Entities must begin with a & character and end with a semi-colon (e.g. &copyright;).

Valid entities are:

EntityMeaning
ltOutputs the less than symbol (<).
gtOutputs the greater than symbol (>).
ampOutputs the ampersand symbol (&).
copyrightOutputs the copyright symbol (©).
startboldOutputs a tag to start a run of bold text (<b>).
endboldOutputs a tag to end a run of bold text (</b>).
startitalicOutputs a tag to start a run of italicized text (<i>).
enditalicOutputs a tag to end a run of italicized text (</i>).
newlineOutputs a tag to add a line break (<br>).