Gem Configuration Examples

The following are example configurations for gems and their wscript files.

Contents

Gem with a GameModule

The following example gem adds one module type as GameModule.


{
    "GemFormatVersion": 4,
    "Uuid": "e5f049ad7f534847a89c27b7339cf6a6", // Required
    "Name": "MyGem",                            // Required
    "Version": "1.0.0",                         // Required
    "Modules": [                                // Optional
        {
            "Type": "GameModule"                // Required
        }
    ]
}

The following is the wscript file for the gem.


def build(bld):
 
    bld.DefineGem(
        # The following are the default settings, and do not need to be specified (unless changes are preferred)
        # target    = ['MyGem'],
        # file_list = ['mygem.waf_files'],
        # vs_filter = ['Gems'],
    )

Gem with a GameModule and Name

The following example gem has one module type as GameModule and specifies a name for that module.


{
    "GemFormatVersion": 4,                      // Required
    "Uuid": "e5f049ad7f534847a89c27b7339cf6a6", // Required
    "Name": "MyGem",                            // Required
    "Version": "1.0.0",                         // Required
    "Modules": [                                // Optional
        {
            "Type": "GameModule",               // Required
            "Name": "Components"                // Required
        }
    ]
}

The following is the wscript file for the gem.


def build(bld):
 
    bld.DefineGem(
        Components = dict(
            # The following are the default settings, and do not need to be specified (unless changes are preferred)
            # target    = ['MyGem.Components'],
            # file_list = ['mygem_components.waf_files'],
            # vs_filter = ['Gems'],
        ),
    )

Gem with a StaticLib and Name

The following example gem has one module type as StaticLib and specifies a name for that module.


{
    "GemFormatVersion": 4,                      // Required
    "Uuid": "e5f049ad7f534847a89c27b7339cf6a6", // Required
    "Name": "MyGem",                            // Required
    "Version": "1.0.0",                         // Required
    "Modules": [                                // Optional
        {
            "Type": "StaticLib",                // Required
            "Name": "HelperCode"                // Required
        }
    ]
}

The following is the wscript file for the gem.


def build(bld):
 
    bld.DefineGem(
        HelperCode = dict(
            # The following are the default settings, and do not need to be specified (unless changes are preferred)
            # target    = ['MyGem.HelperCode'],
            # file_list = ['mygem_helpercode.waf_files'],
            # vs_filter = ['Gems'],
        ),
    )

Gem with an EditorModule and Name

The following example gem has one module type as EditorModule and specifies a name for the module.


{
    "GemFormatVersion": 4,                      // Required
    "Uuid": "e5f049ad7f534847a89c27b7339cf6a6", // Required
    "Name": "MyGem",                            // Required
    "Version": "1.0.0",                         // Required
    "Modules": [                                // Optional
        {
            "Type": "EditorModule",             // Required
            "Name": "Editor"                    // Required
        }
    ]
}

The following is the wscript file for the gem.


def build(bld):
 
    bld.DefineGem(
        Editor = dict(
            # The following are the default settings, and do not need to be specified (unless changes are preferred)
            # target    = ['MyGem.Editor'],
            # file_list = ['mygem_editor.waf_files'],
            # vs_filter = ['Gems'],
            # platforms = ['win', 'darwin'],
            # configurations = ['debug', 'debug_test', 'profile', 'profile_test'],
        ),
    )

Gem with an EditorModule that Extends a GameModule

The following example gem has two module types, GameModule and EditorModule, specifies a name for both, and then extends the EditorModule.


{
    "GemFormatVersion": 4,                      // Required  
    "Uuid": "e5f049ad7f534847a89c27b7339cf6a6", // Required
    "Name": "MyGem",                            // Required
    "Version": "1.0.0",                         // Required
    "Modules": [                                // Optional
        {
            "Type": "GameModule",               // Required
            "Name": "Components"                // Optional
        },
        {
            "Type": "EditorModule",            // Required
            "Name": "Editor",                  // Required
            "Extends": "Components"            // Optional
        }
    ]
}

The following is the wscript file for the gem.


def build(bld):
 
    bld.DefineGem(
        Components = dict(
            # The following are the default settings, and do not need to be specified (unless changes are preferred)
            # target    = ['MyGem.Components'],
            # file_list = ['mygem_components.waf_files'],
            # vs_filter = ['Gems'],
            defines     = ['MY_GEM'],
            use         = ['AzCore'],
        ),
        Editor = dict(
            # The following are the default settings, and do not need to be specified (unless changes are preferred)
            # target    = ['MyGem.Editor'],
            # file_list = ['mygem_components.waf_files', 'mygem_editor.waf_files'],
            # vs_filter = ['Gems'],
            # platforms = ['win', 'darwin'],
            # configurations = ['debug', 'debug_test', 'profile', 'profile_test'],
            # defines   = ['MY_GEM'], # this is inherited from Components
            use         = ['AzToolsFramework'], # This overrides the Components module's 'use', so only 'AzToolsFramework' is 'use'd
        ),
    )

Gem with a StaticLib and Standalone Module

The following example gem has a StaticLib module, a Standalone module, and specifies a name for both.


