# openrl-lab/tizero architecture

> Architecture diagram of the GitHub repository openrl-lab/tizero, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openrl-lab/tizero
- Repository: https://github.com/openrl-lab/tizero

## Overview

TiZero is a reinforcement-learning agent and toolkit for Google Research Football. Its main workflow is to provide an agent to a football environment, where observations are handled and actions advance a match; the repository also exposes local match evaluation and post-match dump inspection, keypoint analysis, and video conversion. The source index supports the CLI-to-evaluation and CLI-to-visualization routes, plus several internal module references. Some agent and environment internals were only partially sampled, so uncertain connections are omitted rather than inferred.

Main entry points: [`tizero/cli/cli.py`](https://github.com/openrl-lab/tizero/blob/main/tizero/cli/cli.py) (CLI commands), [`submission/tizero/submission.py`](https://github.com/openrl-lab/tizero/blob/main/submission/tizero/submission.py) (Submission agent), [`tizero/utils/visualize_tools/visualizer/visualizer.py`](https://github.com/openrl-lab/tizero/blob/main/tizero/utils/visualize_tools/visualizer/visualizer.py) (Match visualizer), [`tizero/football_env/core/football_env.py`](https://github.com/openrl-lab/tizero/blob/main/tizero/football_env/core/football_env.py) (Gym environment)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent["Agent"]
  node_submission["Submission agent<br/>[submission.py]"]
  node_policy["OpenRL policy<br/>[openrl_policy.py]"]
  node_agent_utils["Agent utilities<br/>[openrl_utils.py]"]
  node_keeper["Goalkeeper logic<br/>[goal_keeper.py]"]
end

subgraph group_environment["Football environment"]
  node_config["Environment config<br/>[config.py]"]
  node_scenarios["Match scenarios"]
  node_scenario_builder["Scenario builder"]
  node_env_core["Football engine"]
  node_env_wrapper["Gym environment<br/>[football_env.py]"]
  node_env_factory["Environment factory<br/>[__init__.py]"]
  node_pettingzoo["PettingZoo adapter"]
  node_jidi["JiDi evaluation env"]
end

subgraph group_evaluation["Evaluation"]
  node_cli["CLI commands<br/>[cli.py]"]
  node_evaluation_runner["Evaluation runner<br/>[evaluation.py]"]
  node_helpers["Environment helpers<br/>[script_helpers.py]"]
end

subgraph group_visualization["Match visualization"]
  node_dump_video["Dump to video<br/>[dump2video.py]"]
  node_show_dump["Show match dump<br/>[show_dump.py]"]
  node_show_keypoint["Show keypoints<br/>[show_keypoint.py]"]
  node_tracer["Match tracer<br/>[tracer.py]"]
  node_game_graph["Game event graph<br/>[game_graph.py]"]
  node_visualizer["Match visualizer<br/>[visualizer.py]"]
  node_geometry["Pitch geometry<br/>[geometry.py]"]
  node_raw_drawer["Field renderer<br/>[raw_drawer.py]"]
  node_ball_table["Ball information<br/>[ball_info_table.py]"]
  node_team_table["Team information<br/>[team_info_table.py]"]
end

node_user(("Agent user"))
node_football["Google Research Football"]

node_user -.->|"supplies agent"| node_submission
node_submission -->|"uses"| node_policy
node_submission -->|"uses"| node_agent_utils
node_submission -->|"uses"| node_keeper
node_config -->|"uses"| node_scenario_builder
node_env_wrapper -->|"reads"| node_config
node_env_wrapper -->|"delegates"| node_env_core
node_env_factory -->|"uses"| node_config
node_env_factory -->|"wraps"| node_env_wrapper
node_pettingzoo -->|"uses"| node_jidi
node_evaluation_runner -->|"runs"| node_pettingzoo
node_cli -->|"dispatches"| node_evaluation_runner
node_cli -->|"dispatches"| node_dump_video
node_cli -->|"dispatches"| node_show_dump
node_cli -->|"dispatches"| node_show_keypoint
node_dump_video -->|"uses"| node_helpers
node_helpers -->|"uses"| node_config
node_helpers -->|"uses"| node_env_wrapper
node_football -.->|"provides game"| node_env_factory
node_show_dump -->|"loads dump"| node_tracer
node_show_dump -->|"opens"| node_visualizer
node_show_keypoint -->|"loads dump"| node_tracer
node_show_keypoint -->|"builds"| node_game_graph
node_visualizer -->|"renders with"| node_raw_drawer
node_visualizer -->|"updates"| node_ball_table
node_visualizer -->|"updates"| node_team_table
node_game_graph -->|"calculates distances"| node_geometry

click node_submission "https://github.com/openrl-lab/tizero/blob/main/submission/tizero/submission.py"
click node_policy "https://github.com/openrl-lab/tizero/blob/main/submission/tizero/openrl_policy.py"
click node_agent_utils "https://github.com/openrl-lab/tizero/blob/main/submission/tizero/openrl_utils.py"
click node_keeper "https://github.com/openrl-lab/tizero/blob/main/submission/tizero/goal_keeper.py"
click node_config "https://github.com/openrl-lab/tizero/blob/main/tizero/football_env/core/config.py"
click node_scenarios "https://github.com/openrl-lab/tizero/tree/main/tizero/football_env/scenarios"
click node_scenario_builder "https://github.com/openrl-lab/tizero/blob/main/tizero/football_env/core/scenario_builder.py"
click node_env_core "https://github.com/openrl-lab/tizero/blob/main/tizero/football_env/core/football_env_core.py"
click node_env_wrapper "https://github.com/openrl-lab/tizero/blob/main/tizero/football_env/core/football_env.py"
click node_env_factory "https://github.com/openrl-lab/tizero/blob/main/tizero/football_env/__init__.py"
click node_pettingzoo "https://github.com/openrl-lab/tizero/blob/main/tizero/football_env/football_pettingzoo.py"
click node_jidi "https://github.com/openrl-lab/tizero/blob/main/tizero/football_env/football_jidi_eval.py"
click node_cli "https://github.com/openrl-lab/tizero/blob/main/tizero/cli/cli.py"
click node_evaluation_runner "https://github.com/openrl-lab/tizero/blob/main/tizero/cli/evaluation.py"
click node_helpers "https://github.com/openrl-lab/tizero/blob/main/tizero/utils/script_helpers.py"
click node_dump_video "https://github.com/openrl-lab/tizero/blob/main/tizero/cli/dump2video.py"
click node_show_dump "https://github.com/openrl-lab/tizero/blob/main/tizero/cli/show_dump.py"
click node_show_keypoint "https://github.com/openrl-lab/tizero/blob/main/tizero/cli/show_keypoint.py"
click node_tracer "https://github.com/openrl-lab/tizero/blob/main/tizero/utils/visualize_tools/tools/tracer.py"
click node_game_graph "https://github.com/openrl-lab/tizero/blob/main/tizero/utils/visualize_tools/game_graph/game_graph.py"
click node_visualizer "https://github.com/openrl-lab/tizero/blob/main/tizero/utils/visualize_tools/visualizer/visualizer.py"
click node_geometry "https://github.com/openrl-lab/tizero/blob/main/tizero/utils/visualize_tools/tools/geometry.py"
click node_raw_drawer "https://github.com/openrl-lab/tizero/blob/main/tizero/utils/visualize_tools/visualizer/raw_drawer.py"
click node_ball_table "https://github.com/openrl-lab/tizero/blob/main/tizero/utils/visualize_tools/visualizer/ball_info_table.py"
click node_team_table "https://github.com/openrl-lab/tizero/blob/main/tizero/utils/visualize_tools/visualizer/team_info_table.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_submission,node_policy,node_agent_utils,node_keeper,node_user toneBlue
class node_config,node_scenarios,node_scenario_builder,node_env_core,node_env_wrapper,node_env_factory,node_pettingzoo,node_jidi toneAmber
class node_cli,node_evaluation_runner,node_helpers toneMint
class node_dump_video,node_show_dump,node_show_keypoint,node_tracer,node_game_graph,node_visualizer,node_geometry,node_raw_drawer,node_ball_table,node_team_table toneRose
class node_football toneIndigo
```

## Components

### Agent

- [Submission agent](https://github.com/openrl-lab/tizero/blob/main/submission/tizero/submission.py): `submission/tizero/submission.py`
- [OpenRL policy](https://github.com/openrl-lab/tizero/blob/main/submission/tizero/openrl_policy.py): `submission/tizero/openrl_policy.py`
- [Agent utilities](https://github.com/openrl-lab/tizero/blob/main/submission/tizero/openrl_utils.py): `submission/tizero/openrl_utils.py`
- [Goalkeeper logic](https://github.com/openrl-lab/tizero/blob/main/submission/tizero/goal_keeper.py): `submission/tizero/goal_keeper.py`

### Football environment

- [Environment config](https://github.com/openrl-lab/tizero/blob/main/tizero/football_env/core/config.py): `tizero/football_env/core/config.py`
- [Match scenarios](https://github.com/openrl-lab/tizero/tree/main/tizero/football_env/scenarios): `tizero/football_env/scenarios`
- [Scenario builder](https://github.com/openrl-lab/tizero/blob/main/tizero/football_env/core/scenario_builder.py): `tizero/football_env/core/scenario_builder.py`
- [Football engine](https://github.com/openrl-lab/tizero/blob/main/tizero/football_env/core/football_env_core.py): `tizero/football_env/core/football_env_core.py`
- [Gym environment](https://github.com/openrl-lab/tizero/blob/main/tizero/football_env/core/football_env.py): `tizero/football_env/core/football_env.py`
- [Environment factory](https://github.com/openrl-lab/tizero/blob/main/tizero/football_env/__init__.py): `tizero/football_env/__init__.py`
- [PettingZoo adapter](https://github.com/openrl-lab/tizero/blob/main/tizero/football_env/football_pettingzoo.py): `tizero/football_env/football_pettingzoo.py`
- [JiDi evaluation env](https://github.com/openrl-lab/tizero/blob/main/tizero/football_env/football_jidi_eval.py): `tizero/football_env/football_jidi_eval.py`

### Evaluation

- [CLI commands](https://github.com/openrl-lab/tizero/blob/main/tizero/cli/cli.py): `tizero/cli/cli.py`
- [Evaluation runner](https://github.com/openrl-lab/tizero/blob/main/tizero/cli/evaluation.py): `tizero/cli/evaluation.py`
- [Environment helpers](https://github.com/openrl-lab/tizero/blob/main/tizero/utils/script_helpers.py): `tizero/utils/script_helpers.py`

### Match visualization

- [Dump to video](https://github.com/openrl-lab/tizero/blob/main/tizero/cli/dump2video.py): `tizero/cli/dump2video.py`
- [Show match dump](https://github.com/openrl-lab/tizero/blob/main/tizero/cli/show_dump.py): `tizero/cli/show_dump.py`
- [Show keypoints](https://github.com/openrl-lab/tizero/blob/main/tizero/cli/show_keypoint.py): `tizero/cli/show_keypoint.py`
- [Match tracer](https://github.com/openrl-lab/tizero/blob/main/tizero/utils/visualize_tools/tools/tracer.py): `tizero/utils/visualize_tools/tools/tracer.py`
- [Game event graph](https://github.com/openrl-lab/tizero/blob/main/tizero/utils/visualize_tools/game_graph/game_graph.py): `tizero/utils/visualize_tools/game_graph/game_graph.py`
- [Match visualizer](https://github.com/openrl-lab/tizero/blob/main/tizero/utils/visualize_tools/visualizer/visualizer.py): `tizero/utils/visualize_tools/visualizer/visualizer.py`
- [Pitch geometry](https://github.com/openrl-lab/tizero/blob/main/tizero/utils/visualize_tools/tools/geometry.py): `tizero/utils/visualize_tools/tools/geometry.py`
- [Field renderer](https://github.com/openrl-lab/tizero/blob/main/tizero/utils/visualize_tools/visualizer/raw_drawer.py): `tizero/utils/visualize_tools/visualizer/raw_drawer.py`
- [Ball information](https://github.com/openrl-lab/tizero/blob/main/tizero/utils/visualize_tools/visualizer/ball_info_table.py): `tizero/utils/visualize_tools/visualizer/ball_info_table.py`
- [Team information](https://github.com/openrl-lab/tizero/blob/main/tizero/utils/visualize_tools/visualizer/team_info_table.py): `tizero/utils/visualize_tools/visualizer/team_info_table.py`

### Other components

- **Agent user**
- **Google Research Football**

## Connections

- Agent user → Submission agent: supplies agent
- Submission agent → OpenRL policy: uses (evidence: `submission/tizero/submission.py`)
- Submission agent → Agent utilities: uses (evidence: `submission/tizero/submission.py`)
- Submission agent → Goalkeeper logic: uses (evidence: `submission/tizero/submission.py`)
- Environment config → Scenario builder: uses (evidence: `tizero/football_env/core/config.py`)
- Gym environment → Environment config: reads (evidence: `tizero/football_env/core/football_env.py`)
- Gym environment → Football engine: delegates (evidence: `tizero/football_env/core/football_env.py`)
- Environment factory → Environment config: uses (evidence: `tizero/football_env/__init__.py`)
- Environment factory → Gym environment: wraps (evidence: `tizero/football_env/__init__.py`)
- PettingZoo adapter → JiDi evaluation env: uses (evidence: `tizero/football_env/football_pettingzoo.py`)
- Evaluation runner → PettingZoo adapter: runs (evidence: `tizero/cli/evaluation.py`)
- CLI commands → Evaluation runner: dispatches (evidence: `tizero/cli/cli.py`)
- CLI commands → Dump to video: dispatches (evidence: `tizero/cli/cli.py`)
- CLI commands → Show match dump: dispatches (evidence: `tizero/cli/cli.py`)
- CLI commands → Show keypoints: dispatches (evidence: `tizero/cli/cli.py`)
- Dump to video → Environment helpers: uses (evidence: `tizero/cli/dump2video.py`)
- Environment helpers → Environment config: uses (evidence: `tizero/utils/script_helpers.py`)
- Environment helpers → Gym environment: uses (evidence: `tizero/utils/script_helpers.py`)
- Google Research Football → Environment factory: provides game (evidence: `README.md`)
- Show match dump → Match tracer: loads dump (evidence: `tizero/cli/show_dump.py`)
- Show match dump → Match visualizer: opens (evidence: `tizero/cli/show_dump.py`)
- Show keypoints → Match tracer: loads dump (evidence: `tizero/cli/show_keypoint.py`)
- Show keypoints → Game event graph: builds (evidence: `tizero/cli/show_keypoint.py`)
- Match visualizer → Field renderer: renders with (evidence: `tizero/utils/visualize_tools/visualizer/visualizer.py`)
- Match visualizer → Ball information: updates (evidence: `tizero/utils/visualize_tools/visualizer/visualizer.py`)
- Match visualizer → Team information: updates (evidence: `tizero/utils/visualize_tools/visualizer/visualizer.py`)
- Game event graph → Pitch geometry: calculates distances (evidence: `tizero/utils/visualize_tools/game_graph/game_graph.py`)
