Metadata-Version: 2.4
Name: frondori-football
Version: 0.1.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Education
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Requires-Dist: frondori-engine>=0.4
Requires-Dist: numpy>=1.24
Requires-Dist: gymnasium>=1.0
Requires-Dist: pettingzoo>=1.24
Requires-Dist: pytest>=7 ; extra == 'dev'
Provides-Extra: dev
License-File: LICENSE
Summary: football-v0: a 2D football duel for Frondori, on a deterministic Rust physics engine — a PettingZoo environment.
Author: Melvine Nargeot
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://frondori.com/documentation/environments
Project-URL: Homepage, https://frondori.com
Project-URL: Issues, https://github.com/Melvin-klein/frondori-football/issues
Project-URL: Source, https://github.com/Melvin-klein/frondori-football

# frondori-football

`football-v0` : football 2D en duel pour Frondori.
Deux équipes de trois joueurs ; chaque agent contrôle une équipe entière.
Moteur physique Rust déterministe (rapier2d) : même seed et mêmes actions,
même match, pas pour pas.

## Installation

```bash
pip install frondori-football     # installe aussi frondori-engine
```

Wheel précompilée prévue sur PyPI (pas encore publiée). Depuis un clone, il
faut une toolchain Rust :

```bash
python -m venv .venv && source .venv/bin/activate
pip install -e ../frondori-engine maturin
maturin develop
```

## Utilisation

```python
import frondori_engine

env = frondori_engine.make("football-v0")   # découvert automatiquement
observations, infos = env.reset(seed=0)
while env.agents:
    actions = {agent: env.action_space(agent).sample() for agent in env.agents}
    observations, rewards, terminations, truncations, infos = env.step(actions)
```

Paramètres (les matchs de compétition utilisent toujours les valeurs par
défaut) : `players_per_team` (3), `max_ticks` (9000), `max_score` (aucun),
`field_width`, `field_height`, `goal_width`, `player_max_speed`,
`kick_max_speed`, `kick_range`...

Règles, observations et actions : docstring de `frondori_football.env`, et
en anglais sur le site (Documentation > Environments).

## Organisation

- `engine/` : le moteur, pur Rust, sans Python ni réseau (`cargo test -p engine`).
  **Déterminisme total** exigé : jamais de `rand::thread_rng()` dans la
  simulation. Observations ET actions sont exprimées dans le repère de
  l'équipe (elle attaque toujours vers `x = +1`) : cf. `to_field_frame`.
- `src/lib.rs` : les bindings PyO3 (module natif `frondori_football._football`).
- `python/frondori_football/` : l'environnement PettingZoo.

## Tester

```bash
cargo test --workspace         # le moteur
maturin develop && python -m pytest
```

`.cargo/config.toml` ajoute des flags de lien macOS, sans lesquels la
feature `extension-module` de PyO3 casse `cargo test --workspace` sur macOS.
Un simple `cargo build` ne produit pas un module importable : passer par
`maturin develop`.

## Publier une version

1. Mettre à jour `version` dans `pyproject.toml` et commiter.
2. Pousser un tag du même numéro : `git tag v0.1.0 && git push origin v0.1.0`.

La CI (`.github/workflows/ci.yml`) teste, construit et publie sur PyPI ; elle
refuse un tag qui ne correspond pas à la version. Publication par *Trusted
Publishing*, sans token : à configurer une fois sur PyPI (projet `frondori-football` >
Publishing > trusted publisher GitHub : ce dépôt, workflow `ci.yml`,
environnement `pypi`).

`frondori-engine` doit être publié AVANT ce paquet (il en dépend, et la CI
l'installe depuis PyPI).

Licence : MIT.

