Basic Modding Primer - Adding New Units
Posted: Tue Aug 13, 2013 5:13 pm
Some time ago Calvinus increased the maximum number of Units available in WW1G, which opened the door to adding new units to the available force pool of all Nations. I am certainly grateful for this small change, something that made my Naval Mod possible and allows us to tinker and explore the potential of this game. Having obtained the permission of PhilThib, Pocus and Calvinus to post a tutorial on modding WW1G, I would like to thank them for taking the time to answer my questions and give their approval but must stress that all errors of commission and or omission that follow belong solely to me.
In this primer we will add a new Naval Unit to the Grand Campaign, the small Russian Pacific Fleet, based in Vladivostok.
Historically the Russian cruisers Askold and Zhemchug represented Russia outside of domestic waters and were active in hunting the German high-seas raiders. Or vice-versa as Zhemchug was sunk at anchor in Penang harbour by SMS Emden on 28 October 1914.
Adding new units in WW1G is relatively straightforward but there are some potential pitfalls that the Modder should be aware of. We will be editing several files, it is always best and cannot be overstressed that your save the original files some place safe. I will be editing files from my GC Naval Mod but this works as well with stock. If you are editing files that are part of a Mod enabled with JSGME, make sure that you roll back the mod before editing the files.
The following files will be edited and I will briefly comment on each one and where to find it. The *.csv format makes identifying what the values mean difficult so I would recommend that if you're just starting out modding WW1G, you might also have a look at the *.xls versions of the game files found in the ...\Modding folder of the main ...\World War One Gold folder.
[color="#00FF00"]...\DB\Units.csv[/color] - This file is used by all scenarios at the start of a new game and it is where all of the characteristics of the units are defined. Unit characteristics are written onto the *.SAV file when a scenario is saved so changes to the Units.csv file may not affect saved games and this should be kept in mind when testing your mods. This file seems to load from the top down so an error in syntax or punctuation may not crash the game but may result in every unit below the error not loading and so vanishing from your game. This can be somewhat disconcerting when first it happens.
[color="#00FF00"]...\GoldScenarios\GrandCampaignTwo\Detachments.csv[/color] - This file is used to define the unit that will appear on the map at the start of the scenario. Here the unit will receive its unique name, numerical ID designator and deployment location. It is vital that the numerical ID designator is absolutely unique as duplicate ID numbers can cause all sorts of mischief when you try to run the game.
[color="#00FF00"]...\GrandCampaignTwo\Fleets.csv[/color] - In WW1G, all ship units live in Fleets and those are defined in this file. Land units and Headquarters of both types are defined in the Detachments.csv file.
[color="#00FF00"]...\GrandCampaignTwo\Nations.csv[/color] - This is where all of the characteristics of all the countries in WW1G are found. It is where the numerical ID of all the defined armies, detachments and fleets are entered to so that they will appear on the map when the scenario is loaded.
DEFINING A UNIT
An entry for a naval unit, in this case the light cruiser (CL) unit Aurora from the Russian Baltic Fleet, looks something like below. Find this entry, a word search for Aurora should work to facilitate this.
[color="#00FF00"]RUS_CL_Aurora;-;-;Aurora;UT_NavalSquadron;RUS;43;0;-;NE_Slavic;-;-;-;-;NST_LightCruisers;-;-;-;3;-;-;-;2;1;1;-;-;-;-;1;1;4;4;RT_ShortRange;RT_ShortRange;"Aurora;Bogatyr;Oleg;Diana;Svetlana";0[/color]
If you want to know what the numbers mean see the Units.xls in the Modding folder. For our purposes we should note some of the features of this Unit.
Please note the following.
[color="#00FF00"]RUS[color="#FF0000"]_[/color]CL[color="#FF0000"]_[/color]Aurora[/color] - It is essential to retain or insert underscore where they appear ([color="#FF0000"]_[/color]) and not dashes (-)
Colons ([color="#FF0000"]:[/color]) cannot be used, the *.csv format requires semi-colons ([color="#FF0000"];[/color])
Dashes ([color="#FF0000"]-[/color]) are used as place-holders since the same format is used to define all types of units.
I have found it best to copy and edit an existing entry rather than creating one from scratch. There is actually an error in the Aurora unit; the cruiser Svetlana had been sunk in 1905 and so did not exist in 1914. We can correct this now by removing here so our new entry will read:
[color="#00FF00"]RUS_CL_Aurora;-;-;Aurora;UT_NavalSquadron;RUS;43;0;-;NE_Slavic;-;-;-;-;NST_LightCruisers;-;-;-;3;-;-;-;2;1;1;-;-;-;-;1;1;4;4;RT_ShortRange;RT_ShortRange;"Aurora;Bogatyr;Oleg;Diana";0[/color]
Copy the entry for Aurora and paste it directly below its current location taking care that it is inserted into a new line rather than overwriting any existing text. Your Units.csv should now resemble this:
[color="#00FF00"]RUS_CL_Aurora;-;-;Aurora;UT_NavalSquadron;RUS;43;0;-;NE_Slavic;-;-;-;-;NST_LightCruisers;-;-;-;3;-;-;-;2;1;1;-;-;-;-;1;1;4;4;RT_ShortRange;RT_ShortRange;"Aurora;Bogatyr;Oleg;Diana";0[/color]
[color="#FFD700"]RUS_CL_Aurora;-;-;Aurora;UT_NavalSquadron;RUS;43;0;-;NE_Slavic;-;-;-;-;NST_LightCruisers;-;-;-;3;-;-;-;2;1;1;-;-;-;-;1;1;4;4;RT_ShortRange;RT_ShortRange;"Aurora;Bogatyr;Oleg;Diana";0[/color]
Now we can proceed to define our new unit, which we will call Askold and the changes are noted in [color="#FF0000"]RED[/color].
[color="#FFD700"]RUS_CL_[color="#FF0000"]Askold[/color];-;-;[color="#FF0000"]Askold[/color];UT_NavalSquadron;RUS;43;0;-;NE_Slavic;-;-;-;-;NST_LightCruisers;-;-;-;[color="#FF0000"]2[/color];-;-;-;2;1;1;-;-;-;-;1;1;[color="#FF0000"]4+[/color];4;RT_ShortRange;RT_ShortRange;"[color="#FF0000"]Askold;Zhemtchug[/color]";0[/color]
Save and close, the new unit has now been defined.
Open the Detachments.csv and find the entry below. Here we define where our new unit will live. Note that the Black Sea Fleet is defined by two ID numbers, the detachment itself is ID = 599041 and the Fleet ID = 599040.
[color="#00FF00"];RUS_Black_Sea;599041;Black Sea;DT_NavalDetachment;RUS;LDS_Static;;599040;;;SEVASTOPOL;"{RUS_SS_Akula;0;0;0}";;0;0;0;0;0;0;0;0;0;0;0;0;;;;;;;;;;;;;;;;;[/color]
We will now add the entry for the Pacific Fleet using copy-paste similar to in the Units.csv file. The new entry that is inserted below the Black Sea Fleet line should read:
[color="#FFD700"];RUS_[color="#FF0000"]Pacific;599051;Pacific[/color];DT_NavalDetachment;RUS;LDS_Static;;[color="#FF0000"]599050[/color];;;[color="#FF0000"]SIBERIA_EAST_BOX[/color];"[color="#FF0000"]{RUS_CL_Askold;0;0;0}[/color]";;0;0;0;0;0;0;0;0;0;0;0;0;0;;;;;;;;;;;;;;;;[/color]
Note that we the new ID is sequential as 599050 follows 599040 and 599051 is a unit of the new detachment and the deployment area is the SIBERIA_EAST_BOX retaining the underscores (_) found in the ...\GoldMaps\GrandCampaign\MapAreas.csv file.
Save and close, the new Detachment has been defined.
Now we need to add the Fleet where the new Detachment will live so open the Fleets.csv. We already have the unique ID for our new Fleet (599050) and its detachment (599051) so we can insert it directly below the Black Sea Fleet where the new Pacific Fleet becomes Russian F05:
[color="#00FF00"];599050;RUS_F05;Pacific;RUS;5;599051;;0;2;3[/color]
[color="#FF0000"];0;2;3[/color] = Cost 0;Maximum 2 Battleships;Maximum 3 ship detachments. You may set these values to taste.
Save and close, you are almost done.
Now we must include our new Fleet into the OOB of Russia by entering the unique ID in the Nations.csv file. The Nations.csv file is complex so having the easier to read Nations.xls for the scenario is handy. Open the file and find the paragraph for Russia. It looks like this with the Fleets shown in [color="#00FF00"]Green.[/color]
[color="#FFD700"]2015;RUS;1;[IDS_RUS];40;NE_Slavic;"PETROGRAD;MOSCOW";0;PS_Allies;1;NPA_SacredUnion;NWD_MovementDoctrine;GR_Autocracy;30;6;15;6;RUS_WP_Grand Duke;0;0;0;0;0;-;;0;1;"0;0;0";"0;1";"501000;502000;503000;504000;505000;506000;507000;508000;509000;510000;511000;512000;513000";[color="#00FF00"]"599010;599020;599030;599040"[/color];"500111;550027;550028;550029;550030";"RUS_L01;RUS_L02;RUS_L04;RUS_L06;RUS_L08;RUS_L09;RUS_L12;RUS_L14;RUS_L15;RUS_L16";"566010;566020;566030;566040;566050;566060;566070;566080;566090;566100;566110;566120;566130;566140;566150;566160;566170;566180";"3217;3218;3219;3220;3221;3222;3223;3224";"3411;3412;3413;3414;3415";;;"2268;2269;2270;2271;2272;2273;2274";"171;79;17";"20;5";IMG_MAP_RUSSIANS[/color]
It is essential that the unique ID for the new Leader, Fleet or Detachment be correctly added to this file otherwise it will not appear on the map when the game is run. We add the Pacific Fleet ID 599050 sequentially to the Fleet entries taking care to ensure that the text remains inside the quotation marks ("") as follows.
[color="#FFD700"]2015;RUS;1;[IDS_RUS];40;NE_Slavic;"PETROGRAD;MOSCOW";0;PS_Allies;1;NPA_SacredUnion;NWD_MovementDoctrine;GR_Autocracy;30;6;15;6;RUS_WP_Grand Duke;0;0;0;0;0;-;;0;1;"0;0;0";"0;1";"501000;502000;503000;504000;505000;506000;507000;508000;509000;510000;511000;512000;513000";[color="#00FF00"]"599010;599020;599030;599040;[/color][color="#FF0000"]599050"[/color];"500111;550027;550028;550029;550030";"RUS_L01;RUS_L02;RUS_L04;RUS_L06;RUS_L08;RUS_L09;RUS_L12;RUS_L14;RUS_L15;RUS_L16";"566010;566020;566030;566040;566050;566060;566070;566080;566090;566100;566110;566120;566130;566140;566150;566160;566170;566180";"3217;3218;3219;3220;3221;3222;3223;3224";"3411;3412;3413;3414;3415";;;"2268;2269;2270;2271;2272;2273;2274";"171;79;17";"20;5";IMG_MAP_RUSSIANS[/color]
Save and close. You're done.
Now start a new Two-Player Grand Campaign and the Russian Pacific Fleet consisting of the CL's Askold and Novik will start in the port of Vladivostok ready to hunt German raiders in the Pacific Ocean.
[ATTACH]23659[/ATTACH]
You can copy the files over to the Four-Player Grand Campaign, overwriting the originals and all should be well.
Thanks for reading and keeping this game alive, I am happy to help if I can should anyone need it and good luck modding WW1G
-C
In this primer we will add a new Naval Unit to the Grand Campaign, the small Russian Pacific Fleet, based in Vladivostok.
Historically the Russian cruisers Askold and Zhemchug represented Russia outside of domestic waters and were active in hunting the German high-seas raiders. Or vice-versa as Zhemchug was sunk at anchor in Penang harbour by SMS Emden on 28 October 1914.
Adding new units in WW1G is relatively straightforward but there are some potential pitfalls that the Modder should be aware of. We will be editing several files, it is always best and cannot be overstressed that your save the original files some place safe. I will be editing files from my GC Naval Mod but this works as well with stock. If you are editing files that are part of a Mod enabled with JSGME, make sure that you roll back the mod before editing the files.
The following files will be edited and I will briefly comment on each one and where to find it. The *.csv format makes identifying what the values mean difficult so I would recommend that if you're just starting out modding WW1G, you might also have a look at the *.xls versions of the game files found in the ...\Modding folder of the main ...\World War One Gold folder.
[color="#00FF00"]...\DB\Units.csv[/color] - This file is used by all scenarios at the start of a new game and it is where all of the characteristics of the units are defined. Unit characteristics are written onto the *.SAV file when a scenario is saved so changes to the Units.csv file may not affect saved games and this should be kept in mind when testing your mods. This file seems to load from the top down so an error in syntax or punctuation may not crash the game but may result in every unit below the error not loading and so vanishing from your game. This can be somewhat disconcerting when first it happens.
[color="#00FF00"]...\GoldScenarios\GrandCampaignTwo\Detachments.csv[/color] - This file is used to define the unit that will appear on the map at the start of the scenario. Here the unit will receive its unique name, numerical ID designator and deployment location. It is vital that the numerical ID designator is absolutely unique as duplicate ID numbers can cause all sorts of mischief when you try to run the game.
[color="#00FF00"]...\GrandCampaignTwo\Fleets.csv[/color] - In WW1G, all ship units live in Fleets and those are defined in this file. Land units and Headquarters of both types are defined in the Detachments.csv file.
[color="#00FF00"]...\GrandCampaignTwo\Nations.csv[/color] - This is where all of the characteristics of all the countries in WW1G are found. It is where the numerical ID of all the defined armies, detachments and fleets are entered to so that they will appear on the map when the scenario is loaded.
DEFINING A UNIT
An entry for a naval unit, in this case the light cruiser (CL) unit Aurora from the Russian Baltic Fleet, looks something like below. Find this entry, a word search for Aurora should work to facilitate this.
[color="#00FF00"]RUS_CL_Aurora;-;-;Aurora;UT_NavalSquadron;RUS;43;0;-;NE_Slavic;-;-;-;-;NST_LightCruisers;-;-;-;3;-;-;-;2;1;1;-;-;-;-;1;1;4;4;RT_ShortRange;RT_ShortRange;"Aurora;Bogatyr;Oleg;Diana;Svetlana";0[/color]
If you want to know what the numbers mean see the Units.xls in the Modding folder. For our purposes we should note some of the features of this Unit.
Please note the following.
[color="#00FF00"]RUS[color="#FF0000"]_[/color]CL[color="#FF0000"]_[/color]Aurora[/color] - It is essential to retain or insert underscore where they appear ([color="#FF0000"]_[/color]) and not dashes (-)
Colons ([color="#FF0000"]:[/color]) cannot be used, the *.csv format requires semi-colons ([color="#FF0000"];[/color])
Dashes ([color="#FF0000"]-[/color]) are used as place-holders since the same format is used to define all types of units.
I have found it best to copy and edit an existing entry rather than creating one from scratch. There is actually an error in the Aurora unit; the cruiser Svetlana had been sunk in 1905 and so did not exist in 1914. We can correct this now by removing here so our new entry will read:
[color="#00FF00"]RUS_CL_Aurora;-;-;Aurora;UT_NavalSquadron;RUS;43;0;-;NE_Slavic;-;-;-;-;NST_LightCruisers;-;-;-;3;-;-;-;2;1;1;-;-;-;-;1;1;4;4;RT_ShortRange;RT_ShortRange;"Aurora;Bogatyr;Oleg;Diana";0[/color]
Copy the entry for Aurora and paste it directly below its current location taking care that it is inserted into a new line rather than overwriting any existing text. Your Units.csv should now resemble this:
[color="#00FF00"]RUS_CL_Aurora;-;-;Aurora;UT_NavalSquadron;RUS;43;0;-;NE_Slavic;-;-;-;-;NST_LightCruisers;-;-;-;3;-;-;-;2;1;1;-;-;-;-;1;1;4;4;RT_ShortRange;RT_ShortRange;"Aurora;Bogatyr;Oleg;Diana";0[/color]
[color="#FFD700"]RUS_CL_Aurora;-;-;Aurora;UT_NavalSquadron;RUS;43;0;-;NE_Slavic;-;-;-;-;NST_LightCruisers;-;-;-;3;-;-;-;2;1;1;-;-;-;-;1;1;4;4;RT_ShortRange;RT_ShortRange;"Aurora;Bogatyr;Oleg;Diana";0[/color]
Now we can proceed to define our new unit, which we will call Askold and the changes are noted in [color="#FF0000"]RED[/color].
[color="#FFD700"]RUS_CL_[color="#FF0000"]Askold[/color];-;-;[color="#FF0000"]Askold[/color];UT_NavalSquadron;RUS;43;0;-;NE_Slavic;-;-;-;-;NST_LightCruisers;-;-;-;[color="#FF0000"]2[/color];-;-;-;2;1;1;-;-;-;-;1;1;[color="#FF0000"]4+[/color];4;RT_ShortRange;RT_ShortRange;"[color="#FF0000"]Askold;Zhemtchug[/color]";0[/color]
Save and close, the new unit has now been defined.
Open the Detachments.csv and find the entry below. Here we define where our new unit will live. Note that the Black Sea Fleet is defined by two ID numbers, the detachment itself is ID = 599041 and the Fleet ID = 599040.
[color="#00FF00"];RUS_Black_Sea;599041;Black Sea;DT_NavalDetachment;RUS;LDS_Static;;599040;;;SEVASTOPOL;"{RUS_SS_Akula;0;0;0}";;0;0;0;0;0;0;0;0;0;0;0;0;;;;;;;;;;;;;;;;;[/color]
We will now add the entry for the Pacific Fleet using copy-paste similar to in the Units.csv file. The new entry that is inserted below the Black Sea Fleet line should read:
[color="#FFD700"];RUS_[color="#FF0000"]Pacific;599051;Pacific[/color];DT_NavalDetachment;RUS;LDS_Static;;[color="#FF0000"]599050[/color];;;[color="#FF0000"]SIBERIA_EAST_BOX[/color];"[color="#FF0000"]{RUS_CL_Askold;0;0;0}[/color]";;0;0;0;0;0;0;0;0;0;0;0;0;0;;;;;;;;;;;;;;;;[/color]
Note that we the new ID is sequential as 599050 follows 599040 and 599051 is a unit of the new detachment and the deployment area is the SIBERIA_EAST_BOX retaining the underscores (_) found in the ...\GoldMaps\GrandCampaign\MapAreas.csv file.
Save and close, the new Detachment has been defined.
Now we need to add the Fleet where the new Detachment will live so open the Fleets.csv. We already have the unique ID for our new Fleet (599050) and its detachment (599051) so we can insert it directly below the Black Sea Fleet where the new Pacific Fleet becomes Russian F05:
[color="#00FF00"];599050;RUS_F05;Pacific;RUS;5;599051;;0;2;3[/color]
[color="#FF0000"];0;2;3[/color] = Cost 0;Maximum 2 Battleships;Maximum 3 ship detachments. You may set these values to taste.
Save and close, you are almost done.
Now we must include our new Fleet into the OOB of Russia by entering the unique ID in the Nations.csv file. The Nations.csv file is complex so having the easier to read Nations.xls for the scenario is handy. Open the file and find the paragraph for Russia. It looks like this with the Fleets shown in [color="#00FF00"]Green.[/color]
[color="#FFD700"]2015;RUS;1;[IDS_RUS];40;NE_Slavic;"PETROGRAD;MOSCOW";0;PS_Allies;1;NPA_SacredUnion;NWD_MovementDoctrine;GR_Autocracy;30;6;15;6;RUS_WP_Grand Duke;0;0;0;0;0;-;;0;1;"0;0;0";"0;1";"501000;502000;503000;504000;505000;506000;507000;508000;509000;510000;511000;512000;513000";[color="#00FF00"]"599010;599020;599030;599040"[/color];"500111;550027;550028;550029;550030";"RUS_L01;RUS_L02;RUS_L04;RUS_L06;RUS_L08;RUS_L09;RUS_L12;RUS_L14;RUS_L15;RUS_L16";"566010;566020;566030;566040;566050;566060;566070;566080;566090;566100;566110;566120;566130;566140;566150;566160;566170;566180";"3217;3218;3219;3220;3221;3222;3223;3224";"3411;3412;3413;3414;3415";;;"2268;2269;2270;2271;2272;2273;2274";"171;79;17";"20;5";IMG_MAP_RUSSIANS[/color]
It is essential that the unique ID for the new Leader, Fleet or Detachment be correctly added to this file otherwise it will not appear on the map when the game is run. We add the Pacific Fleet ID 599050 sequentially to the Fleet entries taking care to ensure that the text remains inside the quotation marks ("") as follows.
[color="#FFD700"]2015;RUS;1;[IDS_RUS];40;NE_Slavic;"PETROGRAD;MOSCOW";0;PS_Allies;1;NPA_SacredUnion;NWD_MovementDoctrine;GR_Autocracy;30;6;15;6;RUS_WP_Grand Duke;0;0;0;0;0;-;;0;1;"0;0;0";"0;1";"501000;502000;503000;504000;505000;506000;507000;508000;509000;510000;511000;512000;513000";[color="#00FF00"]"599010;599020;599030;599040;[/color][color="#FF0000"]599050"[/color];"500111;550027;550028;550029;550030";"RUS_L01;RUS_L02;RUS_L04;RUS_L06;RUS_L08;RUS_L09;RUS_L12;RUS_L14;RUS_L15;RUS_L16";"566010;566020;566030;566040;566050;566060;566070;566080;566090;566100;566110;566120;566130;566140;566150;566160;566170;566180";"3217;3218;3219;3220;3221;3222;3223;3224";"3411;3412;3413;3414;3415";;;"2268;2269;2270;2271;2272;2273;2274";"171;79;17";"20;5";IMG_MAP_RUSSIANS[/color]
Save and close. You're done.
Now start a new Two-Player Grand Campaign and the Russian Pacific Fleet consisting of the CL's Askold and Novik will start in the port of Vladivostok ready to hunt German raiders in the Pacific Ocean.
[ATTACH]23659[/ATTACH]
You can copy the files over to the Four-Player Grand Campaign, overwriting the originals and all should be well.
Thanks for reading and keeping this game alive, I am happy to help if I can should anyone need it and good luck modding WW1G
-C