Google Research Football

This repository contains an RL environment based on open-source game Gameplay Football.
It was created by the Google Brain team for research purposes.

Useful links:

For non-public matters that you'd like to discuss directly with the GRF team, please use google-research-football@google.com.

We'd like to thank Bastiaan Konings Schuiling, who authored and open-sourced the original version of this game.

Quick Start

In colab

Open our example Colab, that will allow you to start training your model in less than 2 minutes.

This method doesn't support game rendering on screen - if you want to see the game running, please use the method below.

Using Docker

This is the recommended way to avoid incompatible package versions. Instructions are available here.

On your computer

1. Install required packages

Linux

sudo apt-get install git cmake build-essential libgl1-mesa-dev libsdl2-dev \
libsdl2-image-dev libsdl2-ttf-dev libsdl2-gfx-dev libboost-all-dev \
libdirectfb-dev libst-dev mesa-utils xvfb x11vnc libsdl-sge-dev python3-pip

Mac OS X

First install brew. It should automatically install Command Line Tools. Next install required packages:

brew install git python3 cmake sdl2 sdl2_image sdl2_ttf sdl2_gfx boost

and boost-python3, that supports Python 3.7:

brew install https://raw.githubusercontent.com/Homebrew/homebrew-core/527d96f84d4632d30b281ef5b26717e0a75edcb4/Formula/boost-python3.rb

2a. From PyPi package

pip3 install gfootball

2b. Installing from sources using GitHub repository

git clone https://github.com/google-research/football.git
cd football

Optionally you can use virtual environment:

python3 -m venv football-env
source football-env/bin/activate

The last step is to build the environment:

pip3 install .

This command can run for a couple of minutes, as it compiles the C++ environment in the background.

3. Time to play!

python3 -m gfootball.play_game --action_set=full

Make sure to check out the keyboard mappings. To quit the game press Ctrl+C in the terminal.

Contents

Training agents to play GRF

Run training

In order to run TF training, install additional dependencies:

Then:

In order to train with nice replays being saved, run python3 -m gfootball.examples.run_ppo2 --dump_full_episodes=True --render=True

In order to reproduce PPO results from the paper, please refer to:

Playing the game

Please note that playing the game is implemented through an environment, so human-controlled players use the same interface as the agents. One important implication is that there is a single action per 100 ms reported to the environment, which might cause a lag effect when playing.

Keyboard mappings

The game defines following keyboard mapping (for the keyboard player type):

Play vs built-in AI

Run python3 -m gfootball.play_game --action_set=full. By default, it starts the base scenario and the left player is controlled by the keyboard. Different types of players are supported (gamepad, external bots, agents...). For possible options run python3 -m gfootball.play_game -helpfull.

Play vs pre-trained agent

In particular, one can play against agent trained with run_ppo2 script with the following command (notice no action_set flag, as PPO agent uses default action set): python3 -m gfootball.play_game --players "keyboard:left_players=1;ppo2_cnn:right_players=1,checkpoint=$YOUR_PATH"

Trained checkpoints

We provide trained PPO checkpoints for the following scenarios:

In order to see the checkpoints playing, run python3 -m gfootball.play_game --players "ppo2_cnn:left_players=1,policy=gfootball_impala_cnn,checkpoint=$CHECKPOINT" --level=$LEVEL, where $CHECKPOINT is the path to downloaded checkpoint.

In order to train against a checkpoint, you can pass 'extra_players' argument to create_environment function. For example extra_players='ppo2_cnn:right_players=1,policy=gfootball_impala_cnn,checkpoint=$CHECKPOINT'.

Frequent Problems & Solutions

Rendering not working / "OpenGL version not equal to or higher than 3.2"

Solution: set environment variables for MESA driver, like this:

MESA_GL_VERSION_OVERRIDE=3.2 MESA_GLSL_VERSION_OVERRIDE=150 python3 -m gfootball.play_game