Documentation

1 - Getting Started

This guide takes you from “I don’t have OPAL yet” to “I’m looking at the O3DE Editor with my project open” in about ten minutes. There’s no prerequisite knowledge of O3DE — but if you’ve used Unity Hub or the stock O3DE Project Manager, the flow will feel familiar.

1. Install OPAL

Head to the Download page and grab the installer for your platform. Run it. On first launch, OPAL will ask for a workspace directory — this is where projects go by default. Pick something with a few GB free. You can change it later in Settings.

2. Install your first engine

On first launch (and any time you open the Engines page with no engines installed), OPAL prompts you to install one.

You’ll see three options:

• Latest stable — the most recent O3DE release. Recommended for new projects.
• Older stable — pick any prior version. Useful when a project is pinned.
• Build from source — clone and build the engine’s development or a specific branch. Use this when you need engine patches.

Pick one. OPAL kicks off the download (or clone + build) and tracks progress in the Downloads queue. You can keep working in the rest of the app while it runs.

3. Create or import a project

Once an engine is installed, go to the Projects page.

Create a new project

Click New Project. Fill in:

• Name — used for the folder and project_name in project.json.
• Template — OPAL bundles the standard O3DE templates. Pick one.
• Engine — defaults to your default engine; override per project if needed.
• Location — defaults to your workspace; override if you want it elsewhere.

Hit Create. OPAL runs o3de create-project, registers the project, and adds it to the list.

Or import an existing project

Click Import. Point at a project folder containing a valid project.json. OPAL reads the manifest, detects the engine pin, and adds the project.

4. Launch the editor

Find the project in your list. Look at the status badge:

For a fresh project, you’ll see Not built. Click Build. OPAL queues it and starts the CMake configure + compile. This will take a while the first time — that’s the O3DE engine compiling your project modules.

When the status flips to Built, click Open. The Editor launches with your project loaded.

5. Next steps

• Configure gems for your project: Gems
• Tweak your default build settings: Settings
• Set up multiple engines: Engines
• Learn the queue controls: Queues

2 - Features

Once you’ve followed Getting Started, this is where to dig into the details. Each page covers one feature area — what it does, how it’s configured, and the edge cases worth knowing.

In this section

• Engines — Install, remove, and switch between O3DE engine versions. Installer builds and source builds.
• Projects — Create, import, build, and launch projects. Engine pinning and per-project overrides.
• Gems — Browse configured repositories, enable gems per project, and manage custom gem sources.
• Queues — How OPAL schedules downloads, builds, and long-running tasks. Pausing, cancelling, and priorities.
• Settings — Workspace paths, default engine, build preferences, update channel, and telemetry.

2.1 - Engines

The Engines page is OPAL’s answer to the question “which O3DE do I use?”. Install as many versions as you want. Pin projects to specific versions. Remove engines you no longer need — with full awareness of what will break.

Install an engine

Click Install Engine (top right of the Engines page). OPAL offers three install modes:

1. Latest stable — the most recent tagged release.
2. Specific version — pick any prior tagged release.
3. Source build — clone a branch and build locally. Useful when you need engine patches.

Installer downloads run in the Downloads queue. Source builds run in the Builds queue. Both are interrupt-safe — you can close OPAL mid-install and resume later.

Set a default engine

Your default engine is the one used for new projects when you don’t override it. Click the Set Default button on any installed engine. The badge updates immediately.

Switch a project to a different engine

Open the project’s Settings dialog (right-click the project card → Settings, or the gear icon). Change Engine to any installed engine. OPAL writes the pin into project.json and prompts for a rebuild.

Remove an engine

Click the Remove button on an installed engine. OPAL shows an impact preview:

• How many projects are pinned to this engine
• Which projects will be orphaned (no compatible fallback)
• Total disk space reclaimed

Confirm to remove. Orphaned projects remain in your list but will show a Missing engine warning until you assign a new engine or reinstall the old one.

