Guide de création de scénarios

Ce guide s’adresse aux intervenants et créateurs qui veulent concevoir leur propre scénario. Il part de zéro, construit pas à pas le scénario « Le stand de limonade », puis donne les clés d’un scénario réussi : pédagogique, équilibré et amusant.

Documents de référence : format · langage de formules · kit IA.

1. Avant d’écrire une ligne

Répondez à ces cinq questions. Elles valent plus que n’importe quelle formule.

Question	Exemple (limonade)
Qu’est-ce que les joueurs doivent avoir compris à la fin ? (3 à 5 objectifs)	La marge ; le prix fait varier le nombre de clients ; les invendus et les ruptures coûtent ; s’adapter à une information
Quels arbitrages vont-ils faire ? Une bonne décision est un dilemme : plus de X, mais moins de Y	Prix haut = grosse marge mais peu de clients ; beaucoup de verres = pas de rupture mais des invendus
Combien de temps dure une session ?	30 minutes, 6 journées de 2–3 minutes
Qui joue ?	Débutants, dès le lycée
Qu’est-ce qui rend la partie vivante ?	La météo change chaque jour, une canicule, la fête du village, un quiz

Règle d’or : peu de décisions, mais chacune importante. Comptez 3 à 5 décisions en niveau facile, 8 à 12 en niveau normal, 15 au maximum en expert.

2. Trois façons de créer

Méthode	Pour qui	Comment
Éditeur visuel (V1)	Tout le monde	Des formulaires guidés pour chaque partie du scénario, avec aide et aperçu
Éditeur de code	À l’aise avec le JSON	Le fichier `scenario.json` avec autocomplétion et erreurs en direct
IA	Pour aller vite	Donnez le kit IA et votre idée à une IA, importez le résultat, corrigez avec les messages d’erreur

Dans tous les cas, vous finirez par tester (partie solo instantanée) et équilibrer (banc d’essai).

3. Tutoriel : le stand de limonade

Le fichier complet est scenarios/officiels/limonade/scenario.json. Nous le construisons ici en 9 étapes.

Étape 1 — Présenter le scénario

"meta": {
  "title": "Le stand de limonade",
  "summary": "Fixez votre prix, préparez le bon nombre de verres selon la météo et attirez les passants.",
  "sector": "commerce",
  "language": "fr",
  "estimatedDuration": { "min": 25, "max": 45 }
},
"settings": {
  "roundLabel": { "singular": "journée", "plural": "journées" },
  "companyLabel": { "singular": "stand", "plural": "stands" },
  "rounds": { "default": 6, "min": 4, "max": 10 },
  "practiceRound": true,
  "marketModes": ["parallel", "shared"],
  "playModes": ["individual", "teams"]
}

On renomme les tours en « journées » et les entreprises en « stands » : l’interface parlera la langue du scénario.

Étape 2 — Les paramètres fixes (constantes)

"constants": [
  { "id": "tresorerieInitiale", "label": "Économies de départ", "value": 30, "format": "money",
    "adjustable": { "min": 10, "max": 100, "step": 5 } },
  { "id": "coutVerre", "label": "Coût d'un verre", "value": 0.25, "format": "money", "decimals": 2 },
  { "id": "loyerJour", "label": "Emplacement", "value": 2, "format": "money" },
  { "id": "demandeBase", "label": "Passants intéressés par beau temps", "value": 60, "visibility": "facilitator" },
  { "id": "prixReference", "label": "Prix habituel d'une limonade", "value": 1, "format": "money" },
  { "id": "elasticite", "label": "Sensibilité des clients au prix", "value": 1.8, "visibility": "facilitator" }
]

adjustable permet à l’intervenant de changer la trésorerie de départ en créant sa session. visibility: "facilitator" cache les paramètres que les joueurs doivent découvrir par l’expérience.

Étape 3 — Ce qui se reporte d’un jour à l’autre (variables)

"variables": [
  { "id": "tresorerie", "label": "Caisse", "format": "money", "initial": "tresorerieInitiale", "next": "tresorerie + resultat" },
  { "id": "reputation", "label": "Réputation", "initial": 50, "min": 0, "max": 100, "visibility": "public",
    "next": "reputation + 10 * (tauxService - 0.8) + if(prix > 1.5, -3, 1)" },
  { "id": "temperature", "label": "Température du jour", "scope": "world", "unit": "°C", "initial": 24,
    "next": "round(clamp(0.4 * temperature + 0.6 * 24 + normal(0, 4), 10, 36))" }
]

