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

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 :

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

Utilisation

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

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.