2.2 - Projects

The Projects page is the landing view of OPAL. Every project you’ve created or imported lives here. Each card shows at a glance what state the project is in and what actions are available.

Status badges

Actions per project

Every project card has:

• Launch — opens the Editor
• Build — queues a build using the configured build command
• Gems — opens the per-project gem editor
• Settings — opens the project settings dialog (engine pin, build command, CPU cores)
• View logs — shows the most recent build logs
• Open in file system — jumps to the project folder in Explorer/Finder/your file manager
• Remove from OPAL — removes from OPAL’s list (does NOT delete the folder)

2.3 - Gems

Gems are O3DE’s unit of reusable functionality — art, code, systems, whole frameworks. OPAL gives you three things the stock tooling doesn’t:

1. A real browser with filters, search, and a proper inspector.
2. Repository management that’s easy to keep current.
3. Per-project gem editing that stays in sync with project.json and CMake.

Browse the registry

The Gems page lists all gems available across every repository you’ve added. By default it includes the canonical O3DE gem registry; you can add any number of additional repositories.

Filter pills at the top: All, Installed, Updates available, Compatible with current engine. Search bar supports full-text plus operators:

• author:Acme — only gems by Acme
• tag:audio — only audio-tagged gems
• engine:25.05 — only gems compatible with a specific engine
• category:ui — category match

Combine freely: author:Acme tag:audio works.

The Gem Inspector

Click any gem to open the Inspector. You’ll see:

• Overview — name, author, version, short description
• README — rendered markdown from the gem’s README
• Dependencies — other gems required
• Compatibility — which O3DE engine versions it supports
• Changelog — if the gem maintains one
• Install / Update / Remove — one-click actions

Per-project gem editing

From a project card, click Gems → OPAL opens the Gem Editor for that project. You see the full list of available gems with checkboxes for the ones currently enabled. Toggle to enable or disable. OPAL:

1. Updates project.json’s gem_names array
2. Updates the project’s Gem/CMakeLists.txt
3. Offers a rebuild prompt when you close the dialog

Repository management

Go to Settings → Repositories to add, remove, or refresh gem repositories. Each repo has:

• URL
• Refresh interval (manual, hourly, daily, weekly)
• Authentication (optional — for private repos)
• Offline cache status

OPAL keeps a local cache of every indexed repo so you can browse offline.

2.4 - Queues

OPAL ships with two separate queues: one for downloads (engines, gems, assets) and one for builds (engine source builds, project builds). They behave the same way from a UX perspective: add, pause, resume, reorder, remove.

What you can do in a queue

• Pause / Resume individual items
• Pause All / Resume All the whole queue
• Move to top / Move to bottom an item
• Cancel an item (asks for confirmation; preserves partial state to a trash area)
• Retry a failed item
• Clear completed to reclaim the list

All of these persist across launches. Close OPAL mid-download, reopen an hour later, and the queue looks exactly like you left it — same items, same order, same progress.

Parallelism

How many downloads run in parallel? How many builds? Configurable — independently — in Settings → Queues.

Good defaults:

• Downloads: 4 concurrent connections
• Builds: 1 concurrent on laptops, 2–3 on workstations

Speed limits

Settings → Queues → Download speed limit sets a cap in MB/s. Set to 0 (default) for unlimited. Useful when OPAL is competing with Zoom calls or a home connection that doesn’t love saturated uploads.

Schedule windows

Settings → Queues → Schedule lets you restrict download activity to a time window — for example, 22:00 to 07:00 so you don’t burn daytime bandwidth. When the window closes, OPAL:

• Allows downloads >90% complete to finish
• Pauses everything else
• Resumes automatically at the next window open

Overnight windows that cross midnight (e.g. 22:00–06:00) are handled correctly.

2.5 - Settings

OPAL’s settings are grouped into categories. Defaults are called out in bold — you don’t need to touch most of these.

Appearance

Storage locations

