World of Tanks: Mod Packages
version 0.4, 2017-05-04
Anton Bobrov, Wargaming.net
Mikhail Paulyshka, XVM teamAndrey Andruschyshyn, Independent
Koreanrandom.com community
License: CC BY-SA 4.0

1. General Information
A package is a method of arranging modiﬁcation ﬁles. According to the method, all content of a particular
modiﬁcation is packed into a single ﬁle.
In case of using the old ﬁle distribution scheme, modiﬁcations are installed into the following folder<WoT_game_folder>/res_mods/<WoT_version>/ . According to this scheme, ﬁles of diﬀerent modiﬁcations arelocated in the same folders, thus it is rather diﬃcult to ﬁnd ﬁles of a particular modiﬁcation.
The package method will make arrangement of modiﬁcation ﬁles far less complicated: to install a
modiﬁcation, a player simply needs to copy a package to the folder <WoT_game_folder>/mods/<WoT_version>/ , or remove the same ﬁle to uninstall the modiﬁcation.

2. Package Structure
A package is a zip-archive with the following features:no compression
extension: .wotmod
the maximum archive size: 2 Gb - 1 byte (2 147 483 647 bytes)
NOTE: compressed archives are not supported in the current version of World of Tanks, thus set thecompression level to “without compression” when creating archives.
NOTE: 2 Gb archives and larger are not supported in the current version of World of Tanks, thus they shouldbe split into archives smaller than 2 Gb - 1 byte.
A package contains the following:
required: the /res/ folder. A modiﬁcation content is located in this folder, i.e., the very ﬁles that used
to be installed in the following folder: < WoT_game_folder>/res_mods/<WoT_version>
optional: utility ﬁle meta.xml (view section 5)
optional: ﬁle LICENSE containing a license agreement
optional: any other content that a modiﬁcation developer might need: link to the modiﬁcation web
page, documents, change list, etc.
Example of a package structure:/package.wotmod/meta.xml/README.md/LICENSE/res/scripts/client/gui/mods/mod_example.pyc

3. Installing a Package
Packages are to be installed in the following folder: <WoT_game_folder>/mods/<WoT_version> . They can either
be copied manually, or installed via a special installer ﬁle that contains a particular modiﬁcation or a pack of
modiﬁcations.
If required, packages can be split into sub-folders, which allows developers to arrange ﬁles in particulargroups:mods/
0.9.17.1/
MultiHitLog_2.8.wotmod
DamagePanel/
Some_common_library_3.14.5.wotmod
DamagePanel_2.6.wotmod
DamagePanel_2.8.wotmod
DamagePanel_2.8_patch1.wotmod

4. Recommendations on Naming Packages
We recommend the following scheme of naming a package (hereinafter package_id ):package_id = author_id.mod_id

Where:
author_id : a developer identiﬁer. It can be either a developer’s web site ( com.example ) or thedeveloper’s nickname ( noname )mod_id : a modiﬁcation identiﬁer. It is selected at developer’s discretion.

This name is used in the meta.xml ﬁle (view section 5) and as a part of the package ﬁle name.
Example of package names:com.example.coolmod
noname.supermodA ﬁle name is formed in the following way:<author_id>.<mod_id>_<mod_version>.wotmod

Where:
mod_version : modiﬁcation version, set by the modiﬁcation developer in meta.xml (view section 5).

Examples:com.example.coolmod_0.1.wotmod
noname.supermod_0.2.8.wotmod

5. Metadata File meta.xml
The meta.xml optional ﬁle contains special ﬁelds for describing a modiﬁcation.
Example:<root><!‐‐ Package identifier ‐‐><id>noname.crosshair</id><!‐‐ Package version ‐‐><version>0.2.8</version><!‐‐ Package name clear for players ‐‐><name>Crosshair</name><!‐‐ Package description ‐‐><description>New cool Crosshair with feature1.....N</description></root>Values speciﬁed in the <id> and <version> ﬁelds are used for determining the order of loading packages.
Values speciﬁed in the <name> and <description> ﬁelds will subsequently be used in the modiﬁcation
management system.

