TableSmith Help

TableSmith Basic File Format

Table files are the heart of TableSmith. These are the tables that contain the rules and data used to generate names, treasure hoards, village shops, encounters, and anything else you can think of. The information below covers the basics of TableSmith tables, and is enough to help you figure out how to edit existing tables or create new ones of your own. When you're comfortable with the basic functionality described below, you can move on to the Advanced Features and add even more power and flexibility to your tables. A simple example file is shown below:

The example above illustrates the following basic TableSmith concepts: Comments, Groups, Group Calls, and Dice-Rolling.

Comments

The first line, with the '#' character, is a comment. Comments may be placed anywhere within your table, generally to explain why something was done in a table in a particular way, to describe the table's purpose, to show who authored the table or where it's original source was, etc. Comments are intended for use by a person looking at a table; if a line has a '#' as its first character, the entire line is ignored by TableSmith.

Groups

The parts of the table above starting with "Start", "Creature", and "Color" are groups. A group consists of a name, followed by Entries. A group may have any name you wish (though it cannot contain the characters "+", "-", or "=" as these have special meaning when used in a group call), and is preceded in a table by a colon (":"). Groups can be considered "subtables" within the larger table files. Note: There is one "special" group, known as "Start". Whenever a table is selected from TableSmith, the first group that is rolled on is "Start" (it has to start somewhere).

Group Entries
The entries under each group follow a specific format, which is:

number,text

Note that the comma is very important. When an entry is read into TableSmith, everything up to the first comma it reads is used for probability, and everything after is a line of text. Note that if you put a space after the comma, that space is part of your line of text. Also note that when it comes to commas, TableSmith only cares about the first one it finds. You may put commas in anywhere in your text line that you care to.

The number before the comma in an entry line is a probability. This is the chance that if that line's group is selected, that particular line will be used. For instance, in the "Color" group in the example, the entry "Red" has a number of 1. Since the range of numbers for that group is 1-4, if the Color group is selected for something, a random number from 1 to 4 will be generated, and if it comes up a '1', "Red" will be the text used from the Color group. This number may be either a single value, or a range, in the format of "X-Y", where 'X' is the lower limit of the range and 'Y' the upper. The range for a group is determined by the lower limit (or value if a single number) of the first entry beneath it and the upper limit of its last entry. In the example above, when rolling on the "Creature" group, the range is 1-9, and for the "Color" group, it is 1-4. Note: This number cannot be negative, and if a '0' is used, that entry will not be used (though '0' won't generate an error).

Alternate Group Format
Groups may also follow an additional format. It is similar to the above, but looks like this:

This type of group works in a similar manner, but rather than the numbers describing ranges, they describe relative probabilities. In the example above, for instance, the 3 represents '1-3', the 2 is '4-5', the dagger has a range of '6-10', and the pole arm's 2 is the equivalent of '11-12'. Note that groups following this format should start with a semi-colon (";"), rather than a colon (":").

Groups that Don't Repeat
If you include an exclamation point ("!") after a group designator (":" or ";"), this will signal TableSmith that the group should not allow duplicate results. In other words, if an item is selected in the group, and the group is called later, previously selected items will not be selected again. For example, take a group that looks like this:

A roll on the group indicates that, say, "Dagger" is selected and returned to the caller. Later in the table, this "Weapons" group is called again. On this roll, the result will be anything but "Dagger", since that has already been used. Say the result of the second roll is "Axe". Now, if this table is called a third time, the only results to be returned will either be "Sword" or "Pole arm".

Note: Take care when using this feature. TableSmith will give you an error (appearing in your table output) if a group is called that is already "maxed-out" (i.e.; it is a non-duplicating group that has had all its members used, and another call is made).

Group Calls

Whenever an entry line contains something in double square brackets ('[' and ']'), rather than using that text as part of the selected line, the program will jump to the group with the name that is between the brackets, and insert the generated result from that group into the current line. For instance, in the example, the "Creature" group has an entry that says "9,[Color] Spirit". This means that if that entry is selected, TableSmith will jump to the "Color" group, make a selection, and replace "[Color]" with that selection. Thus, the result would be "Red Spirit", "White Spirit", or "Blue Spirit", depending on the value generated for the "Color" group.

Calling Groups in Other Tables
Besides calling groups in the same table, you may also call group in other tables. If the text between the two brackets contains a period, TableSmith treats the text before the period as a table, and the text after it as a group. So while [Treasure] means the program would look in the current table for a group called "Treasure", [Treasure.Coins] means the program would load the "Treasure" table and generate a result from that table's "Coins" group.

If you wish to generate a result from the entire table, reference the "Start" group (for instance, to generate a result from a table called "Weapons" as if you were selecting it directly through the TableSmith interface, the syntax would be [Weapons.Start]).

