get started - loherangrin/o3tanks GitHub Wiki

Get started

Thank you for your interest in O3Tanks! This page will provide you step-by-step instructions to install the tool and to manage your first O3DE project. Let's get started!

1. Introduction

Before starting, let's see what is O3Tanks and why it can simplify your daily workflow for game development. If you already know it, you can skip to the next chapter.

O3DE (Open 3D Engine) is a multi-platform 3D engine to build AAA games and high-fidelity simulations. Based on a modular architecture, it can be integrated into projects in several ways (e.g. engine-centric vs project-centric workflows). Moreover, thanks to its open source nature, the engine can be forked, customized and remixed as you want!

All these possibilities imply that a simple version number such as x.y.z may not be enough to track which O3DE-derived engine a project depends on. A first attempt could be to add the engine as a sub-module of the project repository. But the more projects share the same engine, the more space is required on your machine to clone and build the same code. And it could get worse: if a project requires to apply a custom patch to the engine, you probably need to create another copy for that patched engine only, needing to maintain and document all additional instructions to use that custom engine version.

O3Tanks tries to address all of these issues. As a version manager, it allows to install multiple versions of the engine, downloading and building the source code automatically. When you create / edit an O3DE project, O3Tanks saves all information about the required engine (e.g. version, repository address, branch, ...) into a text file in the project directory, so that it can be stored in its repository along the project source files. Other team members that clone the project repository will be instructed by O3Tanks about the required engine version and, if they don't have it, O3Tanks will download and install it automatically for them.

But there is more: O3Tanks exposes a set of minimal commands to execute non-trivial actions, such as installing an engine version from a personal fork, build a project runtime or add a new object into a project. Each command has several options to tailor its behavior to different scenarios.

Last but not least, O3Tanks is able to run most of its features inside containers, which are isolated execution instances (see Docker overview for more details). This architecture minimizes dependencies with your machine, easing the creation of portable development environments for your team or its addition into your CI/CD pipeline to automate development actions (e.g. building, testing).

2. Install O3Tanks

O3Tanks can be executed in three different modes to address several scenarios. Before continuing, it's important that you choose which is more suitable for you:

  • containerized mode (Linux only): O3Tanks and O3DE are built and run in containers, avoiding to install any dependency on your machine. Project files are mounted into containers on demand. This mode is suggested for non-technical users, or for who needs a reproducible development environment across all team members, or for who is running a distro which isn't supported by O3DE.
  • hybrid mode (Linux only): similar to the previous mode, except cli component of O3Tanks is running on the host machine. This mode gives an extra boost on low-spec computers since communications between containers are halved. It is suggested only if you are experiencing bad performance with the containerized mode.
  • native mode (Linux, MacOS, Windows): containers are disabled and all components work directly on the host machine. This mode gives fastest performance, however all build dependencies must be installed on the host machine. This is suggested for advanced users, or for who cannot use containers (e.g. unsupported operating system, pre-configured machine, limited privileges, ...).

Note: Don't worry if you cannot choose one mode at this time. You are free to change it anytime after the first installation. However, at each mode change, engines data must be migrated manually to the new required pathes.

After choosing your preferred execution mode, verify you meet its system requirements:

  • containerized mode:
    • Docker Engine 19.03 (or greater), both root and rootless mode are supported. See official documentation for installation details.
    • If you have a NVIDIA GPU, proprietary drivers and NVIDIA Container Toolkit are required to open graphics runtimes (e.g. editor). See official documentation for installation details.
  • hybrid mode:
    • The same points of containerized mode, plus Python 3.8 (or greater).
  • native mode:
    • Python 3.8 (or greater). See official site for more details.
    • pygit2 1.6.1 (or greater). See official documentation for installation details.
    • all O3DE prerequisites to build from sources. See official documentation according to your operating system:

Note: O3Tanks will check requirements too. If you don't know if or how to satisfy one of the previous points, just go ahead and O3Tanks will suggest you how to install the missing ones.

Open a new shell session (terminal) and clone this repository into a directory of your choice:

git clone https://github.com/loherangrin/o3tanks.git --branch stable <YOUR_O3TANKS_DIR>

Note: Use the the main branch instead of stable to try out the latest features.

Note: If you don't have a git client, you can also download the source code using the Releases page or pressing the green Code button in the main page.

Register o3tanks globally to be accessible from any location, like any other system command.

  • On Linux or MacOS, create a symbolic link in a valid $PATH location:
sudo ln -s <YOUR_O3TANKS_DIR>/o3tanks.sh /usr/local/bin/o3tanks
  • On Windows, add the installation directory to PATH in your System > Environment Variables.

Activate the preferred execution mode, changing your global preferences:

  • on Linux or MacOS, set permanent environment variables as new lines in your shell configuration file (e.g. .bashrc).
  • on Windows, add new entries in the dialog in System > Environment Variables.

Note: On Linux containerized mode is active by default, whereas on Windows and MacOS native mode. If you have chosen the default mode, you can skip this step.

Following values can be used:

  • for containerized mode:
O3TANKS_NO_CONTAINERS=0
  • for hybrid mode:
O3TANKS_NO_CLI_CONTAINER=1
  • for native mode:
O3TANKS_NO_CONTAINERS=1
O3TANKS_DATA_DIR=<choose_a_directory>

Note: The last variable can be omitted. In that case, all engine data will be stored in a default directory under your user profile.

3. Install an O3DE version

Add a new O3DE version using install command. In this case, you will download the latest version of the engine source code from the official repository:

o3tanks install engine --as development

Note: O3DE supports three different installation setups, which define how the engine is related to its projects. O3Tanks will install the most convenient one for a daily use (i.e. project-centric with a pre-built engine). If you need a different setup, pass --engine-centric or --project-centric/engine-source options in the previous command.

In containerized and hybrid modes, since this is the first time, O3Tanks will build the container images that are needed for its execution (builder, cli, updater). This process may take several minutes, but it is required only once.

When the images are ready, the engine installation is resumed. The source code is downloaded and built automatically with profile configuration. A confirmation message will be shown when the installation is completed.

Note: In containerized and hybrid modes, engine files are stored inside volumes, which are mounted automatically when a container starts. Since it may run as a different user than the one on your host machine, O3Tanks tries to adjust volumes permissions accordingly. If it isn't running with privileged grants (root), it will show you a list of commands to be launched manually.

You can verify that the engine version is installed correctly showing its details with list command:

o3tanks list

4. Initialize a new project

You are ready for your first O3DE project. Create a new empty directory and enter in it:

mkdir <YOUR_WORKSPACE_DIR>/my_project
cd <YOUR_WORKSPACE_DIR>/my_project

Then, initialize the project using init command. You must supply the engine version to bind and, if you want, an alternative name for the project. This may be useful if you are using different naming conventions between the project source code and your filesystem (in this example, snake_case is used for the filesystem and CamelCase for the project code). If not provided, the directory name will be used by default:

o3tanks init project --as MyProject --engine development

5. Develop the project

You need to open the editor to develop a scene in your O3DE project. Use the open command (requires O3Tanks v0.2.0 or greater):

o3tanks open

O3Tanks will start to build the dynamic libraries that are required to launch the editor. This operation is performed automatically only the first time that you open a project, or after cleaning its intermediate files.

If you plan to edit C++ files of the engine or the project, you will need to force a rebuild manually prior opening the editor. You can use build command:

o3tanks build tools

How to populate a scene with entities and components is out-of-scope for this guide. Please refer to the official documentation for more details about the editor.

6. Run the project

To try out your project as a standalone application, you need to compile the source code first. Use the build command, specifying which runtime you want to create:

  • client - Standard application (requires O3Tanks v0.2.0 or greater).
  • server - Dedicated application without audio and rendering capabilities. It is mean for multiplayer servers.

You can also select the optimization level to be used, appending --config option:

  • debug - No optimizations and debug symbols.
  • profile - Non-aggressive optimizations and debug symbols.
  • release - Non-aggressive optimizations and no debug symbols. If not provided, profile will be used by default.
o3tanks build client

When the operation is completed, you can use run command to execute the built binary:

o3tanks run client

Note: In containerized and hybrid modes, at the first run, O3Tanks will build the remaining container image (runner). This process may take several minutes, but it is required only once.

7. Review the bound engine version

Note that the previous commands doesn't require to provide the engine version. In fact, at the project initialization time, O3Tanks creates an hidden directory .o3tanks in the project root where it stores the bind with the chosen engine version.

You can review this value using settings command to display all the settings that are related to the current project:

o3tanks settings

If you want to bind the project to another engine version, you can edit its settings to point to the new one:

o3tanks settings --clear engine.id
o3tanks settings engine.repository http://localhost/my_custom_engine.git
o3tanks settings engine.branch main

When you launch again a command on the project, O3Tanks will verify if the new engine version exists and will suggest you to install it using a new name:

o3tanks run client

  The engine for this project is not installed, but it is available at:
  http://localhost/my_custom_engine.git#main

  Do you want to install it? [y/n]

8. Update an O3DE version

O3DE is under development and new changes are released frequently, so your local copy may soon become out-of-date.

You can check if there are new updates using refresh command. Please provide the engine version as argument, in this example development:

o3tanks refresh engine development

If there is at least one update, you can apply it using the upgrade command. It will download all new changes from the repository where the engine version was cloned from and it rebuild all the related installations automatically. The operation may take several minutes:

o3tanks upgrade engine development

9. Update O3Tanks

O3Tanks is under development too! There are many new features to be released in the next months, so to be sure not to miss them you can check regularly using refresh command with the special keyword self:

o3tanks refresh self

When an update is available, you can apply it using upgrade command with the special keyword self:

o3tanks upgrade self

Note: In containerized and hybrid modes, images need to be re-built after each upgrade. This operation is delayed to the next O3Tanks execution. If you want to force it immediately, try to run a view-only command such as list or settings.

10. What's next?

This is only a quick tour through the main features of O3Tanks. You can go deeper reading:

  • Overview - Describe O3Tanks architecture and how it works under the hood.
  • Cookbook - Instructions to use O3Tanks in several common scenarios.
  • CLI reference - Describe all available commands and their options.
  • Contributing Guidelines - How you can contribute to this project.