Assets & Gems
Browse the Asset Library, configure gems per project, and manage repositories, local gems, and watch folders.
Gems are O3DE’s unit of reusable functionality — art, code, tools, whole frameworks. OPAL gives them a real home: a browsable Asset Library with a proper inspector, per-project gem configuration that stays in sync with project.json and CMake, and flexible ways to bring gems in — from repositories, local folders, or watch folders.
In this section
- Asset Library — Browse and filter gems, and inspect them across the five-tab inspector.
- Project gems — Enable and disable gems for a specific project, with dependencies handled for you.
- Repositories & sources — Add gem repositories, local gems, and watch folders; how caching and credentials work.
1 - Asset Library
Browse and filter gems, and inspect them with the five-tab Gem Inspector.
The Asset Library is OPAL’s gem browser: a gem list on the left and the Gem Inspector on the right. It gathers gems from every source you’ve configured — repositories, local gems, and the gems bundled with your engines — and lets you search and filter across all of them.
Search & filter
The search box does a live text match across gem name, display name, summary, and origin. On top of free text, you can use filter prefixes — combine as many as you like:
| Prefix | Matches |
|---|
author:<name> | Gems by a given author |
tag:<value> | Gems with a tag (repeatable; tags OR together) |
gemType:<Asset|Code|Tool> | Gems of a given type |
compatibleEngines:<engine>[,<engine>...] | Gems compatible with the given engine(s) |
downloaded:<true|false> | Downloaded (or not) gems |
hasUpdate:<true|false> | Gems with an available update |
updatedBefore:<date> / updatedAfter:<date> | Gems by last-updated date |
Free text and prefixes combine — for example author:Acme tag:audio hasUpdate:true.
The Gem Inspector
Select a gem to open the inspector, which has five tabs:
- Overview — name, author, summary, type, license, requirements, compatible engines, dependencies.
- Images — screenshots and media the gem provides.
- Imported Assets — the assets the gem brings in.
- Releases — version history with release notes fetched automatically from the gem’s host (GitHub, GitLab, or Bitbucket).
- Instances — where the gem is present/used.
For local or user-managed gems, the inspector also supports an edit mode for fields like display name, summary, type, license, docs URL, requirements, compatible engines, and dependencies.
Kinds of gems
OPAL distinguishes local gems, engine-bundled (built-in) gems, and repository / marketplace gems, so you always know where a gem came from.
See also
2 - Project Gems
Enable and disable gems for a specific project, with dependencies handled for you.
Browsing gems is one thing; deciding which gems a project uses is another. OPAL gives each project its own gem configuration, reached from the project’s Gems quick-action (available once the project’s engine is resolved).
Enable and disable gems
The project gem view reuses the same list-and-inspector layout as the Asset Library, but scoped to the gems available for that project’s engine plus your repository gems. Toggle a gem active or inactive for the project, and OPAL keeps the project’s gem set in sync — updating project.json’s gem list and the project’s CMake gem list together.
Required dependencies
Gems that are pulled in as dependencies of an active gem are marked with a Required dependency badge and can’t be switched off directly — OPAL won’t let you disable something another active gem needs.
Sorting
Sort the list to suit the task: Name A–Z, Name Z–A, Active First, or Inactive First.
Downloading a gem’s source
Per gem, you can download the gem or its source — OPAL uses git clone or an archive download as appropriate (see Repositories & sources for how credentials and the git/archive choice work).
Engine not resolved
If the project’s engine can’t be resolved, the page shows an engine-missing banner — resolve the engine first (see status & health) and the gem configuration becomes available.
See also
3 - Repositories & Sources
Add gem repositories, local gems, and watch folders; how caching and credentials work.
The Asset Library is only as good as the gems it can see. OPAL lets you add gems from several kinds of source, all managed from the Asset Library’s Add menu.
Ways to add gems
- Add Repository — point OPAL at a gem repository URL (it must end in
.json). OPAL indexes it and folds its gems into the library. - Add Local Gem — select a local gem folder to register a gem that lives on your machine.
- Add Watch Folder — choose a folder that OPAL watches and auto-syncs gems from as they appear. If a watched folder later goes missing, OPAL prompts you to keep or stop watching it.
- Create Gem — scaffold a brand-new gem from within OPAL.
Caching & refresh
OPAL caches indexed repositories and scans your installed gems on startup, so browsing works offline and stays fast. It refreshes automatically when the cache is stale and you’re online, and a Check for Updates / Refresh button forces a refresh on demand. The automatic refresh interval is configurable in Asset Library settings.
Source downloads & credentials
When you download a gem’s source, OPAL uses git clone or an archive download automatically. You can prefer git globally via the useGitForSourceDownload setting; when git isn’t available or is disabled, OPAL falls back to the HTTP archive method.
If a source needs authentication, a Git credential prompt handles it — labeling the clone versus LFS-fetch stages distinctly so you know what’s being requested.
Release notes
For gems hosted on GitHub, GitLab, or Bitbucket, OPAL fetches release notes automatically (shown in the inspector’s Releases tab). The provider is detected from the gem’s metadata URLs, and the provider system is extensible for additional hosts.
See also