6. Loading Packages
6.1 Order of Loading
All packages located in the <WoT_game_folder>/mods/<WoT_version>/ folder are sorted by the <id> node
value speciﬁed in the meta.xml ﬁle and are loaded according to this order. If the meta.xml ﬁle is missing,the ﬁle name will be used as the package identiﬁer.
The load_order.xml ﬁle can be used for changing the order of loading. It should be located in theabovementioned folder.
If all packages are speciﬁed in the load_order.xml ﬁle, they are loaded according to the order set in the ﬁle.

If some packages are not speciﬁed in the load_order.xml ﬁle, packages speciﬁed in load_order.xml areloaded ﬁrst. The rest of the packages are loaded in alphabetical order.

6.2 Using Packages Together with the res_mods Folder
From the point of the game client, the virtual system root is formed of:/res_mods/<WoT_version>/mods/<WoT_version>/<package_name>.wotmod/res//res/packages/*.pkg//res/

Other locations speciﬁed in the <WoT_game_folder>/paths.xml ﬁleThese paths are listed descending by priority. I.e., ﬁles located in the /res_mods/<WoT_version>/ folder havehigher priority regardless of the load_order.xml ﬁle.

6.3 Resolving Conﬂicts that Occur upon Loading
Generally, the package method does allow a situation, when identical ﬁles are located within diﬀerent
packages in the res/ folder. Such situations are considered to be conﬂicts.
If a conﬂict is detected, the conﬂicted package is not loaded, a corresponding is displayed to the user.
In other words, if both packages a.wotmod and b.wotmod contain the res/scripts/entities.xml ﬁle, thea.wotmod package will be loaded successfully, while the b.wotmod package will cause a conﬂict and thus will

not be loaded.
Use the following to handle conﬂicts:
1. The load_order.xml ﬁle
The load_order.xml ﬁle should be located in the following folder: <WoT_game_folder>/mods/<WoT_version>/ .
It is formed in the following way:<root><Collection><pkg>package1_name.wotmod</pkg><pkg>package2_name.wotmod</pkg><!‐‐ ... ‐‐><pkg>packageN_name.wotmod</pkg></Collection></root>Packages speciﬁed in this ﬁle are not regarded as conﬂicts. They are loaded without checking for identicalnames. A package ﬁle speciﬁed at the end has the highest priority.
2. Values of the <id> and <version> nodes from meta.xml
If the <id> node is speciﬁed in the meta.xml ﬁle, names of package ﬁles are not considered in the loading
order. Packages that have identical <id> values, are regarded as diﬀerent versions or parts of one
modiﬁcation. Conﬂicts between such elements are not considered. They are loaded in the version order(versions are speciﬁed in the <version> node).

Packages versions are compared by characters according to the ASCII table. The behavior is similar to thebehavior of the following function: strcmp():version 9.0.0 has a higher priority than version 10.0.0 ;version b has a higher priority than version B ;version c<any characters> has a higher priority than version c ;if versions are identical, packages are loaded in the alphabetical order.

If diﬀerent packages contain ﬁles with identical names, and the conﬂicts they cause are resolved with theload_order.xml or meta.xml ﬁles, the ﬁle from the most recently added package has a higher priority.

6.4 Executing Python CodeAfter adding all packages and resolving conﬂicts, all .pyc ﬁles with names starting from mod_ located the/scripts/client/gui/mods/ folder are executed in alphabetical order.

Within a package, this ﬁle should be located here:<author_id>.<mod_id>_<version>.wotmod/res/scripts/client/gui/mods/mod_<anything>.pyc

7. Recommended Paths for Modiﬁcation Files
7.1 Conﬁguration Files
Modiﬁcation conﬁguration ﬁles are recommended to be located here:<WoT_game_foler>/mods/configs/<author_id>.<mod_id>/Where:
author_id и mod_id - identiﬁers described in section 4 of this document.

7.2 Log Files
Apart from the python.log standard ﬁle, it is recommended to use the following path:<WoT_game_folder>/mods/logs/<author_id>.<mod_id>/

