Version:

Adding and Removing Gems in a Project

This tutorial shows you how to add and remove Gems in your project by using the Project Manager or the command line interface (CLI) in Open 3D Engine (O3DE). Gems provide features and assets to your project. For more details on Gems and what Gems are available with O3DE, refer to the Gems section.

O3DE includes many Gems that you can add to your project. You can also use Gems from external sources. External Gems must be registered to your project before you can activate them. Refer to Registering Gems for instructions on how to register additional Gems.

Overview

The basic steps to configure Gems for your project are as follows:

  1. (Optional) Register the Gem if it is from an external source.

  2. Locate the Gem you want to activate or deactivate.

  3. Activate or deactivate the Gem.

  4. (Optional) Selecting a Gem version.

  5. Save changes.

  6. Rebuild your project (if necessary).

Using Project Manager

Opening the Configure Gems screen

  1. Launch Project Manager, which can be found on your desktop or in bin/Windows/profile/Default/o3de.exe if you installed O3DE, or in your engine build directory if you built O3DE from source.

  2. Open the menu for a project and select the Configure Gems… button.

    For a project, go to the menu and select ‘Edit Project Settings’.

  3. In the Configure Gems screen, you can filter or search for available Gems. Scroll through the resulting list to find the Gem you want to activate or deactivate for your project.

    Configure Gems screen.

Locating Gems

Filtering the catalog

Filter the Gem catalog to help you find a particular set of Gems.

Filter Gems

You can filter by the following groups:

CriteriaDescription
StatusDisplays Gems that are already either active or inactive, and the Gems that are currently selected or unselected for your project as well as Gems that are missing.
VersionsDisplays Gems that are compatible with your project or have version updates.
ProviderDisplays Gems based on their provider. O3DE displays Gems that are built with O3DE source. Local displays local Gems that are provided by other sources. Remote displays Gems that are provided by remote sources.
TypeDisplays Gems based on the type of Gem. Asset displays Gems that add assets to your project. Code displays Gems that extend functionality in your project. Tool displays Gems that provide a tool you can use in O3DE.
Supported PlatformsDisplays Gems based on the platforms that support it.
FeaturesDisplays Gems based on its provided features.

Searching the catalog

Search the Gem catalog by entering text in the search field. You can search for Gems using any of the following search terms:

  • Gem name
  • Gem display name
  • Origin
  • Summary
  • Features

Search field

Viewing Gem details

Select a Gem to view its description, other Gems it depends on or conflicts with, and additional information.

View Gem details

When an update is availble for an active gem a yellow notification icon will appear in the gem row next to the gem version.

Gem update available

Activating or deactivating Gems

Activate or deactivate Gems in your project by toggling the switch under the Selected column for a given Gem.

Gems to activate or deactivate during configuration.

You can activate or deactivate multiple Gems at once. The changes that will be made to the project are summarized in the top right corner of the window. Select the Gem bag icon to view the Gems to activate or deactivate. These changes will take effect after you’ve saved and (depending on the Gem requirements) rebuilt your project.

Gems to activate or deactivate during Gem configuration.

Selecting a Gem version

If multiple versions of a Gem are available, a drop-down box will be visible in the Gem details panel showing available versions. Select a version to see the details about it.

Gem version details.

When you activate the gem, the selected version will be used. If the Gem is already active, a Use Version button will appear in the Gem details panel when the Gem version is changed.

Use Gem version button.

Saving and rebuilding

  1. Select the Save button when you are finished adding and removing Gems from your project. If any compatibility issues are found with the added gems, a popup appears with information, and asks if you want to continue adding those gems or cancel.

  2. Asset-only Gems do not typically require a rebuild of your project, however Gems that include code do. When you save changes to your project configuration, a warning message will appear if you need to rebuild.

    Project rebuild warning

  3. In the Project Manager home screen, select the Build Project button on your project to rebuild it (if necessary).

    Build project button

Using the Command Line Interface (CLI)

You can also configure Gems using the CLI. Refer to CLI Reference for additional supported CLI commands.

  1. Open a command prompt to the folder where your engine is located.

  2. Use the following commands to activate/enable or deactivate/disable a Gem for a project.

    Activate/Enable

    scripts/o3de enable-gem -gp <gem-path> -pp <project-path>
    

    Deactivate/Disable

    scripts/o3de disable-gem -gp <gem-path> -pp <project-path>
    

    There are several variations of these commands that you can use to specify either the name with optional version specifier or the path of the Gem and project.

    • -gp, --gem-path: Path to the Gem folder (can be absolute or relative).
    • -gn, --gem-name: Name of the Gem with optional version specifier, which can be found in the Gem’s gem.json configuration file: i.e. --gem-name Atom>=1.0.0. Refer to the Gem Versioning section for more information about Gem version specifiers.
    • -pp, --project-path: Path to the project folder (can be absolute or relative).
    • -pn, --project-name: Name of the project with optional version specifier, which can be found in the project’s project.json configuration file.
  3. Rebuild your project. Refer to the Build section for more information about building your project from the command line.