CharSys d20 Tags Reference

CharSys d20 allows you to use tags to control various aspects of the classes, races, and deities you create. You can use tags for something as simple as printing information on the character to complex IF structures. This tag language is called CharSys Markup Language or CSML.

Tag Syntax

CSML is partnered after XML. That is, the tag is surrounded by angle brackets (<>). The word immediately following the left bracket is the name of the tag. The remainder of the tag are parameter names and value pairs separated by an equals sign. For example, a PRINT tag looks like this: <PRINT STYLE=ITALIC>. Tags are case insensitive, so you don’t have to type them in all uppercase.

The only exception to the above syntax are the control tags (IF, ELSE, ELSEIF, and ENDIF). It was decided that the syntax of these tags should resemble traditional IF statements from programming languages.

Note: Tag names and parameter names are case insensitive. However, variable names are not. For example, CHOOSE and choose are considered the same whereas tag.choice and tag.CHOICE would be considered different.

The VAR parameter

There are times when you may wish the result of a tag to be placed in a variable. This way, you can check the value of the variable later on. A good use of this is the CHOOSE tag. The CHOOSE tag lets the player make a choice from a list. Sometimes, you may wish for the player to be able to make another choice based on the first choice. In this case, you would want to assign the value of the first choice to a variable. This is where you would use the VAR parameter. You can call your variable anything you wish with one exception: it must begin with “tag.” (minus the quotes). For example, let’s say you have a CHOOSE tag that lets the player choose from a list of skills. You might do something like this (the CHOOSE tag is explained in detail later):

Hunting

Fishing

Speak Language

</CHOOSE>

Once the player has made a choice, their choice is now in the variable “tag.skills”. Now, you can check the value of the variable to decide what to do next. Since you would probably want the player to choose a language if he/she chooses Speak Language, you would do something like this:

Giant

Goblin

Orc

</CHOOSE>

<ELSE>

<ENDIF>

If you don’t understand all of the above, don’t worry. The purpose of this section is just to show you why you may want to use a variable.

Getting and Setting Character Data

There are times where you will need to either set some data to or get some data from the character. For example, you may need to know what race the character is or the character’s Charisma bonus, or even the alignment of the character’s deity. You may want to add to or change certain data. The syntax for referring to a piece of character data is “hero.fieldname”. For example, hero.race refers to the character’s race. Some fields can only be read from and some may be written to. Below is a list of the field names, their description, and whether you can write to them or just read from them. Whenever a field is has two square brackets after it that indicates you must place something in the brackets. For example, if you wish to test how many skill ranks the character had in Appraise, you would use hero.skillRanks[Appraise]

Field	Description	Read/Write
STR	Strength	Read/Write
DEX	Dexterity	Read/Write
CON	Constitution	Read/Write
INT	Intelligence	Read/Write
WIS	Wisdom	Read/Write
CHA	Charisma	Read/Write
STRBonus	Strength Bonus	Read
DEXBonus	Dexterity Bonus	Read
CONBonus	Constitution Bonus	Read
INTBonus	Intelligence Bonus	Read
WISBonus	Wisdom Bonus	Read
CHABonus	Charisma Bonus	Read
skillRanks[]	Skill Rank	Read/Write
attackBonus	Base Attack Bonus	Read
alignment	Alignment	Read/Write
Armor[]	Armor Carried	Read/Write
armorWorn	Armor Worn	Read/Write
class	Class	Read/Write
deity	Chosen Deity	Read/Write
domain	Chosen Domain(s)	Read/Write
experience	Experience Points	Read/Write
Feats[]	Feats	Read/Write
level	Experience Level	Read/Write
Misc[]	Miscellaneous Information	Read/Write
miscEquipment[]	Miscellaneous Equipment	Read/Write
name	Character Name	Read/Write
playerName	Player's Name	Read
prohibitedSchools	Prohibited Schools for Wizards	Read/Write
race	Race	Read
raceAbilities	Racial Abilities	Read/Write
school	Magic School for Wizards	Read/Write
Spells[]	Magic Spells	Read/Write
weaponProficiency	Weapon Proficiencies	Write
Weapons[]	Weapons Carried	Read/Write

The Tags

This section details each tag. While using the CharSys Database Manager or the Prestige Class Editor, you will notice you can place tags in different sections. The different sections control when the tags are processed. While you a free to place any tag in any section, some tags don’t make sense in certain sections. For example, the PRINT tag only makes sense in the Character Sheet section. The IF tags can safely be placed anywhere. The sections are:

Create – Place tags here that you wished to have processed when a character is created. Good examples might be the GIVE or CHOOSE tags.
Level Change – Place tags here that you wish to have processed when a character increases in level. Once again, the GIVE and CHOOSE tags would be good examples.
Character Sheet – Placed tags here that you wish to have processed when the character sheet is displayed. Don’t place GIVE or CHOOSE tags in this section since they would be processed each time the character sheet is displayed. You will probably only want to use the LEVEL and PRINT tags.
Buy Equipment, Feats, Skills, Spells – Tags in any of these sections will be processed when the player uses that particular editor. For example, any tags in the Feats section will be processed when the player chooses Edit Feats for his/her character.

The tags are presented in alphabetical order.

Add

Description: Adds something to a list of choices.

Syntax: <ADD cost=#>items</ADD>

The ADD tag will add a items to a list of choices depending on what section the tag is in. The COST parameter is how much the selection will cost if the player chooses it. You can place multiple items in between the ADD tags following each item with a carriage return.

Examples:

Let’s say you wanted to add certain skills to the skills list so the player could choose from them. You could put this in the Skills section:

Knowledge (arcana)

Knowledge (religion)

</add>

The above example means the player could choose either skill (regardless of whether they could normally be chosen or not) and it would cost no skill points to choose them.

Bold

Description: Prints text in bold.

Syntax: <b>text</b>

This tag should only be used within the PRINT tag and only in the Character Sheet section.

Choose

Description: Presents the player with a list of items from which to make a choice.

Syntax: <CHOOSE FIELD=”” NAME=”” VAR=”” CAPTION=”” TIMES=# CANCEL=TRUE/FALSE> items to be chosen</CHOOSE>

The CHOOSE tag is one of the most powerful and useful tags in CSML. Essentially, all it does is put a list into a window from which the player can make a choice. However, as you can see with all of the parameters, it offers you a lot of control.

The parameters are:

FIELD – This is where in the character data the choice will be placed. For example, if you are giving the player a list of feats to choose from, you would set FIELD to feats (i.e. FIELD=”feats”). This parameter is required.
NAME – This is mainly used in conjunction with the hero field of misc. It is the name of the item. For example, a ranger must choose a favored enemy. This data is part of the miscellaneous data. Therefore, it needs a name so it can be retrieved later. The syntax would be: <CHOOSE FIELD=”misc” NAME=”Favored Enemy”>
VAR – If you are going to assign the choice selection to a variable, this is the parameter you would use. Remember, you must precede the variable name with “var.” (see The VAR parameter). For example, a wizard gets to choose a school to specialize in. After making that choice, the player must choose one or more prohibited schools. So, you’d want to assign the player’s choice to a variable so you can use an IF tag to test it later. The syntax would be: <CHOOSE var=”tag.School” caption=”Choose a school to specialize in”>
CAPTION – This is simply the caption you wish to be displayed at the top of the list box the player will see. If omitted, the default is “Please make a choice”.
TIMES – This is how many selections the player can make. If omitted, the default is one.
CANCEL – If set to true, then a Cancel button will appear allowing the player to cancel. If omitted, the default is false.

There are three different ways you can specify the items the player can choose.

List them individually – You can list them individually, following each item with a carriage return.
Show items from the database – You can list items from a table in the database. To do this, you will need to use an SQL statement. For example, a human can select any language as a bonus language except Druidic. So, you would put this between the CHOOSE tags: select * from Languages where Name!=’Druidic’. This would show all languages except Druidic.
Use the special command – If you place a dollar sign($) followed by a command, the list will vary based on current character data. The only command supported at this time is DEITYDOMAINS. For example, a cleric must choose two domains of his/her chosen deity. Of couse, this list can vary depending on the deity chosen. So, you would put this in between the CHOOSE tags: $deitydomains.

Examples:

A wizard gets to choose a familiar upon creation. So, the following would be placed in the Create section:

Bat\nCat

Hawk

Owl\nRat

Raven

Snake (Tiny)

Toad\nWeasel

</choose>

A human can choose any language as a bonus except Druid. So, the following would be placed in the Create section:

select * from Languages where Name!=’Druidic’

</choose>

A cleric must choose two domains based on the chose deity. So, the following would be placed iin the Create section:

$deitydomains

</choose>

Give

Description: Gives the character something.

Syntax: <GIVE FIELD=”” NAME=”” VAR=”” CAPTION=”” CANCEL=TRUE/FALSE DEFAULT=”” >items to be given</GIVE>

The GIVE tag allows you to give something to a character. This might be a skill, language, weapon, etc. As you can see, there are several parameters which are:

FIELD – This is where in the character data the choice will be placed. For example, if you are giving the player a list of feats to choose from, you would set FIELD to feats (i.e. FIELD=”feats”). This parameter is required.
NAME – This is mainly used in conjunction with the hero field of misc. It is the name of the item. For example, a ranger must choose a favored enemy. This data is part of the miscellaneous data. Therefore, it needs a name so it can be retrieved later. The syntax would be: <CHOOSE FIELD=”misc” NAME=”Favored Enemy”>
VAR – If you are going to assign the choice selection to a variable, this is the parameter you would use. Remember, you must precede the variable name with “var.” (see The VAR parameter). You will normally not use this in the GIVE tag.
CAPTION – If you wish a text input window to be displayed, passing a value in the CAPTION parameter not only displays a text input window, it is also displayed as the caption.
CANCEL – If you have a value in the CAPTION parameter, the CANCEL parameter determines if the player can cancel the text input or not. If omitted, the default is false.
DEFAULT – If you are displaying a text input window, this is what the default value will be that appears in the text field.

Since GIVE adds something to the character, you will mostly likely use this tag in the Create and Level Change sections.

Examples:

A monk gets the feat of Improved Unarmed Strike, Deflect Arrows at 2nd level. So, in the Level Change section, you would do this (the LEVEL tag is explained later):

Improved Unarmed Strike, Deflect Arrows

</give>

</level>

A ranger gets to choose a Favored Enemy upon creation. You will notice in this example that there is nothing between the GIVE tags. This is fine. The following would go in the Create section:

An Elf gets several languages upon creation. The following would go in the Create section:

Draconic

Gnoll

Gnome

Goblin

Orc

Sylvan

</give>

Italic

Description: Prints text in italics.

Syntax: <I>text</I>

This tag should only be used within a PRINT tag and only in the Character Sheet section.

Level

Description: Allows you to control when certain things happen based on the character’s level.

Syntax: <LEVEL MIN=# MAX=# STEP=#>anything (including other tags)</LEVEL>

The LEVEL tag tests the character’s level based on the parameters you passed. If the test returns true, whatever you placed between the LEVEL tags is processed. The LEVEL tag takes three parameters which are:

MIN – The minimum level at which the items should be processed.
MAX – The maximum level at which the items should be processed.
STEP – The level increment. For example, you want a character to choose a new language every third level starting at level 3 and continuing until level 12. The syntax would be:<LEVEL MIN=3 MAX=12 STEP=3>

You must pass either the MIN or MAX parameters. If you omit the MIN parameter, then level 1 will be assumed. If you omit the MAX parameter, then no upper level limit will be assumed.

Essentially, the LEVEL tag is a shortcut to doing something similar with the IF tags. You could accomplish the same thing by doing something like this: <IF hero.level>=2 and hero.level<8>. As you can see, the LEVEL tag requires less typing.

The LEVEL tag may safely be used in any section.

Examples:

The LEVEL tag is extremely useful for displaying level-specific information on the character sheet. Consider the following snippet from the Barbarian’s Sheet section (the MATH and PRINT tags are explained later):

</level>

<print>Gains +10 feet to movement when wearing no armor, light armor, or medium armor and not carrying a heavy load; </print>

</level>

</level>

Beginning at 2nd and continuing on for every two levels, a fighter gets to choose a bonus feat. The following would go in the Level Change section (the feats aren’t actually shown for the sake of space):

the feats would go here

</choose>

</level>

Math

Description: Calculates a mathematical formula.

Syntax: <MATH FORMULA=”” VAR=”” PRINT=TRUE/FALSE></MATH>

The MATH tag will calculate a mathematical formula and return the result. You can use any of the hero variable names (see Getting and Setting Character Data) in place of any number in the formula. You can use the keyword LEV for the character’s level.

The parameters are:

FORMULA – The formula to calculate.

VAR – If you are going to assign the result to a variable, this is the parameter you would use. Remember, you must precede the variable name with “var.” (see The VAR parameter).
PRINT – If you do not wish the result to be printed on the character sheet (if the tag is in the Character Sheet section), set this to FALSE. If omitted, the default is TRUE.