Where:
author_id и mod_id - identiﬁers described in section 4 of this document.

7.3 Temporary Files
Temporary ﬁles are recommended to be located here:<temp>/world_of_tanks/<author_id>.<mod_id>/

Where:
temp - path to a folder containing temporary ﬁles for a current user in the OS;
author_id и mod_id - identiﬁers described in section 4 of this document.

7.4 Other Modiﬁcation Files
Use the following path to store content that should be accessible in the game client:<package_name>.wotmod/res/mods/<author_id>.<mod_id>/

Where:
author_id и mod_id - identiﬁers described in section 4 of this document.

8. Working with Files within Packages
Use the ResMgr module for working with ﬁles within packages.

8.1 Standard Operations
8.1.1 Reading a File from a Package#importimport ResMgr#function
def read_file(vfs_path, read_as_binary=True):
vfs_file = ResMgr.openSection(vfs_path)if vfs_file is not None and ResMgr.isFile(vfs_path):
if read_as_binary:
return str(vfs_file.asBinary)
else:
return str(vfs_file.asString)
return None
#examplemyscript = read_file('scripts/client/gui/mods/mod_mycoolmod.pyc')

8.1.2 Obtaining a List of Elements in a Folder

#import
import ResMgr#function
def list_directory(vfs_directory):
result = []folder = ResMgr.openSection(vfs_directory)
if folder is not None and ResMgr.isDir(vfs_directory):
for name in folder.keys():if name not in result:result.append(name)return sorted(result)#example
content = list_directory('scripts/client/gui/mods/')

8.1.3 Copying a File from a Package to a Folder#importimport os
import ResMgr#function
def file_copy(vfs_from, realfs_to)
realfs_directory = os.path.dirname(realfs_to)
if not os.path.exists(realfs_directory):os.makedirs(realfs_directory)
vfs_data = file_read(vfs_from) #view 8.1.1
if vfs_data:with open(realfs_to, 'wb') as realfs_file:
realfs_file.write(vfs_data)#examplefile_copy('scripts/client/gui/mods/mod_my.pyc','res_mods/0.9.17.1/scripts/client/gui/mods/mod_my.
pyc')

9. Known Issues
9.1 Case-Sensitive File Names
Issue Description
Currently, when adding ﬁles to the virtual ﬁle system:ﬁles from packages are added in the lower-caseﬁles from the <WoT_game_folder>/res_mods/ folder are added as they areAs a result, if a ﬁle is located both in a package and in the res_mods folder, and the ﬁle name contains atleast one upper-case letter, the ﬁle may load twice.
Temporary Solution
Use only lower-case letters for names of ﬁles and folders located in the <WoT_game_folder >/res_mods
folder.

9.2 Working with the GNU Gettext Files
Issue Description
Currently it is impossible to assign the .mo ﬁles in a package instead of the .mo ﬁles located in the<WoT_game_folder>/res/text/LC_MESSAGES/ folder.

Temporary Solution
Use net.openwg.vfsgettext as a temporary solution:
http://openwg.net/download/vfsgettext/net.openwg.vfsgettext_1.0.0.wotmod

9.3 Executing the .py Files
Issue Description
Currently, the .py ﬁles located in a package cannot be executed.
Temporary Solution
Add the compiled into byte code .pyc ﬁles to a package, in addition to the .py ﬁles.

Attachment А. Change-list
v 0.4 (2017-05-04)
reworked description of resolving package conﬂicts with the load_order.xml ﬁle.

v 0.3 (2017-05-03)
added information on restrictions to the .wotmod ﬁle formats;supplemented description of resolving conﬂicts for packages with identical identiﬁers

v 0.2 (2017-04-10)
reworked design: new layout, separation into articles
reworked description of the package naming scheme
reworked description of the package loading orderadded recommendations concerning the locations of logs and conﬁguration ﬁles
added examples of the source code for working with ﬁles within packages
added description of currently known issues

v 0.1 (2017-01-13)

v 0.1 (2017-01-13)
First version.