# pf1e-simulator

Simulateur de combat Monte Carlo déterministe pour Pathfinder 1re édition.

Le moteur joue une rencontre définie (carte + camps) un grand nombre de fois —
chaque combat est reproductible grâce à un générateur aléatoire seedé — puis
produit un rapport d'équilibrage en français : taux de victoire par camp avec
bande de confiance 3σ, nuls, rounds moyens et attrition par combattant.

## Prérequis et installation

**Prérequis :**
- Python ≥ 3.12
- [uv](https://docs.astral.sh/uv/) (gestionnaire de paquets et d'environnements)

**Installation :**
```bash
git clone <url-du-dépôt> pf1e-simulator
cd pf1e-simulator
uv sync --dev        # inclut pytest, ruff et basedpyright
```

`uv sync` seul suffit pour n'utiliser que la CLI (pas d'outillage de dev).

**Vérification :**
```bash
uv run pf1e-sim --help
```

## Démarrage rapide

La carte d'exemple `data/maps/sample_arena.yaml` et les monstres
`data/monsters/goblin.json` / `data/monsters/orc.json` permettent de lancer une
première simulation immédiatement. 3 gobelins (camp `players`) contre 2 orcs
(camp `monsters`), 1000 combats, seed 1 :

```bash
uv run pf1e-sim \
  --map data/maps/sample_arena.yaml \
  --side players data/monsters/goblin.json data/monsters/goblin.json data/monsters/goblin.json \
  --side monsters data/monsters/orc.json data/monsters/orc.json \
  --runs 1000 --seed 1
```

**Sortie (extrait) :**
```
=== Rapport d'équilibrage ===
Carte : Arène d'essai
players : 3 combatants
monsters : 2 combatants
1000 combats simulés (seed 1, plafond 100 rounds)

Victoires players : 96.2% (962) — bande 3σ : [94.4%, 98.0%]
Victoires monsters : 3.6% (36) — bande 3σ : [1.8%, 5.4%]
Nuls : 0.2% (2)
Rounds moyens : 6.6
```

## Utilisation de la CLI

```
usage: pf1e-sim [-h] --map MAP [--side NAME [FILE ...]] [--runs RUNS]
                [--seed SEED] [--round-cap ROUND_CAP] [--transcript]
                [--simple-monster-death] [--llm-report] [--output OUTPUT]
                [--llm-model MODEL] [--llm-base-url URL] [--llm-api-key KEY]
```

| Option | Rôle | Défaut |
|---|---|---|
| `--map MAP` | Fichier YAML de la carte (obligatoire) | — |
| `--side NAME [FILE ...]` | Camp `NAME` avec un ou plusieurs JSON de monstres ; répétable pour chaque camp | — |
| `--runs RUNS` | Nombre de combats simulés | `1000` |
| `--seed SEED` | Graine du générateur aléatoire | `1` |
| `--round-cap ROUND_CAP` | Plafond de rounds par combat, entier ≥ 1 | `100` |
| `--transcript` | Imprimer le déroulé du premier combat en tableau | désactivé |
| `--simple-monster-death` | Mort simplifiée des monstres : `hp ≤ 0` | désactivé |
| `--llm-report` | Générer un rapport narratif FR via LLM | désactivé |
| `--output OUTPUT` | Écrire le rapport complet (factuel + LLM) dans ce fichier | — |
| `--llm-model MODEL` | Modèle LLM (défaut: `PF1E_LLM_MODEL` ou `gpt-4o-mini`) | — |
| `--llm-base-url URL` | URL de base LLM (défaut: `PF1E_LLM_BASE_URL`) | — |
| `--llm-api-key KEY` | Clé API LLM (défaut: `PF1E_LLM_API_KEY`) | — |

**Exemple avec rapport LLM :**
```bash
export PF1E_LLM_API_KEY=sk-...
export PF1E_PROMPT_PACK_DIR=/chemin/vers/prompt-pack
uv run pf1e-sim \
  --map data/maps/sample_arena.yaml \
  --side players data/monsters/goblin.json \
  --side monsters data/monsters/orc.json \
  --runs 100 --seed 1 --llm-report --output rapport.md
```

## Formats de données

Voir la documentation complète dans [`docs/data-formats/`](docs/data-formats/) :
- [Carte (YAML)](docs/data-formats/map.md)
- [Monstre (JSON)](docs/data-formats/monster.md)
- [Fiches de personnages PJ](docs/data-formats/pc-sheets.md)

## Règles implémentées

Voir la documentation complète dans [`docs/rules/`](docs/rules/) :
- [Règles Phase 0 implémentées](docs/rules/phase-0-implemented.md)
- [Conformance SRD](docs/rules/conformance-srd.md)

## Architecture & développement

Voir [`docs/architecture/`](docs/architecture/) pour l'architecture technique,
le plan d'implémentation Phase 2 (LLM), et les décisions de design.

## Contribuer

Consultez [`docs/contributing.md`](docs/contributing.md) pour les guidelines de
contribution : style de code, tests, gate de validation, processus de PR.