Getting Started

Index

Prerequisites

  • Installation completed and tested as described in Installation and Quickstart homepage sections
  • ROMs downloaded and placed all in the same folder, whose absolute path will be referred in the following as /absolute/path/to/roms/folder/

To avoid specifying ROMs path at every run, you can define the environment variable DIAMBRAROMSPATH=/absolute/path/to/roms/folder/, either temporarily in your current shell/prompt session, or permanently in your profile (e.g. on linux in ~/.bashrc).

Running the Environment

Basic Script

The most straightforward and simple script to use DIAMBRA Arena is reported below. It features a random agent playing Dead Or Alive ++, and it represents the general interaction schema to be used for every game and context of DIAMBRA Arena.

#!/usr/bin/env python3
import diambra.arena

if __name__ == '__main__':

    env = diambra.arena.make("doapp")
    observation = env.reset()

    while True:
        env.render()

        actions = env.action_space.sample()

        observation, reward, done, info = env.step(actions)

        if done:
            observation = env.reset()
            break

    env.close()

More complex and complete examples can be found in the Examples section.

DIAMBRA Command Line Interface (CLI)

DIAMBRA Arena comes with a very handy tool: the DIAMBRA Command Line Interface (DIAMBRA CLI). It provides different useful commands, with related options, that contribute to make running DIAMBRA Arena environments super easy.

The main use of the CLI is running a command after brining up DIAMBRA Arena containerized environment(s). It sets the DIAMBRA_ENVS environment variable to list the endpoints of all running environments.

Usage:

diambra run [flags] <command-to-execute>

The only flag needed for simple executions is listed below. Advanced usage and options can be found in the CLI Advanced Options section below.

FlagTypeDescription
-r, --path.romsstrPath to ROMs (default to DIAMBRAROMSPATH env var if set)
Script Execution

To run a python script using the CLI, one can just execute the following command:

diambra run -r /absolute/path/to/roms/folder/ python diambra_arena_gist.py

This will start a new container with the environment, load in the DIAMBRA_ENVS environment variable the port on which the environment accepts connections, and run the script where the DIAMBRA Arena python module is imported and used to instantiate a new environment, that will automatically retrieve the port and connect to it.

Advanced Usage

In what follows, we will omit the -r flag for the CLI, assuming the user has set the DIAMBRAROMSPATH environment variable in his system.

DIAMBRA CLI Advanced Options
Run Command

Usage:

diambra run [flags] <command-to-execute>

It runs a command after brining up DIAMBRA Arena containerized environment(s). It sets the DIAMBRA_ENVS environment variable to list the endpoints of all running environments.

The next snippet shows the help message for this command, where all available options are reported:

Version: 0.0.14
Usage:
  diambra run [flags] command [args...]

Flags:
  -a, --agent.image string        Run given agent command in container
  -l, --engine.lockfps            Lock FPS
  -g, --engine.render             Render graphics server side
      --engine.sound              Enable sound
  -x, --env.autoremove            Remove containers on exit (default true)
      --env.containerip           Use <containerIP>:<containerPort> instead of <env.host/localhost>:<hostPort>
      --env.host string           Host to bind ports on (default "127.0.0.1")
      --env.image string          Env image to use, omit to detect from diambra-arena version
      --env.mount strings         Host mounts for env container (/host/path:/container/path)
      --env.preallocateport       Preallocate port for env container. Workaround for port conflicts on Windows
  -s, --env.scale int             Number of environments to run (default 1)
      --env.seccomp string        Path to seccomp profile to use for env (may slow down environment). Set to "" for runtime's default profile. (default "unconfined")
  -h, --help                      help for run
  -n, --images.no-pull            Do not try to pull image before running
      --init.image string         Init image to use (default "ghcr.io/diambra/init:main")
  -i, --interactive               Open stdin for interactions with arena and agent (default true)
      --path.credentials string   Path to credentials file (default "$HOME/.diambra/credentials")
  -r, --path.roms string          Path to ROMs (default to DIAMBRAROMSPATH env var if set)

Global Flags:
  -d, --log.debug           Enable debug logging
      --log.format string   Set logging output format (logfmt, json, fancy) (default "fancy")

Currently, the -g, --engine.render option to render graphics server side, is only available for Linux systems. For additional info and for Windows/MacOS alternatives, see Environment Native Rendering section below.

Arena Command

Usage:

diambra arena [flags] [command]

It brings up DIAMBRA Arena containerized environment(s) and returns to the terminal output the endpoints of all running environments.

The snippet below lists all available commands for this mode.

Flags reported for the Run command above apply also to this mode.

Version: 0.0.14
Usage:
  diambra arena [command]

Available Commands:
  check-roms  check roms
  down        Stop DIAMBRA Arena
  list-roms   list roms
  status      Show status of DIAMBRA arena
  up          Start DIAMBRA arena
  version     version

Flags:
  -h, --help   help for arena

