CSV files for missions

Overview

The effect of a CSV on the mission selection screen (top image without, bottom image with)

The effect of a CSV on how objectives appear in mission (top image without, bottom image with)

The effect of a CSV on how objectives look on the map screen in game (top image without, bottom image with)

CSV (Comma-Separated Values) Files are used in War Thunder as "localization" files. They convert the text coded into the game (or in this case mission) into one or more languages, ready for display on the game's user interface. In the case of user missions this text comes in the form of the mission's properties (its name, etc.), the mission's objectives (the objectives given to the player during the mission), and any other text in the mission (hints, etc.).

It is not necessary to create a CSV file for a user mission; however, doing so has several advantages. These include: allowing the mission's text elements to be displayed in multiple languages (instead of just the language you programmed the mission in); making the mission text batter formatted (e.g. missions no longer have "missions/" prefixing their name); and allowing a more wide range of characters to be used (e.g. missions names can have a space in them if a CSV file is used). The effects of creating a CSV file for a mission can be seen in the 3 images to the right.

The most radical change is in the mission selection menu (top image); the mission name, campaign name and chapter name are no longer prefixed with "missions/" (or "campaigns/" and "chapters/"); the mission name includes characters it was not previously allowed to; and the "date" (below the mission name in the right portion of the screen) and "objective" fields now contain information instead of being blank. Overall the mission looks much more professional and presentable. Another major change, seen in the second image, is that objectives now appear at the top of the screen when they are assigned to the player. Without a CSV file, the objectives appear as a "smudge" at the top of the screen, this is because the game does not know what text to display for the objective so loads in the dark strip for the objective to be written on, but then write no text to it. As can be seen in the image, with a CSV any new objectives assigned to the player appear clearly at the top of the screen. The final effect shown in the images is how the mission objective is displayed on the map screen. Even without a CSV file, the mission objective will be displayed here (however not at the top of the screen). Creating a CSV file will change the mission objective displayed on the map screen from what was typed in the mission editor to what was put in the CSV file; this allows for mission objectives to be named more simply in the editor, with a more detailed explanation of the objective written in the CSV file, to be displayed in-game.

