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 enable 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 enable or disable.

3. Enable or disable the Gem.

4. Save changes.

5. 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 Edit Project Settings… button.

   

3. Select the Configure Gems button.

   

4. 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 enable or disable for your project.

   

Locating Gems

Filtering the catalog

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

You can filter by the following groups:

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

Viewing Gem details

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

Enabling or disabling Gems

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

You can enable or disable 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 enable or disable. These changes will take effect after you’ve saved and (depending on the Gem requirements) rebuilt your project.

Saving and rebuilding

1. Select the Save button when you are finished adding and removing Gems from your project.

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.

   

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

   

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 enable or disable a Gem for a project.

   Enable

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

   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 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, which can be found in the Gem’s gem.json configuration file.
   • -pp, --project-path: Path to the project folder (can be absolute or relative).
   • -pn, --project-name: Name of the project, 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.