initial : la valeur au premier jour. next : comment elle évolue. Pendant un jour, tresorerie vaut la caisse du matin ; next calcule celle du soir.
temperature est de portée world : la même pour tous les stands. Elle est tirée au hasard pour le lendemain, mais reste proche de celle de la veille et de 24 °C. Comme elle est connue le matin, les joueurs peuvent s’y adapter.

Étape 4 — Les décisions

"decisions": [
  { "id": "prix", "label": "Prix du verre", "type": "money", "min": 0.2, "max": 3, "step": 0.1,
    "initial": 1, "widget": "slider", "visibility": "public",
    "help": "Plus le verre est cher, plus vous gagnez par verre… mais moins les passants s'arrêtent." },
  { "id": "verres", "label": "Verres préparés", "type": "integer", "min": 0, "max": "floor(tresorerie / coutVerre)",
    "step": 5, "initial": 50,
    "help": "Chaque verre préparé coûte {{ coutVerre | money }}, vendu ou non." },
  { "id": "publicite", "label": "Publicité du jour", "type": "choice", "initial": "aucune", "widget": "cards",
    "levels": ["normal"], "auto": "'aucune'",
    "options": [
      { "id": "aucune",  "label": "Aucune",      "props": { "cout": 0, "effet": 1 } },
      { "id": "affiche", "label": "Une affiche", "props": { "cout": 3, "effet": 1.15 } },
      { "id": "flyers",  "label": "Des flyers",  "props": { "cout": 8, "effet": 1.35 } }
    ] }
]

Points à retenir :

La borne max des verres est une expression : on ne peut pas préparer plus de verres que la caisse ne le permet.
Chaque décision a une aide qui énonce l’arbitrage.
Les options d’un choix portent des propriétés (props) que les formules liront : publicite.cout, publicite.effet.
La publicité n’existe qu’en niveau normal (levels) ; en « Découverte », elle vaut automatiquement 'aucune' (auto).
Le prix est public : chaque stand voit le prix des autres après chaque journée.

Étape 5 — Les règles de calcul (formules)

"formulas": [
  { "id": "demandeMeteo", "label": "Passants assoiffés", "scope": "world",
    "expr": "demandeBase * curve(effetMeteo, temperature)" },
  { "id": "attractivite", "label": "Attractivité du stand", "visibility": "hidden",
    "expr": "pow(prixReference / prix, elasticite) * publicite.effet * (0.7 + 0.6 * reputation / 100)" },
  { "id": "ca", "label": "Chiffre d'affaires", "expr": "ventes * prix", "format": "money" },
  { "id": "coutIngredients", "label": "Coût des verres préparés", "expr": "verres * coutVerre", "format": "money" },
  { "id": "resultat", "label": "Bénéfice du jour", "expr": "ca - coutIngredients - publicite.cout - loyerJour", "format": "money" }
]

L’ordre n’a pas d’importance : le moteur calcule dans le bon ordre. La courbe effetMeteo (section curves) traduit la température en envie de boire, sans équation :

"curves": { "effetMeteo": { "label": "Envie de limonade selon la température",
  "points": [[10, 0.25], [18, 0.6], [25, 1], [30, 1.35], [36, 1.6]] } }

Remarquez que ventes n’est déclaré nulle part dans les formules : c’est une sortie du marché (étape suivante).

Étape 6 — Le marché

"market": { "segments": [ {
  "id": "passants", "label": "Passants",
  "size": "demandeMeteo * if(mode == 'shared', companyCount * 1.25, 2.5)",
  "attractiveness": "attractivite",
  "supply": "verres",
  "outsideOption": "0.25 * if(mode == 'shared', companyCount, 1)",
  "spillover": 0.5,
  "virtualCompetitors": [ { "id": "glacier", "label": "Le marchand de glaces", "modes": ["parallel"], "attractiveness": "1.25" } ],
  "outputs": { "demand": "demande", "sales": "ventes", "share": "partDeMarche", "lost": "clientsPerdus" }
} ] }

Le marché répartit les passants entre les stands selon leur attractivité :

supply: "verres" : on ne vend pas plus que ce qu’on a préparé ; les clients refoulés vont en partie chez un concurrent (spillover).
outsideOption : des passants renoncent si tous les prix sont trop élevés.
En marché parallèle, chaque stand est seul dans sa rue ; le marchand de glaces (concurrent virtuel) crée la concurrence.
La taille du marché et l’option extérieure dépendent du mode pour que, au prix habituel, un stand vende à peu près demandeMeteo verres dans les deux modes. C’est la méthode de calibrage du kit IA §6.

