IN THIS ARTICLE
Create an O3DE Gem
You can develop your own independent modules to distribute and build as Open 3D Engine (O3DE) Gems. A Gem is just a bundle of code and/or assets, a manifest file, a CMake build file, and an optional display icon for project configuration tools. This is all that’s needed to ship a Gem.
The minimum requirements for a Gem is a directory with a
CMakeLists.txt build file and a
gem.json manifest file.
Although you can create a Gem manually by creating all of the files yourself, it’s recommended to use the
o3de tool located in the
<engine>\scripts\o3de.bat create-gem -gp <path to create gem at>
<engine>/scripts/o3de.sh create-gem -gp <path to create gem at>
This will create your Gem with a standard file structure and CMake files created from templates .
For more information on how to use the
o3de tool, refer to
Project Configuration CLI Reference.
Each Gem has an
Assets directory that can contain models, textures, scripts, animations, and more. Asset files are accessed the same way as they are in a game project. O3DE uses this root directory to find the asset file path. For example, when O3DE looks for the
textures/rain/rainfall_ddn.tif file, it looks in the
This file contains a list of compiled asset paths and platforms that will automatically appear in the Asset Bundler GUI making it easy for users to find and include in their project asset bundle.
They will also be included in a bundle when the
--addDefaultSeedListFiles CLI option is used.
seedList.seed approach is useful when you want to provide a ready-to-use list of default compiled assets and the platforms they’re used on.
Refer to the
Asset Bundler documentation for more information on the Asset Bundler,
.seed files, and bundling assets.
seedList.seedis case-sensitive and must be in your Gem
Assetsfolder or the seed list will not automatically appear in the Asset Bundler GUI.
The Gem dependencies
.xml file contains a list of source assets which will be used by the Asset Processor to create a seed list containing all the compiled asset paths and platforms.
Using the Gem dependencies file is convenient for specifying source assets with glob patterns, for example when you want to include all shader variants, but does require running the Asset Processor.
Refer to Default dependencies for O3DE projects for instructions on creating Gem dependencies.
Gem code can be contained in any directory that is picked up by the
CMakeLists.txt file of the Gem, although, by convention, Gems with only one source module use
Code for the directory name.
A Gem that contains code is known as a Code Gem. For more information on developing Code Gems, refer to Code Gem Specifications.
Each Gem is required to have a
gem.json manifest file, describing the Gem. See the
Gem manifest documentation for information on configuring a
Each Gem can also contain an optional image to use as an icon in GUI project configuration tools. This image should be a
.jpg with dimensions of 140x80, and named
preview.<ext>. The relative path to a Gem’s icon is specified in
Gems also require a
CMakeLists.txt CMake build file, so that they can be picked up by the O3DE build system. This should be a standard CMake file for building your
Gem’s source code, and it should be located in the Gem’s root directory.
For Gems that use binary libraries or executables that aren’t distributed as source, O3DE has a third-party package system.
CMakeLists.txt file is like any other CMake file. When you create it, keep the following important points in mind:
- The target generated for the Gem will have the Gem name as defined in the
gem.jsonmanifest. This will be the active target during the invocation of your Gem’s
- You can use the functions available in the core O3DE build system. See the contents of the
cmakedirectory in source.
- Avoid the use of
file(DOWNLOAD ...). The package system of O3DE is a robust replacement, and should be used instead.
When you create a Gem without specifying a template, it’s created from the “DefaultGem” template. This creates a Gem for packaging both code and assets. You can also create a Gem that provides only assets by specifying the “AssetGem” template through the
<engine>\scripts\o3de.bat create-gem --gem-path <path to create gem at> --template-name AssetGem # or <engine>\scripts\o3de.bat create-gem --gem-path <path to create gem at> --template-path <engine-root>\Templates\AssetGem
<engine>/scripts/o3de.sh create-gem --gem-path <path to create gem at> --template-name AssetGem # or <engine>/scripts/o3de.sh create-gem --gem-path <path to create gem at> --template-path <engine-root>/Templates/AssetGem
O3DE provides a list of Gem templates, which can be found in the Templates directory in the O3DE repository, or in your O3DE engine installation.