Examples:

Starting a level 2, a Barbarian gets to add his dexterity bonus to his Armor Class. Therefore, this would go in the Character Sheet section:

</level>

As you can see by the above example, this is no actual formula – it is simply printing the current dexterity bonus.

A Bard gets certain abilities based on his level (the SMART tag will be explained later).

<print>Bardic Music Abilities (may be used <math formula=hero.level*1> <smart one="time" others="times"> per day): </print>

Note: You will notice in the above examples that the formula is not enclosed in quotes and there is no </MATH> tag. For the MATH tag, neither are enforced.

Misc

Description: The MISC tag is used in the Character Sheet section to display miscellaneous information about a character (such as a Ranger’s favored enemy).

Syntax: <MISC NAME=”” VAR=”” PRINT=TRUE/FALSE></MISC>

Miscellaneous data is usually set with either the GIVE or CHOOSE tags. Use MISC when you are ready to display the data.

The parameters are:

NAME – The name of the miscellaneous data.
VAR – If you are going to assign data to a variable, this is the parameter you would use. Remember, you must precede the variable name with “var.” (see The VAR parameter).
PRINT – If you do not wish the result to be printed on the character sheet (if the tag is in the Character Sheet section), set this to FALSE. If omitted, the default is TRUE

Examples:

Rangers get to select a Favored Enemy. To display that choice on the Character Sheet, the following would go in the Character Sheeet section:

<print>Favored enemy: <misc name="Favored Enemy"></print>

Note: You will notice in the above example that there is no </MISC> tag. While supported, it is not enforced.

MsgBox

Description: Displays a message box to the player.

Syntax: <MSGBOX>message</MSGBOX>

The MSGBOX tag simply displays a message to the player.

Examples:

Beginning at level 10 and proceeding every third level until level 19, a Rogue gets to choose a special ability. The following is in the Rogue’s Level Change section (the SET tag will be explained later):

Crippling Strike

Defensive Roll

Improved Evasion

Opportunist

Skill Mastery

Slippery Mind

</choose>

<set field=skillBonus action=add value=hero.INTBonus+3> <msgbox>You have been given additional skill points to distribute which you may use the next time you select skills.</msgbox>

<endif>

</level>

Let’s take a closer look at this example. We want to place the choice the player makes in the character’s miscellaneous data and we want to call it Special Abilities. So, we set the field to “misc” and the name to “Special Abilities”. We also want to check what the player chose, so we are going to use a variable called “tag.ability”. If the player chose “Skill Mastery”, then we need to add some bonus skill points for the player to use (that’s what the IF tag checks for). The SET tag adds this points (which is the INT bonus plus 3) to the characters skillBonus. Then, a message box is displayed to let the player know what happened.

Print

Description: Prints something on the character sheet.

Syntax: <PRINT STYLE=””>content</PRINT>

As you ca probably guess, PRINT only works in the Character Sheet section. The Style parameter (which is optional) determines the style the text should be printed in. You can use BOLD, ITALIC, and UNDERLINE. You may also embed style tags (<B>,<I>,<U>) in the contents as well. If you are using the STYLE parameter, you can combine styles with the + symbol. For example, BOLD+ITALIC.

Example:

This would go in the Character Sheet section:

<PRINT STYLE=ITALIC>See Pages 34&35 of PHB for more information</PRINT>

Set

Description: The SET tag lets you set character data.

Syntax: <SET FIELD=”” NAME=”” ACTION=”>data</SET>

The SET tag allows you to add to or replace certain character data.

The parameters are:

FIELD – The name of the character field you are setting (see Getting and Setting Character Data),
NAME – If setting MISC data, the name of the data.
ACTION – This can be ADD or REPLACE. ADD will add to the current data and REPLACE will replace it. If omitted, the default is REPLACE.

Examples:

See MsgBox for a good example of the SET tag.

Smart

Description: Used in conjunction with the MATH tag.

Syntax: <SMART ONE=”” OTHERS=””></SMART>

The SMART tag is used to display “smart” numbers resulting from calculations of the MATH tag.

The parameters are:

ONE – This should be displayed if the result is 1.
OTHERS – This should be displayed if the result is not a 1.

Important: In order for the SMART tag to work properly, it must immediately follow a MATH tag.