Note: Referenced tables must exist in the Tables subdirectory, and must be spelled the same as the table files (without the ".tab" extension).

Also note that with both types of Group Calls, it is possible to create endless loops that will freeze up the program (example: Having a table called "Freeze", with one entry in the "Start" group, being "1,[Start]"). Due to the complexities involved, TableSmith does not check for this. You will have to be careful about this sort of thing.

Roll Modifiers
Normally, when a group is called, TableSmith generates a random number within the range of the groups limits, and then looks up the corresponding entry for that number. For example: In the sample table at the top of this page, when TableSmith rolls on the "Creature" table, it generates a random number from 1 to 9, and selects the corresponding entry. However, you may modify this roll if you wish. When a group call is made, a "roll modifier" may be applied: If a group call contains a "+", "-", or "=", the value of whatever follows is either added, subtracted, or "forced" from the roll made on the referenced group. For example:

[Potions+3] - This would add 3 to whatever roll was made on the group 'Potions'
[Castles-5] - This would subtract 5 from whatever roll was made on the group 'Castles'.
[Undead=4] - Rather than roll on the group 'Undead', the result generated will be for whatever line the value 4 is located.

The modifier is never required, and is simply used if you wish to modify a group roll.

Die Rolls

TableSmith allows for random die rolling in the middle of tables (useful for any number of things, from the value of treasure to character generation to monster hits). To generate a die roll, a special syntax is required:

{Dice~XdY?Z}

X - Any non-decimal number (1, 5, 100, etc.). May be omitted, in which case it is considered to be '1'.
d - The letter 'd' must be in the declaration (think of it as the 'd' in "2d8" or the like)
Y - The number of "sides" of the die you are rolling.
? - This, and 'Z' can be left out. The ? symbol means you can place a '+', '-', '*', or '/' in the formula (so you can generate results such as "3d6+2" or "4d8-5")
Z - This is the amount you wish to add, subtract, multiply by, or divide by.

When TableSmith sees curly brackets ('{' and '}') containing the text "Dice~", rather than printing these characters directly, it "rolls dice", and substitutes the result in place of the brackets and their contents. So, for instance, if you have "{Dice~3d6}" in a group entry, the program will "roll" 3d6, take the result, and put it in place of the bracketted text.

How does all this work?

When TableSmith generates results for a table, it first goes to that table's "Start" group. Taking the total range of numbers based on the entries, it generates a random number, and matches it up with the appropriate entry. It then builds a string of text, calling various groups, tables, and die rolls as needed. This text is then displayed as the results of the table generation.

Here's an example using the table shown at the top of this page:

The program looks at the "Start" group and determines a range of numbers. Since there is one entry with a value of '1', this range is 1-1 (pretty simple). A random number is generated in the range of 1 to 1, and strangely enough, '1' is the result.
Looking at the selected entry in "Start", the program sees that a call is made to the group "Creature". A range is again determined, this time being 1 to 9. A random number is generated in this range, and the result, say, is '9'.
If the result was '2', "Orc" would have been the result of the call to "Creature", and that would have been passed back to the Start entry. However, with '9', there is a call to another group, "Color".
TableSmith goes to the "Color" group, determines a range of 1 to 4, and generates a random value. '4' is the result, so "Blue" is passed back up.
"Blue" has been generated as a result for the call to the "Color" group, so this is substituted for "[Color]", meaning the call to the "Creature" group has come up with "Blue Spirit".
"Blue Spirit" is passed up to the "Start" entry, which uses it to replace "[Creature]".
So far we have "You see a Blue Spirit". To this we continue to add text, resulting in "You see a Blue Spirit with a " - but now we have another link, this time to another table called "Treasure" and one of its groups, "Coins".
In summary, TableSmith loads the "Treasure" table and generates a result from its "Coins" group. Let's say we got back "pouch of 20 gold"; we continue, so until we hit that first curly bracket, we have "You see a Blue Spirit with a pouch of 20 gold, worth ".
TableSmith looks at the formula "1d6*1000", and generates a number from 1 to 6, multiplying it by 1000. Let's say the result is "4000".
The final outcome of this generation is: "You see a Blue Spirit with a pouch of 20 gold, worth 4000 experience."

This is just an example of what TableSmith does. The best way to learn the potential of this program is to look at the sample tables provided.

A few other notes:

Tables are all in standard ASCII text format.
Table names, like group names, should not contain the following characters: "+", "-", and "=".
TableSmith is case-sensitive when it comes to group names/calls as well as variables and functions (which are covered in the "Advanced" section of Help). Thus, the calls [Creature] and [creature] are not the same.
Any new tables must be added/copied/whatever into the 'Tables' subdirectory, which is found in the directory that TableSmith was installed into.
TableSmith uses an HTML control for display, so you may place HTML tags into your entry lines for special formatting. For an example of how HTML is used in a table, look at the "Book Description" table.