Changing a storage path prompts to migrate existing contents — you can opt out and leave the old contents in place.

O3DE defaults

Queues

Notifications

Accounts

Manage connected marketplace accounts. (Marketplace is a planned post-1.0 feature.)

Advanced

Import / export

Advanced → Export config writes every setting to a JSON file you can back up or share with a teammate. Advanced → Import config reads it back.

3 - Troubleshooting

When something goes sideways, start here. If you don’t find the answer, ping Discord or send us a message.

Quick triage

1. Does the same thing fail in a fresh project? — If yes, it’s an OPAL or engine issue. If no, it’s likely project state.
2. Have you tried the operation outside OPAL? — For build/install failures, try the equivalent o3de.py command. If the CLI also fails, the issue is upstream of OPAL.
3. Check the logs. — Every failed operation produces a log. Click View Logs on the project/queue item.

Common symptoms

“Missing engine” banner won’t go away

Caused by: the engine folder got moved or deleted externally.

Fix: Go to Engines, reinstall the missing version, or open the affected project’s Settings and assign it to a different installed engine.

Download is stuck at 0%

Caused by: network handshake failed silently, or the mirror is down.

Fix: Cancel the download, and reattempt. If it still fails, switch mirrors in Settings → Advanced → Download mirror (if multiple are available), or send us the log.

Build succeeds in CLI, fails in OPAL

Caused by: an environment variable is set in your shell but not inherited by OPAL.

Fix: Check Settings → Advanced → Environment variables and add any engine-required vars (e.g. VULKAN_SDK).

Queue shows duplicates after a crash

Caused by: the queue state file didn’t flush before the crash.

Fix: Click Clear completed to remove any completed duplicates. For active duplicates, cancel one of each pair. (We’re hardening this for a future release.)

Gem browser says “no gems” but a repo is configured

Caused by: the repo cache hasn’t been built yet, or the fetch failed.

Fix: Settings → Repositories → Refresh all. If that fails, the repo URL may be unreachable — open it in a browser to confirm.

Error decoder

Recovery: queue state corruption

If the Downloads or Builds page refuses to load after a hard crash:

1. Close OPAL.
2. Open the config directory (~/.opal/) and rename downloads-state.json / builds-state.json to *.json.bak.
3. Restart OPAL. Queues will be empty; your engines and projects are untouched.
4. Re-queue anything you still needed to download.

4 - FAQ

Short answers to the questions we get most. Missing one? Ask us.

General

What is OPAL?

OPAL — O3DE Project Asset Launcher — is a third-party desktop launcher for the Open 3D Engine. It manages engine installations, projects, gems, builds, and downloads in a single app, with drastically improved functionality and UX compared to the stock O3DE Project Manager.

Is OPAL affiliated with the O3DE Foundation?

No. OPAL is an independent project from the O3DM team. It’s built on O3DE, for O3DE users, but it’s not an official O3DE Foundation product.

What does OPAL cost?

OPAL is free to download and use. See the License page for terms.

What platforms does OPAL run on?

Windows 10 21H2+, macOS 12+, and modern Linux distros (Ubuntu 22.04+, Fedora 38+, current Arch). AppImage, deb, rpm, and Flatpak packages available.

Install & setup

Do I need to install O3DE before OPAL?

No — that’s the whole point. OPAL installs O3DE for you. Download OPAL, open it, pick an engine version, and OPAL handles the rest.

Can OPAL coexist with the stock O3DE Project Manager?

Yes. They share the same project.json format and the same engine manifest. Projects created in one are visible in the other. Engines installed by OPAL are discoverable by the stock tool, and vice versa.

Can I import projects I already have?

Yes. Projects → Import → point at the project folder. OPAL reads the existing project.json and adds it to your list without modifying anything.

Where does OPAL store things?

All configurable in Settings.

Engines

Can I install multiple O3DE versions?

Yes. Every engine lives in its own folder and is registered independently. Projects pin to specific versions.

