skori_games/CONTRIBUTING.md

Contribuer

Chaque ajout ou correction passe par une demande de fusion (pull request), relue avant publication. Le CI vérifie automatiquement les fichiers.

Ajouter un jeu

1. Trouvez le jeu sur BoardGameGeek et notez son bggId (le nombre dans l'adresse de sa page).

2. Créez le dossier games/<bggId>-<nom-en-kebab-case>/, par exemple games/9209-les-aventuriers-du-rail/.

3. Ajoutez game.json :

   {
     "$schema": "../../schemas/game.schema.json",
     "schemaVersion": 1,
     "bggId": 9209,
     "name": "Les Aventuriers du Rail",
     "officialRulesUrl": "https://www.daysofwonder.com/…"
   }
   

4. Ajoutez scoring.json, le modèle de score. Son id vaut bgg-<bggId>. Le plus simple : dans l'app, Jeux → Ajouter un jeu, créez le modèle, puis Exporter le modèle depuis la fiche du jeu. Inspirez-vous aussi des jeux existants (catégories, options, cible de fin de partie, équipes…).

5. Facultatif : rules.fr.json, la fiche de règles :

   {
     "$schema": "../../schemas/rules.schema.json",
     "schemaVersion": 1,
     "locale": "fr",
     "summary": "Le jeu en une ou deux phrases.",
     "goal": "But du jeu.",
     "setup": "Mise en place.",
     "turn": "Déroulement d'un tour.",
     "end": "Fin de partie.",
     "scoring": "Décompte des points.",
     "tips": "Conseils."
   }
   

   summary, goal et turn sont obligatoires. Texte brut, retours à la ligne autorisés. Rédigez avec vos propres mots : pas de copier-coller du livret de l'éditeur.

Ajouter une extension

Une variante incluse dans la boîte du jeu (mode alternatif, règle optionnelle) est une option dans scoring.json. Un produit vendu à part, avec sa propre fiche BoardGameGeek, est une extension :

games/414317-harmonies/
  expansions/
    472690-crescendo/        # <bggId de l'extension>-<nom>
      expansion.json         # obligatoire
      rules.fr.json          # facultatif : seulement ce qui change

expansion.json décrit uniquement ce que l'extension ajoute au modèle du jeu de base :

{
  "$schema": "../../../../schemas/expansion.schema.json",
  "schemaVersion": 1,
  "bggId": 472690,
  "name": "Crescendo",
  "adds": {
    "options": [
      { "type": "boolean", "id": "murmures", "label": "Module Murmures", "default": true }
    ],
    "choices": [
      { "optionId": "plateau", "values": [{ "value": "C", "label": "Face C" }] }
    ],
    "categories": [
      { "id": "murmures", "label": "Murmures", "requiresOption": "murmures", "after": "animaux" }
    ]
  }
}

• options : chaque module de l'extension devient une option, que les joueurs cochent au lancement de la partie.
• choices : nouvelles valeurs pour un choix existant du jeu de base.
• categories : nouvelles catégories de score, placées après after (sinon à la fin) ; requiresOption les lie au module correspondant.
• players / end : remplacent le nombre de joueurs ou la fin de partie.

Le CI vérifie que l'extension s'applique au jeu de base, et que toutes les extensions d'un jeu peuvent être jouées ensemble (pas deux fois le même identifiant, pas deux extensions qui changent la même règle).

La fiche de règles d'une extension (rules.fr.json, schéma expansion-rules.schema.json) n'exige que summary : décrivez ce qui change (mise en place, déroulement, décompte), pas tout le jeu.

Ajouter des images

Par défaut, l'app affiche la miniature BoardGameGeek du jeu. Vous pouvez fournir un logo (carré) et une bannière (format large, environ 3:1), uniquement si leurs droits le permettent :

Licence (license)	Quand l'utiliser
CC0-1.0	domaine public, aucune attribution requise
CC-BY-4.0	réutilisation libre avec attribution
CC-BY-SA-4.0	réutilisation libre avec attribution et partage à l'identique
publisher-permission	l'éditeur autorise cet usage par écrit : permission doit pointer vers cette autorisation

Une image trouvée sur internet, une photo de boîte ou un visuel de l'éditeur sans licence libre ni autorisation écrite n'a pas sa place ici.

games/230802-azul/
  assets/
    assets.json
    logo.webp
    banner.webp

{
  "$schema": "../../../schemas/assets.schema.json",
  "schemaVersion": 1,
  "files": [
    {
      "file": "logo.webp",
      "role": "logo",
      "license": "CC-BY-4.0",
      "author": "Nom de l'auteur",
      "source": "https://… (page d'origine de l'image)"
    }
  ]
}

Le CI vérifie que :

• chaque image est déclarée dans assets.json, et chaque image déclarée est présente ;
• c'est vraiment une image PNG, JPEG ou WebP (pas de SVG) qui correspond à son extension ;
• elle pèse 512 Ko au maximum (préférez WebP) ;
• l'auteur est indiqué (sauf CC0), et le lien d'autorisation pour publisher-permission.

L'app affiche le crédit (auteur, licence, lien vers la source) près de chaque image. Une extension peut aussi avoir son dossier assets/, dans son propre dossier.

À la relecture, vérifiez la licence sur la page source (et l'autorisation sur permission) : le CI ne peut pas le faire à votre place.

Vérifier avant d'envoyer

Avec un éditeur qui comprend les schémas JSON (VS Code…), la clé $schema donne l'autocomplétion et signale les erreurs au fil de la frappe.

La validation complète (celle du CI) se lance depuis le dépôt de l'app :

pnpm --filter @skori/server content:validate ../skori-games

Jeux intégrés à l'app

Les dossiers dont game.json contient un slug (azul, cabo…) correspondent aux jeux livrés avec l'app ; leur scoring.json garde l'id du jeu intégré. Une correction de leur modèle de score doit aussi être reportée dans le dépôt de l'app.

Licence

En contribuant, vous acceptez que votre contribution soit publiée sous licence CC BY-SA 4.0.