RPG+ - Import/Export

Import and Export RPG Plus Dice Notation Groups from/to your SD Card.

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

The RPG Plus Dice Notation Groups 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 RPG Plus Dice Notation Groups 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 RPG Plus Dice Notation Groups 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 RPG Plus Dice Notation Groups to export. The file will be saved on the SD Card in the folder /data/data/com.ecsoftareconsulting.TrulyRandom/files.

Technical Stuff

This is a sample of what the XML looks like in order to represent a RPG Plus Dice Notation Group.

Note: If you are having difficulties creating the file structure, try creating the RPG Plus Dice Notation Group 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"?>
<rpg_plus>
    <group>
        <title>Special Sword</title>
        <description>Example</description>
        <equation>
            <title>Attack 1</title>
            <numthrows>1</numthrows>
            <expression>1d20+12</expression>
        </equation>
        <equation>
            <title>Attack 2</title>
            <numthrows>1</numthrows>
            <expression>1d20+10</expression>
        </equation>
        <equation>
            <title>Attack 3</title>
            <numthrows>1</numthrows>
            <expression>1d20+8</expression>
        </equation>
        <equation>
            <title>Damage</title>
            <numthrows>3</numthrows>
            <expression>2d8+1d6+5</expression>
        </equation>
    </group>
</rpg_plus>

Now for a little explanation. As you can imagine from the screen interface, a RPG Plus Dice Notation Group is a hierarchy of items. Each group has one or more equation, each equation has a number of attributes that define it. XML is well suited to represent this hierarchy. Each element that defines the RPG Plus Dice Notation Group is represented by a tag.

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

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.

<rpg_plus>

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

<group>

This element identifies a dice group. The import file can contain multiple groups, 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"?>
<rpg_plus>
    <group>
        Body of Group 1....
    </group>
    <group>
        Body of Group 2....
    </group>
</rpg_plus>

<title>

The title element defines the title of each group. It is also used to define the title of each equation.

<description>

The description element is optional and is used to provide more detailed information about the group.

<equation>

The equation element collects the information necessary to run and present the results of the calculation.

<numthrows>

The numthrows element is a number (1 or more) that defines how many times this equation is executed.

<expression>

The expression element is the calculation that needs to be performed.

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 description element might indicate the following:

Apply damage if a roll is < 12.

Enter this in the XML document like this:

Apply damage if a roll is &lt; 12.