Skip to content

cookbook

Jump to bottom
Loherangrin edited this page May 11, 2022 · 8 revisions

Cookbook

This page is a collection of O3Tanks commands that you can use in different scenarios. They are grouped by topic and accessed quickly by the following index:

Engines

Built-in gems

Local gems

Third-party gems

Projects

Others

Engines

Multiple installations of O3DE engine can exist on the same system. Each one is identified by an unique name (called version) that can be chosen arbitrary by the user. This must not be confused with the release number of O3DE engine (e.g. 2107.1, 2111.1, ...), since multiple versions may refer to the same engine release number.

Install a new engine version (from the main repository)

o3tanks install engine --tag <release_number> --as <engine_version>

If you want to use the latest source code, replace --tag option with --branch development

If you need a specific revision (e.g. for troubleshooting), replace --tag option with --commit <hash>

Engine is installed as sdk with profile config only. Please refer to Install a new engine version (using a specific build workflow) and Install a new engine version (using a specific configuration) if you need a different combination

Install a new engine version (from a fork)

o3tanks install engine --fork <github_username>/<project_name> --branch <branch_name> --as <engine_version>

Fork is a copy repository of the main one on GitHub. If you are using a generic GIT repository on a different host, please replace --fork option with: --repository <url>

Engine is installed as sdk with profile config only. Please refer to Install a new engine version (using a specific build workflow) and Install a new engine version (using a specific configuration) if you need a different combination

Install a new engine version (from an existing installation)

The following steps allow to save bandwidth when an engine installation already exists on the system. Only missing/updated files are downloaded from the main repository, but it requires to build everything from scratch.

cp --archive <data_dir>/o3tanks-source_<existing_version> <data_dir>/o3tanks-source_<new_version>

cd <data_dir>/o3tanks-source_<new_version>
git checkout <new_release_number>

o3tanks install engine --tag <new_release_number> --as <new_version> --force

Engine is installed as sdk with profile config only. Please refer to Install a new engine version (using a specific build workflow) and Install a new engine version (using a specific configuration) if you need a different combination

Install a new engine version (using a specific build workflow)

A build workflow defines how the engine is related to its linked projects, affecting the behavior of build commands and where their output binaries are stored.

  • All projects are built inside the engine:
o3tanks install engine --engine-centric <other_installation_options>
  • The engine is built inside each project:
o3tanks install engine --project-centric/engine-source <other_installation_options>
  • The engine is built only once and each project links against it (as a SDK). It is recommended for daily usage and it is the default option when none is provided:
o3tanks install engine --project-centric/engine-prebuilt <other_installation_options>

Install a new engine version (using a specific configuration)

A configuration defines which optimizations the compiler must apply while installing the engine.

  • No optimizations and add debug symbols:
o3tanks install engine --config debug <other_installation_options>
  • Non-aggressive optimizations and add debug symbols. It is recommended for daily usage and it is the default option when none is provided:
o3tanks install engine --config profile <other_installation_options>
  • Non-aggressive optimizations and no debug symbols:
o3tanks install engine --config release <other_installation_options>

Add a configuration to an engine version

o3tanks install engine --config <new_config> --as <engine_version> --force <first_installation_options>

In <first_installation_options> must be provided all options that were used to get the engine from at its first installation, i.e. one or more from --tag <release>, --branch <name>, --commit <hash>, --repository <url>, --fork <username>/<project>, --workflow <build_workflow>

Duplicate an existing engine version

Following steps allow to create a new engine installation without downloading and building any file.

cp --archive <data_dir>/o3tanks-source_<existing_version> <data_dir>/o3tanks-source_<new_version>
cp --archive <data_dir>/o3tanks-build_<existing_version> <data_dir>/o3tanks-build_<new_version>
cp --archive <data_dir>/o3tanks-install_<existing_version> <data_dir>/o3tanks-install_<new_version>

Show installed engine versions

o3tanks list

Upgrade an engine version

o3tanks refresh engine <engine_version>
o3tanks upgrade engine <engine_version>

If the version is tracking a release number (e.g. it was installed using --tag option), only fixes for that specific release would be installed (e.g. 2111.1.0 > 2111.1.5). To upgrade to a newer major release (e.g. 2111.1.x > 2205.1.x), please follow the steps at Install a new engine version (from an existing installation) and then Switch the linked engine version for any project that must be upgraded.