Additionally, like mission objectives, other texts in the mission (hints, etc.) can be added to CSV files. This has the benefit of allowing them to be displayed in multiple languages, and as discussed previously allowing for more simplistic naming of the text in the mission editor. Additionally, if several triggers are meant to display the same message they can all be set to display the same simple text string in the editor, which is then elaborated on by the CSV file. For example, several triggers may want to print the same message "Enemy bombers are inbound, find cover". Instead of typing that in each trigger you could set them all to, for example, "missionText1", and then set that text in the CSV file to mean "Enemy bombers are inbound, find cover" in English. The game will then replace every instance of "missionText1" with "Enemy bombers are inbound, find cover" (it will not replace the text if it is part of a larger string value, so don't worry about that). This way if you decide you want to change the wording of the text you only have to change it once, in the CSV file, instead of in the action of each trigger.

Structure and layout of CSV files

Comma-Separated Values (CSV) files contain rows of data, with values separated by a "delimiter" (a character used to signify the end of one value and the start of the next). The CSV files used by War Thunder use a semicolon (;) as the delimiter. In War Thunder's localization CSV files each row represents a line of text; the first value in each row represents how the text is programmed in the game/mission; then each subsequent value in the row represents what the text should be displayed as in each specified language. The first row in the CSV file is used to specify how the game should treat each value (e.g. the first value is the ID, the next value is what to display in English, the next value after that is what to display in Russian, etc.).

Other than the first line of the file containing the headings to tell the game what each value is for, the rest of the file can be in any order. However to improve readability, and keep the file organised it is recommended to keep the text of the same type together (i.e. keep all the mission objectives together, all the hints together, all the mission properties together, etc.). Again the order of these groups does not matter from a functional point of view; however general convention from the community tends to be, to put mission objectives at the top of the file (under the heading row), followed by hints, finally any other text used in the mission, and finally the mission properties, with a blank line separating each group.

Making a CSV file for a mission

Creating the blank CSV file

To create a CSV file you should create a new plain text document (in Windows you can right-click and select the "New > Text Document" option) in the "UserMissions" folder (where your mission is). Give this the same name as the mission you are making it for, prefixed with "usr_" and change the file extension to ".csv". For example, if the mission file is called "myUserMission.blk" your CSV file should be called "usr_myUserMission.csv". Open the file in a text editor; notepad or notepad++ will work fine, but MS Excel (if installed it may be set as your default editor for CSV files) probably won't; and save the file with UTF-8 encoding (in notepad select save as, then save the file with the save name it currently has, but with the encoding box switched from ANSI to UTF-8).

Editing the file

You can use a text editor of your choice to edit CSV files. Open the CSV file you created and start adding information to it.

The header / language identifier line

The first line of the CSV file is used to tell the game what each value in a line means. It will look something like this:

"<ID|readonly|noverify>";"<English>";"<Russian>";

Semicolons (;) are used to separate the values, which are entered in quotation marks. The first value in this row is "<ID|readonly|noverify>"; this will be the same for every CSV file you make. It tells the game that the first value in each row is the ID (the text what was programmed into the mission) and passes the "readonly" and "noverify" arguments to the game (just required so the game reads the file correctly). The next value (separated by a semicolon) is "<English>"; this tells the game that the second value in each line is the text which should be displayed in place of the text in the ID field when the game language is set to English. The next value (the third value in the line) is "<Russian>"; this tells the game that the third value in each line is the text to display in Russian. This process is repeated for each language in the top row of the file. You can just have two values in the top row of the file; the ID field, and then the language you want your mission to be available in. However if you want your language to be available in multiple languages you simply add each language to the row, putting a semicolon after each one. The example above shows the first line of a CSV file where the second value on each line is English and the third value is Russian.

It does not matter which order languages are entered in but you must stay consistent throughout the file. If you specify the second value in each row to be English and the third as French, then the second value entered in every row of the file will be considered English by the game; and the third value entered in every row of the file will be considered French; so the text in the second value should always be English, and the text in the third value should always be in French. A full list of valid language identifiers (as of patch 1.75) is shown below.

"<English>"
"<French>"
"<Italian>"
"<German>"
"<Spanish>"
"<Russian>"
"<Polish>"
"<Czech>"
"<Turkish>"
"<Chinese>"
"<Japanese>"
"<Portuguese>"
"<Vietnamese>"
"<Ukrainian>"
"<Serbian>"
"<Hungarian>"
"<Korean>"
"<Belarusian>"
"<TChinese>"
"<HChinese>"
"<Comments>" (used to explain what a line is to someone reading the file, not used by the game).

So to start writing your CSV file, enter the following into the first line of the file (substituting "<English>" for another language if you want):

"<ID|readonly|noverify>";"<English>";

For simplicity, most of this guide will just use a single language, English. However, you can replace "<English>" with one or more of the other languages seen in the list above, when you write the CSV file for your mission. You can add additional languages in the same way "Russian" is present in the first example. For each language, you want to add to the CSV file write its identifier, followed by a semicolon.

Mission objectives, hints, and other mission text

For this guide we will use the example of a mission with these properties:

• The mission has been called "BomberDefencePt1" (the mission name not the file name)
• The mission is in a custom campaign called "BattleOfBritain"
• The mission is in a custom chapter called "BomberDefence"
• The mission has one objective, to destroy a group of enemy bombers
• The Mission has a hint which tells the player the bombers have arrived.

According to the convention, the first thing we will put in the CSV file is the mission objectives. You may wish to enter objectives in the order in which they are given to the player during the mission, to keep the file in a logical order, although this is optional and down to personal preference. To enter a mission objective into the file you type the name you gave it in the editor (in quotation marks), into a new line in the file, and then enter a semicolon after it. You have now entered the first value into the line (the ID, as discussed previously). Now you need to fill in the second value of the line, what you want the objective to appear as in the language you specified for the second value when writing the first line of the file. To do this you simply write what you want the objective to display as (in quotation marks) and put a semicolon after it. The example mission had an objective called "Kill Bombers", and we want it to be displayed in-game as "Destroy the bombers before they bomb the airfield" so we write:

"Kill Bombers";"Destroy the bombers before they bomb the airfield";

In this example, the CSV file only has English specified at the top of the file. If you specified a different then type the objective would need to be written in that language. If you have multiple languages specified then the objective needs to be rewritten in each language; this is done by writing the objective in each language, in the order they were specified, as a new value each time. For example, if you specified English as the second value in each line (the first being the ID) and French as the third value, you would instead write:

"Kill Bombers";"Destroy the bombers before they bomb the airfield";"Détruisez les bombardiers avant qu'ils ne bombardent l'aérodrome";

You would repeat this for each language you want the objective to be displayed in.

Hints and other text (custom vehicle names, loading screen text, etc.) are specified in the same manner. You write what you called it in the editor, followed by how you want it to appear in-game, for each language you specified in the first line of your file. The example mission had a hint called "misHint01" which we would enter it like this:

"misHint01";"Bombers are in the area";

Mission properties

The mission properties are visible when you select the mission from the menu in-game; they were discussed at the start of this article. The main properties you may want to include in the CSV file for the mission are the missions, name, date, objective, and the name of the campaign & chapter it is in (if you have put it in a user-made campaign & chapter, instead of one of the default ones). The first thing we will put in the file is the name. This is done in a similar way to the mission objectives talked about previously.

To enter the name of the mission into the CSV file you need to enter "missions/[Your Mission's Name]" as the first value, followed by how you want the mission to appear in each language. The example mission (called "BomberDefencePt1") would be entered like this:

"missions/BomberDefencePt1";"Defending against German bombers - Part 1";

This will make the mission appear in the mission list as "Defending against German bombers - Part 1".

We can add the date and objective of the mission to the file in a similar manner. The date and objective for the example mission would be added to the CSV file like this:

"missions/BomberDefencePt1/date";"September 1940";
"missions/BomberDefencePt1/objective";"Defend the airfield against enemy bombers";

To add the campaign and chapter of the mission to the file is again a similar process. The campaign (called "BattleOfBritain") and chapter (called "BombersDefence") of the example mission would be added like this;

"campaigns/BattleOfBritain";"The Battle of Britain";
"chapters/BombersDefence";"Defence against German bombers";

These examples have only been using one language, but if you have multiple specified in the first line of your CSV file, then like mission objectives, you add each one on to the line in the order they are specified.

Finished CSV file

So the finished CSV file for the example mission would look like this (with only one language):

"<ID|readonly|noverify>";"<English>";

"Kill Bombers";"Destroy the bombers before they bomb the airfield";

"misHint01";"Bombers are in the area";

"missions/BomberDefencePt1";"Defending against German bombers - Part 1";
"missions/BomberDefencePt1/date";"September 1940";
"missions/BomberDefencePt1/objective";"Defend the airfield against enemy bombers"; 

"campaigns/BattleOfBritain";"The Battle of Britain";
"chapters/BombersDefence";"Defence against German bombers";

And with English, French and German languages it would look like:

"<ID|readonly|noverify>";"<English>";"<French>";"<German>";

"Kill Bombers";"Destroy the bombers before they bomb the airfield";Détruisez les bombardiers avant qu'ils ne bombardent l'aérodrome";"Zerstöre die Bomber, bevor sie den Flugplatz bombardieren";

"misHint01";"Bombers are in the area";"Les bombardiers sont dans la région";"Bomber sind in der Gegend";

"missions/BomberDefencePt1";"Defending against German bombers - Part 1";"Défendre contre les bombardiers allemands - Partie 1";"Verteidigung gegen deutsche Bomber - Teil 1";
"missions/BomberDefencePt1/date";"September 1940";"Septembre 1940";"September 1940";
"missions/BomberDefencePt1/objective";"Defend the airfield against enemy bombers";"Défendre l'aérodrome contre les bombardiers ennemis";"Verteidige den Flugplatz gegen feindliche Bomber";

"campaigns/BattleOfBritain";"The Battle of Britain";"La bataille d'Angleterre";"Die Schlacht von Großbritannien"
"chapters/BombersDefence";"Defence against German bombers";"Défense contre les bombardiers allemands";"Verteidigung gegen deutsche Bomber";

Mission CSV file template

The below template can be copied into your plank CSV files and the parts in square brackets removed and replaced to reflect the actual values for your mission.

"<ID|readonly|noverify>";"<[Language 1]>";"<[Language 2]>";"<[Language 3]>";

"[Mission Objective / Other Text 1]";"[What you want it to say in Language 1]";"[What you want it to say in Language 2]";"[What you want it to say in Language 3]";
"[Mission Objective / Other Text 2]";"[What you want it to say in Language 1]";"[What you want it to say in Language 2]";"[What you want it to say in Language 3]";
"[Mission Objective / Other Text 3]";"[What you want it to say in Language 1]";"[What you want it to say in Language 2]";"[What you want it to say in Language 3]";

"missions/[Your Mission Name]";"[Mission name in Language 1]";"[Mission name in Language 2]";"[Mission name in Language 3]";
"missions/[Your Mission Name]/date";"[Mission date in Language 1]";"[Mission date in Language 2]";"[Mission date in Language 3]";
"missions/[Your Mission Name]/objective";"[Mission objective in Language 1]";"[Mission objective in Language 2]";"[Mission objective in Language 3]";

"campaigns/[Your Campaign Name]";"[Campaign name in Language 1]";"[Campaign name in Language 2]";"[Campaign name in Language 3]";
"chapters/[Your Chapter Name]";"[Chapter name in Language 1]";"[Chapter name in Language 2]";"[Chapter name in Language 3]";

Remember to delete the square brackets themselves when using this template. More mission objectives can be added or deleted. More languages can be added or deleted.

Things to be aware of when making CSV files

There are a few things you should know when making CSV files to avoid issues:

Making changes to CSV files

Unlike mission (.blk) files, the CSV files are not reloaded each time you refresh the mission list or play a mission. They are only loaded when the game starts up or the language is changed. This means you must either restart your game; or change the game's language to a different one and back again; for any changes you make to a CSV file to take effect.

The CSV "Propagation" issue

CSV files do not only affect the mission they are related to. If a mission without a CSV file contains an objective (or other text) which is the same as text defined in another mission's CSV file then the game will replace the text in both missions with the text the CSV file tells it to. To avoid this it is best to name things in missions with CSV files uniquely (so the text will not be the same in another mission) so that they do not "bleed" or "propagate" into other missions. Alternatively, CSV files could be created for other missions to override the CSV file not meant for the mission.

This phenomenon can be used for your benefit though. If multiple missions share common text, which you want to be the same, then you can use a single CSV file which is common to all of the missions, instead of writing the same thing in the CSV files of each mission.

CSV Files for multiplayer missions

Multiplayer user missions (accessed in custom battles) need to be uploaded as just the mission file, so the game has direct access to it. CSV files for these missions can be distributed separately for individual users to install. This is done by simply placing the CSV file in the "UserMissions" folder. If the mission is designed to be used with a CSV file, players without the file can still join but will experience the issues discussed at the start of the article (objectives not displaying properly, etc.)

Using variables

A notable difference with the standard CSV format is that you can refer to variables using {var} (must be var, you can't use multiple different variables), although it is only known to work in the following contexts:

• The playHint action, you need to set the "name" value to the hint's name in the CSV file, and then give the variable you want to display in the "var_name" field. Only Integer variables work, though it is possible to use String variables if their only content is an integer (whole number).

Note: It is also possible to make references to (supposedly) variables or namespaces using "%var_name%" and "%var_name", although it is currently unknown how and where it can be used