Google Research Football

EnvPool supports the Google Research Football scenarios listed below under EnvPool-native IDs of the form gfootball/<scenario>-v1. The runtime path is pure C++: EnvPool builds and calls the upstream engine directly, and only uses the upstream Python scenario files at build time to generate a static C++ scenario table. There is no Python-environment bridge in the runtime hot path.

Options

  • task_id (str): any task listed in Available Tasks;

  • num_envs (int): how many environments to create;

  • batch_size (int): the expected batch size for returned results, default to num_envs;

  • num_threads (int): the maximum worker count used for env.step, default to batch_size;

  • seed (int | Sequence[int]): the environment seed. When a sequence is provided, it must contain exactly one seed per environment. Default to 42;

  • max_episode_steps (int): the episode horizon. Each task defaults to the upstream scenario duration, but callers can override it;

  • physics_steps_per_frame (int): physics updates per policy step, default to 10.

Rendering is intentionally unsupported for gfootball. The upstream headless renderer does not produce reliable output across EnvPool’s supported CI platforms, so render_mode, render_width, and render_height are not part of the public contract for this environment, and env.render() raises RuntimeError.

Observation Space

The Gymnasium wrapper exposes a uint8 minimap tensor obs with shape (72, 96, 4):

  • channel 0 marks left-team players;

  • channel 1 marks right-team players;

  • channel 2 marks the ball position;

  • channel 3 marks the currently controlled left-team player.

The info dict contains:

  • score: int32[2] with [left_goals, right_goals];

  • game_mode: current upstream game-mode enum value;

  • ball_owned_team and ball_owned_player;

  • steps_left and elapsed_step;

  • engine_seed and episode_number.

Rewards follow upstream score-delta semantics: each step returns the change in left_goals - right_goals since the previous observation.

Action Space

The action space is discrete with 19 actions matching EnvPool’s default Google Research Football action set:

  • 0: idle

  • 1: left

  • 2: top_left

  • 3: top

  • 4: top_right

  • 5: right

  • 6: bottom_right

  • 7: bottom

  • 8: bottom_left

  • 9: long_pass

  • 10: high_pass

  • 11: short_pass

  • 12: shot

  • 13: sprint

  • 14: release_direction

  • 15: release_sprint

  • 16: sliding

  • 17: dribble

  • 18: release_dribble

Available Tasks

  • gfootball/11_vs_11_competition-v1

  • gfootball/11_vs_11_easy_stochastic-v1

  • gfootball/11_vs_11_hard_stochastic-v1

  • gfootball/11_vs_11_kaggle-v1

  • gfootball/11_vs_11_stochastic-v1

  • gfootball/1_vs_1_easy-v1

  • gfootball/5_vs_5-v1

  • gfootball/academy_3_vs_1_with_keeper-v1

  • gfootball/academy_corner-v1

  • gfootball/academy_counterattack_easy-v1

  • gfootball/academy_counterattack_hard-v1

  • gfootball/academy_empty_goal-v1

  • gfootball/academy_empty_goal_close-v1

  • gfootball/academy_pass_and_shoot_with_keeper-v1

  • gfootball/academy_run_pass_and_shoot_with_keeper-v1

  • gfootball/academy_run_to_score-v1

  • gfootball/academy_run_to_score_with_keeper-v1

  • gfootball/academy_single_goal_versus_lazy-v1

Correctness Tests

The gfootball integration is held to the same no-skip, all-platform standard as the rest of EnvPool’s core environments:

  • Full registry coverage: every registered gfootball/*-v1 ID is created through the public Gymnasium API, reset, stepped, and closed in CI;

  • Bitwise rollout alignment: envpool/gfootball/gfootball_align_test.py runs each registered task to episode completion and checks observations, rewards, terminated / truncated, and the public info fields bitwise against an independent oracle that uses the same C++ engine with upstream scenario semantics;

  • Render rejection: envpool/gfootball/gfootball_render_test.py checks every registered task rejects both render_mode="rgb_array" and render_mode="human" with a runtime error instead of exposing a known-bad renderer;

  • Determinism: envpool/gfootball/gfootball_deterministic_test.py requires identical seeds and action streams to produce identical rollouts, while a different seed must change the rollout;

  • Cross-platform coverage: the build, render-rejection, alignment, and determinism paths are validated in CI on Linux, macOS, and Windows rather than being skipped on any platform.