homer
ea397622bb
Validation du contenu / validate (push) Has been cancelled
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
222 lines
8.2 KiB
Markdown
222 lines
8.2 KiB
Markdown
# 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/<bggId>-<nom-en-kebab-case>/`, 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-<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…).
|
||
|
||
Le jeu, ses catégories et ses saisies peuvent avoir une icône (`"icon"`),
|
||
choisie parmi : Anchor, Apple, Atom, Award, Axe, Banknote, Beef, Beer,
|
||
Bird, BookOpen, Brain, Bug, Building2, Car, Carrot, Castle, Cat, Church,
|
||
Circle, Clock, Cloud, Club, Coffee, Cog, Coins, Compass, Cookie, Crown,
|
||
Diamond, Dice5, Dices, Dog, Drama, Droplet, Egg, Eye, Factory, Feather,
|
||
Fish, Flag, FlaskConical, Flame, Flower2, Gem, Ghost, Gift, Globe, Grape,
|
||
Hammer, Hand, Heart, Hexagon, Hourglass, House, Key, Landmark, Layers,
|
||
Leaf, Lock, Map, Medal, Moon, Mountain, Music, Palette, PawPrint, Pickaxe,
|
||
Pizza, Puzzle, Rabbit, Rocket, Route, Scroll, Shield, Ship, Skull,
|
||
Snowflake, Spade, Sparkles, Sprout, Square, Squirrel, Star, Sun, Sword,
|
||
Swords, Target, Tent, TrainFront, TreePine, Trees, Triangle, Trophy,
|
||
Turtle, User, Users, Warehouse, Waves, Wheat, Wine, Wrench, Zap. Leur
|
||
dessin est visible sur [lucide.dev/icons](https://lucide.dev/icons). Un nom
|
||
inconnu affiche un dé. Pour une image à vous, voir « Ajouter des images ».
|
||
|
||
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/ # <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 :
|
||
|
||
```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).
|