Using ESFviaXML to Unpack Startpos and Save Games into Text Files
This tutorial will explain how to convert *.esf files (startpos, save games) to xml files. The purpose of this method is to open up editing options of *.esf files and allow for more access to the structure and/or content. I didn't create any of the tools here, I am simply explaining how to go about installation and usage of them. Warning - this tutorial assumes some modding knowledge and is mainly for advanced users.
Reasons to use XML conversion
For most of your basic startpos editing, you can simply use EditSF without any issue. The XML method allows for access to the content in text documents. Some reasons you would want to use this method include:
1. Converting a save game file into a startpos.
2. Mass editing of specific content, such as unit sizes, unit ID entries, etc.
3. Insertion of content/structures not present in the esf file. For example, a Chapter Mission Array in a Faction Array. Or, missing Victory Conditions (back when that was a problem in the assembly kit)
4. Easier editing/insertion of content in general.
Installation of ESF via XML
1. Download the following file - https://github.com/taw/etwng
2. Create a new folder directory named d:\modding\ESFviaXML and unzip the etwng-master folder into that directory.
3. Install Jruby - http://jruby.org/. Make sure to check that jruby is active through the cmd prompt (Type jruby -version). You may need to restart your computer after this to have it fully in effect.
4. Install the nokogiri gem by using the following command - "jgem install nokogiri --pre". Once again, you may need to restart your computer.
5. Create 2 new text documents in the following folder - D:\modding\ESFviaXML\etwng-master\esfxml
6. The first text document will be named UnpackESF.ps1 (make sure that is its file name, no .txt). Put the following in that file:
*Change the drive number or directory structure if you did not install ESFviaXML to d:\moddingCode:$esfdir = "d:\modding\ESFviaXML" $esfname = "\startpos.esf" $esfxmldir = "d:\modding\ESFviaXML\etwng-master\esfxml" $tempdir = "d:\modding\ESFviaXML\startpos" $currpwd = pwd cd $esfxmldir jruby --server $esfxmldir\esf2xml $esfdir$esfname $tempdir\xml .\lzma d $tempdir\xml\compressed_data.esf.xz $tempdir\xml\compressed_data.esf rm $tempdir\xml\compressed_data.esf.xz jruby --server .\esf2xml $tempdir\xml\compressed_data.esf $tempdir\xml\compressed_data rm $tempdir\xml\compressed_data.esf cd $currpwd
7. The second text document will be named PackESF.ps1. Put the following in this file:
*Change the drive number or directory structure if you did not install ESFviaXML to d:\moddingCode:$esfdir = "d:\modding\ESFviaXML" $esfname = "\startposnew.esf" $esfxmldir = "d:\modding\ESFviaXML\etwng-master\esfxml" $tempdir = "d:\modding\ESFviaXML\startpos" $currpwd = pwd cd $esfxmldir cp -r $tempdir\xml $tempdir\packdir jruby --server .\xml2esf $tempdir\packdir\compressed_data $tempdir\packdir\compressed_data.esf rm -r $tempdir\packdir\compressed_data\ .\lzma e $tempdir\packdir\compressed_data.esf $tempdir\packdir\compressed_data.esf.xz rm $tempdir\packdir\compressed_data.esf jruby --server .\xml2esf $tempdir\packdir $esfdir$esfname rm -r $tempdir\packdir cd $currpwd
Using ESFviaXML
*For the purposes of this tutorial, I will assume you have installed the tool into D:\modding\ESFviaXML\etwng-master\. If your directory structure is different, then use that structure instead of the one I will be listing.
1. Find the startpos or save game you want to edit. Copy that over to D:\modding\ESFviaXML.
2. Make sure your script files (UnpackESF.ps1) are referencing that startpos name. Change it if the file is named differently. To be clear, here is what the script entries are referring to:
$esfdir = The base directory you unzipped the etwng-master folder into
$esfname = The name of the startpos or save file that you placed into that directory
$esfxmldir = The name of the directory that the esfviaxml tool itself is in
$tempdir = The temporary directory that will house the unpacked esf files to edit
3. Open Windows Powershell as an administrator.
4. First, type set-executionpolicy unrestricted. This will allow for the running of scripts.
5. Navigate to your ESFviaXML directory by typing d: . Then, type cd D:\modding\ESFviaXML\etwng-master\esfxml
4. Now that you are in the folder D:\modding\ESFviaXML\etwng-master\esfxml, type ./unpackesf.ps1 to run the unpack script.
5. The script should take some time to unpack, it will list a few errors but should work properly. If you see red text, then something has gone wrong. Common problems are mispelled directories/files or improper installation of jruby and nokogiri.
6. Once the unpack script runs, go to D:\modding\ESFviaXML\startpos . Here you will find your unpacked startpos to edit. Most of the data can be found under /xml/compressed_data.
7. After you are done editing the text files, go back to the same location in Powershell. Type ./packesf.ps1 to run the repack script. This should repack your startpos into a new one named "startposnew.esf" or whatever name you chose in the script.
8. Make sure to type set-executionpolicy restricted once you are done. This will make sure you don't open your computer up to security risk.
Various Uses and Random Tips
- You can use this method to turn a save game into a startpos. This is how I created most of my early scenario/startpos mods before there was an assembly kit. To do this, you simply have to unpack the save file and a basic startpos. Then, copy over the save_game_header and preopen_map_info folders. Then, repack it as a startpos. It should function properly. Some problems may arise, however, from this method.
- Inserting chapter mission or other startpos structure entries into factions or areas that don't have them in an existing startpos. The easiest way to do this is to have an unpacked vanilla startpos to use. You can simply find the entry you want and carefully place it in the corresponding area of the missing entry.
- Making changes to these files can cause problems when re-packing. If you get a smaller startpos (by a lot, not a few bytes), there has been a problem. Make sure you always look for what you are replacing or inserting and check the <rec></rec> or other tags.
- Mass editing of some entries is the most useful thing this tool can accomplish. For example, if you want to change all units that are 120 in size to 160. Simply open all the /army/ text files and do a mass search for <u>120</u>. Find/replace all with <u>160</u>.
- Notepad ++ is by far the best way to edit these files.
Special Thanks
I learned this method from many modders coming together right after Rome 2's release in efforts to figure out how to change region ownership. Before the assembly kit, it was a major problem. Styrry really helped in that regard (and many others) as can be seen in this thread - http://www.twcenter.net/forums/showt...rovinces/page7
Reply With Quote
Not jruby console...command is still working
Originally Posted by Palaiogos
