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 (gestionnaire de paquets et d'environnements)

Installation :

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 :

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 :

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 :

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/ :

• Carte (YAML)
• Monstre (JSON)
• Fiches de personnages PJ

Règles implémentées

Voir la documentation complète dans docs/rules/ :

• Règles Phase 0 implémentées
• Conformance SRD

Architecture & développement

Voir 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 pour les guidelines de contribution : style de code, tests, gate de validation, processus de PR.