Étape 7 — Les événements

{ "id": "canicule", "type": "effect", "scope": "world", "tone": "positive",
  "title": "Canicule !", "text": "La météo annonce **{{ temperature }} °C**. Les passants vont avoir très soif.",
  "trigger": { "type": "random", "probability": 0.15, "from": 2 }, "maxOccurrences": 2, "cooldown": 2,
  "effects": [ { "target": "temperature", "op": "add", "value": 7 } ],
  "teaching": "Une forte demande se prépare : plus de verres, et c'est le jour où la publicité rapporte le plus." }

Le scénario complet contient aussi un orage (modificateur temporaire sur la demande), une hausse du prix des citrons (programmée au jour 3), un dilemme (la fête du village) et un quiz sur la marge. Chaque événement porte une leçon (teaching).

Étape 8 — Gagner, voir, apprendre

scoring : le score est l’argent gagné (tresorerie - tresorerieInitiale) ; trophées du stand le plus populaire et du roi du volume ; badges « Zéro gaspillage » et « Jamais dans le rouge ».
reports : un compte de la journée (statement), un tableau des clients, un graphique de la caisse, une page « La rue » qui compare les prix publics.
pedagogy : objectifs, briefing, glossaire, conseils pendant la partie (« Hier, vous avez jeté 18 verres… »), enseignements de fin, questions de débrief, notes pour l’animateur.

Étape 9 — Tester

Importez le fichier : aucune erreur ne doit apparaître.
Jouez une partie test : vérifiez que le compte de la journée « tombe juste » à la main au moins une fois.
Essayez des stratégies extrêmes (prix à 0,20 €, à 3 €, 0 verre, 200 verres) : rien ne doit casser, et elles ne doivent pas gagner.
Lancez le banc d’essai et lisez les alertes.

4. Concevoir un bon jeu

4.1 Des arbitrages, pas des évidences

Une décision sans contrepartie n’est pas une décision. Pour chaque décision, écrivez la phrase « plus de X, mais moins de Y » :

Décision	Gain	Contrepartie
Prix élevé	Marge	Moins de clients
Grosse production	Pas de rupture	Stock, obsolescence, trésorerie
Marketing	Clients, notoriété future	Coût immédiat, rendements décroissants
Embauche	Capacité	Masse salariale, compétence moyenne en baisse
Investissement	Capacité future	Trésorerie aujourd’hui, amortissement
Fournisseur bon marché	Coût	Qualité, risque

4.2 Des effets visibles… et des effets retardés

Les joueurs apprennent quand ils voient le lien entre décision et résultat. Mélangez :

des effets immédiats (prix → ventes du tour) ;
des effets différés (marketing → notoriété des tours suivants ; ligne achetée → capacité au tour suivant) : c’est là qu’on apprend l’anticipation.

Le bouton « Comprendre ce chiffre » affiche vos label et description : soignez-les.

4.3 L’information

Décidez de ce que chacun voit :

les règles (constantes) sont publiques par défaut ; cachez ce qui doit être découvert (facilitator) ;
en marché partagé, rendez public ce qu’on observe chez un vrai concurrent (prix, part de marché, notoriété), gardez private les comptes ;
l’intervenant voit tout : c’est sa matière pour le débrief.

4.4 Le hasard, avec mesure

Le hasard rend la partie vivante mais ne doit pas décider du gagnant :

annoncez les chocs en début de tour (événements effect) pour que les joueurs réagissent ;
limitez l’ampleur : un choc ne devrait pas coûter plus de 30 à 50 % du résultat d’un tour ;
utilisez maxOccurrences et cooldown ;
en marché parallèle, tous les joueurs ont exactement la même chance ; en marché partagé, choisissez sharedModeLuck: "identical" si l’équité prime.

4.5 Le rythme d’une séance

Durée de séance	Tours	Temps de décision
30 min	5–6	2–3 min
1 h 30	6–8	5–7 min (10 au premier tour)
3 h	8–12	7–10 min

Prévoyez un tour d’essai, et des événements forts au milieu de partie (tours 3 à 5) pour relancer l’intérêt.

4.6 Le plaisir de jouer

Un choix fondateur en mise en place (phase: "setup") donne une identité à chaque équipe.
Des dilemmes avec une part de risque (outcomes) créent des discussions dans les équipes.
Des quiz rythment la séance et récompensent l’attention.
Des trophées variés (qualité, social, croissance…) : tout le monde ne joue pas que pour le profit.
Des rumeurs (rumor) apprennent l’esprit critique.
Des images et un thème soignés font entrer dans l’histoire.

