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
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/ :
Règles implémentées
Voir la documentation complète dans docs/rules/ :
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.