Exporting Data

Exporting your data in any arbitrary format is what makes Tome really useful compared to similar tools. No matter what game engine you use, or which data format you prefer, you can automatically write and format your data in any way you like.

Creating Export Templates

Tome needs to know how to export your data. You specify your custom output format by creating a bunch of template files that will be automatically injected and filled where appropriate by Tome. Special placeholder strings will be filled with your actual data.

We are using multiple file templates instead of just one, because we've had a bad experience with separating templates from each other in text-based formats. For example, Resharper code templates are stored in XML files, which require the templates themselves to be escaped in strange manners, turning these template files hard to read and edit. Also, splitting templates up into multiple files supports one of the goals of Tome, improved collaboration.

Because this is a rather abstract topic, we'll walk through a JSON export template as example. The following sections will describe each of the template files in detail.

Export File Template (.texportf)

Tome will create a data file of your custom output format. It will write your file template (.texportf), and replace the special placeholder string $RECORDS$ with the actual record data (see below).

Placeholder	Minimum Tome Version	Description
$APP_VERSION$	0.7	Application version number (e.g. 0.6).
$APP_VERSION_NAME$	0.7	Application version name (e.g. Hydra).
$EXPORT_TIME$	0.7	UTC date and time of the export (ISO 8601).
$HASH$	0.9	MD5 hash of all record data (not the exported file itself).
$RECORDS$	0.3	Applies .texportr file to all project records.

An example JSON export file template might look like this:

{
  "records": [
$RECORDS$
  ]
}

Export Record Template (.texportr)

Upon encountering the $RECORDS$ placeholder in the file template (see above), Tome will inject all of your records by applying your record template.

Placeholder	Minimum Tome Version	Description
$RECORD_COMPONENTS$	0.3	Applies .texportc file to all record components.
$RECORD_DISPLAY_NAME$	0.7	Editor display name of the record.
$RECORD_FIELDS$	0.3	Applies .texportv file to all record field values.
$RECORD_ID$	0.3	Unique ID of the record.
$RECORD_PARENT$	0.4	Unique ID of the parent of the record, or an empty string, if none.
$RECORD_ROOT$	0.8	Unique ID of the root of the record, or the id of the current record, if it's a root itself.

Example:

    {
        "id": "$RECORD_ID$",
        "attributes": {
    $RECORD_FIELDS$
        },
        "components": [
    $RECORD_COMPONENTS$
        ],
        "parent_id": "$RECORD_PARENT$"
    }

In some cases, you want a handful of fields to be handled differently from others. For example, some XML data formats might require you to export a field as XML attribute, while all other data should be exported as XML elements.

Tome allows you to use the $FIELD_VALUE:yourfieldname$ placeholder to insert the value of yourfieldname at the specified place in your record template. The respective field will automatically be skipped when evaluating the $RECORD_FIELDS$ placeholder.

Export Record Delimiter (.texportrd)

As most text-based data formats require records to be separated from each other by one or more delimiter characters, you may specify your delimiter string in this additional file. This will be inserted after each record except for the last one. In our JSON example, this file contains just a single comma and a line break.

,

Export Field Value Template (.texportv)

Next, Tome will write the actual values of all of your record fields by applying your field value template.

Placeholder	Minimum Tome Version	Description
$FIELD_COMPONENT$	0.7	Name of the component the field belongs to.
$FIELD_DESCRIPTION$	0.7	Editor description of the field.
$FIELD_DISPLAY_NAME$	0.7	Editor display name of the field.
$FIELD_ID$	0.3	Unique ID of the field.
$FIELD_TYPE$	0.3	Name of the type of the field, or matching value of the type map of the export template (see below).
$FIELD_VALUE$	0.3	Value of the field.
$RECORD_DISPLAY_NAME$	0.7	Editor display name of the current record.
$RECORD_ID$	0.3	Unique ID of the current record.
$RECORD_PARENT$	0.8	Unique ID of the parent of the record, or an empty string, if none.
$RECORD_ROOT$	0.8	Unique ID of the root of the record, or the id of the current record, if it's a root itself.

Example:

      "$FIELD_ID$": "$FIELD_VALUE$"

Export Localized Field Value Template (.texportvloc)

Whenever encountering a field of a derived type with the Localized facet, Tome will apply your localized field value template instead. This allows you to export localization keys here, and creating another export template for exporting the actual localization data. Then, you can import the data with the localization keys once in your game, and the localized strings multiple times, once for each language.

Placeholder	Minimum Tome Version	Description
$FIELD_COMPONENT$	0.8	Name of the component the field belongs to.
$FIELD_DESCRIPTION$	0.8	Editor description of the field.
$FIELD_DISPLAY_NAME$	0.8	Editor display name of the field.
$FIELD_ID$	0.8	Unique ID of the field.
$FIELD_TYPE$	0.8	Name of the type of the field, or matching value of the type map of the export template (see below).
$FIELD_VALUE$	0.8	Value of the field.
$RECORD_DISPLAY_NAME$	0.8	Editor display name of the current record.
$RECORD_ID$	0.8	Unique ID of the current record.
$RECORD_PARENT$	0.8	Unique ID of the parent of the record, or an empty string, if none.
$RECORD_ROOT$	0.8	Unique ID of the root of the record, or the id of the current record, if it's a root itself.

Example:

      "$FIELD_ID$": "$RECORD_ROOT$.$RECORD_ID$.$FIELD_ID$"

Export Field Value Delimiter (.texportvd)

Just as for records, field values often require to be separated from each other by one or more delimiter characters. This will be inserted after each field value of the same record, except for the last one. Again, in our JSON example, this file contains just a single comma and a line break.

