User Guide (Version 1.18)

Gems and AZ Modules

The gems system was developed to make it easy to share code between projects. Gems are reusable packages of module code and/or assets which can be easily added to or removed from a Lumberyard game. Gems also promote writing code in a way that is more modular than that found in legacy libraries. For example, each gem has its own include folder for its public interface code files. Gems also come with package management metadata such as semantic versioning and the ability to state dependencies on other gems.

Structure of a Gem

A gem's directory contents are organized as follows:

GemDirectory/ Assets/ (assets usable to projects) Code/ Include/ (public interface code files) Source/ (private implementation code files) Tests/ (code files for tests) wscript (waf build info) gem.json (gem metadata)

Waf Integration

Each game project must explicitly list the gems that it uses. When Using the Waf Build System runs, it builds only those gems which are actively in use. Waf also makes a gem’s include/ directory accessible to any gems or projects that explicitly depend upon the gem.

Gems Built as AZ Modules

Beginning with Lumberyard 1.5, all gems that ship with Lumberyard are built as AZ modules. When you build a gem as an AZ module, the gem uses the initialization functions expected by the AZ framework. An AZ module gem has public interfaces that are event buses and is better integrated with the new component entity system. Although legacy gems are still supported, it is highly recommended that you use gems based on AZ modules going forward. For information on migrating a legacy gem, see Migrating Your Gems.

When you use the Project Configurator to enable or disable a gem, Lumberyard updates the application descriptor file accordingly to ensure it references all AZ modules. If you edit the dev\<project_asset_directory>\gems.json list of gems by hand, you can use the following command to bring the application descriptor file up to date:

dev\Tools\LmbrSetup\Win\lmbr.exe projects populate-appdescriptors

About Gem Versioning

The GemFormatVersion value is versioning for how a gem is built. Gem version numbers like 0.1.0 refer to the gem's API version.

Gems from Lumberyard 1.4 and earlier (legacy gems) all have a GemFormatVersion value of 2. Starting in Lumberyard 1.5, all the gems included with Lumberyard are AZ modules and have a GemFormatVersion value of 3. This tells Lumberyard that the gem is an AZ module and that it should be loaded accordingly.

A gem may also have an API version number like 0.1.0. This is independent of the GemFormatVersion. The API version alerts your users to API changes. If the API version number changes, then users of the gem may need to make changes to their code. For example, the Rain gem will stay at version 0.1.0 until its API changes. If you were using the Rain gem from Lumberyard 1.4, you can still use the Rain gem from Lumberyard 1.5 without changing any of your data or code.

For more information about gems, see Using Gems to Add Modular Features and Assets.