4.7 Les niveaux de difficulté

Un même scénario peut servir à des publics différents :

Découverte : moins de décisions (les autres en auto), plus de trésorerie, moins de chocs, moins de tours ;
Normal : l’expérience prévue ;
Expert : clients plus sensibles aux prix, trésorerie réduite, plus de chocs, bots plus nombreux.

5. Calibrer et équilibrer

Entreprise de référence. Écrivez le compte de résultat attendu d’une entreprise « moyenne » au tour 1 (voir le kit IA §6). Déduisez-en les constantes.
Vérification à la main. En mode test, jouez le tour 1 avec les décisions de départ : retrouvez-vous vos chiffres ? Notez-les dans facilitatorNotes.
Stratégies extrêmes. Prix minimal et maximal, production nulle et maximale, aucun marketing et marketing maximal : aucune ne doit gagner à coup sûr.
Banc d’essai. Il joue des centaines de parties et signale :

Alerte	Ce qu’elle veut dire	Piste de correction
`B810` Trop de faillites	Le jeu est trop dur même en jouant raisonnablement	Plus de trésorerie, coûts fixes plus bas, chocs moins forts
`B811` Aucune faillite, même au hasard	Rien n’est puni	Coûts fixes plus élevés, élasticité plus forte
`B820` Stratégie dominante	Une valeur extrême gagne presque toujours	Ajouter une contrepartie (rendement décroissant, coût, effet négatif)
`B821` Décision sans effet	Elle ne change pas le score	Renforcer son effet, ou la supprimer
`B830` Scores trop proches	Les bonnes décisions ne sont pas récompensées	Élargir les effets (élasticité, qualité, marketing)
`B840` Événement trop fort	Il décide du gagnant	Réduire son effet ou sa probabilité

6. Images et thème

Image	Format conseillé	Usage
Couverture (`meta.cover`)	1600 × 900 (16/9)	Marketplace, salle d’attente
Fond (`theme.background`)	1920 × 1080	Écran de projection, salle d’attente (prévoir une zone calme au centre)
Événements	1200 × 675	Annonces
Éléments de liste, options	800 × 600	Cartes de choix
Avatars d’entreprise	512 × 512, sujet centré	Équipes

Toujours un texte alternatif (alt) qui décrit l’image. Utilisez des images dont vous avez les droits (licence indiquée dans credit). Les couleurs du thème sont vérifiées automatiquement : si le contraste est insuffisant, la palette par défaut est utilisée.

7. Publier

Version. Publiez une version (1.0.0). Toute modification ultérieure crée une nouvelle version ; les sessions déjà créées gardent la leur.
Licence. Choisissez une licence (meta.license) : CC-BY-4.0 permet aux autres de réutiliser et adapter votre scénario en vous citant.
Marketplace. La soumission déclenche automatiquement la validation et le banc d’essai. Un modérateur vérifie :
- aucune erreur, avertissements corrigés ou justifiés ;
- textes corrects, respectueux, sans contenu choquant ;
- images libres de droits avec texte alternatif ;
- objectifs pédagogiques et notes de l’animateur présents ;
- scénario joué au moins une fois en entier.
Vie du scénario. Lisez les avis, répondez-y, publiez des versions améliorées avec des notes de version claires.

8. Comment modéliser… ?

Je veux…	Voir
Un stock, des invendus, une rupture	Recettes du langage, scénario usine-ram (`stock`, `obsolescence`)
Une capacité limitée par les machines et le personnel	usine-ram : `capacite`, `tauxCharge`
Un investissement qui arrive au tour suivant	usine-ram : `nouvellesLignes` → `lignes`
Un emprunt, des intérêts, un découvert	usine-ram : `emprunt`, `interets`, `agios`
Un compte de résultat et un tableau de flux de trésorerie	usine-ram : `reports.pages`
Du surbooking	Kit IA §5, scénarios hôtel et compagnie aérienne
Plusieurs produits	Une liste (`lists`) et des grandeurs `per`
Une commande spéciale hors marché	usine-ram : dilemme `commandeGeante`, formule `commandeB2B`
Un coût exceptionnel visible dans les comptes	usine-ram : `chargesExceptionnelles`
Une saisonnalité	usine-ram : `saisonnalite`
Des concurrents automatiques	`bots` (usine-ram : trois profils)