If the version is tracking development, all latest files will be installed and no other actions are required.

Uninstall an engine version

o3tanks uninstall engine <engine_version>

Built-in gems

Built-in gems are included in the engine source code. They provide the main features of O3DE such as rendering (Atom), input handling, script canvas, etc.

Activate a built-in gem

cd <project_dir>
o3tanks add gem engine/<gem_name>

Project will be rebuilt automatically. Append --no-rebuild option to do it later manually

Disable a built-in gem

cd <project_dir>
o3tanks remove gem engine/<gem_name>

Project will be rebuilt automatically. Append --no-rebuild option to do it later manually

Local gems

Local gems are workspaces that you can create anywhere on your filesystem to develop a new gem. They can contain assets, source code or both.

Create a new local gem

mkdir <gem_dir>
cd <gem_dir>
o3tanks init gem --type <gem_type> --as <gem_name>

The new gem will be embedded in a preconfigured workspace to simplify its future release. It contains a sample project (to try and show the gem features), a readme with installation instructions and other boilerplate. Append --no-project option if you want to create gem files only.

Activate a local gem

cd <project_dir>
o3tanks add gem <gem_dir>

Project will be rebuilt automatically. Append --no-rebuild option to do it later manually

Disable a local gem

cd <project_dir>
o3tanks remove gem <gem_dir>

Project will be rebuilt automatically. Append --no-rebuild option to do it later manually

Third-party gems

Third-party gems are published by other developers (e.g. indie, companies, etc...). They provide advanced features that aren't included in the main release of O3DE and can be downloaded from any external Git repository.

Install a third-party gem

o3tanks install gem https://<gem_repository_url>.git --as <gem_version_name>

If you don't provide the gem version name, it will be calculated automatically from the last part of the repository URL.

Activate a third-party gem

cd <project_dir>
o3tanks add gem <gem_version_name>

Project will be rebuilt automatically. Append --no-rebuild option to do it later manually

Disable a third-party gem

cd <project_dir>
o3tanks remove gem <gem_version_name>

Project will be rebuilt automatically. Append --no-rebuild option to do it later manually

Show installed gems

o3tanks list

Uninstall a third-party gem

o3tanks uninstall gem <gem_version_name>

Projects

A project contains all assets, configurations and source files that define a runnable application in O3DE. It is linked to a specific engine version, which is automatically checked for existence at each command and can be switched manually by the user.

Create a new empty project

mkdir <project_dir>
cd <project_dir>
o3tanks init project --as <project_name> --engine <engine_version>

If you want to activate only the minimum set of required gems, append --minimal option at the end of the command.

Install an existing project (from a repository)

mkdir <project_dir>
cd <project_dir>
o3tanks install project <repository_url>

If the project contains a O3Tanks settings file, it will ask to install all dependencies (engine, gems, ...) automatically

Open a project in the scene editor

Build required libraries (only once after the the project creation, or anytime that project source files are changed):

cd <project_dir>
o3tanks build tools

Then:

o3tanks open editor

Run a single-player project

Build the project launcher (only once after the the project creation, or anytime that project source files are changed):

cd <project_dir>
o3tanks build client

Then:

o3tanks run client

Run a single-player project (from a specific level)

Build the project launcher (only once after the the project creation, or anytime that project source files are changed):

cd <project_dir>
o3tanks build client

Then:

o3tanks run client --level <level_name>

<level_name> is one of the directory names that you can find inside <project_dir>/Levels directory.

Run a multiplayer project in a container network

Following steps requires that containerization mode is active.

Create a new container network according to your needs (internal only, with internet access, etc.)

docker network create <your_options> <network_name>

Build all required binaries (only once after the the project creation, or anytime that project source files are changed):

cd <project_dir>
o3tanks build tools
o3tanks build client
o3tanks build server
o3tanks build assets

Run the server:

export O3TANKS_NETWORK=<network_name>
o3tanks run server

You can change the listening port appending --listen <port>. If you are using a console file to set the starting behavior, it won't be loaded automatically anymore and you have to append --console-command exec[server.cfg] too.

