Table of Contents
This chapter lists the steps necessary to prepare the game for its release.
The following sections detail each of these steps.
In order to allow the client to run on a system with limited privileges, the engine should not try to write to the installation directory (which, depending on how the game is installed, is usually a privileged location). Certain files that need to be written must be configured to be written to the user's directory.
-
The prefrences.xml file contains end-user specific settings such as graphics settings and is written whenever the client closes or when
BigWorld.savePreferences()is called. To configure where this file is saved, edit thepreferences/pathBaseconfiguration key in engine_config.xml.For example, you may want to configure preferences.xml to be written to
MY_DOCS/GameTitle/preferences.xmlSee File
<preferences>.xml for details on how to configure this setting. -
Screenshots can be taken either by pressing PrtScn or by calling
BigWorld.screenShot(). To configure where screenshots are saved, edit thepreferences/screenShot/path/pathBaseconfiguration key in engine_config.xml.For example, you may want screen shots to be written to
MY_DOCS/GameTitle/ScreenshotsSee Taking Screenshots for details on how to configure this setting.
Since "just-in-time" resource processing is not enabled in the
Consumer Release client (e.g. converting textures to DDS format on the
fly), all resources must be pre-prepared for release. A command line tool,
called res_packer, is provided which will process a given
list of assets. A higher level wrapper for res_packer is
bin_convert (implemented in Python), which will batch process
an entire resource tree.
This section provides an overview of how to use both
res_packer and bin_convert.
bin_convert is a command-line tool
implemented in Python that prepares assets in batch, which makes use of
the res_packer binary. Its usage is described below:
bin_convert [--res|-r search_paths] [source_path [dest_path [base_path]]]
The options for invoking
bin_convert.py are described
below:
-
search_paths
Search paths of the original source assets, as specified in
<res>(the resources folders list) — for details on how BigWorld compiles this list, see the document Content Tools Reference Guide's chapter Starting the Tools.This value overrides the local paths.xml, if there is one.
-
source_path
Path of the original source assets.
-
dest_path
Path of the final game, i.e., the destination of processed assets.
-
base_path
The resource root for dest_path, only needs to be specified if not converting the entire resource folder.
This tool can be customised in different ways, so it can skip certain files, skip entire folder, have special handlers for asset types (overriding res_packer).
For more information on customising bin_convert.py, please refer to its source code.
If the desired processing cannot be achieved in Python, then you can modify the source of res_packer using any of the included packer classes as example.
The list below shows some example of usage of bin_convert.py:
-
python bin_convert.py /mf/fantasydemo/res /mf/fantasydemo/packed
Converts all FantasyDemo assets in res to packed folder.
-
python bin_convert.py --res /mf/fantasydemo/res;/mf/bigworld/res /mf/fantasydemo/res /mf/fantasydemo/packed
Converts all FantasyDemo assets in res to packed folder, specifying the search paths in the command line.
-
python bin_convert.py /mf/fantasydemo/res/characters /mf/fantasydemo/packed/characters /mf/fantasydemo/packed
Converts all FantasyDemo assets in the res/characters folder to the packed/characters folder.
Note that base_path (in this case c:/mf/ fantasydemo/packed) must be specified to ensure that res_packer works properly.
res_packer is a command-line tool that is capable of processing assets depending on their type, pre-processing assets to make them load faster and stripping information that is not needed when running the game. Usually, it is called from bin_convert and is not used directly by the developer. Its usage is as follows:
Batch list mode:
res_packer [--res|-r search_paths] [--encrypt] --list|-l asset_list_file --in|-i src_path --out|-o dest_path [--err|-e error_log_file]
Compatible mode:
res_packer [--res|-r search_paths] [--encrypt] source_file [dest_file [base_path] ]
The options for invoking res_packer are described below:
Batch list mode:
-
search_paths
Search paths of the original source assets, as specified in
<res>(the resources folders list) — for details on how BigWorld compiles this list, see the document Content Tools Reference Guide's chapter Starting the Tools.This value overrides local paths.xml, if there is one.
Note
For some asset types, search paths have to be specified, either in the command line, in the game's paths.xml, or in the BW_RES_PATH environment variable.
These paths should be the source search paths used by the game, so that res_packer can find other source files that might be needed in the processing.
For instance, to process a model file, other assets such as the visual, textures, and animations must be also read.
-
--encrypt
This option encrypts the assets so they cannot be viewed by the user. This may be required as a license condition by some vendors of assets. Generally it is not required.
-
asset_list_file
A text file that contains a list of all the assets to process. This expected the dissolved paths with one per line.
-
src_path
The root path of the input files.
-
dest_path
The root path of the output files.
-
error_log_file
An optional error output log. Any files that fail to process will be added to this log.
Compatible mode:
-
source_file
Source file (with path) to process.
-
dest_file
Destination file (with path) of the processed assets.
In some cases, source_file might not be copied at all (.bmp files are not copied), or the processed file could be of a different type than the original source file (.bmp files are converted to .dds files).
If this argument is missing, then source_file will not be processed, and a message will be sent to the standard output (useful for examining XML files, for instance).
-
base_path
Base path of the final game — usually corresponds to dest_file's path.
This argument is used when packing file types that require special processing, such as images, models, and chunk files.
If this argument is missing, then the dest_file's path is used.
To modify res_packer's default behaviour for an asset type, or to add new asset types for processing, modify the source code using any of the included packer classes as example.
Note
When processing Python files,
res_packer does not compile the
.py files into .pyc when
called directly without bin_convert. Compiling of
.py files is done directly inside
bin_convert. Furthermore, if old
.pyc files exist in the source folder,
res_packer copies them to the destination folder
without recompiling when run directly without
bin_convert.
The default processing done by these tools is as follows:
-
bin_convert
-
Skips the scripts/editor, scripts/cell and scripts/base folders.
-
Skips the animations, .bwthumbs and CVS folders.
-
Skips the thumbnail files (i.e., files with .thumbnail.* extension).
-
For .py files
Generates .pyc compiled Python files and skips the source .py, using a custom handler.
-
-
res_packer:
-
For .bmp, .tga, .jpg, .png, .texformat and .dds files:
Generates DDS for source image files that do not have one, and copies DDS files that do not have a corresponding source image file. The .texformat files are skipped after processing.
-
For .model and .anca files:
Loads models to generate .anca files. The .animation files are skipped after processing, and the .model files are packed.
-
For .cdata files:
Strips thumbnail.dds and navgen sections.
-
For .chunk files:
Strips entities that are not client-only, then packs the file.
-
For .fx, .fxh and .fxo files:
By default it ignores
.fxand.fxhfiles, and only copies .fxo files, but it can also be configured to copy the source .fx and .fxh (requires recompiling, seesrc/tools/res_packer/config.hpp) .Note
res_packer itself does not rebuild shaders, it only copies any existing binaries. Use the utility script located in
bigworld/tools/misc/rebuild_shaders/RebuildShaders.pyto pre-build all shader combinations before running res_packer. -
For all other file types:
Text XML files — i.e., files beginning with the < (left angle bracket) character, regardless of extension — will be packed, while others will just be copied.
-
Both bin_convert and res_packer try their best to slim down the game's assets that will be shipped to the end user, but because each game has different architecture and requirements, some final tuning might be needed for your game. Following is a list of files and folders to help identify what should not be shipped to the end user:
-
Files *.bmp, *.tga, *.jpg, *.png, *.texformat: The final dds files are generated and packed by res_packer, so the source images are not needed.
-
Files *.thumbnail.*: These files are not packed, as these are generated and used in the tools' Asset Browser only.
-
Files *.animation: Packed .anca files are generated from the source .animation files by res_packer.
-
Files *.py: Compiled .pyc files are generated by bin_convert, so Python source is not needed.
-
Folders to skip: animations, .bwthumbs, scripts/editor, scripts/cell, scripts/base, scripts/db, scripts/bot, bigworld/res/server, bigworld/res/helpers.
By default, res_packer will pack any font
DDS files into your game's destination folder, and
font authors usually require buying a license in order to allow their
font(s) to be used. Please make sure you own license(s) to the font(s)
you use in your game.
To pack assets to zip files, simply create one or more zip files containing the game's assets. To create a set of Zip files that can be used by the BigWorld client application:
-
Zip files bigger than 2GB are not supported. More than one Zip file might be required.
The maximum Zip file size supported is 2GB.
-
Before creating the Zip files, the assets should be prepared via bin_convert.py.
This tool is located under bigworld/tools/misc/res_packer folder.
-
Zip file access is done through zlib, and the supported Zip compression methods are DEFLATE and STORE. Non-ASCII file names should be encoded as UTF-8.
Zip files created with WinRAR, WinZip and 7-Zip have been successfully tested. If Non-ASCII file names are included, make sure they are encoded as UTF-8, ie. in the case of 7-Zip, choose "Add to archive..", set "cu" as the parameters which will force the file names to be encoded as UTF-8.
7-Zip Add to Archive dialog
-
Create Zip files for the base BigWorld resources.
Navigate to the folder containing BigWorld's packed assets, and create the Zip files for its files and sub-folders.
-
Create Zip files for the actual game assets.
Navigate to the game assets folder, and create the Zip files for its files and sub-folders.
-
Specify Zip files as paths in the paths.xml file, in order of precedence.
The paths.xml file's Path tag can be set either to a path, or to a Zip file. Usually, game asset folders/zip files are listed before BigWorld resources folders/zip files. All paths must be specified relative to the client executable.
Assuming the following:
-
Common BigWorld resources compressed to bwres001.zip.
-
Final game assets compressed to res001.zip and res002.zip.
-
The resource packages are located next to client executable.
Your paths.xml file should look similar to this:
<root> <Paths> <Path> res001.zip </Path> <Path> res002.zip </Path> <Path> bwres001.zip </Path> </Paths> </root>You can also combine Zip file paths with normal file system paths as well, so that you can have additional assets in unzipped folder (this is required, for example, by streamed FMOD sound banks).
If your unzipped folder is called resunpacked, then paths.xml will look like this:
<root> <Paths> <Path> res001.zip </Path> <Path> res002.zip </Path> <Path> bwres001.zip </Path> <Path> resunpacked </Path> </Paths> </root> -
-
If this has not already been done, compile the final release of your game's executable. This can be done in the VisualStudio's Configuration Manager dialog box (accessed by the Build → Configuration Manager menu item).
The Active Solution Configuration drop-down list must be set to Consumer_Release.
-
Copy binaries to their final location in the redistributable directory structure. The final structure is quite flexible, as long as the resource paths are specified as relative to the executable. For example, if the paths.xml described in the previous section is used, then the final structure would look like:
-
InstallDir/bwclient.exe -
InstallDir/res001.zip -
InstallDir/res002.zip -
InstallDir/bwres001.zip -
InstallDir/resunpacked/
-