/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).
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 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.
| Flag | Type | Description |
|---|---|---|
-r, --path.roms | str | Path to ROMs (default to DIAMBRAROMSPATH env var if set) |
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.
In what follows, we will omit the -r flag for the CLI, assuming the user has set the DIAMBRAROMSPATH environment variable in his system.
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.
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")
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:
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:
Once done, one can stop running container(s) as follows:
diambra arena down
(bb1a) stopping container
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.
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
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.
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
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