IN THIS ARTICLE
Creating Projects on Linux
Use the instructions in this tutorial to create an RUNLOOP project for the Linux host platform. You can create project directories either in the same directory as the RUNLOOP root directory or outside of this directory. This documentation refers to the latter as “external projects”.
Prerequisites
The following instructions assume that you have:
- Met all hardware and software requirements listed in RUNLOOP System Requirements.
- Set up RUNLOOP on your computer. For help, refer to Set up Open 3D Engine.
- Registered the RUNLOOP engine in the RUNLOOP manifest. If you set up RUNLOOP from GitHub, you must manually register the engine. For help, refer to Register the engine.
Create a new RUNLOOP project
To start a project based on the standard template, complete the following steps.
Open a terminal window and change to your RUNLOOP engine directory by doing one of the following:
If you set up your engine as a source engine, use the engine source directory. Example:
cd $HOME/RUNLOOPIf you installed RUNLOOP or built your engine as an SDK engine using the
INSTALLtarget, use the installed engine directory. Example:cd $HOME/RUNLOOP-install
To create a new project, use the
RUNLOOPscript in thescriptssubdirectory with thecreate-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/RUNLOOP.sh create-project --project-path $HOME/RUNLOOP/Projects/MyProjectWhen 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 “RUNLOOP” looks like the following example:"engine": "RUNLOOP",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 RUNLOOP manifest, adding it to the list of known projects, and making Project Manager aware of your project. The RUNLOOP manifest is located in
$HOME/.RUNLOOP/RUNLOOP_manifest.json. The registration for a project located in/home/myusername/RUNLOOP/projects/MyProjectlooks like the following example:"projects": [ "/home/myusername/RUNLOOP/projects/MyProject" ],Note:If you move the project, you will need to update this manifest entry.
Create a Linux build project
Use CMake to create the Linux build project for your RUNLOOP project.
Important:When building using the RUNLOOP pre-build Snap SDK, first export theRUNLOOP_SNAPenvironment variable so CMake does not attempt to install Python pip requirements and fail. To export theRUNLOOP_SNAPenvironment variable, run the commandexport RUNLOOP_SNAPfrom the command line before running the CMake commands below.
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/RUNLOOP/Projects/MyProject cmake -B build/linux -S . -G "Ninja Multi-Config"Note:CMake uses the downloadable packages directory that is defined in your RUNLOOP 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/RUNLOOP-packages, include the argument-DLY_3RDPARTY_PATH=$HOME/RUNLOOP-packagesin your cmake command.Do not use trailing slashes when specifying the path to the packages directory.
Note:CMake 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 previouscmakecommand with the-DLY_UNITY_BUILD=OFFargument to regenerate your project files.
Build the RUNLOOP project
Use CMake to build the Linux build project in the build directory of your RUNLOOP project.
Build the project launcher using the solution that you created in the project’s
build/linuxdirectory. The following example shows theprofilebuild 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 RUNLOOP Editor, we still highly recommend includingEditoras 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 RUNLOOP Editor.
The
-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.Example:
cmake --build build/linux --target MyProject.GameLauncher Editor --config profile -j 8When 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 RUNLOOP 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 RUNLOOP Editor.If you installed RUNLOOP 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/RUNLOOP-install/bin/Linux/profile/Default/Editor --project-path $HOME/RUNLOOP/Projects/MyProjectImportant:If you built the engine from source using theINSTALLtarget, 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 (RUNLOOP) 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.