# 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](https://boardgamegeek.com) et notez son `bggId` (le nombre dans l'adresse de sa page). 2. Créez le dossier `games/-/`, par exemple `games/9209-les-aventuriers-du-rail/`. 3. Ajoutez `game.json` : ```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-`. 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 : ```json { "$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/ # - 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 : ```json { "$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 et des symboles génériques. Vous pouvez fournir vos propres images, **uniquement si leurs droits le permettent** : | Rôle (`role`) | Image | Format conseillé | |---|---|---| | `logo` | remplace la miniature du jeu | carré, 256 × 256 | | `banner` | bannière en haut de la fiche | large, environ 3:1 | | `category-icon` | icône d'une catégorie de score ; `category` donne son identifiant dans `scoring.json` (ex : `arbres`) | carré, 96 × 96, fond transparent (PNG ou WebP) | | `starter-icon` | pastille du joueur qui a la main (ex : le jeton premier joueur d'Azul) ; le modèle doit avoir un champ `starter` | carré, 96 × 96, fond transparent | Une image par rôle, et une icône par catégorie. Licences acceptées : | 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. **Votre propre création** (dessinée par vous, publiée ici pour la première fois) : mettez `"original": true` à la place de `source`, avec une licence libre et votre nom dans `author`. En la publiant ici, vous la placez sous cette licence. ``` games/230802-azul/ assets/ assets.json logo.webp banner.webp ``` ```json { "$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)" }, { "file": "jeton.png", "role": "starter-icon", "license": "CC-BY-4.0", "author": "Votre nom", "original": true } ] } ``` Les icônes des catégories ajoutées par une extension (ex : `murmures` pour Crescendo) vont dans le dossier `assets/` de l'extension ; celles du jeu de base et le jeton, dans le dossier du jeu. 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), la page d'origine (sauf création originale), et le lien d'autorisation pour `publisher-permission` ; - chaque icône de catégorie illustre une catégorie qui existe, et le jeton un jeu qui suit le joueur qui a la main. L'app affiche le crédit (auteur, licence, lien vers la source) près du logo et de la bannière, et regroupe celui des icônes en bas de la fiche du jeu. **À 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 : ```bash 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](LICENSE).