Basilisk Data File Format

Basilisk requires that all attributes used in any definition of any thing be predeclared via the "attribute" statement. Any attributes not predeclared will generate errors during the parse of your data file.

Basilisk also supports units (like pounds, dollars, inches, meters, years, etc.), and allows you to convert between units easily and quickly. You do not need to use units to use Basilisk, but they come in very handy.

For more information, click on a chapter heading:

1. Identifiers
2. Units
3. Attributes
4. Things
   • Templated Things
   • Anonymous Things
5. Categories
   • Anonymous Categories
6. Including Files
7. Conclusion

1. Identifiers

In the case of Basilisk, all identifiers must be unique. You cannot have two separate things both named "Sword", for instance. You must make the identifiers unique by making them more descriptive: "shortSword" versus "longSword", for example.

Note that those two identifiers both lacked a space to separate the words. This is because identifiers cannot contain spaces. They also cannot contain dashes, slashes, asterisks, ampersands, or any other punctuation. In fact, the only valid characters you can put in an identifier are letters, numbers, and the underscore ('_'), and numbers can never be the first characters in an identifier.

Examples of valid identifiers:

• longSword
• Long_Sword
• bilbo1
• thing1234
• thing_1234

• long sword (has a space in it)
• 1longSword (starts with a number)
• long-sword (has a dash in it)
• bilbo&frodo (has an ampersand in it)

2. Units

Likewise, if you were playing a game of D&D, and the DM says to you, "you just found 64!" 64 what? It would make a big difference if he said "copper pieces" versus "platinum pieces."

Basilisk allows you to define units that you will use in your data file. For example:

unit cp;
unit sp = 10 cp;
unit gp = 10 sp;
unit pp = 10 gp;


The benefit of explicitly defining units in relation to other units (as in the example above), is that you can easily request the conversion of, say, 1552 cp into pp (1.552 pp). Basilisk will perform the work of converting it for you.

You could also do the following:

unit second;
unit round = 6 second;
unit minute = 10 round;
unit hour = 60 minute;
unit day = 24 hour;


unit second;
unit seconds = 1 second;
unit round = 6 seconds;
unit rounds = 1 round;
unit minute = 10 rounds;
unit minutes = 1 minute;
unit hour = 60 minutes;
unit hours = 1 hour;
unit day = 24 hours;
unit days = 1 day;


3. Attributes

An "attribute" statement lets you associate a given identifier with a type. The identifier must be unique in the file, and only be used to reference an attribute of a thing.

Here's some examples of attribute definitions:

attribute name string
attribute weight number
attribute isSmart boolean
attribute family thing
attribute children category
attribute nameRoutine rule


• string - this is a sequence of characters between double quotes, "like this." All characters between the quotes are taken literally, so strings are useful for things like names, descriptions, and narrative text.
• number - the number type is very flexible in Basilisk. It may be an integer, like 1, or 15, or -144, or it may be a floating point number, like 3.141592, or 21.5. However, numbers may also represent dice values, like 2d8, or 1d4+3, or 3d8*1000. Numbers may also have units associated with them.
• boolean - Boolean values are strictly limited to two values, "true" or "false." You may also use "yes" or "no" and "off" or "on". Boolean values are like light switches -- the light is either on or off. Thus, they are good for "yes" or "no" type answers, like whether or not one's sibling is smart.
• thing - Things are complex entities that are composed of various attributes. You are a thing, as is the chair you are sitting on, or the emotion you are feeling for your boyfriend or girlfriend.
• category - Categories are logical groupings or sets of things or other categories. The children of a family is a category, as is the set of all slashing weapons.
• rule -- Rules describe processes, like "how do I select a name for my baby" or "how do I roll for ability scores."

4. Things

The first way is the most straightforward:

longSword
	.name "longsword"
	.cost 15 gp
	.weight 4 lb
	.size medium
	.damage 1d8
	.criticalRange 19
	.criticalMultiplier 2
end

The example shows how you could define a longsword, with all of it's attributes. You could then do the same thing for a flail, nunchaku, a quarterstaff, and so forth.

If you did so, however, you would quickly realize that you were typing the same attributes over and over -- name, cost, weight, size, damage, etc. being fairly common to most weapons. If you find yourself entering attribute names over and over, you might want to look at the "template" statement.

Templates allow you to abbreviate much of your data entry. Here's an example:

template { name cost damage criticalRange 
           criticalMultiplier weight size }
	weaponClub { "club" $ 1d6 20 2 3 lb medium }
	weaponDagger { "dagger" 2 gp 1d4 19 2 2 lb tiny }
	weaponDart { "dart" 5 sp 1d4 20 2 1/2 lb small }
end

The last method for entering things requires another example to demonstrate:

flailSpecialAttack
	.name "bonus"
	.description "+2 to disarm attempts"
end

weaponFlail
	.name "flail"
	.cost 8 gp
	.damage 1d8
	.criticalRange 20
	.criticalMultiplier 2
	.weight 5 lb
	.size medium
	.bonus flailSpecialAttack
end

Anonymous things are things that are actually embedded within the definition of another thing or category. They are not named (hence the term "anonymous"), and take up much less space in the data file. They are also faster to parse. Here's the same data as the example above, but with the "flailSpecialAttack" thing made anonymous:

weaponFlail
	.name "flail"
	.cost 8 gp
	.damage 1d8
	.criticalRange 20
	.criticalMultiplier 2
	.weight 5 lb
	.size medium
	.bonus { .name "bonus" 
					 .description "+2 to disarm attempts" }
end

One final note about things: you may define and redefine the same thing over and over. If a thing is encountered that has already been defined, the attributes in the second definition are added to the thing's previous attribute list. It is very important to note that a thing may have multiple of the same attribute, so a redefinition will never overwrite an existing attribute! Be very careful with this, as the parser will not even issue a warning when you are redefining a thing.

5. Categories

A category, in it's simplest form, has the following format:

attribute name string
attribute birth string

template { name birth }
  Jamis { "Jamis Gordon Buck"  "25 Jul 1974" }
  Eric { "Eric Victor Bristow" "4 Feb 1976" }
  Nicole { "Nicole Suzanne Buck" "30 Apr 1976" }
  Emily { "Emily Rene Bristow" "28 Aug 1978" }
  Rebecca { "Rebecca Lynn Bristow" "3 Dec 1979" }
  Andrew { "Andrew Michael Bristow" "8 May 1986" }
end

category familyMembers
  Jamis
  Eric
  Nicole
  Emily
  Rebecca
  Andrew
end

A shorter way to do this, if you are using templates, is as follows:

template in ( familyMembers ) { name birth }
  Jamis { "Jamis Gordon Buck"  "25 Jul 1974" }
  Eric { "Eric Victor Bristow" "4 Feb 1976" }
  Nicole { "Nicole Suzanne Buck" "30 Apr 1976" }
  Emily { "Emily Rene Bristow" "28 Aug 1978" }
  Rebecca { "Rebecca Lynn Bristow" "3 Dec 1979" }
  Andrew { "Andrew Michael Bristow" "8 May 1986" }
end

template ( familyMembers ) { name birth }
  Jamis in ( buckFamily ) { "..." "..." }
  Eric in ( bristowFamily ) { "..." "..." }
  Nicole in ( buckFamily ) { "..." "..." }
  Emily in ( bristowFamily ) { "..." "..." }
  Rebecca in ( bristowFamily ) { "..." "..." }
  Andrew in ( bristowFamily ) { "..." "..." }
end

Categories may also be specified when defining things with the basic format, as demonstrated here:

longSword in ( weapons slashingWeapons )
.name "longsword"
.cost 15 gp
.weight 4 lb
.size medium
.damage 1d8
.criticalRange 19
.criticalMultiplier 2
end

Note that categories may belong to other categories, just as things (and even rules) do. The syntax is exactly the same as for both things and templates, using the "in" keyword. Here's an example:

category weapons in ( equipableItems )
  ...
end

category groupGemLookup
[50] { .cost 4d4 gp }
[30] { .cost 2d4*10 gp }
[25] { .cost 4d4*10 gp }
[15] { .cost 2d4*100 gp }
[ 9] { .cost 4d4*100 gp }
[ 1] { .cost 2d4*1000 gp }
end

Note that if weights are not specified, they default to 1. If a weight is specified, however, it must be an integer value (it cannot have a fractional value, or numbers after the decimal point).

Lastly, just as things may be declared anonymously, so may categories. An anonymous category declaration may be used anywhere a category identifier would be used, and is simply the category members (including weights, if you want them) enclosed in parentheses. For example:

attribute name string
attribute favoriteMovies category

template in ( allMovies ) { name }
Bambi { "Bambi" }
RobinHood { "Robin Hood" }
TrumanShow { "The Truman Show" }
MrHollandsOpus { "Mr. Holland's Opus" }
Contact { "Contact" }
BugsLife { "A Bug's Life" }
ToyStory2 { "Toy Story 2" }
end

Jamis
  .name "Jamis Buck"
  .favoriteMovies ( ToyStory2 
                    BugsLife 
                    TrumanShow 
                    { .name "Secret of Roan Inish" } )
end

Tarasine
  .name "Tarasine Buck"
  .favoriteMovies ( [3] MrHollandsOpus 
                    Contact 
                    TrumanShow )
end

I got tricky in my movie list. Perhaps you noticed the anonymous thing, listed in the anonymous category! You can nest them as deep as you need to.

Lastly, notice in my wife's movie list that the movie "Mr. Holland's Opus" is weighted so that it will be chosen 3 times out of 5. The other two movies are left to the default weighting of 1, each being chosen 1 time out of 5. You can use weightings wherever you feel you will need them.

A special thing, "null," may also be used in a category to indicate that the particular category member is non-existant. Any given category may only contain one null member.

One final note about categories: you may define and redefine the same category over and over. If a category is encountered that has already been defined, the members of the second definition are added to the category's previous member list. It is important to note that a category may only have one of any given thing or category, and multiples are silently ignored. Be very careful with this, as the parser will not even issue a warning when you are redefining a category.

6. Including Files

The answer, my friend, lies in Basilisk's ability to include the contents of one file from within another. Here's an example:

#include "coredata.bsk"

Any given file may include any number of files, each of which may include files, etc. The Baslisk parser includes a safeguard which will prevent a file from being included more than once, so you don't have to worry about redefining your categories or things, either.

7. Conclusion

If you feel you're ready, proceed to the scripting section!