Open a new terminal session for each client:

export O3TANKS_NETWORK=<network_name>
o3tanks run client --connect

By default the server opens a window to show the current scene for debugging / troubleshooting. If you need an headless instance (e.g. running on a remote server), set the following environment variable export O3TANKS_GPU=none before running the run command

Clean built files (for source code)

cd <project_dir>
o3tanks clean --build

All available configurations will be cleaned. If you need to limit to a specific one, append --config <config_name>

If the project is corrupted, append --force to restore it to a valid state

Clean cached files (for assets)

cd <project_dir>
o3tanks clean --cache

Show the active gem versions

cd <project_dir>
o3tanks settings

Show the linked engine version

cd <project_dir>
o3tanks settings

Switch the linked engine version

cd <project_dir>
o3tanks clean --force
o3tanks open editor --engine <new_engine_version>

Export a single-player project to an archive (all levels)

cd <project_dir>
o3tanks export client

The filename is generated automatically according to your project name. Append --as <name> to define a new one.

The file extension is calculated automatically according to your operating system. On Windows is set to .zip, whereas Linux and MacOS uses .tar.gz. Append --type <extension> if you need to force a specific archive type.

Export a single-player project to an archive (only a single level)

cd <project_dir>
o3tanks export client --level <level_name>

The filename is generated automatically according to your project name. Append --as <name> to define a new one.

The file extension is calculated automatically according to your operating system. On Windows is set to .zip, whereas Linux and MacOS uses .tar.gz. Append --type <extension> if you need to force a specific archive type.

Export a single-player project to an archive (re-using an existing build)

cd <project_dir>
o3tanks export client --no-build --no-process

The filename is generated automatically according to your project name. Append --as <name> to define a new one.

The file extension is calculated automatically according to your operating system. On Windows is set to .zip, whereas Linux and MacOS uses .tar.gz. Append --type <extension> if you need to force a specific archive type.

Export a multiplayer project to a container image

Following steps requires that containerization mode is active.

cd <project_dir>
o3tanks export server --as <image_name> --type container

The resulting container image is already configured to run as an headless dedicated server. Its behavior can be customized appending any additional console variables to the command used to start the container. For instance, to listen on a specific address:

docker run -it --network <network_name> --ip <server_ip> <...> <image_name> +sv_port <server_ip> +host

Note: The resulting container image don't contain any security setting. It isn't intended for running in a production environment!

Select assets to be exported

Previous export commands regenerate two pack files (game_<platform>.pak and engine_<platform>.pak) at each execution. If you need a more fine-grained control over exported assets, you can open Asset Bundler using:

o3tanks export assets

Follow O3DE official documentation for instructions about how to generate pak files using the graphical interface. Then, export the project injecting the new bundles:

cd <project_dir>
o3tanks export client --bundle <new_bundle_1> --bundle <new_bundle_2> <...>

Others

Activate containerized mode

export O3TANKS_NO_CONTAINERS=0

This is the default setting on Linux. Not available yet on Windows and MacOS

Activate hybrid mode (limited containers)

export O3TANKS_NO_CONTAINERS=0
export O3TANKS_NO_CLI_CONTAINER=1

Not available yet on Windows and MacOS

Activate native mode (no containers)

export O3TANKS_NO_CONTAINERS=1

This is the only available mode on Windows and MacOS. It is active by default oh these operating systems

Change the storage directory (for engines and gems)

Following steps requires that native mode is active.

export O3TANKS_DATA_DIR=<absolute_filesystem_path>

Force a container OS

Following steps requires that containerization mode is active.

export O3TANKS_CONTAINER_OS=<distro_name>:<distro_version>

Supported distro are:

  • arch
  • debian
  • fedora
  • open-suse
  • ubuntu

If not provided, the suggested operating system ubuntu:20.04 is used for all containers

Force a GPU card

Following steps requires that containerization mode is active.

  • Low-power consumption card for common applications
export O3TANKS_GPU=integrate
  • Dedicated card for 3D graphics
export O3TANKS_GPU=discrete

If not provided, the tool will try automatically to find the most suitable card for the current command

Run in headless mode

Following steps requires that containerization mode is active.

export O3TANKS_DISPLAY=none
Clone this wiki locally