CodePraxis Football

Write a Python agent that plays football. Test it on your laptop, watch it play, record videos, and score it the same way the judges do.

Install

pip install codepraxis-football        # Python 3.12 or newer; Mac, Linux, Windows
codepraxis-football doctor             # checks the engine, rendering and video
codepraxis-football init my-agent      # sample agent + this guide + a practice level
cd my-agent

On a Linux server or a minimal Linux install, the game needs the system OpenGL libraries: sudo apt install libgl1 libegl1 (desktops already have them). No GPU is needed.

Try it

codepraxis-football play shoot_keeper                    # play it yourself with the keyboard
codepraxis-football watch agent.py shoot_keeper          # watch your agent in a window
codepraxis-football eval agent.py shoot_keeper           # official score: 100 seeded episodes
codepraxis-football video agent.py shoot_keeper -o a.mp4 # record without a window
codepraxis-football watch-match agent.py random match_5v5 # two agents live: yellow vs blue
codepraxis-football match agent.py other.py match_5v5    # same, no window, JSON result
codepraxis-football levels                               # every level

The window and videos hold the picture for a moment after goals, cards and set pieces. Add --fast to skip that. Training and eval never pause. The 3D view (window, video --view 3d) runs extra engine code that changes how a match plays out, so the same seed can end differently there than in eval. video --view topdown shows exactly what eval scored.

Keyboard: arrows move, hold e sprint, hold c dribble, s short pass, a high pass, w long pass, d shoot, x slide tackle, Esc quit.

Write an agent

An agent is a file with one function. It gets what its player sees and returns one action:

from codepraxis_football import Action

def agent(obs):
    me = obs['left_team'][obs['active']]
    if me[0] > 0.7:
        return Action.SHOT
    return Action.RIGHT

Agents that need memory can use a class instead:

class Agent:
    def reset(self):          # start of every episode
        self.steps = 0
    def act(self, obs):
        self.steps += 1
        return Action.RIGHT

Optional settings at the top of the file:

The pitch

x runs from -1 (our goal) to 1 (the goal you attack). y runs from -0.42 (top) to 0.42 (bottom). You always attack to the right, also when the judges play your agent as the other team.

Raw observation fields

Actions

Directions, sprint and dribble stay on until released. Passes and shots go the way the player faces.

Use it from Python (training)

import codepraxis_football as cpf

env = cpf.make('shoot_keeper', observation='vector')    # Gymnasium API
obs, info = env.reset(seed=0)
obs, reward, terminated, truncated, info = env.step(cpf.Action.SHOT)

reward is +1 for our goal and -1 for theirs. With no window the game runs at several hundred steps per second per CPU core; run one environment per core to train faster:

import gymnasium as gym

def make_env():
    return cpf.make('shoot_keeper', observation='vector')

if __name__ == '__main__':
    envs = gym.vector.AsyncVectorEnv([make_env] * 4)   # 4 processes
    obs, info = envs.reset(seed=[0, 1, 2, 3])

On a 2024 laptop, 4 environments run ~1,500 steps/s: a million training steps in about 11 minutes.

Reinforcement learning

Any library that speaks Gymnasium works. With Stable-Baselines3 (pip install stable-baselines3):

from stable_baselines3 import PPO
from stable_baselines3.common.vec_env import SubprocVecEnv, VecMonitor
import codepraxis_football as cpf

def make_env():
    return cpf.make('shoot_keeper', observation='vector', reward='checkpoints')

if __name__ == '__main__':
    envs = VecMonitor(SubprocVecEnv([make_env] * 4))
    model = PPO('MlpPolicy', envs, n_steps=512, batch_size=512, gamma=0.993)
    model.learn(total_timesteps=2_000_000)
    model.save('model')

reward='checkpoints' adds small rewards for carrying the ball towards the goal, so learning starts long before the first goal. Use the saved model as an agent:

import os
from stable_baselines3 import PPO
OBSERVATION = 'vector'
model = PPO.load(os.path.join(os.path.dirname(__file__), 'model.zip'))  # next to agent.py

def agent(obs):
    return int(model.predict(obs, deterministic=True)[0])

Scoring

eval runs your agent for 100 episodes with fixed seeds and prints JSON: goal_rate (episodes where you scored), avg_steps_to_goal, wins/draws/losses, timeouts and errors. A step slower than 50 ms counts as IDLE. If your agent raises an error, that episode scores nothing and the rest still run. The judges use the same command with seeds you haven't seen.

Make your own practice level

See my_level.py from init. Use a level file anywhere a level name goes: codepraxis-football watch agent.py my_level.py.