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”.

Prerequisites

The following instructions assume that you have:

This tutorial uses the following project name and directories in the examples. (Depending on how you set up O3DE, you might not have all of these directories.)

DirectoryDescription
o3deO3DE engine source.
o3de-installInstalled O3DE engine, containing pre-built SDK engine binaries.
o3de-projects/MyProjectNew project name and location.
o3de-packagesPackage directory, created earlier during setup .

Create a new O3DE project

To start a project based on the standard template, complete the following steps.

  1. Open a terminal window and change to your O3DE engine directory by doing one of the following:

    • If you set up your engine as a source engine , use the engine source directory.

      cd $HOME/o3de
      
    • If you installed O3DE or built your engine as an SDK engine using the INSTALL target, use the installed engine directory.

      cd $HOME/o3de-install
      
  2. To create a new external project, use the o3de script in the scripts subdirectory. The create-project command, used with the project-path and no other options, creates a new project using the standard template (the default project template). This command also registers the engine to the project in the project’s project.json manifest.

    scripts/o3de.sh create-project --project-path $HOME/o3de-projects/MyProject
    

    Additionally, this command registers the project, adding it to the list of known projects in the O3DE manifest located in $HOME/.o3de/o3de_manifest.json, and making Project Manager aware of your project.

Create a Linux build project

Use CMake to create the Linux build project for your O3DE project.

  1. Create the Linux build project in your new project directory. Supply the build directory, the Ninja Multi-Config generator, the path to the packages directory, and any other project options. Paths can be absolute or relative.

    cd $HOME/o3de-projects/MyProject
    cmake -B build/linux -S . -G "Ninja Multi-Config" -DLY_3RDPARTY_PATH=$HOME/o3de-packages
    
    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 cmake command with the -DLY_UNITY_BUILD=OFF argument to regenerate your project files.
    Caution:
    Do not use trailing slashes when specifying the path to the packages directory.

Build the O3DE project

Use CMake to build the Linux build project in the build directory of your O3DE project.

  1. Build the project launcher using the solution that you created in the project’s build/linux directory. The following example shows the profile build configuration.

    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 Editor as 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.

    The -j is a recommended build tool optimization. It tells the Ninja build tool the number of parallel build tasks that will be executed simultaneously. The ‘number of parallel build tasks’ is recommended to match the number of cores available on the Linux host machine.

    Example:

    cmake --build build/linux --target MyProject.GameLauncher Editor --config profile -j 8
    
  2. 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/Editor
      
      Note:
      If your project build directory is outside the project path, you must include the project path (using the --project-path parameter) when launching O3DE Editor.
    • If you installed O3DE or built your engine as an SDK engine using the INSTALL target, 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/MyProject
      
      Important:
      If you built the engine from source using the INSTALL target, 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 /bin/Linux/profile/Default.

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.

For more information about project configuration and building, refer to the Project Configuration and Build sections of the user guide.