November 17, 2019

736 words 4 mins read



Check out the new game server:

repo name google-research/football
repo link
language Python
size (curr.) 27403 kB
stars (curr.) 1863
created 2019-06-03
license Apache License 2.0

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

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.

On your computer

Install required apt packages with:

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

Then install the game from GitHub master:

git clone
cd football
pip3 install .

This command can run for a couple of minutes, as it compiles the C++ environment in the background. Now, it’s time to play!

python3 -m gfootball.play_game --action_set=full


Training agents to play GRF

Run training

In order to run TF training, install additional dependencies:

  • Update PIP, so that tensorflow 1.15rc2 is available: python3 -m pip install --upgrade pip
  • TensorFlow: pip3 install "tensorflow==1.15rc2" or pip3 install "tensorflow-gpu==1.15rc2", depending on whether you want CPU or GPU version;
  • Sonnet: pip3 install dm-sonnet;
  • OpenAI Baselines: pip3 install git+


  • To run example PPO experiment on academy_empty_goal scenario, run python3 -m gfootball.examples.run_ppo2 --level=academy_empty_goal_close
  • To run on academy_pass_and_shoot_with_keeper scenario, run python3 -m gfootball.examples.run_ppo2 --level=academy_pass_and_shoot_with_keeper

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:

  • gfootball/examples/
  • gfootball/examples/

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):

  • ARROW UP - run to the top.
  • ARROW DOWN - run to the bottom.
  • ARROW LEFT - run to the left.
  • ARROW RIGHT - run to the right.
  • S - short pass in the attack mode, pressure in the defense mode.
  • A - high pass in the attack mode, sliding in the defense mode.
  • D - shot in the the attack mode, team pressure in the defense mode.
  • W - long pass in the the attack mode, goalkeeper pressure in the defense mode.
  • Q - switch the active player in the defense mode.
  • C - dribble in the attack mode.
  • E - sprint.

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

comments powered by Disqus