Custom Dice Sets - Import/Export

Import and Export Custom Dice Sets from/to your SD Card.

This feature will give you a lot of flexibility in managing your Custom Dice Sets. Share them with your friends. Build them on your computer and copy them to your device.

The Custom Dice Sets are represented in XML format, but it's not complicated. See the Technical Stuff below for an explanation.

Import

To start, choose Import/Export | Import from the menu.

A file selection dialog will be presented allowing you to navigate to the location of your import file. It will initially open in the /data/data/com.ecsoftwareconsulting.TrulyRandom/files/ directory, unless your SD Card is not mounted, in which case it will start at the root of your file system.

Truly Random Import

Once you've selected your file, it will be read, presented as a list of the Custom Dice Sets found in the file. If it discovers one in the file that is named the same as one you already have, a sequence number will be appended to it so that it does not overwrite the one you have on the device already.

Truly Random Import

Choose any or all (at least one) of the Custom Dice Sets to import.

Export

To start, choose Import/Export | Export from the menu.

Truly Random Import

Enter a filename for your export and choose any or all (at least one) of your Custom Dice Sets to export. The file will be saved on the SD Card in the folder /data/data/com.ecsoftwareconsulting.TrulyRandom/files.

Technical Stuff

This is a sample of what the XML looks like in order to represent a Custom Dice Set.

Note: If you are having difficulties creating the file structure, try creating the Custom Dice Set in the app and exporting it. Then you can compare the file exported with what you have and hopefully sort out any issues. Of course, you can always contact us and we will be glad to help.

<?xml version="1.0" encoding="utf-8"?>
<custom_dice>
    <set>
        <title>Dinner</title>
        <variable>
            <name>Guests</name>
            <expression>1d10</expression>
        </variable>
        <variable>
            <name>CookiesPerGuest</name>
            <expression>2</expression>
        </variable>
        <die>
            <title>Entree</title>
            <face>
                <title>Chicken</title>
                <weight>1</weight>
            </face>
            <face>
                <title>Hamburgers %%</title>
                <weight>1</weight>
                <expression>Guests+d4</expression>
            </face>
            <face>
                <title>Pasta</title>
                <weight>1</weight>
            </face>
        </die>
        <die>
            <title>Desert</title>
            <face>
                <title>%% Cookies</title>
                <weight>1</weight>
                <expression>Guests*CookiesPerGuest</expression>
            </face>
            <face>
                <title>%% Cake(s)</title>
                <weight>1</weight>
                <expression>ifgt(Guests, 8, 2, 1)</expression>
            </face>
        </die>
    </set>
</custom_dice>

Now for a little explanation. As you can imagine from the screen interface, a Custom Dice Set is a hierarchy of items. Each set has one or more dice, each die has one or more faces and each face has zero or more expressions. XML is well suited to represent this hierarchy. Each item that defines the dice set is represented by a tag. The element <title> is used to identify the name of the set, die, or face depending on where it falls in the hierarchy.

Notice that for every element there is both an opening and closing tag. The element <die> defines the beginning of the definition for a die within the dice set. So, when we have finished defining a die, we close that element using a slash "/" as follows: </die>.

The following will define the elements and what we expect to find in them.

<?xml version="1.0" encoding="utf-8"?>

This is just a header that XML files have which define some basic information about the version and content of the file. Just include this as the first line of your file (only once in the file) and don't worry about it beyond that.

<custom_dice>

This element identifies the main body of the file. Everything that is being imported will be defined within the body of this element.

<set>

This element identifies a custom dice set. The import file can contain multiple custom dice sets, so if you have more than one you want to add in the file, you would define multiple set elements.

<?xml version="1.0" encoding="utf-8"?>
<custom_dice>
    <set>
        Body of Set 1....
    </set>
    <set>
        Body of Set 2....
    </set>
</custom_dice>

<title>

The title element is used in a couple of places above. Each Set, Die, and Face requires a title to be defined. The text is placed between the opening and closing elements as noted above.

<variable>

The variable element is used to define local variables that are executed prior to the expressions associated with the faces on the defined die. This element is included for each variable you need and requires the name and expression sub-elements to be defined as well.

<variable>
    <name>
        Name of the variable....
    </name>
    <expression>
        Expression to calculate....
    </expression>
</variable>

<die>

The die element is the definition of each die in the set. You can define one or more die for each set in the file.

<face>

The face element is the definition of each face for its related die. This is the value that will be displayed when you roll the dice in the application.

<weight>

The weight element is optional and will default to 1. This is used to weight the statistical distribution of the faces if used.

<expression>

The expression element is used for faces where you wish to embed a calculation in the definition of the face. For example, if you define a face to be:

Eat %% cookies.

You would be required to have an expression defined that would replace the "%%" place holder found in the face name. You can define a face name to embed multiple expressions and you would simply need to list multiple expressions within the face body. The order in which the expressions are specified is the order in which they will be used.

For example, the following face embeds multiple expressions:

Eat %% cookies and %% slices of cake.

We want to assign the following expressions to this:
First %%: d6
Second %%: d2+1

The XML needed to define this face would be:

<face>
    <title>Eat %% cookies and %% slices of cake.</title>
    <expression>d6</expression>
    <expression>d2+1</expression>
</face>

See RPG+ - RPG Dice Notation for more information on the rules for these expressions

Special Characters

As you can see, XML uses certain characters to identify its structural parts. As such, including those characters in the title and description elements will confuse the parser. So, to get around this, these special characters are "escaped" or replaced as follows:

Special Character Example Replace with
Ampersand & &amp;
Apostrophe ' &apos;
Double Quote " &quot;
Less Than < &lt;
Greater Than > &gt;

For example, a face element might indicate the following:

If your age > 21, you may have wine with dinner.

Enter this in the XML document like this:

If your age &gt; 21, you may have wine with dinner.

Formatting Options

The formatting options are explained in the Custom Dice Set section of the Truly Random page. In order to include them in the import file, a little more work will need to be done. Because we are using what are essentially XML tags to specify the formatting options we will need to escape them just like we described above. The following table will show you how the line would look if entered into the app and if entered in the XML file.

Format Option In App Import File
Bold <b>Bold</b> &lt;b&gt;Bold&lt;/b&gt;
Italic <i>Italic</i> &lt;i&gt;Italic&lt;/i&gt;
Underline <u>Underline</u> &lt;u&gt;Underline&lt;/u&gt;
Big <big>Big</big> &lt;big&gt;Big&lt;/big&gt;
Small <small>Small</small> &lt;small&gt;Small&lt;/small&gt;
SuperScript Super<sup>Script</sup> Super&lt;sup&gt;Script&lt;/sup&gt;
SubScript Sub<sub>Script</sub> Sub&lt;sub&gt;Script&lt;/sub&gt;
Line Break <br /> &lt;br /&gt;

Using one of the examples above and applying a little formatting to it, we write something like this:

<face>
    <title>Eat %% &lt;b&gt;cookies&lt;/b&gt; and %% slices of &lt;b&gt;cake&lt;/b&gt;.</title>
    <expression>d6</expression>
    <expression>d2+1</expression>
</face>

When this face is selected, it might appear as follows:

Eat 4 cookies and 2 slices of cake.

One additional note. Because the face title can have formatting, if you want to use an ampersand as part of the text, you will need to do the following:

<face>
    <title>Ampersand &amp;amp; in the face &lt;b&gt;for formatting.&lt;/b&gt;</title>
    <weight>1</weight>
</face>

Which should appear as follows when this face is selected.

Ampersand & in the face for formatting.