Bulk Importer and Exporter Tool

A tool to assist with stat and achievement management

The Bulk Importer/Exporter Tool provides developers using Epic Online Services (EOS) with the ability to manage a product's stats and achievements outside of the Developer Portal interface. The tool uses zip archives containing CSV-format data, enabling developers to view and edit their stats and achievements in a wide variety of existing programs, or with their own tools.

Exporting

The export process creates a zip archive that developers can download. This archive will contain .csv files comprising all existing stats and achievements for the product. These files adhere to the standard .csv format, meaning that they are human-readable text files with one or more lines containing values separated by commas. Most spreadsheet software packages can export to, and import from, this format.

Importing

The import process uses the same file format as the export process. Specifically, the process requires a zip archive containing the following files:

File Name

Contents

Stats.csv

A list of "name and type" pairs that define each stat

AchievementDefinitions.csv

A list of achievement names, along with the stats they reference, if any, and the file names of icons they use

AchievementLocalizations.csv

Achievement Localization locale keys

One or more .png files

The icons referenced in AchievementDefinitions.csv

To begin the process, all stats and achievements in the archive must pass a validation check. Once this is complete, the back-end service will delete the all existing stats and achievements, then replace them with the ones found in the zip file. This includes caching any icons that the new achievements use on the back-end service.

Importing data with the tool permanently overwrites any previously existing data related to stats or achievements for that deployment. We recommend keeping a backup; a simple way to do this is to perform an export from the tool immediately before importing.

The following sections describe the format requirements in detail. You can also use Epic's sample archive as a template.

During an import operation on a live deployment, stat and achievement definitions can be in an incomplete state. Users may not be able to record stats or unlock achievements as a result. We recommend that live deployments import data during maintenance windows to minimize disruption and unexpected behavior for end users.

CSV File Format Requirements

To ensure that the .csv files you upload will pass the validation check, adhere to the data format for each file and avoid leaving any blank lines.

Stats.csv Format

The Stats.csv file has two columns for each stat; these are the name of the stat, and its aggregation type. Supported values for aggregation type are SUM, MIN, MAX, or LATEST. A sample Stats.csv file follows:

name,aggregationType
numTreesChopped,SUM
lastTreesChopped,LATEST
maxTreesChopped,MAX
minTreesChopped,MIN
numAxesUsed,SUM

See the Stats Interface for more information.

AchievementDefinitions.csv Format

Achievements.csv uses three columns to define each achievement and the requirements for unlocking it. The first two columns hold the achievement's internal name and a Boolean value indicating whether the achievement is hidden or not. The third column is optional; if it is empty, the achievement can only be unlocked by an explicit command from the EOS SDK. When present, the third column is a list of stat names and thresholds, taking the form Stat1:Threshold1;Stat2:Threshold2;StatN:ThresholdN, as shown in the following sample Achievements.csv file:

name,hidden,statThresholds
achvTutorial,FALSE,
achvLumberjack,FALSE,numTreesChopped:3
achvWoodsman,TRUE,numTreesChopped:100;numAxesUsed:5

See the Achievements Interface for more information.

AchievementLocalizations.csv Format

All user-visible information about achievements is subject to localization. AchievementLocalizations.csv sets up all the data that the system needs to describe each achievement to users in different locales. This includes the internal name of the achievement and the locale, followed by its title and description when locked, its title and description when unlocked, its flavor text, and its locked and unlocked icons. The following sample AchievementLocalizations.csv file shows the default (with the second column empty) and German (with "de" in the second column) versions of the same set of achievements:

name,locale,lockedTitle,lockedDescription,unlockedTitle,unlockedDescription,flavorText,lockedIcon,unlockedIcon
achvTutorial,,Intro,Complete the Tutorial,Intro,Completed the Tutorial,Onwards!,locked.png,tutorial.png
achvTutorial,de,Einführung,Schließe die Einführung ab,Einführung,Die Einführung abgeschlossen,Weiter!,locked.png,tutorial.png
achvLumberjack,,Lumberjack,Chop 3 trees,Lumberjack,Chopped 3 trees,Timber!,locked.png,lumberjack.png
achvLumberjack,de,Holzfäller,Fälle drei Bäume,Holzfäller,Drei Bäume gefällt,Holz!,locked.png,lumberjack_de.png
achvWoodsman,,Woodsman,Roam the woods,Woodsman,Travelled the woods and chopped some trees,,lockedSecret.png,woodsman.png
achvWoodsman,de,Waldmensch,Durschtreife die Wälder,Waldmensch,Die Wälder bereist und Bäume gefällt,,lockedSecret.png,woodsman.png

Icon Requirements

The icons that you reference in AchievementDefinitions.csv must exist in the zip archive that you send to the back-end service with the tool's import feature. All icons must be in .png format, and should exist at the root level of the archive.

As of EOS SDK version 1.8, achievements can share icons with each other if they refer to the same icon image file, which eliminates redundant downloads for your end users. Use this feature wherever multiple achievements use the same image; this is especially common in the case of "locked" icons for hidden achievements.