Can OPAL manipulate any O3DE version?

Yes. OPAL isn’t tied to a specific engine release. It manages every O3DE version we’ve tested — current stable back through prior releases — and doesn’t care whether you installed the engine binary or built it from source.

Can I build O3DE from source?

Yes. Install Engine → Build from source. OPAL runs the clone, CMake configure, and compile. Source builds are interrupt-safe like every other queue item.

What happens if I delete an engine folder manually?

OPAL detects the mismatch on next launch and surfaces a Missing engine warning on affected projects. From there you can reinstall or re-pin.

Projects

Do projects created with OPAL work with other O3DE tools?

Yes. OPAL writes standard project.json manifests. The O3DE Editor, o3de.py CLI, and stock Project Manager all see your OPAL projects as normal O3DE projects.

Can I have the same project use different engines on different machines?

Yes — OPAL’s config is per-machine. Commit the project to Git; the engine pin is advisory. OPAL prompts to reassign if the pinned engine isn’t installed locally.

Can I use custom CMake flags per project?

Yes. Project → Settings → Build command lets you override the default CMake generator, toolchain file, config, and arbitrary extra args. Save as a preset.

Gems & assets

Where do gems come from?

The canonical O3DE gem registry is enabled by default. You can add any number of additional repositories in Settings → Repositories, including private ones with auth.

Can I install a gem globally and use it in multiple projects?

Yes — shared gem storage is the default. Install once, reference from any project.

Does OPAL edit my project’s project.json?

Only when you explicitly toggle gems via the Gem Editor. OPAL keeps project.json and the Gem CMakeLists in sync automatically.

Downloads & builds

My download was interrupted — did I lose progress?

No. Every download is resume-safe. Partial files are preserved. On next launch (or next network recovery), the download picks up from the last committed byte.

Can I pause a build mid-compile?

Yes. Pause stops the compile process cleanly. Resume restarts from the last incremental step — not from scratch.

How many builds can I run in parallel?

Configurable in Settings → Queues. Defaults to 1 because O3DE builds are RAM-hungry. Workstations with 32 GB+ can comfortably run 2–3.

Can I schedule downloads to run overnight?

Yes. Settings → Queues → Schedule lets you set a time window. OPAL respects it — pauses at window close, resumes at window open. Overnight windows (22:00–07:00) are handled correctly.

Privacy & telemetry

Does OPAL collect telemetry?

Off by default. If you opt in, OPAL collects anonymous crash reports and feature-use stats — nothing else, and nothing tied to you personally. See the Privacy page for the full breakdown.

Does OPAL phone home?

It checks for its own updates (toggleable). It pulls from configured gem repositories and engine release metadata. That’s it.

Getting help

Something’s broken — what do I do?

1. Check Troubleshooting
2. Ask on Discord
3. Contact us directly

How do I request a feature?

Easiest: bring it up on Discord or via the contact form. Most features start as conversations.

5 - Changelog

Human-readable release notes for every OPAL release.

0.9.0-beta — 2026-04

Public beta release.

Added

• Multi-connection download manager with rate limiting (leaky-bucket)
• Schedule windows for downloads (overnight-aware)
• Per-project gem editor synced with project.json and CMake
• Gem Inspector with README rendering and dependency view
• Repository cache for offline gem browsing

Changed