Global Flags:
  -d, --log.debug           Enable debug logging
      --log.format string   Set logging output format (logfmt, json, fancy) (default "fancy")
Using Python Notebooks

DIAMBRA Arena can also be used inside python notebooks. There are two options to do it, explained here after.

The most straightfoward one is to launch Jupyter Notebook through the CLI as shown by the next command:

diambra run jupyter notebook

This step is needed to boot up the environment container and load its connection port in the DIAMBRA_ENVS environment variable. This variable is thus accessible from within Jupyter Notebook, that looks like the following one:

View in full screen

If one wants to execute a notebook from somewhere else (for example from inside Visual Studio Code), it is not possible to leverage the DIAMBRA_ENVS environment variable for passing the connection port information. In such cases, one should activate the environment container and retrieve its port, and this can be done by means of the CLI command diambra arena up that returns the port address, as shown below:

diambra arena up
Server listening on 0.0.0.0:50051
127.0.0.1:49153

This information is then passed to the make function of DIAMBRA Arena through the setting "env_address" as shown in the next jupyter notebook:

View in full screen

Once done, one can stop running container(s) as follows:

diambra arena down
(bb1a) stopping container
Environment Native Rendering

It is possible to activate emulator native rendering while running environments (i.e. bringing up the emulator graphics window). The CLI provides a specific flag for this purpose, but currently this is supported only on Linux, while Windows and MacOS users have to configure a Xserver and link it to the environment container. The next tabs provide hints for each context.

On Linux, the CLI allows to render emulator natively on the host, the user only needs to add the -g flag to the run command, as follows:

diambra run -g python diambra_arena_gist.py

Activating emulator native rendering will open a GUI where the game executes. Currently, this feature is affected by a problem: the mouse cursor disappears and remains constrained inside such window. To re-aquire control of the OS Xserver, one can circle through the active windows using the key combination ALT+TAB and highlight a different one.

To run environments with native emulator GUI support on Windows, currently requires the user to setup a virtual XServer and connect it to the container. We cannot provide support for this use case at the moment, but we plan to implement this feature in the near future.

A virtual XServer that in our experience proved to be effective is VcXsrv Windows X Server.

To run environments with native emulator GUI support on MacOS, currently requires the user to setup a virtual XServer and connect it to the container. We cannot provide support for this use case at the moment, but we plan to implement this feature in the near future.

A virtual XServer that in our experience proved to be effective is XQuartz 2.7.8 coupled to socat that can be installed via brew install socat.

Running Multiple Environments in Parallel

It can be useful to run multiple environment instances in parallel, for example for Deep RL training. The CLI provides a flag to control this, it can be used both by the run and the arena commands. The former will load a string in the DIAMBRA_ENVS environment variable where connection addresses are listed and separated by a space, while the latter will print out in the terminal the same string. These values can then be used properly to setup multiple parallel connections.

Running a script after having started 16 containers:

diambra run -s=16 python training_script.py

Starting 4 containers and printing their addresses in the terminal:

diambra arena -s=4 up
Server listening on 0.0.0.0:50051
127.0.0.1:49154 127.0.0.1:49155 127.0.0.1:49156 127.0.0.1:49157
Run DIAMBRA Engine without CLI

Agents connect via network using gRPC to DIAMBRA Engine running in a Docker container. The diambra CLI’s run command starts the DIAMBRA Engine in a Docker container and sets up the environment to make it easy to connect to the Engine. For troubleshooting it might be useful to run the Engine manually, using host networking.

Creating the ~/.diambra and ~/.diambra/credentials is only needed when you never ran the diambra CLI before. Otherwise this step can be skipped.

Start Engine
mkdir ~/.diambra
touch ~/.diambra/credentials

docker run -d --rm --name engine \
  -v $HOME/.diambra/credentials:/tmp/.diambra/credentials \
  -v /absolute/path/to/roms/folder/:/opt/diambraArena/roms \
  --net=host docker.io/diambra/engine:v2.1
mkdir %userprofile%/.diambra
echo > %userprofile%/.diambra/credentials

docker run --rm -ti --name engine ^
  -v %userprofile%/.diambra/credentials:/tmp/.diambra/credentials ^
  -v %userprofile%/.diambra/roms:/opt/diambraArena/roms ^
  --net=host docker.io/diambra/engine:v2.1
mkdir $Env:userprofile/.diambra
echo "" > $Env:userprofile/.diambra/credentials

docker run --rm -ti --name engine `
  -v $Env:userprofile/.diambra/credentials:/tmp/.diambra/credentials `
  -v $Env:userprofile/.diambra/roms:/opt/diambraArena/roms `
  --net=host docker.io/diambra/engine:v2.1
Connect to Engine

Now you can run the script that uses DIAMBRA Arena by opening a new terminal and setting DIAMBRA_ENVS environment variable followed by the python command:

DIAMBRA_ENVS=localhost:50051 python ./script.py