root
373 lines
13 KiB
Markdown
373 lines
13 KiB
Markdown
<div align="center">
|
||
|
||
# 🎲 Boidelo
|
||
|
||
**L'application de jeux de soirée — questions, défis et cartes entre amis**
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
</div>
|
||
|
||
---
|
||
|
||
## 📖 Description
|
||
|
||
**Boidelo** est une application Android de jeux de soirée regroupant plusieurs mini-jeux autour d'un hub central. Entrez les noms des joueurs, choisissez un jeu, et laissez l'ambiance opérer !
|
||
|
||
L'application propose trois jeux distincts ainsi qu'un consulteur de règles de jeux d'ambiance populaires.
|
||
|
||
---
|
||
|
||
## 🎮 Jeux disponibles
|
||
|
||
### 1. Boidelo Classic
|
||
|
||
Le jeu original de questions et défis. Inspiré de jeux comme *King's Cup* ou *Never Have I Ever*.
|
||
|
||
- **150+ questions** préchargées depuis un fichier JSON, avec 10 catégories distinctes
|
||
- Questions dynamiques avec remplacement de variables (`<J1>`, `<J2>`, `<J3>`, `<variante>`)
|
||
- **Défis multi-manches** avec compte à rebours et message de fin
|
||
- Gestion intelligente : pas d'accumulation de défis simultanés
|
||
- Système de **gorgées** (boire / distribuer) avec accord grammatical automatique
|
||
- Catégorisation automatique des questions avec couleur de fond dynamique :
|
||
- Ciblage, Classement, Jugement, Duel, Interactif, Défi, Variante, Caliente, Vote, Classique
|
||
- Paramètres personnalisables : nombre de questions, gorgées supplémentaires, durée des défis
|
||
- **Intégration OpenAI** (optionnelle) pour générer des questions via ChatGPT
|
||
|
||
### 2. 89++
|
||
|
||
Un jeu de cartes avec timer et défis spéciaux.
|
||
|
||
- Objectif : ne pas être celui qui atteint ou dépasse **89**
|
||
- Règles spéciales : Valet (−10), Dame (changement de sens), Roi (choix de valeur)
|
||
- Gorgées distribuées à chaque dizaine atteinte (70 = double !)
|
||
- **9 types de défis** aléatoires :
|
||
- Changement de sens, Immunité, Gorgée surprise, Joker (passer son tour), Échange de mains, Double prochaine valeur, Compte mystère, Tour générale, Victime au choix
|
||
- Timer configurable pour les défis
|
||
- Suivi des gorgées par joueur
|
||
|
||
### 3. Papelito (Undercover)
|
||
|
||
Un jeu de déduction sociale. Trouvez l'Undercover avant qu'il ne soit trop tard !
|
||
|
||
- **20 paires de mots** préchargées (Pizza/Burger, Chat/Chien, Vin/Bière, etc.)
|
||
- Attribution aléatoire des rôles : **Civil**, **Undercover**, **Mr. White**
|
||
- Mécanique de **discussion → vote → élimination**
|
||
- Conditions de victoire :
|
||
- Civils gagnent si tous les Undercovers sont éliminés
|
||
- Undercovers gagnent s'ils sont en nombre ≥ aux Civils
|
||
- Gestion des égalités de votes (personne n'est éliminé)
|
||
- Machine à états avec validation des transitions légales
|
||
|
||
### 4. Règles de jeux
|
||
|
||
Consultez les règles des jeux d'ambiance populaires directement dans l'application.
|
||
|
||
---
|
||
|
||
## 🏗 Architecture
|
||
|
||
### Vue d'ensemble
|
||
|
||
Boidelo suit un pattern **Repository + Séparation des responsabilités**. Chaque jeu est isolé dans son propre package avec sa propre logique métier.
|
||
|
||
```
|
||
app/src/main/java/com/example/boidelov3/
|
||
├── hub/ # Hub central
|
||
│ ├── GameSelectionActivity.java # Activité LAUNCHER (point d'entrée)
|
||
│ ├── adapter/
|
||
│ │ └── GameAdapter.java # RecyclerView adapter
|
||
│ └── model/
|
||
│ └── GameInfo.java # Modèle (nom, description, icône, type)
|
||
│
|
||
├── games/ # Jeux isolés par package
|
||
│ ├── boideloclassic/ # Boidelo Classic
|
||
│ │ ├── BoideloClassicSetupActivity.java
|
||
│ │ ├── BoideloClassicParamsActivity.java
|
||
│ │ ├── BoideloClassicGameActivity.java
|
||
│ │ └── manager/
|
||
│ │ ├── BoideloPlayerManager.java
|
||
│ │ └── BoideloPlayerRowManager.java
|
||
│ ├── game89/ # 89++
|
||
│ │ ├── Game89SetupActivity.java
|
||
│ │ ├── Game89GameActivity.java
|
||
│ │ ├── Game89Player.java # Modèle joueur
|
||
│ │ └── Game89ChallengeManager.java # Gestionnaire de défis
|
||
│ └── papelito/ # Papelito (Undercover)
|
||
│ ├── PapelitoSetupActivity.java
|
||
│ ├── PapelitoGameActivity.java
|
||
│ ├── PapelitoResultActivity.java
|
||
│ ├── PapelitoResultAdapter.java
|
||
│ ├── PapelitoGame.java # Logique complète du jeu
|
||
│ └── PapelitoPlayer.java # Modèle joueur (Serializable)
|
||
│
|
||
├── data/ # Couche d'accès aux données
|
||
│ ├── QuestionRepository.java # Chargement JSON + SharedPreferences
|
||
│ ├── Result.java # Wrapper type-safe succès/erreur
|
||
│ ├── PlayerStats.java # Stats joueur (Parcelable)
|
||
│ └── QuestionCategory.java # Catégorisation + couleurs
|
||
│
|
||
├── game/ # Logique métier commune
|
||
│ └── GameEngine.java # Moteur de jeu (pur Java)
|
||
│
|
||
├── utils/ # Utilitaires
|
||
│ ├── ErrorHandler.java
|
||
│ ├── SecureConfig.java
|
||
│ ├── SoundManager.java
|
||
│ └── SoundGenerator.java
|
||
│
|
||
├── MainActivity.java # Legacy (à supprimer)
|
||
├── Jeux.java # Legacy (à supprimer)
|
||
├── JeuxParametres.java # Legacy (à supprimer)
|
||
├── EndGameActivity.java # Legacy (à supprimer)
|
||
├── OpenAIService.java # Service OpenAI
|
||
├── ChatGPTTask.java # Task async OpenAI
|
||
├── DatabaseConnection.java # Connexion PostgreSQL
|
||
├── Question.java # Modèle de question
|
||
├── Questions.java # Conteneur de questions (Gson)
|
||
├── PreferencesKeys.java # Constantes SharedPreferences
|
||
└── BoideloAnimationUtils.java # Animations UI
|
||
```
|
||
|
||
### Flux d'une partie
|
||
|
||
Chaque jeu suit le même schéma d'activité :
|
||
|
||
```
|
||
Hub (GameSelectionActivity)
|
||
└─► Setup (saisie des joueurs)
|
||
└─► Parameters (configuration, optionnel)
|
||
└─► Game (partie en cours)
|
||
└─► End Game (statistiques & résultats)
|
||
```
|
||
|
||
### Pattern Result<T, E>
|
||
|
||
Le projet utilise un wrapper type-safe pour la gestion des erreurs, évitant les exceptions non contrôlées :
|
||
|
||
```java
|
||
Result<Questions, QuestionLoadException> result = repository.loadQuestions();
|
||
if (result.isSuccess()) {
|
||
Questions questions = result.getData();
|
||
} else {
|
||
Exception error = result.getError();
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🛠 Stack technique
|
||
|
||
| Élément | Version / Détail |
|
||
|---|---|
|
||
| **Langage** | Java 8 |
|
||
| **Min SDK** | 24 (Android 7.0) |
|
||
| **Target / Compile SDK** | 35 (Android 15) |
|
||
| **Build system** | Gradle 8.12.0 + AGP 8.12.0 |
|
||
| **UI** | Material Design 3, AppCompat 1.7.0 |
|
||
| **Layout** | ConstraintLayout 2.2.0 |
|
||
| **Réseau** | OkHttp 4.12.0 |
|
||
| **JSON** | Gson 2.11.0 |
|
||
| **Base de données** | pgjdbc-ng 0.8.3 (PostgreSQL, actuellement inutilisé) |
|
||
| **Tests unitaires** | JUnit 4.13.2, Mockito 5.7.0, Robolectric 4.11.1 |
|
||
| **Tests UI** | AndroidX Test JUnit 1.2.1, Espresso 3.6.1 |
|
||
|
||
---
|
||
|
||
## 🧪 Tests
|
||
|
||
Le projet dispose de **11 classes de test** couvrant l'ensemble des jeux et des composants de données :
|
||
|
||
| Classe de test | Fichier |
|
||
|---|---|
|
||
| `GameEngineTest` | `game/GameEngineTest.java` (15 tests) |
|
||
| `ResultTest` | `data/ResultTest.java` (8 tests) |
|
||
| `PlayerStatsTest` | `data/PlayerStatsTest.java` |
|
||
| `QuestionCategoryTest` | `data/QuestionCategoryTest.java` |
|
||
| `QuestionTest` | `QuestionTest.java` |
|
||
| `QuestionsClassTest` | `QuestionsClassTest.java` |
|
||
| `BoideloPlayerManagerTest` | `games/boideloclassic/manager/BoideloPlayerManagerTest.java` |
|
||
| `Game89PlayerTest` | `games/game89/Game89PlayerTest.java` |
|
||
| `Game89ChallengeManagerTest` | `games/game89/Game89ChallengeManagerTest.java` |
|
||
| `PapelitoPlayerTest` | `games/papelito/PapelitoPlayerTest.java` |
|
||
| `PapelitoGameTest` | `games/papelito/PapelitoGameTest.java` |
|
||
|
||
---
|
||
|
||
## 🔨 Compilation et installation
|
||
|
||
### Prérequis
|
||
|
||
- **Android Studio** (recommandé) ou **JDK 17-21** + SDK Android
|
||
- Android SDK avec compileSdk 35
|
||
|
||
### Build depuis la ligne de commande
|
||
|
||
```bash
|
||
# Cloner le projet
|
||
git clone <url-du-repo>
|
||
cd boidelo
|
||
|
||
# Build
|
||
./gradlew build
|
||
|
||
# APK debug
|
||
./gradlew assembleDebug
|
||
|
||
# Installer sur un appareil connecté
|
||
adb install -r app/build/outputs/apk/debug/app-debug.apk
|
||
```
|
||
|
||
### Exécuter les tests
|
||
|
||
```bash
|
||
# Tous les tests unitaires
|
||
./gradlew test
|
||
|
||
# Tests instrumentés (appareil/émulateur requis)
|
||
./gradlew connectedAndroidTest
|
||
|
||
# Test spécifique
|
||
./gradlew test --tests com.example.boidelov3.game.GameEngineTest
|
||
```
|
||
|
||
> ⚠️ **Note :** Un bug connu avec Gradle 8.13 peut causer l'échec des tests unitaires en CLI. Utilisez Android Studio ou un JDK 17-21 pour contourner le problème.
|
||
|
||
### Clean
|
||
|
||
```bash
|
||
./gradlew clean
|
||
```
|
||
|
||
---
|
||
|
||
## 🎨 Interface
|
||
|
||
- **Material Design 3** avec composants modernes (MaterialCardView, TextInputLayout, etc.)
|
||
- **Mode sombre** avec thèmes dédiés (`values-night/`)
|
||
- **Animations fluides** : fade in/out, slide, color transition, button press/release
|
||
- **Feedback haptique** et effets sonores via `SoundManager` / `SoundGenerator`
|
||
- **Palette principale** : Violet (`#9395D3`) / Lavande (`#B3B7EE`) sur fond blanc cassé (`#FBF9FF`)
|
||
- Couleurs dynamiques par catégorie de question (10 couleurs distinctes)
|
||
- Toutes les activités en mode **portrait**
|
||
|
||
---
|
||
|
||
## 📁 Structure des ressources
|
||
|
||
```
|
||
app/src/main/res/
|
||
├── anim/ # 10 animations (slide, fade, button, color)
|
||
├── drawable/ # Icônes de jeux, boutons, fonds
|
||
├── layout/ # 19 layouts XML
|
||
│ ├── activity_game_selection.xml # Hub principal
|
||
│ ├── activity_boidelo_classic_setup.xml
|
||
│ ├── activity_boidelo_classic_params.xml
|
||
│ ├── activity_boidelo_classic_game.xml
|
||
│ ├── activity_game89_setup.xml
|
||
│ ├── activity_game89_game.xml
|
||
│ ├── activity_papelito_setup.xml
|
||
│ ├── activity_papelito_game.xml
|
||
│ ├── activity_papelito_result.xml
|
||
│ ├── dialog_papelito_vote.xml
|
||
│ └── dialog_papelito_word_reveal.xml
|
||
├── values/ # Strings, couleurs, thèmes, styles
|
||
├── values-night/ # Variantes mode sombre
|
||
├── mipmap-*/ # Icônes launcher (mdpi → xxxhdpi)
|
||
└── xml/ # Backup rules, data extraction rules
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 Données
|
||
|
||
Les questions de Boidelo Classic sont stockées dans `app/src/main/assets/question.json`. Chaque question contient :
|
||
|
||
- `id` — identifiant unique
|
||
- `question` — texte avec placeholders (`<J1>`, `<variante>`, `<manches>`)
|
||
- `gorger` — nombre de gorgées
|
||
- `distribution` / `recois` — flags pour boire ou distribuer
|
||
- `variante` — liste de variantes alternatives
|
||
- `manches` — nombre de manches pour les défis
|
||
- `arret` — message de fin de défi
|
||
|
||
---
|
||
|
||
## 🔐 Configuration
|
||
|
||
### Clé API OpenAI (optionnel)
|
||
|
||
Les clés sensibles sont stockées dans `local.properties` (non versionné) :
|
||
|
||
```properties
|
||
OPENAI_API_KEY=sk-votre-cle-ici
|
||
```
|
||
|
||
La classe `SecureConfig` fournit un accès sécurisé à ces valeurs.
|
||
|
||
### Base de données PostgreSQL
|
||
|
||
La connexion PostgreSQL est préparée mais le backend n'est pas encore en production. Les identifiants BuildConfig sont intentionnellement vides — l'usage d'une API backend est recommandé.
|
||
|
||
---
|
||
|
||
## 🚀 Ajouter un nouveau jeu
|
||
|
||
1. Créer un package sous `com.example.boidelov3.games.<nom_du_jeu>`
|
||
2. Implémenter les activités **Setup**, **Game** et **Result** (suivre le flux standard)
|
||
3. Ajouter une valeur à l'enum `GameInfo.GameType`
|
||
4. Enregistrer le jeu dans `GameSelectionActivity.setupGamesList()`
|
||
5. Ajouter le cas dans le `switch` de `GameSelectionActivity.onItemClick()`
|
||
6. Déclarer les activités dans `AndroidManifest.xml` avec `screenOrientation="portrait"`
|
||
7. Ajouter l'icône drawable `ic_<nom_du_jeu>.xml`
|
||
8. Écrire les tests unitaires correspondants
|
||
|
||
---
|
||
|
||
## 📝 Conventions
|
||
|
||
- **Langue métier** : français (`gorgees`, `manches`, `caliente`)
|
||
- **Code technique** : anglais (`allPlayers`, `activeManches`)
|
||
- **Interface utilisateur** : français
|
||
- **Clés SharedPreferences** : centralisées dans `PreferencesKeys.java`
|
||
- **Nommage layouts** : `activity_<jeu>_<écran>.xml`, `dialog_<jeu>_<usage>.xml`
|
||
- **Nommage strings** : préfixe par jeu (`papelito_`, `boidelo_`, `game89_`)
|
||
|
||
---
|
||
|
||
## 📋 Statut des fonctionnalités
|
||
|
||
| Fonctionnalité | Statut |
|
||
|---|---|
|
||
| Hub de sélection de jeux | ✅ Opérationnel |
|
||
| Boidelo Classic (150+ questions) | ✅ Opérationnel |
|
||
| 89++ (cartes + défis) | ✅ Opérationnel |
|
||
| Papelito / Undercover | ✅ Opérationnel |
|
||
| Règles de jeux | 🚧 En cours |
|
||
| Intégration OpenAI (questions IA) | 🚧 En développement |
|
||
| Connexion PostgreSQL | 🔧 Prête (backend requis) |
|
||
| Mode sombre | ✅ Opérationnel |
|
||
| Tests unitaires (11 classes) | ✅ Opérationnel |
|
||
|
||
---
|
||
|
||
## 📚 Documentation supplémentaire
|
||
|
||
- [`ANALYSE_CODE.md`](ANALYSE_CODE.md) — Analyse détaillée du code (ancienne architecture)
|
||
- [`README_ARCHITECTURE.md`](README_ARCHITECTURE.md) — Documentation de l'architecture Repository
|
||
- [`CLAUDE.md`](CLAUDE.md) — Guide de développement pour l'IA
|
||
|
||
---
|
||
|
||
## 📄 Licence
|
||
|
||
Projet privé — tous droits réservés.
|
||
|
||
---
|
||
|
||
*Boidelo — buvez responsable* 🍻
|