• Status bar refactored to widget registration system (#28)
• Engines page now shows install-in-progress indicator
• Sidebar: resizable, collapsible, density-aware

Fixed

• Queue state no longer duplicates items after hard crash
• Missing-engine warnings clear correctly after reinstall

0.8.0-alpha — 2026-02

Added

• Dedicated Downloads section (#11)
• Settings bottom-offset option (#6)
• Missing-engine indicator on project cards (#4)
• Project-level gems and settings icons (#5)
• Page-title layout refinement (#7)

Changed

• Engines page moved to first-class navigation (#2)
• Login vs. Accounts resolved in favor of Accounts (#3)

0.7.0-alpha — 2025-12

Added

• First end-to-end project launch path
• Native application menu (Tauri)
• Preferences dialog with theme switching
• Comprehensive test suite scaffolding (Vitest)

0.6.0-alpha — 2025-10

Initial internal alpha. Project list, sidebar nav, mock data only.

What’s next?

Follow along on Discord for milestone previews, dev streams, and nightly notes.

6 - Legal

The legal basics for using OPAL: what you’re allowed to do with the software, and what data it touches.

In this section

• License — OPAL is proprietary, free to use, and not open source. The full terms of use.
• Privacy — What OPAL collects (by default: nothing), what it sends when you opt in, and the handful of endpoints it must talk to.

Related

• O3DE’s own license — OPAL is a third-party launcher for O3DE; the engine itself is Apache 2.0 and governed separately.
• Contact — for licensing questions, bundling requests, or data concerns.

6.1 - License

OPAL is proprietary software, free to download and use, distributed by the O3DM team. OPAL is not open source.

What you can do

• Download and use OPAL. Free of charge, for personal or commercial O3DE work.
• Install, manage, and build O3DE engines, projects, and gems with it — that’s the whole point of the tool.
• Run OPAL on as many machines as you own or control. No seat caps, no license keys, no activation servers.

What you can’t do

• Redistribute the OPAL binaries or installers outside this site. Point people at opal.o3dm.net instead.
• Modify, reverse-engineer, decompile, or repackage OPAL — in whole or in part.
• Bundle OPAL inside another product without a written agreement from the O3DM team.
• Remove or obscure branding, attribution, or in-app notices.

O3DE is separate

OPAL is a third-party launcher for O3DE. The O3DE engine itself is an independent, Apache 2.0-licensed project of the O3DE Foundation. Installing, building, and shipping engines or games made with O3DE is governed by O3DE’s own license — see o3de.org. Nothing here changes that.

Third-party components

OPAL bundles a number of third-party libraries. The full third-party license list ships with every release as THIRD-PARTY-LICENSES.md inside the install directory.

Questions

Licensing questions, bundling requests, or enterprise arrangements — get in touch.

Related

• O3DE license information
• Privacy policy

6.2 - Privacy

Short version: OPAL ships with telemetry off. We don’t collect anything unless you explicitly opt in. We never sell, share, or monetize user data.

What OPAL does not collect by default

• Your name, email, IP address, machine identifiers
• Which projects you have, what they contain, where they live
• Which engines you install, what you build
• Any content from project.json, gem.json, or your source code

What OPAL collects when you opt in

Under Settings → Advanced → Telemetry, you can opt in to two categories:

1. Crash reports

• Stack traces from crashes and unhandled errors
• OPAL version, OS name + version, CPU architecture
• A generated install ID (not tied to you)

Never included: file paths containing user data, project or engine contents, personal identifiers.

2. Anonymous feature-use stats

• Which pages you visit in OPAL (counts, not sessions)
• Which actions you invoke (e.g. “installed engine”, “started build”)
• Time-to-first-project on first install (a UX metric)

All stats are aggregated, bucketed, and stripped of anything identifying before they leave your machine. We don’t run analytics inside OPAL — it’s a single HTTPS POST to a collector endpoint you can block via your firewall or network policy.

What OPAL must connect to, regardless of telemetry settings

Data retention

• Crash reports: 90 days, then purged.
• Feature-use stats: aggregated indefinitely in anonymous bucket counts only.
• No user-identifying data is retained at any stage.

Your rights

Because we don’t collect user-identifying data, there’s nothing to delete, export, or correct. If you believe that has changed — for example, a bug causes personal data to leak into a crash report — contact us and we’ll address it.

Changes to this policy

Material changes will be announced in the Changelog and via the in-app update notification. The policy is versioned and ships with every release as PRIVACY.md inside the install directory.

Last updated: 2026-04-20.