Technical Documentation
Page tree

Versions Compared

Old Version 7

changes.mady.by.user Unknown User (michaelma)

Saved on

compared with

New Version Current

changes.mady.by.user Unknown User (achim)

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Warning

This document applies to version 3.8.6 of CRYENGINE.

Overview

Sometimes, you want to ship the most optimized and most secure binaries and assets for a project to your end-users.

...

Table of Contents
maxLevel3
minLevel2
excludeOverview

One-time setup

Setting up cryptography keys

Open a command prompt, and make <root>/Tools/PakEncrypt the current directory.

...

Info

It's not required to provide the RSA key for profile or debug configurations.
Not providing a key can reduce the initial start-up time by ~1 second, but binaries from that configuration can no longer open encrypted PAK files. 

Setting up CVar whitelist

In the file <root>/Code/GameSDK/GameDll/GameStartup.cpp there is a function:

...

However, think of the target machines of end-users and don't freeze quality CVars at too high quality levels. 

Creating a Release build

Compilation

You should compile your code in the [GameSDK] Release (and [GameSDK Server] Release if you use dedicated servers in your project) configuration for your target platforms.

...

Note

Don't mix release with non-release DLLs (ie, don't rename DLLs), because they are NOT compatible and the end result will be unstable, if it runs at all.
Combine the release DLLs with the release EXE only, and combine the non-release DLLs with the non-release EXE only.
Release DLLs cannot be used/loaded from the editor (and therefore, there is no Editor.exe in the release folders)

Packed assets

We will not go into detail in this document on how to pack your assets, but we assume you have all the assets required by the game packaged into appropriate PAK files.

...

See also Compiling Assets for Multiple Platforms and the RCJob_Build_SDK.xml that has been shipped to you.

Collecting files into staging

Copy ONLY the following files to a new folder that will contain all the files for the final version of your project (ie, the distribution)

...

Note

Note for users that are not using Visual C++ 2012 compiler, make sure that runtimes (if any) are either shipped or are installed in some other way.
Even if you don't use the Visual C++ 2012 compiler, we used that one to compile the _Release.exe, so the runtimes for 2012 still need to be present or installed (which causes duplicate runtime requirement)

We recommend against mixing runtimes from different Visual C++ editions, since it can (theoretically) cause hard to diagnose bugs.
If possible, consider building your releases with the same compiler as Crytek used for compilation to minimize chances of problems. 

Signing / Encryption of assets

Once you have your staging folder set-up, you need to either sign OR encrypt your asset PAK files.

...

Info

As an optimization, you can also copy only PAK files into the staging folder (keeping the correct folder structure), and copy all non-PAK files directly to the output folder (with the same structure), which saves a copy operation for those files.
However, that's outside the scope of this document, and since a significant relative amount of data volume is in the PAK files anyway, it might not be worth the additional complexity to your build systems.

Test and redistribute

Now you can take the contents of the output folder and test or redistribute it.

...

Info

Redistributing via a specific publishing platform (ie, Steam) is outside the scope of this document. You should probably read the documentation provided by the publishing platform to find out how it works.
In general, as long as the end-users folder structure matches the one that is described here, there shouldn't be any issues.

The same comment applies to installers of various kinds, as long as the directory structure is maintained and all the files mentioned above are present, the project should be runnable.
It's important to also include your redistribution method in your testing; if you publish on Steam you should test the game downloaded via Steam, if you publish with an installer, you should also run the installer before testing.
This helps finding problems due to missing files, or files installed to a wrong folder.

Troubleshooting

Sometimes it's hard to debug issues with Release builds, because code is optimized and assets may not be easily accessible.

Here are some pointers to isolate problems:

My game doesn't run in Release mode

Make sure that: 

  • You have your PAK files signed or encrypted.
  • You have the correct key set in the code.
  • The profile/debug version of the game does run with the same assets (and the same key).

My CVars don't work in Release mode

Make sure that:

  • The CVar in question is white-listed in your code.

My assets cannot be found in Release mode

Make sure that:

  • The asset exists in a PAK file, and the PAK file is in the list of PAK files to load in the code.
  • The PAK file containing the asset is signed or encrypted with the correct key.

I get a lot of warnings about "Non binary XML found"

This is not a fatal error, however you can convert your XML files to binary XML using RC, see also Binary XML conversion
The conversion is recommended for an end-user distribution

I cannot connect to a dedicated server

Please note that you should connect release clients with release servers. (And also, you should connect profile/debug clients with profile/debug servers)

I have some other problem

The default value of log_severity in release builds are quite low, so to debug an issue it might make sense to set it to 3 or 4 to get more information and messages.
Note that, unless you whitelist this CVar, setting it in system.cfg will not actually work.