Bulk Importer and Exporter Tool

A tool to assist with stat and achievement management

6 min read

You can use the Bulk Importer/Exporter Tool to manage your product's stats and achievements outside of the Developer Portal interface. The tool uses .zip archives containing CSV-formatted data, so you can view and edit your stats and achievements in a wide variety of existing programs or your own tools.

The bulk import tool only affects the definitions of your stats and achievements. It does not add, delete, or change your users' progress in any way. If you delete and recreate your stats or achievements definitions, your users' stat and achievement progression remains intact.

You can find this tool on the Developer Portal, under Games Services > Achievements. The Bulk Import/Export button exists between the Player Lookup and Create New buttons near the top.

Exporting (Step 1)

The export process creates a zip archive for download. This archive contains .csv and .png image files of all existing stats and achievements for your product.

These files adhere to the standard .csv format for easy import and export with most spreadsheet software applications. Your image files should be in standard .png format before exporting.

To start the export, simply select Export Current Achievements. The download automatically begins and creates a .zip folder wherever your downloaded content is typically stored.

You can also skip exporting by selecting Next. If you do not have a backup of your current achievements, it is not recommended to skip this step.

Importing (Step 2 and 3)

The import process follows the same file format as the export process. Your import .zip file should contain the following files in the root of the .zip file:

File NameContents
stats.csvA list of "name and type" pairs that define each stat
achievementDefinitions.csvA list of achievement names, along with the stats they reference
achievementLocalizations.csvAchievement Localization locale keys and the files names of their icons
One or more .png filesThe icons referenced in achievementDefinitions.csv

To help prepare your .zip file for import, you can download our .zip template from the Developer Portal where you would upload your .zip for import (select the Download EOS Achievements Zip Template) or click here. Either option sets off an automatic download of our sample BulkTemplate.zip folder with properly organized content.

Sample of the EOS Achievements Bulk Import template

Before beginning the import process, review the requirements for both your CSV and image files.

Once you are ready to import your files, select Choose File to Upload on Step 2 of the Bulk Import process. Confirm that you have read the notice about the import removing all existing achievements and clears all the stats for your product.

Select Next to begin a validation check for your imported content. Once complete, the backend service deletes all your existing stats and achievements, then replaces them with the ones found in the .zip file. This includes caching any icons that the new achievements use on the backend service.

The final step of the import modal displays the success of your achievements and stats import.

CSV Format Requirements

To ensure that the .csv files you upload pass the validation check, use to the data format listed below for each file type and avoid leaving any blank lines. All CSV files must be UTF-8 encoded.

stats.csv Format

The stats.csv file has two columns for each stat: 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

The achievementsDefinitions.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.

The 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

The text entered into the locale (second) column of the .csv file must match the tag formats below:

LocaleTag
Arabicar
Danishda
Dutchnl
English (America)en-US
English (United Kingdom)en-GB
Finnishfi
Frenchfr
Germande
Italianit
Japaneseja
Koreanko
Norwegianno
Polishpl
Portuguese (Brazil)pt-BR
Russianru
Simplified Chinesezh-Hans
Spanish (Mexico)es-MX
Spanish (Spain)es-ES
Swedishsv
Thaith
Traditional Chinesezh-Hant
Turkishtr

On February 23, 2021, the locale codes for English (United Kingdom), Swedish, Traditional Chinese, and Simplified Chinese were updated. Do not import any of your .zips from before this date. Either update those files to match the new locale codes or perform a new export your data.

Icon Requirements

Icons you reference in achievementDefinitions.csv must exist in the current zip archive you import, because all previous content is erased at the time of the new import. All icons must be in .png format and exist at the root level of the archive. Do not have any subfolders in your .zip file.

Icon filenames cannot include the following characters or it produces Developer Portal errors: \ { ^ } % ` ] > [ ~ < # | & $ @ = ; : + , ? or spaces ' '

To eliminate redundant downloads for your users, achievements can share icons if they refer to the same icon file. Use this capability whenever multiple achievements use the same image, like the “locked” icon for hidden achievements.