IN THIS ARTICLE
Creating Projects on Linux
Use the instructions in this tutorial to create an O3DE project for the Linux host platform. You can create project directories either in the same directory as the O3DE root directory or outside of this directory. This documentation refers to the latter as “external projects”.
The following instructions assume that you have:
- Met all hardware and software requirements listed in O3DE System Requirements.
- Set up O3DE on your computer. For help, refer to Set up Open 3D Engine.
- Registered the O3DE engine in the O3DE manifest. If you set up O3DE from GitHub, you must manually register the engine. For help, refer to Register the engine.
To start a project based on the standard template, complete the following steps.
Open a terminal window and change to your O3DE engine directory by doing one of the following:
To create a new project, use the
o3descript in the
scriptssubdirectory with the
create-projectcommand. Supply an absolute or relative path to the directory where you want to create your new project using the
--project-pathargument. The last component of the path will become the project name, unless you override it with the
--project-nameargument. The script will create a new project using the standard template (the default project template).
scripts/o3de.sh create-project --project-path $HOME/O3DE/Projects/MyProject
When creating a project, this command also makes two important registrations:
It associates your project with an engine by registering the engine in the project’s
project.jsonmanifest, using the engine’s registered name. You can find this manifest in the project’s root directory. The registration for an engine named “o3de” looks like the following example:
"engine": "o3de",Note:If you change the engine’s registered name, or wish to use a different engine with the project, you will need to update this manifest entry.
It registers the project in the O3DE manifest, adding it to the list of known projects, and making Project Manager aware of your project. The O3DE manifest is located in
$HOME/.o3de/o3de_manifest.json. The registration for a project located in
/home/myusername/O3DE/projects/MyProjectlooks like the following example:
"projects": [ "/home/myusername/O3DE/projects/MyProject" ],Note:If you move the project, you will need to update this manifest entry.
Use CMake to create the Linux build project for your O3DE project.
Create the Linux build project in your new project directory. Supply the build directory, the project source directory, the Ninja Multi-Config generator, and any other project options. Paths can be absolute or relative. Example:
cd $HOME/O3DE/Projects/MyProject cmake -B build/linux -S . -G "Ninja Multi-Config"Note:
CMake uses the downloadable packages directory that is defined in your O3DE manifest with
default_third_party_folder. You can specify a different directory to use by including the
-DLY_3RDPARTY_PATHargument. For example, if you created the package directory in
$HOME/o3de-packages, include the argument
-DLY_3RDPARTY_PATH=$HOME/o3de-packagesin your cmake command.
Do not use trailing slashes when specifying the path to the packages directory.Note:CMake unity builds are on by default. This is a CMake feature that can greatly improve build times by merging source files into single compilation units. If you encounter a build error, disabling unity builds might help debug the problem. To disable unity builds, run the previous
cmakecommand with the
-DLY_UNITY_BUILD=OFFargument to regenerate your project files.
Use CMake to build the Linux build project in the build directory of your O3DE project.
Build the project launcher using the solution that you created in the project’s
build/linuxdirectory. The following example shows the
cmake --build build/linux --target MyProject.GameLauncher Editor --config profile -j <number of parallel build tasks>Important:When building the project for a pre-built SDK engine, even though you aren’t building O3DE Editor, we still highly recommend including
Editoras a build target. While the GameLauncher doesn’t depend on the Editor target, some Gems do. If you leave off the Editor target, those Gems aren’t included in the build.
When building the project for a source engine, you build the Asset Processor and Project Manager too, since they are dependencies of O3DE Editor.
-jis a recommended build tool optimization. It tells the Ninja build tool the number of parallel build tasks that will be executed simultaneously. The value for ’number of parallel build tasks’ is recommended to match the number of cores available on the Linux host machine.
cmake --build build/linux --target MyProject.GameLauncher Editor --config profile -j 8
When the build is complete, you can find the project binaries in the project directory under
build/linux/bin/profile. To verify that the project is ready to use, run O3DE Editor by doing one of the following:
If you set up your engine as a source engine, run the Editor from the project build directory.
build/linux/bin/profile/EditorNote:If your project build directory is outside the project path, you must include the project path (using the
--project-pathparameter) when launching O3DE Editor.
If you installed O3DE or built your engine as an SDK engine using the
INSTALLtarget, run the Editor from the installed engine’s build directory. (If you don’t supply the project path, Project Manager launches instead.) The project path can be absolute or relative to the engine directory.
$HOME/o3de-install/bin/Linux/profile/Default/Editor --project-path $HOME/O3DE/Projects/MyProjectImportant:If you built the engine from source using the
INSTALLtarget, make sure that you launch the Editor and other tools from the installed engine’s build directory, not the engine’s build directory. The Linux install directory typically ends in
You can also run Project Manager (
o3de) from the same directory to edit your project’s settings, add or remove Gems from the project, rebuild your project, and launch the Editor.
Caution:When you launch the Editor, the Asset Processor from the same directory will also launch. To launch the Editor from a different directory, you must close any Asset Processor tasks that are running.