Overview

Projects in CRYENGINE are managed by IProjectManager, each project being represented by a .cryproject file. The concept of a project exists in order to create a clear separation between an engine installation, and engine assets.

Each project specifies the plug-ins it requires, these are then loaded at startup. The CRYENGINE Launcher automatically installs a shell extension for Windows users, resulting in a few shortcuts being added to the shell menu when a .cryproject file is right-clicked in the Explorer:

Project File

The project file defines what assets and binaries to load for a project - in addition to configuring CVars and more. This is read by the engine extremely early at startup as a change of project can drastically affect how the engine initializes itself.

The project can be specified to the engine using the '-project' switch. For example:

<engine folder>/bin/win_x64/Sandbox.exe -project MyProject.cryproject

The path to the project can be either relative to engine root, or an absolute path.

If the '-project' switch is not used, the engine will attempt to load a file called Game.cryproject in the engine root. This behavior can be changed by modifying the sys_project CVar's value in system.cfg, for example:

sys_project=MyProject.cryproject

Project Actions

Right-clicking the .cryproject file will give you a number of options that can perform various actions regarding your project:

The available options do the following:

Project File Structure

An example of a .cryproject can be seen below:

{
  "version": 3,
    "content": {
        "assets": [ "Assets" ],
        "code": [ "Code" ]
    },
    "info": {
        "guid": "b8c1c46b-a63e-d4af-9025-0770e4d43048",
        "name": "My Game"
    },
    "require": {
        "engine": "{7893db92-d8c1-4ae5-b3e2-2ce0a0e77782}",
        "plugins": [
            {
                "path": "CryDefaultEntities",
                "type": "EPluginType::Native"
            }
        ]
    },
    "console_variables": [],
  "console_commands": []
}

JSON Breakdown

"version"

Defines the version of the project syntax that the project was exported with. This is used to support automatic migration to newer versions, while maintaining backwards compatibility.

"content"

Defines where content for the project resides.

"assets"

Name of the Assets directory, not required for plug-ins.

"code"

Name of the Code directory, not required.

"info"

Defines project properties.

"guid"

Globally unique identifier used to identify the project.

"name"

Name of the project, used to set the title of the window on Desktop platforms.

"require"

Defines dependencies for the project.

"engine"

The engine that this project depends on, usually a GUID when using the CryVersionSelector. This can also be set to "." to indicate that the engine is present in the same directory as the project.

Engines are registered in %PROGRAMDATA%\Crytek\CRYENGINE\cryengine.json, and is automatically performed when a .cryengine file is double-clicked.

"plugins"

Defines plug-ins that should be loaded when this project starts. Plug-ins in CRYENGINE are represented by the Cry::IEnginePlugin interface, and are typically loaded from disk as a dynamic library (.dll on Windows). The introduction of game code is always done through a plug-in, allowing the addition of components and other logic with relative ease.

The .cryproject file is responsible for defining which plug-ins to load, for reference take a look at a snippet from the example we posted earlier:

"plugins": [
    {
        "path": "CryDefaultEntities",
        "type": "EPluginType::Native"
    }
]

First, this defines which engine to load from the engine registry - this is automatically populated when an engine is downloaded through the Launcher, but can also be added to by right-clicking a .cryengine file. The registry is currently located in <ProgramData>\Crytek\CRYENGINE\cryengine.json.

The "plugins" array can then contain an array of objects defining which plug-ins to load. In our case we choose to load the default "CryDefaultEntities" plug-in included with the engine, which includes the default entity components.

The search pattern for plug-ins is:

1. Project directory
2. Engine binary directory

The final option "type" specifies what type of plug-in we are loading - C# or C++. This can be represented by one of two values:

"console_variables"

Console variables that should be set at startup. If a console variable is not registered during startup, the value is saved and is set immediately when (and if) a console variable with that name is registered. For example:

"console_variables": [
  {
        "name": "sys_target_platforms",
        "value": "pc,ps4,xboxone,linux"
    }
],

This would result in the sys_target_platforms CVar being set as early as possible during engine startup time.

"console_commands"

Console commands that should be executed at startup. If a console command is not registered during startup, the value is saved and is set immediately when (and if) a console command with that name is registered. For example:

"console_commands": [
  {
        "name": "map",
        "value": "MyMap"
    }
],

This would result in the "map" command being executed, resulting in the level "MyMap" being loaded immediately after start up.

The Project & Asset Folder

The project folder is where your .cryproject resides, and will also contain your assets folder. The assets folder is where the engine will load all data such as levels, models and scripts from. The vast majority of Filesystem functions will be relative to this directory, instead of requiring an absolute path. This also ensures that the game will continue to function regardless of where the assets folder is, or what it is named.

Project Folder contents

Temporary Files

The engine will also generate temporary files and directory at run-time, however these do not need to be checked into version control and can be deleted safely.

Engine folder contents

Authoring a custom plug-in

The Launcher provides a default template for plug-in creation, and this can also be seen in <engine directory>\Code\GameTemplates\cpp\Plugin. For a simple example of how Cry::IEnginePlugin can be implemented, see here.

Receiving Updates

Plug-ins are able to subscribe to updates, receiving callbacks every frame to do any custom work on a per-frame basis. In the simplest case, we can simply override the Cry::IEnginePlugin::MainUpdate function, and then call Cry::IEnginePlugin::EnableUpdate to make sure that it is called every frame.

Project Source Code

Assuming that a code folder was specified in your .cryproject file's .json, we can use the Generate solution option in the menu that appears when a .cryproject file is right-clicked in the Windows Explorer:

This results in a CMakeLists.txt file being generated in the Code folder set to automatically compile any C++ source files contained in the Code folder or its subdirectories.

We can at any point regenerate the solution, for example this might be used when new source files are added to the Code folder.

The CMake GUI

For more advanced customization of our builds, we can utilize the 'Open CMake GUI' option in the context menu. This will bring up the CMake GUI as shown below:

This GUI can be used to toggle options in the categories at any time. Clicking Generate afterwards would then re-create your Visual Studio solution.

For example, we can enable 'OPTION_ENGINE' in projects to build the full engine alongside the project - directly to the project directory.

Conclusion

This concludes the article on Projects and Plug-ins, you may be interested in:

• Introduction to the Engine API
• Entity
• Building the Engine from Source Code