Skip to content

Running with a Standalone Environment from CLI

Running Schola from the command line interface (CLI) is a powerful way to interact with the system. This guide will walk you through the steps to run Schola from the CLI, including how to set up your environment and execute commands.

Building Your Environment

Before you can run a standalone executable from the Command-line with Schola, you need to build your environment into a standalone executable. This involves packaging your Unreal Engine project which is detailed in the official unreal engine documentation.

Running From CLI

Training CLIs nest an algorithm subcommand (for example ppo) and a simulator subcommand (editor, executable, or project). Simulator-specific options are merged into the same flag list (see CLI dataclass conventions).

Standalone executable

To launch a standalone environment (i.e. a game built in Development or Shipping mode), use the executable simulator and pass the path to your packaged binary:

schola sb3 train [ppo|sac] executable —executable-path <PATH_TO_EXECUTABLE>

Replace <PATH_TO_EXECUTABLE> with the path to your packaged Unreal Engine executable. To attach to an editor session that is already running, use editor instead of executable (no executable path required).

Project simulator

Use the project simulator when you want Schola to build (cook/package) your Unreal project and then launch the staged standalone game for training, instead of supplying an already packaged .exe. The runtime type is UnrealProject in project_simulator.py: it resolves a .uproject file, invokes Unreal Build Tool / RunUAT via the project’s engine association, then starts the built binary like UnrealExecutable.

Requirements

  • A full Unreal Engine install on the same machine so RunUAT / UBT can be discovered (see get_ubt_path / engine version detection in the project layout).

  • A path to the .uproject file on the CLI (the training dataclass validator expects a file; the Python class can also accept a directory containing a single .uproject).

Basic usage

schola sb3 train [ppo|sac] project —uproject-path <PATH_TO_UPROJECT>

Common options (same names as for executable where applicable)

  • --build-dir — Staging directory for the packaged build. If omitted, a temporary folder under the system temp directory is used (see UnrealProject construction in project_simulator.py).

  • --ubt-path — Explicit path to Unreal Build Tool / RunUAT if auto-detection from the project folder fails.

  • --map — Single map to cook and run. The implementation normalizes paths that contain /Content/ into Unreal /Game/... form and validates the result (see try_and_resolve_map). If you omit --map, the build cooks all maps and the game starts on the project default map.

  • --headless, --fps, --display-logs, --disable-script, --num-simulators — Same semantics as for the executable simulator (see the sections below). The current training CLI wires UnrealProject with use_cached_build=False (see UnrealProjectSimulatorConfig.make), so each training process triggers a full build step when you use project. Expect long startup times compared to executable or editor. If you already have a packaged binary, prefer executable; use project when you want a repeatable “build then train” path from source.

Headless Mode

Schola can be run in headless mode, which is useful for running scripts or automating tasks. To run Schola in headless mode, use the following command:

schola sb3 train [ppo|sac] executable —executable-path <PATH_TO_EXECUTABLE> —headless

This command will start Schola without the graphical user interface (GUI), allowing for accelerated simulation speeds.

Any features requiring rendering will not work when running in headless mode (e.g. UCameraSensor).

Fixed Simulation Timestep

Schola allows you to set a fixed frames per second (FPS) for the simulation. This can be useful for ensuring consistent performance across different runs. To set a fixed FPS, use the following command:

schola sb3 train [ppo|sac] executable —executable-path <PATH_TO_EXECUTABLE> —fps <FPS>

Replace <FPS> with the desired frames per second value. For example, to set the FPS to 30, use:

schola sb3 train [ppo|sac] executable —executable-path <PATH_TO_EXECUTABLE> —fps 30

The FPS determines the delta used when calculating updates in Unreal Engine, however the number of timesteps simulated per second is independent of this setting. For example if --fps 100 and Unreal simulates your environment at 1000fps then for every second in the real world, 10 seconds in the environment will be simulated.

Controlling The Map

Schola allows you to specify the map to load when launching the environment. To do this, use the —map argument followed by the path to the map. For example:

schola sb3 train [ppo|sac] executable —executable-path <PATH_TO_EXECUTABLE> —map <MAP_NAME>

The map should be specified as a relative path from the Content folder, with Content replaced by Game. For example /Content/LevelOne/Map would be specified as Game/LevelOne/Map.

The map must be a valid Unreal Engine map file. If the map is not found or isn’t specified, Schola will default to the main map specified in the project settings.

The map parameter will not work with Shipping builds by default, you need to take additional steps to allow the map to be loaded based on a command line flag.