Robocup Virtual Humanoid League

This folder contains the simulation setup for the Robocup Virtual Humanoid League.

Requirements

In order to run this simulation, you will need to have a fairly powerful Linux, Windows or macOS computer. You will also need to get familiar with Webots by reading the Webots User Guide and following the Tutorials.

Installation for Ubuntu (tested with 22.04)

Install Webots 2022b from https://cyberbotics.com/

Build the latest version of the official RoboCup Humanoid TC fork of the GameController.

apt-get install ant
git clone https://github.com/RoboCup-Humanoid-TC/GameController
cd GameController
ant

Install Python dependencies:

Main dependencies:

pip3 install -r controllers/referee/requirements/common.txt

Optional development dependencies:

pip3 install -r controllers/referee/requirements/dev.txt

Build the controllers:

apt-get install protobuf-compiler libprotobuf-dev libjpeg9-dev
export WEBOTS_HOME=/usr/local/webots # Set WEBOTS_HOME. This might be a different location, depending on your installation type
make # This requires the environment variable WEBOTS_HOME to be set

Run the Demo

Open the robocup.wbt world file in Webots and run it until you see the GameController window showing up.
```
GAME_CONTROLLER_HOME=/path/to/GameController JAVA_HOME=/usr webots ./worlds/robocup.wbt
```
You have to pass the environment variables GAME_CONTROLLER_HOME which points to the GameController folder and JAVA_HOME which points to your Java installation (which might be under /usr).
You can manually move the robots and the ball using the mouse (Shift-right-click-and-drag).
Launch the sample robot controller client.cpp by typing ./client in the controllers/player folder.
The sample client program will simply move the neck of one of the Darwin-OP robot.

Modify the Game and Teams Configuration

Quit Webots.
Edit the game.json (see here for details on configuration) file to change the game configuration. The ports in this file are where the API server will open ports and the API servers will only accept traffic from the whitelisted IP, i.e. you might want to change the IPs to 127.0.0.1 for a local setup.
Edit the team_1.json and team_2.json files to change the teams configuration.
Restart the simulation.

Program your Own Robot Controllers

Update the game.json configuration file (see here and create your own team configuration files, taking inspiration from team_1.json and team_2.json.
Create your own robot controllers, taking inspiration from the sample client.cpp.

Create your Own Robot Model

Create your robot model in the protos folder taking inspiration from RobocupRobot.proto and adjust your team configuration file accordingly.

Exposed Parameters

Your proto should have the following exposed parameters:

PROTO MyOwnRobocupRobot [
  field SFVec3f                 translation    0 0 0   # Is `Transform.translation`.
  field SFRotation              rotation       0 0 1 0 # Is `Transform.rotation`.
  field SFString                name           ""      # Is `Solid.name`.
  field MFString                controllerArgs []      # Is `Robot.controllerArgs`.
]
{
  Robot {
    translation IS translation
    rotation IS rotation
    name IS name
    controllerArgs IS controllerArgs
    ⋮
  }
}

Creating a Jersey with the Correct Color and Player Number

The team color and player number of each robot is set by the referee in the name field of the robot when spawning it. It can takes values like "red player 1" or "blue player 3", etc. You should therefore parse this name field to determine the team color and player number of your robot:

  if fields.name.value ~= '' then
    -- name is supposed to be something like "red player 2" or "blue player 1"
    local words = {}
    for word in fields.name.value:gmatch("%w+") do table.insert(words, word) end
    local color = words[1]
    local number = words[3]

Then, the color and number variables should be used by your PROTO file to display the requested color and player number on the jersey of the robot. This can be achieved by forging a texture name from these variables or using them directly to assign material colors, create shapes, etc. More information about Webots PROTO is available from the Webots Reference Manual.

Add Body Part Tags

The referee needs to identify the different parts of your robot to apply the rules of the game. These parts include the foot, arms, legs, head, etc. In order to identify each part, you should set the model field of each Solid (or derived) node composing your robot with one of the following strings: "foot", "arm", "shoulder", "hip".

Continuous Integration Tests

By default, the referee supervisor will read the game.json file from its local folder. However, if a special environment variable is set, it will use it to load a different game.json file:

export WEBOTS_ROBOCUP_GAME="/path/to/my/special/game.json"

In order to facilitate Continuous Integration (CI) tests, a number of options are available in the game.json file:

{
  "side_left": "red",
  "kickoff": "blue",
  "supervisor": "MyTestSupervisor"
}

"left_side" is used to determine which team will play on the left side of the field (x < 0). It can take the following values: "red", "blue", "random". The default value is "random".
"kickoff" is used to determine which team has the initial kickoff. It can take the same values as the "left_side" field.
"supervisor" is used to define an optional extra supervisor controller process that will run in parallel with the referee. This extra supervisor controller will be spawned by the referee at the beginning of the game. The following new node with be added to the scene after the referee robot: Robot { supervisor TRUE controller "MyTestSupervisor" }.

Model verifier

A semi-automated tool allowing to check if a robot respects the rules is available in the controllers/model_verifier directory. The available scripts are documented in a dedicated README.

Configuration of `game.json`

Configuration that is game-specific is defined in the game.json file. This configuration is used by the referee (and by the udp_bouncer if it is used).

Required fields

type: Type of the game [NORMAL, KNOCKOUT. PENALTY]
class: Subleague of the game [kid, adult]
kickoff: Color of the team that has kickoff at the start of the game [red, blue]
side_left: Color of the team that starts on the left field side [red, blue]
host: IP of the machine the referee is running on [LAN IP, or 127.0.0.1 for local]
maximum_real_time_factor: Referee guarantees that the simulation is not running faster. Values <= 0.0 mean, the simulation can run as fast as possible [float]
data_collection: Configuration for data collection
- enabled: Whether to enable the data collection [true or false]
- directory: Path to directory where to store data collection files
- step_interval: Interval between data collection steps, so it only runs every step_interval steps [integer]
- autosave_interval: Automatically saves collected data every autosave_interval seconds during the game. Set to -1 to disable auto save [integer]
red: Configuration for the red team
- id: ID of the red team
- config: (Relative) Path to the configuration file of the red team
- hosts: List of IPs of the red team robots' machines
- ports: List of ports of the red team robots' machines
blue: Configuration for the blue team
- id: ID of the blue team
- config: (Relative) Path to the configuration file of the blue team
- hosts: List of IPs of the blue team robots' machines
- ports: List of ports of the blue team robots' machines

Optional fields

Some fields are optional, but can be used to influence the behavior of the simulation.

press_a_key_to_terminate: Allows pressing a key to cleanly end the simulation and save the recording (used for testing) [true or false]
use_bouncing_server: Whether to use the udp_bouncer [true or false]
record_simulation: File path to where the simulation should be recorded. If it ends in .html a 3D recording is made. If it ends in .mp4 a video from the default perspective is generated.
max_duration: Maximum duration of the game in real-time seconds [integer]
texture_seed: Seed used for pseudo-random selection of textures (background, background luminosity, and ball) [integer]

game_controller_extra_args: Pass arguments to the game controller, for example

  "game_controller_extra_args": [
    "--halftimeduration",
    "120",
    "--overtimeduration",
    "60"
  ],

jaagut/hlvs_webots