# tartrl/tikick architecture

> Architecture diagram of the GitHub repository tartrl/tikick, 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/tartrl/tikick
- Repository: https://github.com/tartrl/tikick

## Overview

TiKick is a multi-agent Google Research Football agent. Its documented evaluation workflow loads a trained actor, runs deterministic policy actions through parallel football environments, and saves replay data that can be rendered as video. Internally, the driver coordinates policy inference, while MAPPO, the policy network, and shared rollout storage provide learning components. The README also describes replay rendering; source excerpts do not show the full replay-writing path, so that relationship is documented rather than inferred. Several subsystem links rely on the SOURCE INDEX or README, not inspection of unsampled implementations.

Main entry points: [`tmarl/runners/football/football_evaluator.py`](https://github.com/tartrl/tikick/blob/main/tmarl/runners/football/football_evaluator.py) (Football evaluator), [`tmarl/drivers/shared_distributed/football_driver.py`](https://github.com/tartrl/tikick/blob/main/tmarl/drivers/shared_distributed/football_driver.py) (Football driver), [`tmarl/runners/base_evaluator.py`](https://github.com/tartrl/tikick/blob/main/tmarl/runners/base_evaluator.py) (Evaluation runner), [`tmarl/envs/football/env/football_env.py`](https://github.com/tartrl/tikick/blob/main/tmarl/envs/football/env/football_env.py) (Football environment API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_evaluation["Evaluation runtime"]
  node_config["Run configuration<br/>[config.py]"]
  node_evaluator["Evaluation runner<br/>[base_evaluator.py]"]
  node_football_eval["Football evaluator"]
  node_driver["Football driver<br/>[football_driver.py]"]
  node_vecenv["Vector environments<br/>[env_wrappers.py]"]
end

subgraph group_football["Football simulation"]
  node_football_adapter["Multi-agent adapter<br/>[football.py]"]
  node_env_api["Football environment API<br/>[football_env.py]"]
  node_env_core["Football engine core"]
  node_env_config["Scenario configuration<br/>[config.py]"]
  node_scenario_builder["Scenario builder"]
  node_scenarios["Football scenarios"]
end

subgraph group_learning["Policy and learning"]
  node_algorithm["MAPPO algorithm<br/>[mappo_algorithm.py]"]
  node_module["MAPPO module<br/>[mappo_module.py]"]
  node_policy["Policy network<br/>[policy_network.py]"]
  node_action_layer["Action distributions<br/>[act.py]"]
  node_buffer[("Shared rollout buffer<br/>[shared_buffer.py]")]
  node_value_norm["Value normalization<br/>[valuenorm.py]"]
end

subgraph group_replay["Replay output"]
  node_replay_helper["Replay helpers<br/>[script_helpers.py]"]
  node_video_script["Replay video renderer<br/>[replay2video.py]"]
  node_replay_file["Saved replay"]
end

node_user(("Evaluator"))

node_user -->|"starts evaluation"| node_football_eval
node_football_eval -->|"extends"| node_evaluator
node_evaluator -->|"loads options"| node_config
node_evaluator -->|"initializes driver"| node_driver
node_football_eval -->|"selects environment"| node_football_adapter
node_football_eval -->|"creates vector envs"| node_vecenv
node_driver -->|"builds trainer"| node_algorithm
node_driver -->|"uses rollout storage"| node_buffer
node_driver -->|"requests actions"| node_module
node_driver -->|"steps environments"| node_vecenv
node_vecenv -.->|"steps wrapped env"| node_football_adapter
node_football_adapter -->|"creates environment"| node_env_api
node_env_api -->|"uses engine core"| node_env_core
node_env_api -->|"uses configuration"| node_env_config
node_env_config -->|"uses builder"| node_scenario_builder
node_scenario_builder -.->|"loads scenarios"| node_scenarios
node_algorithm -.->|"updates module"| node_module
node_module -->|"constructs policy"| node_policy
node_policy -->|"uses action layer"| node_action_layer
node_algorithm -->|"uses normalization"| node_value_norm
node_buffer -->|"denormalizes returns"| node_value_norm
node_football_eval -->|"saves replay"| node_replay_file
node_video_script -->|"uses helpers"| node_replay_helper
node_user -->|"renders replay"| node_video_script
node_video_script -->|"reads replay"| node_replay_file

click node_config "https://github.com/tartrl/tikick/blob/main/tmarl/configs/config.py"
click node_evaluator "https://github.com/tartrl/tikick/blob/main/tmarl/runners/base_evaluator.py"
click node_football_eval "https://github.com/tartrl/tikick/blob/main/tmarl/runners/football/football_evaluator.py"
click node_driver "https://github.com/tartrl/tikick/blob/main/tmarl/drivers/shared_distributed/football_driver.py"
click node_vecenv "https://github.com/tartrl/tikick/blob/main/tmarl/envs/env_wrappers.py"
click node_football_adapter "https://github.com/tartrl/tikick/blob/main/tmarl/envs/football/football.py"
click node_env_api "https://github.com/tartrl/tikick/blob/main/tmarl/envs/football/env/football_env.py"
click node_env_core "https://github.com/tartrl/tikick/blob/main/tmarl/envs/football/env/football_env_core.py"
click node_env_config "https://github.com/tartrl/tikick/blob/main/tmarl/envs/football/env/config.py"
click node_scenario_builder "https://github.com/tartrl/tikick/blob/main/tmarl/envs/football/env/scenario_builder.py"
click node_scenarios "https://github.com/tartrl/tikick/tree/main/tmarl/envs/football/scenarios"
click node_algorithm "https://github.com/tartrl/tikick/blob/main/tmarl/algorithms/r_mappo_distributed/mappo_algorithm.py"
click node_module "https://github.com/tartrl/tikick/blob/main/tmarl/algorithms/r_mappo_distributed/mappo_module.py"
click node_policy "https://github.com/tartrl/tikick/blob/main/tmarl/networks/policy_network.py"
click node_action_layer "https://github.com/tartrl/tikick/blob/main/tmarl/networks/utils/act.py"
click node_buffer "https://github.com/tartrl/tikick/blob/main/tmarl/replay_buffers/normal/shared_buffer.py"
click node_value_norm "https://github.com/tartrl/tikick/blob/main/tmarl/utils/valuenorm.py"
click node_replay_helper "https://github.com/tartrl/tikick/blob/main/tmarl/envs/football/env/script_helpers.py"
click node_video_script "https://github.com/tartrl/tikick/blob/main/scripts/football/replay2video.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_config,node_evaluator,node_football_eval,node_driver,node_vecenv toneBlue
class node_football_adapter,node_env_api,node_env_core,node_env_config,node_scenario_builder,node_scenarios toneAmber
class node_algorithm,node_module,node_policy,node_action_layer,node_buffer,node_value_norm toneMint
class node_replay_helper,node_video_script,node_replay_file toneRose
class node_user toneIndigo
```

## Components

### Evaluation runtime

- [Run configuration](https://github.com/tartrl/tikick/blob/main/tmarl/configs/config.py): `tmarl/configs/config.py`
- [Evaluation runner](https://github.com/tartrl/tikick/blob/main/tmarl/runners/base_evaluator.py): `tmarl/runners/base_evaluator.py`
- [Football evaluator](https://github.com/tartrl/tikick/blob/main/tmarl/runners/football/football_evaluator.py): `tmarl/runners/football/football_evaluator.py`
- [Football driver](https://github.com/tartrl/tikick/blob/main/tmarl/drivers/shared_distributed/football_driver.py): `tmarl/drivers/shared_distributed/football_driver.py`
- [Vector environments](https://github.com/tartrl/tikick/blob/main/tmarl/envs/env_wrappers.py): `tmarl/envs/env_wrappers.py`

### Football simulation

- [Multi-agent adapter](https://github.com/tartrl/tikick/blob/main/tmarl/envs/football/football.py): `tmarl/envs/football/football.py`
- [Football environment API](https://github.com/tartrl/tikick/blob/main/tmarl/envs/football/env/football_env.py): `tmarl/envs/football/env/football_env.py`
- [Football engine core](https://github.com/tartrl/tikick/blob/main/tmarl/envs/football/env/football_env_core.py): `tmarl/envs/football/env/football_env_core.py`
- [Scenario configuration](https://github.com/tartrl/tikick/blob/main/tmarl/envs/football/env/config.py): `tmarl/envs/football/env/config.py`
- [Scenario builder](https://github.com/tartrl/tikick/blob/main/tmarl/envs/football/env/scenario_builder.py): `tmarl/envs/football/env/scenario_builder.py`
- [Football scenarios](https://github.com/tartrl/tikick/tree/main/tmarl/envs/football/scenarios): `tmarl/envs/football/scenarios`

### Policy and learning

- [MAPPO algorithm](https://github.com/tartrl/tikick/blob/main/tmarl/algorithms/r_mappo_distributed/mappo_algorithm.py): `tmarl/algorithms/r_mappo_distributed/mappo_algorithm.py`
- [MAPPO module](https://github.com/tartrl/tikick/blob/main/tmarl/algorithms/r_mappo_distributed/mappo_module.py): `tmarl/algorithms/r_mappo_distributed/mappo_module.py`
- [Policy network](https://github.com/tartrl/tikick/blob/main/tmarl/networks/policy_network.py): `tmarl/networks/policy_network.py`
- [Action distributions](https://github.com/tartrl/tikick/blob/main/tmarl/networks/utils/act.py): `tmarl/networks/utils/act.py`
- [Shared rollout buffer](https://github.com/tartrl/tikick/blob/main/tmarl/replay_buffers/normal/shared_buffer.py): `tmarl/replay_buffers/normal/shared_buffer.py`
- [Value normalization](https://github.com/tartrl/tikick/blob/main/tmarl/utils/valuenorm.py): `tmarl/utils/valuenorm.py`

### Replay output

- [Replay helpers](https://github.com/tartrl/tikick/blob/main/tmarl/envs/football/env/script_helpers.py): `tmarl/envs/football/env/script_helpers.py`
- [Replay video renderer](https://github.com/tartrl/tikick/blob/main/scripts/football/replay2video.py): `scripts/football/replay2video.py`
- **Saved replay**

### Other components

- **Evaluator**

## Connections

- Evaluator → Football evaluator: starts evaluation (evidence: `tmarl/runners/football/football_evaluator.py`)
- Football evaluator → Evaluation runner: extends (evidence: `tmarl/runners/football/football_evaluator.py`)
- Evaluation runner → Run configuration: loads options (evidence: `tmarl/runners/base_evaluator.py`)
- Evaluation runner → Football driver: initializes driver (evidence: `tmarl/runners/football/football_evaluator.py`)
- Football evaluator → Multi-agent adapter: selects environment (evidence: `tmarl/runners/football/football_evaluator.py`)
- Football evaluator → Vector environments: creates vector envs (evidence: `tmarl/runners/football/football_evaluator.py`)
- Football driver → MAPPO algorithm: builds trainer
- Football driver → Shared rollout buffer: uses rollout storage
- Football driver → MAPPO module: requests actions (evidence: `tmarl/drivers/shared_distributed/football_driver.py`)
- Football driver → Vector environments: steps environments (evidence: `tmarl/drivers/shared_distributed/football_driver.py`)
- Vector environments → Multi-agent adapter: steps wrapped env
- Multi-agent adapter → Football environment API: creates environment (evidence: `tmarl/envs/football/football.py`)
- Football environment API → Football engine core: uses engine core (evidence: `tmarl/envs/football/env/football_env.py`)
- Football environment API → Scenario configuration: uses configuration (evidence: `tmarl/envs/football/env/football_env.py`)
- Scenario configuration → Scenario builder: uses builder (evidence: `tmarl/envs/football/env/config.py`)
- Scenario builder → Football scenarios: loads scenarios
- MAPPO algorithm → MAPPO module: updates module
- MAPPO module → Policy network: constructs policy (evidence: `tmarl/algorithms/r_mappo_distributed/mappo_module.py`)
- Policy network → Action distributions: uses action layer (evidence: `tmarl/networks/policy_network.py`)
- MAPPO algorithm → Value normalization: uses normalization (evidence: `tmarl/algorithms/r_mappo_distributed/mappo_algorithm.py`)
- Shared rollout buffer → Value normalization: denormalizes returns (evidence: `tmarl/replay_buffers/normal/shared_buffer.py`)
- Football evaluator → Saved replay: saves replay (evidence: `README.md`)
- Replay video renderer → Replay helpers: uses helpers (evidence: `scripts/football/replay2video.py`)
- Evaluator → Replay video renderer: renders replay (evidence: `README.md`)
- Replay video renderer → Saved replay: reads replay (evidence: `scripts/football/replay2video.py`)
