Projects

Create, import, build, run, and export O3DE projects, with status-aware cards and missing-engine recovery.

The Projects page is the landing view of OPAL. Every project you’ve created or imported lives here, each on a card that shows its state at a glance and offers the actions available right now. Search filters the list by display name, name, or path.

This is where the whole pipeline runs from — create, build, run, debug, and export — without dropping to a command line.

In this section

Create & import — Make a new project from a template, or bring in an existing one.
Build & run — Build, run the Asset Processor, launch the Editor, and follow live run states.
Status & health — What each status badge means, and how OPAL guides you through a missing engine.
Project settings — Pin an engine, override the build tool, and pass launch arguments per project.

← Previous: Engines Next: Assets & Gems →

1 - Create & Import

Create a new O3DE project from a template, or import an existing one.

Every project in OPAL is a standard O3DE project — OPAL writes and reads the normal project.json manifest, so projects stay compatible with the O3DE Editor, the o3de CLI, and the stock Project Manager.

Create a new project

Click New Project and fill in the dialog:

Name — validated as you type: it must start with a letter and contain only letters, numbers, _, or -, up to 64 characters.
Location — the parent directory the project folder is created in.
Engine — defaults to your default engine; choose any installed engine instead.
Template — OPAL auto-selects DefaultProject; pick a different template if you prefer.

Click Create. OPAL creates the project, writes project.json, registers it, and adds it to your list.

Import an existing project

Click Import and select a folder that contains a valid project.json. OPAL reads the manifest, resolves which engine the project expects, and adds it to your list without modifying the project. This works for projects created anywhere — including the stock O3DE Project Manager.

2 - Build & Run

Build a project, run the Asset Processor, launch the Editor, and follow live run states.

From a project card you drive the core loop: build the project, process its assets, launch the Editor, and stop it again — all with real-time feedback.

Build

Click Build to queue a build using the project’s configured build tool. The build runs through the Builds queue, where it can be paused, resumed, reordered, and cancelled. Its output streams into the Logs viewer, and a View Log shortcut sits right on the item.

The first build of a project takes a while — that’s O3DE compiling your project’s modules.

Run the Asset Processor

Each project has a dedicated Run Asset Processor action. It’s disabled until the project’s engine is resolved (OPAL needs to know which engine’s Asset Processor to run). Its output goes to the Logs viewer like everything else.

Launch and stop

Click Launch to open the O3DE Editor for the project. The card reflects real run states as it goes:

Launching — the Editor is starting.
Processing Assets — assets are being processed before the Editor is ready.
Running — the Editor is open.

While a project is running, a Stop control replaces the quick actions so you can shut it down from OPAL.

3 - Status & Health

What each project status badge means, and how OPAL recovers a missing engine.

Every project card tells you its state without you having to open anything. There are two layers: the build status badge, and — when the project is running — a run state.

Build status badges

Badge	Meaning
Not Built	The project exists but has never been built
Needs Build	The project has changed since its last successful build
Building	A build is in progress
Built	The build is current — ready to launch
Build Failed	The last build errored — check Logs

Run states

While a project is launching or open, the card shows a run state instead: Launching, Processing Assets, or Running, with a Stop control to shut it down.

Missing-engine recovery

A project points at an engine. If OPAL can’t cleanly resolve that engine, it doesn’t just error — it identifies which of three situations you’re in and offers the matching fix inline on the card:

Situation	What it means	Inline action
Engine not on disk	The referenced engine isn’t installed anywhere OPAL can find	Add Engine (go to Engines)
Engine present but unregistered	The engine folder exists on disk but isn’t registered with OPAL	Register Engine
Engine resolved loosely	Matched only by name/version, not an exact pinned path	Pin Engine

Reassigning or reinstalling the engine clears the warning. See also Remove & prune for what happens to pinned projects when you remove an engine.

4 - Project Settings

Pin an engine, override the build tool, and pass launch arguments per project.

Most build behaviour is configured once, globally, in Settings. A few things, though, belong to the individual project — OPAL keeps those in per-project settings, keyed to the project’s path.

Engine pin

Each project resolves to an engine. From the project’s settings you can pin it to a specific installed engine (the same relationship the status & health page describes recovering when it breaks).

Build tool override

Globally, OPAL uses one selected build tool (see Build Tools settings). A project can override that with its own build tool when it needs a different generator than your default — otherwise it inherits the global choice.

Launch arguments

Set extra command-line arguments to pass to the O3DE Editor when this project launches. Useful for project-specific flags without changing anything global.

Global vs per-project

CMake flags and build thread count are global settings that apply to all projects — they live in Build Tools settings, not here. Per-project settings are limited to the engine pin, the build-tool override, and launch arguments.