{
    "GemFormatVersion": 4,
    "Uuid": "089562a2cbbd41749b359f85fa04f1c9",
    "Name": "CrashReporting",
    "DisplayName": "CrashReporting",
    "Version": "0.1.0",
    "Summary": "Enable external crash reporting for a game project",
    "Tags": ["Untagged"],
    "IconPath": "preview.png",
    "Modules": [
        {
            "Type": "StaticLib",
            "Name": "StaticLibrary"
        },
        {
            "Type": "Standalone",
            "Name": "Uploader"
        }
    ]
}

The following is the wscript file for the gem.


def build(bld):
 
    bld.DefineGem(
        StaticLibrary = dict(
            platforms   = ['win'],
 
            includes    = ['.', 'Include'],
            file_list   = ['crashreporting_static.waf_files'],
            win_file_list = ['crashreporting_static_win.waf_files'],
            use         = ['CrashHandler']
        )
    )
 
    uploader_file_list =  ['game_crash_uploader.waf_files']
    platform = bld.env['PLATFORM']
 
    if platform == 'project_generator':
        uploader_file_list.append('game_crash_uploader_win.waf_files')
        uploader_file_list.append('game_crash_uploader_unimplemented.waf_files')
    elif platform in ['win_x64_vs2015', 'win_x64_vs2017']:
        uploader_file_list.append('game_crash_uploader_win.waf_files')
    else:
        uploader_file_list.append('game_crash_uploader_unimplemented.waf_files')
 
    bld.CryQtApplication(
 
        # Settings
        target          = 'CrashReporting.Uploader',
        output_file_name = 'GameCrashUploader',
        file_list       = uploader_file_list,
        vs_filter       = 'Gems',
        includes        = ['Include'],
        platforms       = ['win'],
        configurations  = ['all'],
        use             = ['CrashUploaderSupport', 'AzCore'],
        disable_pch     = True,
        win_lib         = [ 'rpcrt4', 'version', 'powrprof', 'winhttp', 'user32', 'advapi32' ]
    )

Gem with a Header Only Library with Unit Testing

The following example gem has a Standalone module with unit testing.


{
    "GemFormatVersion": 4,                      // Required
    "Uuid": "e5f049ad7f534847a89c27b7339cf6a6", // Required
    "Name": "MyGem",                            // Required
    "Version": "1.0.0",                         // Required
    "Modules": [                                // Optional
        {
            "Type": "Standalone",               // Required
            "Name": "Lib"                       // Optional
        }
    ]
}

The following is the wscript file for the gem.


def build(bld):
    bld.CryEngineModule(
            # The following are the default settings, and do not need to be specified (unless changes are preferred)
            # target    = ['MyGem.Lib'],
            # file_list = ['mygem_lib.waf_files'],
            # vs_filter = ['Gems'],
            test_all_file_list = ['mygem_lib_tests.waf_files'],
            platforms   = ['win', 'darwin'],
            configurations = ['debug_test', 'profile_test'],
    )

Note

The gem must exist in the gems.json for your project but should be removed from the game.xml and editor.xml files.

In Project Configurator, create the gem and make the changes to the gem.json and wscript files.
Do one of the following:
1. In a command line window, navigate to the lmbr.exe file and enter the following command.
```
lmbr projects populate-appdescriptors
```
2. In a text editor, delete the entries for the gem from the game.xml and gem.xml files.

Gem with a StaticLib Only and Unit Testing

The following example gem has a StaticLib module, and a Standalone module for unit testing.


{
    "GemFormatVersion": 4,                      // Required
    "Uuid": "e5f049ad7f534847a89c27b7339cf6a6", // Required
    "Name": "MyGem",                            // Required
    "Version": "0.1.0",
    "Modules": [
        {
            "Name": "StaticLibrary",
            "Type": "StaticLib"
        },
        {
            "Name": "UnitTestModule",
            "Type": "Standalone",
            "Extends": "StaticLibrary"
        }
    ]
}

The following is the wscript file for the gem.


def build(bld):
    bld.DefineGem(
        StaticLibrary = dict(
            # The following are the default settings, and do not need to be specified (unless changes are preferred)
            # target    = ['MyGem.Lib'],
            # file_list = ['mygem_lib.waf_files'],
            # vs_filter = ['Gems'],
        )
    )
 
 
    bld.CryEngineModule(
        # The following are the default settings, and do not need to be specified (unless changes are preferred)
        # vs_filter = ['Gems'],
        target          = 'TestGem.UnitTestModule',
        output_file_name = 'TestGemUnitTests',
        file_list = ['mygem_tests.waf_files'],
        platforms   = ['win', 'darwin'],
        configurations = ['debug_test', 'profile_test']
    )

Note

The gem must exist in the gems.json for your project but should be removed from the game.xml and editor.xml files.

In Project Configurator, create the gem and make the changes to the gem.json and wscript files.
Do one of the following:
1. In a command line window, navigate to the lmbr.exe file and enter the following command.
```
lmbr projects populate-appdescriptors
```
2. In a text editor, delete the entries for the gem from the game.xml and gem.xml files.

Warning Javascript is disabled or is unavailable in your browser.

To use the AWS Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

« Previous Next »