Examples:

See Math for a good example.

Table

Description: Displays or uses data from a table.

Syntax: <TABLE NAME=”” ROW=# COLUMN=# VAR=””></TABLE>

CharSys d20 uses a variety of tables. The TABLE tag will allow you to access that data.

The parameters are:

NAME – The name of the table.
ROW – The row you wish data from (you can use a static number or a character field).
COLUMN – The column you wish data from.
VAR – If you are going to assign the data to a variable, this is the parameter you would use. Remember, you must precede the variable name with “var.” (see The VAR parameter).

Examples:

This tag is definitely explained best through examples. Below is the entire Character Sheet section for the Monk. As you can see, it is quite complex, but it will give you a good example of the TABLE tag as well as how other tags work with each other.

<print>May using stunning attack <math formula=hero.level*1> <smart one="time" other="times"> per day. Opponent must make a Fortitude Save at DC <math formula=10+(hero.level/2)+hero.abilityBonus[WIS]> or is stunned for one round; </print>

<print>Successful Reflex save against magical or unusual attacks deals no damage; </print>

</level>

<print>Receives +2 bonus to Saving Throws against Enchantment spells and effects; </print>

</level>

</level>

<print>Immune to all diseases except magical ones;</print>

</level>

</level>

<print>May heal up to <math formula=hero.level*2> hit points per day; May jump a greater distance than monk's height; </print>

</level>

</level>

<print>Takes no damage on successful Reflex saves against such attacks as dragon's breath or fireball; </print>

</level>

<print>Ki strike (+1); </print>

</level>

<print>Is immune to poisons of all kinds; </print>

</level>

<print>May slip magically between spaces as per <i>dimension door</i> spell. Effective casting level is <math formula=hero.level/2>; </print>

</level>

<print>Has a spell resistance of <math formula=10+hero.level>; </print>

</level>

<print>Ki strike (+2); </print>

</level>

<print>Quivering Palm (once per week). May choose to slay victim <math formula=hero.level*1> days after attack. Victim must make a Fortitude save at DC of <math formula=10+(hero.level/2)+hero.abilityBonus[WIS]> or dies; </print>

</level>

<print>Ki strike (+3); </print>

</level>

<print>Does not suffer ability penalties for aging and cannot be magically aged; Can speak with any living creature; </print>

</level>

<print>Slow fall (any distance); </print>

</level>

<print>May assume ether state for <math formula=hero.level*1> rounds per day; </print>

</level>

<print>Perfect self (see rules); </print>

</level>

<print>

<p><b>Unarmed Attack Bonus</b>:

<b>Unarmed Damage:</b>

<b>AC Bonus:</b> +<math formula=tag.monk+hero.abilityBonus[WIS]> <b>Unarmed Speed</b>:

<table name="Monk" row=hero.level column=6> ft.\n

</print>

<else>

<print>

<p><b>Unarmed Attack Bonus:</b>

<b>Unarmed Damage: </b>

<b>AC Bonus:</b> +<math formula=tag.monk+hero.abilityBonus[WIS]>

<b>Unarmed Speed:</b>

<table name="Monk" row=hero.level column=5> ft.

</print>

<endif>

<print style=italic><p>See pages 37-41 of PHB for more information.</print>

Eyes glazed over yet? As you can see, the Monk has a lot of special abilities that change as the Monk changes levels. We’ll look at the TABLE tags.

The first TABLE tag gets a value from COLUMN 4 and assigns it to a variable called “tag.monk” The ROW is based on the character’s level.

The next line checks to see if the character’s race is Gnome or Halfling. This check determines which column the Unarmed Damage and Unarmed Speed data should come from. You will notice that the “tag.monk” variable is used in the mathematical formula for AC Bonus

Underline

Description: Draws underlined text.

Syntax: <U>text</U>

Use this tag inside the PRINT tags.

Conclusion

There are a lot of things you can do with CSML. This document provides more of an overview with some examples. The best way to learn is to look at the existing CSML in Races, Classes, Deities, and Prestige Classes. As of this writing, neither the CharSys d20 Database Manager not the Prestige Class Editor is finished. This document is presented, at this time, for reference and to show how CSML is used.

The CSML started out as a simple way of display level-based information on a character sheet. It has grown into a full-fledged markup language.

Since CSML is quite complex, I’ll be more than happy to answer any questions. Just send an email to macmage@maccrafters.com