-
Notifications
You must be signed in to change notification settings - Fork 3
RefBox Basic Usage Guide
This guide assumes you are setting up the RCLL Refbox and related tools using the rcll-get-started repository. The setup process relies on Docker and Docker Compose to simplify running the Refbox and its web-based frontend. Key tasks, such as starting and stopping the Refbox, are managed through a set of predefined commands. Configuration is highly flexible and can be customized via environment variables.
We also assume you are comfortable with basic terminal operations and editing configuration files. If you're new to Docker or screen, we recommend reviewing their documentation first.
The rcll-get-started repository simplifies managing the RCLL Refbox and related tools through a set of predefined commands. These commands are available after sourcing the setup.sh script, which can be added to your .bashrc for convenience. Local configuration overrides can be made in local_setup.sh, which is automatically created when you source setup.sh for the first time.
To start the Refbox and its web-based frontend, use:
rc_start
The default configuration files located in rcll-get-started/config/refbox will be used. Once started, the web UI can be accessed at http://localhost:8080/. If you want to access the frontend from a different machine, you can use that machine's IP instead of course. By default, the frontend opens in spectator mode. This means, that the game can not be actively controlled. By pressing ctrl + alt + o, the referee mode can be activated, which allows the user to control the game.
The startup process creates a screen session named rcll by default. You can inspect logs or debug output by attaching to this session:
screen -r rcll
To stop all Refbox services cleanly, use:
rc_stop
This ensures all running containers are terminated.
To fetch the latest Docker images for the Refbox and frontend, run:
rc_pull
This ensures your setup is always up to date with the latest features and fixes.
For temporary or environment-specific changes, update local_setup.sh to include refbox arguments. For example, to use a different challenge configuration, add:
export REFBOX_ARGS="--cfg-challenge challenge_prod_c0.yaml"
This file is ignored by Git, making it safe for local experimentation. It is created when you first source setup.sh.
The RCLL Refbox is highly configurable, allowing you to adjust game settings, communication protocols, field layout, and more. These configurations are primarily managed through environment variables and configuration files. Additionally, you can directly pass configuration arguments to the Refbox using the REFBOX_ARGS variable. For example, if you want to set a default team you can set the following arguments in your local_setup.sh:
export REFBOX_ARGS="--cfg-team team/my_default_team.yaml"
and create the corresponding file.
This flexibility lets you fine-tune the Refbox for specific setups or experiments. By default, configuration files in rcll-get-started/config/refbox are used unless overridden.
Most of the configuration parameters can also be changed via the refbox frontend. However, some configuration changes might lead to inconsistent states in the refbox world model and are thus advised to be only changed through the startup configuration parameter. This applies especially to the challenge modes.
The refbox needs to communicate with each of the teams. Depending on your local network setup, the IP addresses for the peers need to be configured differently from the default. The corresponding default config file can be found in config/refbox/comm. You can either adapt this file, or create your own file with your local config. To configure the use of your own file you can add the flag --cfg-comm comm/<your_config_file>.yml to your REFBOX_ARGS.
The game configuration handles the basic setup of the RCLL game to be played like field size and mirroring, randomization, game report usage, exploration, etc.
Depending on your local setup, you might want to decrease the size of the field in order to fit within your local constraints. The field size and layout are defined in the game configuration file. As usual, the default file can be found in config/game/default_game.yml. For example, to configure a field with only one side and 4 x 5 meters one might use the following configuration:
llsfrb:
game:
field:
width: 5
height: 4
mirrored: false
If you configure random-field: true, a new field will be generated automatically at each startup. random-orders: true, randomizes the orders. With store-to-report: "<report-name>", a game report can be created (or overwritten) in the mongodb database. These contain all events during the game, as well as the orders, the field layout, etc.
Challenges are managed via the config flag --cfg-challenge flag. Each challenge has its own default configuration file that defines the specific rules and behaviors. They can be found in the config/refbox/challenges/ directory.
For example, to enable the C0 Production Challenge, update local_setup.sh:
export REFBOX_ARGS="--cfg-challenge challenge_prod_c0.yaml"
You can add your own challenge files to the config/refbox directory or specify an external path.
Machine settings, including which MPS are active and their network and mode configurations, are controlled by the —cfg-mps flag, respectively.
By default, a PLC connection is established to the MPS. This means that the refbox attempts to connect to the machines configured to be active using the provided IP address. To override this default behavior, for instance, to enable mockup mode, you can add your own configuration:
export REFBOX_ARGS="--cfg-mps /path/to/your/mps_config.yaml"
Alternatively, you can modify the default configuration file.
The Refbox supports advanced saving and loading features to enhance testing and replaying games. These features leverage game reports and the Refbox's database capabilities to record, modify, and replay games.
During gameplay, the Refbox automatically generates a game report if a name for storing it is configured. This report contains all relevant game data, including machine positions, game progress, and results.
Use the DB Explorer in Referee Mode to replay recorded games. This allows you to watch the game's progression step-by-step and analyze gameplay or test strategies.
To reload a previously generated field, configure the Refbox to load a specific game report while turning off field randomization. E.g, if you previously saved a game report with name "test", you can reload it by setting load-from-report: "test" in the game config.
This ensures the field layout and machine positions are restored exactly as saved.
While in Referee Mode, any map modifications are automatically saved to the active game report if a storage name is configured.
- Live Map Editing: In Referee Mode, you can use the map interface to manually adjust the position of machines by dragging and dropping them. These changes are saved into the game report if a name is set.
- Reloading Changes: After editing, the updated map can be reloaded by setting the appropriate game report as described above.