ctan
f61fc5c61f
- Clean README.md with installation, usage, CLI, examples - Move data formats to docs/data-formats/ (map.md, monster.md, pc-sheets.md, index.md) - Move architecture to docs/architecture/ (index.md, technical-architecture.md, phase-2-llm-architecture.md) - Add contributing guidelines in docs/contributing.md - Clean README.md: install, usage, CLI, data-formats/rules/architecture links, contributing link
115 lines
4.1 KiB
Markdown
115 lines
4.1 KiB
Markdown
# 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. |