,

Export Component Template (.texportc)

In case you are exporting record components, Tome will apply this template for each component that contains at least one field used by the record.

Placeholder	Minimum Tome Version	Description
$COMPONENT_NAME$	0.3	Name of the component.

Example:

            "$COMPONENT_NAME$"

Export Component Delimiter (.texportcd)

In most cases, components require to be separated from each other by one or more delimiter characters as well. This will be inserted after each component of the same record, except for the last one. Again, in our JSON example, this file contains just a single comma and a line break.

,

Export List Template (.texportl)

If your field is of a list type, three different field value templates are applied. This allows you to specify that lists should be exported differently than other field values. List templates allow the same placeholders as other values (.texportv).

Example:

      "$FIELD_ID$": [$FIELD_VALUE$]

Export List Item Template (.texportli)

For each item in the list, the list item template is applied.

Placeholder	Minimum Tome Version	Description
$FIELD_ID$	0.3	Unique ID of the list field.
$ITEM_TYPE$	0.3	Name of the type of the list items, or matching value of the type map of the export template (see below).
$LIST_ITEM$	0.3	Actual list item.

Example:

"$LIST_ITEM$"

Export List Item Delimiter Template (.texportld)

Tome inserts the list item delimiter template between each pair of list items:

,

Export Map Template (.texportm)

If your field is of a map type, three different field value templates are applied. This allows you to specify that maps should be exported differently than other field values. Map templates allow the same placeholders as other values (.texportv).

            "$FIELD_ID$": {
    $FIELD_VALUE$
            }

Export Map Item Template (.texportmi)

For each key-value pair in the map, the map item template is applied.

Placeholder	Minimum Tome Version	Description
$FIELD_ID$	0.3	Unique ID of the list field.
$FIELD_KEY$	0.5	Name of the type of the map keys, or matching value of the type map of the export template (see below).
$FIELD_VALUE$	0.5	Name of the type of the map values, or matching value of the type map of the export template (see below).

Example:

            "$FIELD_KEY$": "$FIELD_VALUE$"

Export Map Item Delimiter Template (.texportlm)

Tome inserts the map item delimiter template between the key-value pairs:

,

Adding Export Templates

In order to make the above export template available in Tome, you need create template files and add references to them in your Project Overview window.

Export template files (.texport) specify the name of your template, as it should be shown in the editor menu bar, as well as the default file extension of the exported files:

<?xml version="1.0" encoding="UTF-8"?>
<Template Version="2" ExportLeafs="true">
    <Name>JSON</Name>
    <FileExtension>.json</FileExtension>
    <TypeMap/>
    <IgnoredRecords/>
    <IgnoredFields/>
</Template>

When using an export template, Tome will look for all of the above other files with the same filename as your .texport (but with the above extensions).

You need to explicitly state which types of nodes you want to be exported. Each template has ExportRoots, ExportInnerNodes and ExportLeafs attributes for this. Note that you can exploit this feature for creating export templates that actually behave as code generators!

Because almost every game engine has their own name for the basic data types, you may specify a type map for automatically replacing Tome data type names by the ones of your engine.

<?xml version="1.0" encoding="UTF-8"?>
<Template Version="2" ExportLeafs="true">
    <Name>Slash XML</Name>
    <FileExtension>.blueprints.xml</FileExtension>
    <TypeMap>
        <Mapping TomeType="Armor Type" ExportedType="FantasyGame.Data.ArmorType"/>
        <Mapping TomeType="Boolean" ExportedType="System.Boolean"/>
        <Mapping TomeType="Color" ExportedType="System.String"/>
        <Mapping TomeType="Damage Type" ExportedType="FantasyGame.Data.DamageType"/>
        <Mapping TomeType="Integer" ExportedType="System.Int32"/>
        <Mapping TomeType="Movement Type" ExportedType="FantasyGame.Data.MovementType"/>
        <Mapping TomeType="Real" ExportedType="System.Single"/>
        <Mapping TomeType="Reference" ExportedType="System.String"/>
        <Mapping TomeType="String" ExportedType="System.String"/>
    </TypeMap>
    <IgnoredRecords/>
    <IgnoredFields/>
</Template>

Sometimes, you want to export the data in some table format (such as CSV or HTML). Setting the ExportAsTable attribute of the Template element will cause Tome to add empty field entries for any fields not used by a record.

<?xml version="1.0" encoding="UTF-8"?>
<Template Version="2" ExportAsTable="true" ExportLeafs="true">
    <Name>HTML</Name>
    <FileExtension>.html</FileExtension>
    <TypeMap/>
    <IgnoredRecords/>
    <IgnoredFields/>
</Template>

You may also exclude specific records and/or fields from being exported. Inside the IgnoredFields and IgnoredRecords elements, add Id elements specifying the ids of the records and/or fields you want to ignore. If an ignored record has children, these children will be ignored as well.

Note that records without any fields are not exported. Consequently, records whose parents don't have any fields will have their parent id reset for the export.

Tome allows you to specify the ExportLocalizedFieldsOnly attribute to restrict data export to custom types with the Localized facet. This way, you can create export templates for exporting localization data to send to your localization team and import in your game.

Since Tome 1.1, you can also add an element StringReplacementMap with two element children String and ReplaceWith.

You can always select File > Reload Project to reload all export templates. This allows for faster iteration.

Exporting Data

After having added the export template to your project file, it will be available from the Export menu:

1. In the main window menu bar, click Export.
2. Select the template to export the data with.
3. Specify an output file.
4. Click Save.

Next: Importing Data