diff --git a/docs/MODULES_ARCHITECTURE.md b/docs/MODULES_ARCHITECTURE.md new file mode 100644 index 0000000..fdd10ae --- /dev/null +++ b/docs/MODULES_ARCHITECTURE.md @@ -0,0 +1,301 @@ +# Architecture Modulaire - Mobile Command & WarFactory + +## Vue d'Ensemble + +Les deux projets partagent le **GroveEngine** comme fondation, ce qui permet de créer une bibliothèque de modules réutilisables entre les deux jeux. + +## Modules Partagés (Core Library) + +### 1. **ResourceModule** 🔄 +**Réutilisabilité: 90%** +- Gestion des ressources (inventaire, stockage) +- Craft/production de base +- Qualité des ressources (grades) +- Balance/contraintes + +**Mobile Command**: Ressources scavengées, munitions, fuel, pièces détachées +**WarFactory**: Minerais, composants, produits finis + +### 2. **EconomyModule** 🔄 +**Réutilisabilité: 85%** +- Système de prix dynamiques +- Offre/demande +- Marchés/échanges +- Budgets/finance + +**Mobile Command**: Marché noir, dons, ventes de scavenge +**WarFactory**: Marché global, contrats PMC, ventes d'armes + +### 3. **TransportModule** 🔄 +**Réutilisabilité: 70%** +- Pathfinding +- Logistique/convois +- Optimisation de routes +- Gestion de flotte + +**Mobile Command**: Train + expéditions (drones/humains) +**WarFactory**: Trains, camions, supply chains + +### 4. **CombatModule** 🔄 +**Réutilisabilité: 60%** +- Calculs de dégâts +- Système de santé/armor +- Probabilités de hit +- État des unités + +**Mobile Command**: Combat tactical, pertes permanentes +**WarFactory**: Auto-battler, frontlines persistantes + +### 5. **TechTreeModule** 🔄 +**Réutilisabilité: 75%** +- Progression technologique +- Recherche/unlock +- Dépendances entre techs +- Cost/time calculations + +**Mobile Command**: Timeline 2022→2025 (drones evolution) +**WarFactory**: 3000+ techs, branches industrielles/militaires + +### 6. **EventModule** 🔄 +**Réutilisabilité: 80%** +- Système d'événements +- Conditions/triggers +- Choix multiples +- Conséquences + +**Mobile Command**: 70% events, survie, moral +**WarFactory**: Events diplomatiques, crises + +### 7. **MapModule** 🔄 +**Réutilisabilité: 50%** +- Chunk system (64x64 tiles) +- Streaming/persistence +- Multi-échelle (world/regional/local) +- Procedural generation base + +**Mobile Command**: Ukraine map, sites d'expédition +**WarFactory**: World map, 218 features, geological sim + +### 8. **StorageModule** 🔄 +**Réutilisabilité: 95%** +- Sauvegarde/chargement +- Serialization +- State management +- Persistence + +**Les deux**: Save games, configs, analytics + +## Modules Spécifiques - Mobile Command + +### 9. **TrainBuilderModule** 📦 +- Double-slice view (L/R) +- Balance 2-axes (latéral + longitudinal) +- Wagon management +- Performance malus (déséquilibre) + +### 10. **ExpeditionModule** 📦 +- Gestion d'expéditions +- Team composition (humains + drones) +- Risk/reward calculs +- Moral/fatigue + +### 11. **DroneModule** 📦 +- Evolution timeline (2022-2025) +- Swarm coordination +- FPV controls +- Ground drones + +### 12. **CommanderModule** 📦 +- Commandants nommés (5-7) +- Skills/personnalités +- Mort permanente +- Progression XP + +### 13. **FameModule** 📦 +- Communication/PR +- Influenceurs +- Déblocage de dons +- Risk/reward missions + +### 14. **ScavengeModule** 📦 +- Sites scavengeable +- Danger levels +- Loot tables +- Timeline evolution (facile→suicide) + +## Modules Spécifiques - WarFactory + +### 15. **FactoryModule** 🏭 +- Belt/inserter/assembler +- 60Hz production +- Recipe chains +- Throughput optimization + +### 16. **VehicleDesignModule** 🏭 +- Grid-based chassis +- Component placement +- Pick/place interface +- Templates + +### 17. **DoctrineModule** 🏭 +- Military doctrine creation +- Unit composition +- Tactics/strategies +- Player-driven meta + +### 18. **DiplomacyModule** 🏭 +- Factions/relations +- Contrats/alliances +- Reputation système +- PMC operations + +### 19. **GeologyModule** 🏭 +- 7-phase geological sim +- Tectonics/climate +- Biomes (18 types) +- Resource distribution (70+ features) + +## Architecture de Partage + +### Option 1: Modules GroveEngine Partagés +``` +/grove-modules/ # Shared module library +├── ResourceModule/ +├── EconomyModule/ +├── TransportModule/ +└── ... + +/mobilecommand/ +└── external/ + ├── GroveEngine/ + └── grove-modules/ # Symlink + +/warfactoryracine/ +└── external/ + ├── GroveEngine/ + └── grove-modules/ # Symlink +``` + +**Avantages**: +- Code partagé centralisé +- Updates profitent aux deux projets +- Moins de duplication + +**Inconvénients**: +- Couplage entre projets +- Breaking changes affectent les deux + +### Option 2: Copy-Paste avec Divergence +``` +/mobilecommand/src/modules/ +├── ResourceModule.cpp # Version MC +└── ... + +/warfactoryracine/modules/ +├── resource/ # Version WF +└── ... +``` + +**Avantages**: +- Indépendance totale +- Optimisation per-projet + +**Inconvénients**: +- Duplication de code +- Bugs fixes dupliqués + +### Option 3: Hybride (RECOMMANDÉ) +``` +/grove-modules/core/ # Core stable, partagé +├── ResourceModule/ +├── StorageModule/ +└── ... + +/mobilecommand/src/modules/ +├── TrainBuilderModule/ # Spécifique MC +└── mc_adapters/ # Adaptateurs des core modules + +/warfactoryracine/modules/ +├── factory/ # Spécifique WF +└── wf_adapters/ # Adaptateurs des core modules +``` + +**Avantages**: +- Core stable partagé +- Adaptateurs spécifiques +- Flexibilité maximale + +## Priorités de Développement + +### Phase 1 - Mobile Command Prototype +1. **GameModule** (de base) +2. **ResourceModule** (scavenge, craft simple) +3. **TrainBuilderModule** (3 wagons) +4. **EventModule** (3-5 events) +5. **CombatModule** (1 mission Rimworld-style) + +### Phase 2 - WarFactory Foundations +1. **FactoryModule** (production de base) +2. **ResourceModule** (réutilisé de MC) +3. **MapModule** (geological sim) +4. **TechTreeModule** (subset initial) + +### Phase 3 - Modules Partagés Stabilisés +1. **EconomyModule** (marché dynamique) +2. **TransportModule** (logistics) +3. **StorageModule** (persistence) +4. **EventModule** (framework général) + +## Recommandations + +### Court Terme (Prototype MC) +- Focus sur modules spécifiques MC +- Garder ResourceModule/CombatModule simples et réutilisables +- Documenter les patterns réutilisables + +### Moyen Terme (MVP MC + WF Setup) +- Identifier le core stable +- Créer grove-modules/ library +- Refactor vers adaptateurs + +### Long Terme +- Maintenir core library +- Versioning sémantique des modules +- Tests de compatibilité cross-projet + +## Notes Techniques + +### Communication Inter-Modules +```cpp +// ResourceModule publie +io->publish("resource:craft_complete", craftData); + +// TrainBuilderModule subscribe +io->subscribe("resource:craft_complete", callback); +``` + +### Configuration Partagée +```json +{ + "modules": { + "ResourceModule": { + "maxStackSize": 100, + "qualityGrades": ["poor", "normal", "good", "excellent"] + } + } +} +``` + +### State Preservation +```cpp +// Hot-reload compatible +std::unique_ptr getState() override { + auto state = std::make_unique("state"); + state->setInt("resourceCount", m_resources.size()); + return state; +} +``` + +--- + +**Objectif**: Construire une bibliothèque de modules GroveEngine réutilisables tout en gardant l'indépendance des projets. diff --git a/plans/PROTOTYPE_PLAN.md b/plans/PROTOTYPE_PLAN.md new file mode 100644 index 0000000..51653eb --- /dev/null +++ b/plans/PROTOTYPE_PLAN.md @@ -0,0 +1,834 @@ +# Mobile Command - Plan de Prototype + +**Objectif**: Créer un prototype jouable validant les mécaniques de base du jeu en 3-6 mois. + +**Date**: 1er décembre 2025 +**Version**: 0.1.0 → 0.5.0 (Prototype complet) + +--- + +## Vue d'Ensemble + +### Définition du Succès (Prototype) +✅ **Loop de jeu complet fonctionnel**: +1. Joueur peut builder/modifier le train (3 wagons) +2. Joueur peut crafter ressources basiques (1→1) +3. Joueur peut lancer 1 expédition de combat +4. Joueur rencontre 3-5 événements +5. Joueur peut sauvegarder/charger + +### Non-Objectifs du Prototype +❌ Graphismes polish (placeholders OK) +❌ Balance parfaite (tests rapides prioritaires) +❌ Content exhaustif (subset minimal) +❌ Performance optimale (validité > optimisation) +❌ UI/UX final (functional > beautiful) + +--- + +## Architecture Technique + +### Stack +- **Engine**: GroveEngine (hot-reload C++17) +- **Build**: CMake 3.20+ avec MinGW/GCC +- **Logging**: spdlog +- **Data**: JSON (nlohmann/json) +- **Persistence**: Fichiers JSON (pas de DB) + +### Modules du Prototype + +#### Phase 1 - Fondations (Semaines 1-2) +``` +✅ GameModule # Loop principal 10Hz +⬜ ResourceModule # Inventaire, craft simple +⬜ StorageModule # Save/load states +``` + +#### Phase 2 - Train & Resources (Semaines 3-4) +``` +⬜ TrainBuilderModule # 3 wagons, balance basique +⬜ ResourceModule v2 # Craft 1→1 fonctionnel +``` + +#### Phase 3 - Combat & Events (Semaines 5-8) +``` +⬜ CombatModule # 1 mission Rimworld-style +⬜ EventModule # 3-5 events scriptés +⬜ ExpeditionModule # Lancer expéditions basiques +``` + +#### Phase 4 - Integration & Polish (Semaines 9-12) +``` +⬜ GameModule v2 # Intégration tous modules +⬜ UI basique # Menus, HUD minimal +⬜ Balance pass # Tweaking gameplay +``` + +--- + +## Plan Détaillé par Phase + +## PHASE 1 - Fondations (Semaines 1-2) + +### Objectif +Établir l'architecture de base et valider le hot-reload. + +### Modules + +#### 1.1 GameModule ✅ +**Status**: COMPLÉTÉ (setup initial) + +**Prochaines étapes**: +- [ ] Ajouter state machine (MainMenu, InGame, Expedition, etc.) +- [ ] Game loop avec delta time +- [ ] Event dispatcher basique + +**Fichiers**: +- `src/modules/GameModule.cpp` ✅ +- `config/game.json` ✅ + +#### 1.2 ResourceModule +**Responsabilités**: +- Inventaire des ressources +- Stack management +- Craft simple (1 ressource → 1 produit) +- Quality grades (poor, normal, good, excellent) + +**Topics pub/sub**: +```cpp +// Publish +"resource:craft_started" // {recipe_id, quantity} +"resource:craft_complete" // {result_id, quantity, quality} +"resource:inventory_changed" // {resource_id, delta, total} + +// Subscribe +"train:storage_capacity" // Limite inventaire +"expedition:loot_acquired" // Ajouter loot +``` + +**Data structures**: +```json +{ + "resources": { + "scrap_metal": { + "maxStack": 100, + "weight": 1.5, + "baseValue": 10 + }, + "ammunition_9mm": { + "maxStack": 500, + "weight": 0.01, + "baseValue": 2 + } + }, + "recipes": { + "repair_kit_basic": { + "input": {"scrap_metal": 5}, + "output": {"repair_kit": 1}, + "craftTime": 10.0 + } + } +} +``` + +**Hot-reload state**: +```cpp +std::unique_ptr getState() override { + auto state = std::make_unique("state"); + // Serialize inventory + auto inventory = std::make_unique("inventory"); + for (auto& [id, count] : m_inventory) { + inventory->setInt(id, count); + } + state->setChild("inventory", std::move(inventory)); + return state; +} +``` + +**Fichiers**: +- [ ] `src/modules/ResourceModule.cpp` +- [ ] `src/modules/ResourceModule.h` +- [ ] `config/resources.json` + +**Tests de validation**: +- [ ] Craft 1→1 fonctionne +- [ ] Inventaire persiste après hot-reload +- [ ] Stack limits respectés + +#### 1.3 StorageModule +**Responsabilités**: +- Save game complet +- Load game complet +- Auto-save toutes les 5 minutes +- Versioning des saves + +**Topics pub/sub**: +```cpp +// Publish +"storage:save_complete" // {filename, timestamp} +"storage:load_complete" // {filename, version} +"storage:save_failed" // {error_message} + +// Subscribe +"game:request_save" // Trigger save +"game:request_load" // Trigger load +"*:state_changed" // Collect states pour save +``` + +**Save format**: +```json +{ + "version": "0.1.0", + "timestamp": "2025-12-01T10:30:00Z", + "gameTime": 3600.5, + "modules": { + "GameModule": {...}, + "ResourceModule": {...}, + "TrainBuilderModule": {...} + } +} +``` + +**Fichiers**: +- [ ] `src/modules/StorageModule.cpp` +- [ ] `config/storage.json` +- [ ] `data/saves/` (directory) + +**Tests de validation**: +- [ ] Save/load cycle complet +- [ ] Hot-reload preserves unsaved data +- [ ] Auto-save fonctionne + +### Livrables Phase 1 +- [x] Setup projet complet +- [ ] ResourceModule fonctionnel +- [ ] StorageModule fonctionnel +- [ ] Loop de jeu basique (GameModule v2) +- [ ] Documentation modules + +**Durée estimée**: 2 semaines + +--- + +## PHASE 2 - Train & Resources (Semaines 3-4) + +### Objectif +Système de train fonctionnel avec balance et craft. + +### Modules + +#### 2.1 TrainBuilderModule +**Responsabilités**: +- Gestion de 3 wagons (Locomotive, Cargo, Workshop) +- Balance 2-axes (Latéral L/R, Longitudinal Avant/Arrière) +- Malus performance si déséquilibre +- Upgrade wagons (capacité, armor) + +**Topics pub/sub**: +```cpp +// Publish +"train:composition_changed" // {wagons[], balance_score} +"train:performance_updated" // {speed_malus, fuel_malus} +"train:capacity_changed" // {total_cargo, total_crew} + +// Subscribe +"resource:inventory_changed" // Update cargo weight +"combat:damage_received" // Wagon health +``` + +**Data structures**: +```json +{ + "wagons": { + "locomotive": { + "type": "locomotive", + "health": 100, + "armor": 50, + "weight": 20000, + "position": "front" + }, + "cargo_1": { + "type": "cargo", + "capacity": 10000, + "health": 80, + "weight": 5000, + "position": "middle_left" + } + }, + "balance": { + "lateral_offset": -2.5, // Negative = left heavy + "longitudinal_offset": 1.0, // Positive = front heavy + "speed_malus": 0.85, // 15% penalty + "fuel_malus": 1.25 // 25% more consumption + } +} +``` + +**Balance Algorithm**: +```cpp +// Simplified for prototype +float lateral = (left_weight - right_weight) / total_weight; +float longitudinal = (front_weight - rear_weight) / total_weight; + +float speed_malus = 1.0 - (abs(lateral) + abs(longitudinal)) * 0.5; +float fuel_malus = 1.0 + (abs(lateral) + abs(longitudinal)) * 0.5; +``` + +**UI Requirements (minimal)**: +- [ ] Liste des wagons (texte) +- [ ] Indicateurs balance (barres L/R, Av/Ar) +- [ ] Stats train (speed, fuel, capacity) + +**Fichiers**: +- [ ] `src/modules/TrainBuilderModule.cpp` +- [ ] `config/train.json` + +**Tests de validation**: +- [ ] 3 wagons configurables +- [ ] Balance calcule correctement +- [ ] Malus appliqués +- [ ] State persiste après reload + +#### 2.2 ResourceModule v2 +**Améliorations**: +- [ ] 10+ ressources basiques +- [ ] 5+ recipes craft +- [ ] Quality impact (poor = 50% efficacité, excellent = 150%) +- [ ] Craft queue (1 à la fois pour prototype) + +**Nouvelles ressources**: +```json +{ + "scrap_metal": "Base material", + "ammunition_9mm": "Small arms ammo", + "fuel_diesel": "Train fuel", + "medical_supplies": "First aid", + "repair_kit": "Wagon repair", + "drone_parts": "Basic drone components", + "food_rations": "Crew sustenance", + "water_clean": "Potable water", + "electronics": "Salvaged electronics", + "explosives": "Combat materials" +} +``` + +**Recipes avancées**: +```json +{ + "repair_kit": { + "inputs": {"scrap_metal": 5, "electronics": 1}, + "output": {"repair_kit": 1}, + "time": 30 + }, + "drone_basic": { + "inputs": {"drone_parts": 3, "electronics": 2}, + "output": {"drone_recon": 1}, + "time": 120 + } +} +``` + +**Fichiers**: +- [ ] Update `src/modules/ResourceModule.cpp` +- [ ] Update `config/resources.json` + +### Livrables Phase 2 +- [ ] Train avec 3 wagons fonctionnel +- [ ] Balance système implémenté +- [ ] 10+ ressources craftables +- [ ] UI basique train + inventory + +**Durée estimée**: 2 semaines + +--- + +## PHASE 3 - Combat & Events (Semaines 5-8) + +### Objectif +Première mission de combat et système d'événements. + +### Modules + +#### 3.1 CombatModule +**Responsabilités**: +- Combat Rimworld-style (auto-résolution avec oversight) +- Calculs dégâts/armor +- Pertes permanentes (humains) +- Loot post-combat + +**Topics pub/sub**: +```cpp +// Publish +"combat:started" // {location, enemy_type} +"combat:round_complete" // {casualties, damage_dealt} +"combat:ended" // {victory, casualties[], loot[]} + +// Subscribe +"expedition:combat_triggered" // Start combat +"commander:skill_activated" // Modify combat stats +``` + +**Combat Flow**: +``` +1. Setup combatants (player team vs enemy) +2. Calculate initiative +3. For each round (max 20): + - Each unit attempts attack + - Calculate hit probability + - Apply damage/armor + - Check casualties + - Check morale/retreat +4. Resolve (victory/defeat/retreat) +5. Distribute loot +``` + +**Combat Stats**: +```json +{ + "player_team": { + "humans": 5, + "drones_recon": 2, + "drones_fpv": 0, + "total_firepower": 45, + "total_armor": 20 + }, + "enemy": { + "type": "scavengers", + "count": 8, + "firepower": 30, + "armor": 10, + "morale": 60 + } +} +``` + +**Damage Formula (simplifié)**: +```cpp +float hit_chance = base_accuracy * (1.0 - enemy_cover); +bool hit = random(0, 1) < hit_chance; +if (hit) { + float damage = firepower - target_armor * 0.5; + if (damage > 0) { + target_health -= damage; + } +} +``` + +**Fichiers**: +- [ ] `src/modules/CombatModule.cpp` +- [ ] `config/combat.json` + +**Tests de validation**: +- [ ] Combat se résout correctement +- [ ] Casualties appliqués +- [ ] Loot distribué +- [ ] Morale fonctionne + +#### 3.2 EventModule +**Responsabilités**: +- Trigger événements basés sur conditions +- Choix multiples du joueur +- Conséquences (ressources, moral, réputation) +- Scripting simple (JSON) + +**Topics pub/sub**: +```cpp +// Publish +"event:triggered" // {event_id, conditions_met} +"event:choice_made" // {event_id, choice_id} +"event:outcome" // {resources_delta, moral_delta} + +// Subscribe +"game:game_time_changed" // Time-based events +"expedition:location_reached" // Location events +"resource:inventory_low" // Resource events +``` + +**Event Format**: +```json +{ + "event_id": "scavenger_encounter", + "title": "Scavengers Spotted", + "description": "Your scouts report a small group of scavengers nearby. They seem unaware of your presence.", + "conditions": { + "game_time_min": 600, + "location_type": "urban_ruins" + }, + "choices": [ + { + "id": "attack", + "text": "Attack immediately", + "outcomes": { + "trigger_combat": "scavenger_group_small", + "moral": -5, + "fame": +2 + } + }, + { + "id": "negotiate", + "text": "Attempt to trade", + "requirements": {"reputation": 20}, + "outcomes": { + "resources": {"ammunition": -50, "food": +30}, + "moral": +5 + } + }, + { + "id": "avoid", + "text": "Move on quietly", + "outcomes": { + "time_cost": 60, + "moral": +2 + } + } + ] +} +``` + +**Event System**: +```cpp +class EventModule { + void checkTriggers() { + for (auto& event : m_events) { + if (event.conditions_met() && !event.triggered) { + triggerEvent(event); + } + } + } + + void handleChoice(string event_id, string choice_id) { + auto& event = getEvent(event_id); + auto& choice = event.getChoice(choice_id); + applyOutcomes(choice.outcomes); + } +}; +``` + +**Events Prototype (5)**: +1. **Scavenger Encounter** - Combat/trade/avoid +2. **Supply Cache Found** - Risk/reward loot +3. **Wounded Civilian** - Moral/resources trade-off +4. **Drone Malfunction** - Repair cost decision +5. **Ambush Warning** - Preparation vs speed + +**Fichiers**: +- [ ] `src/modules/EventModule.cpp` +- [ ] `config/events.json` + +**Tests de validation**: +- [ ] 5 events déclenchent correctement +- [ ] Choix appliquent outcomes +- [ ] Conditions fonctionnent +- [ ] State persiste + +#### 3.3 ExpeditionModule +**Responsabilités**: +- Lancer expéditions +- Composer team (humains + drones) +- Progression sur map (simple: A→B) +- Return avec loot/casualties + +**Topics pub/sub**: +```cpp +// Publish +"expedition:started" // {team, destination} +"expedition:progress" // {location, time_remaining} +"expedition:event_triggered" // Forward to EventModule +"expedition:returned" // {loot, casualties, time_elapsed} + +// Subscribe +"event:combat_triggered" // Handle combat +"resource:craft_complete" // Add to expedition supplies +``` + +**Expedition Data**: +```json +{ + "team": { + "humans": [ + {"id": "cmd_01", "name": "Vasyl", "role": "leader", "health": 100}, + {"id": "sol_01", "name": "Ivan", "role": "soldier", "health": 100} + ], + "drones": [ + {"type": "recon", "count": 2} + ] + }, + "destination": { + "type": "urban_ruins", + "distance": 15000, + "danger_level": 2, + "estimated_loot": "medium" + }, + "supplies": { + "fuel": 50, + "ammunition": 200, + "food": 10 + } +} +``` + +**Expedition Flow**: +``` +1. Player selects destination +2. Player assigns team + drones +3. Player allocates supplies +4. Expedition departs (real-time or accelerated) +5. Random events trigger during travel +6. Reach destination → scavenge/combat +7. Return to train +8. Distribute loot, apply casualties +``` + +**Fichiers**: +- [ ] `src/modules/ExpeditionModule.cpp` +- [ ] `config/expeditions.json` + +**Tests de validation**: +- [ ] Expédition complète A→B +- [ ] Events en route +- [ ] Combat déclenché +- [ ] Loot rapporté + +### Livrables Phase 3 +- [ ] 1 mission de combat fonctionnelle +- [ ] 5 événements scriptés +- [ ] Système d'expéditions basique +- [ ] Loop complet jouable + +**Durée estimée**: 4 semaines + +--- + +## PHASE 4 - Integration & Polish (Semaines 9-12) + +### Objectif +Intégrer tous les systèmes et créer une expérience cohérente. + +### Tasks + +#### 4.1 GameModule v2 - State Machine +```cpp +enum class GameState { + MainMenu, + TrainBuilder, + Expedition, + Combat, + Event, + Pause +}; + +class GameModule { + void updateState() { + switch (m_state) { + case MainMenu: updateMainMenu(); break; + case TrainBuilder: updateTrainBuilder(); break; + case Expedition: updateExpedition(); break; + case Combat: updateCombat(); break; + case Event: updateEvent(); break; + } + } +}; +``` + +**Features**: +- [ ] State transitions propres +- [ ] Pause/resume +- [ ] Main menu basique +- [ ] Game over conditions + +#### 4.2 UI Basique +**Minimum viable UI**: +- [ ] Main menu (New Game, Load, Quit) +- [ ] Train view (wagons, stats, balance) +- [ ] Inventory view (ressources, craft) +- [ ] Expedition view (map, team, go) +- [ ] Combat log (rounds, casualties) +- [ ] Event popup (texte, choix) + +**Techno UI**: +- Option 1: ImGui (rapide, debug-friendly) +- Option 2: Console text-based (ultra-rapide) +- **Recommandation**: Console pour prototype, ImGui pour MVP + +**Console UI Example**: +``` +=== MOBILE COMMAND v0.5.0 === +[1] Train Builder +[2] Inventory & Craft +[3] Launch Expedition +[4] Save Game +[5] Quit +> _ +``` + +#### 4.3 Balance Pass +**Metrics à balancer**: +- [ ] Combat difficulty (win rate ~60-70%) +- [ ] Resource scarcity (pénurie sans blocage) +- [ ] Craft times (engageant sans grind) +- [ ] Train balance sensitivity (impactful mais pas punitif) +- [ ] Event frequency (1 event per 10 min gameplay) + +**Playtest objectives**: +- [ ] 30 min gameplay complet +- [ ] Loop ressources→craft→expedition→combat→retour +- [ ] Aucun softlock possible +- [ ] Difficulty curve correcte + +#### 4.4 Documentation +- [ ] README.md à jour +- [ ] CLAUDE.md à jour +- [ ] User guide basique +- [ ] Developer guide (hot-reload workflow) + +### Livrables Phase 4 +- [ ] Game complet jouable de bout en bout +- [ ] UI fonctionnelle (console ou ImGui) +- [ ] Balance initiale validée +- [ ] Documentation complète + +**Durée estimée**: 4 semaines + +--- + +## Calendrier Global + +### Semaines 1-2: Fondations +- GameModule v2 +- ResourceModule +- StorageModule + +### Semaines 3-4: Train & Resources +- TrainBuilderModule +- ResourceModule v2 (10+ resources, craft) + +### Semaines 5-8: Combat & Events +- CombatModule (1 mission) +- EventModule (5 events) +- ExpeditionModule + +### Semaines 9-12: Integration & Polish +- GameModule state machine +- UI basique +- Balance pass +- Documentation + +**Total: 12 semaines (3 mois)** + +--- + +## Metrics de Succès + +### Quantitatifs +- [ ] 10+ ressources craftables +- [ ] 5+ événements scriptés +- [ ] 1 mission de combat complète +- [ ] 3 wagons configurables +- [ ] 30 minutes de gameplay complet +- [ ] Save/load fonctionnel +- [ ] 0 crashes (soft-locks OK si documentés) + +### Qualitatifs +- [ ] Loop de jeu engageant +- [ ] Décisions significatives (events, train builder) +- [ ] Feedback satisfaisant (combat, craft) +- [ ] Hot-reload < 1s (dev velocity) +- [ ] Code réutilisable pour WarFactory + +--- + +## Risques & Mitigation + +### Risque 1: Scope Creep +**Probabilité**: Haute +**Impact**: Critique +**Mitigation**: +- Features freeze après Phase 3 +- Prototype != MVP != Full Game +- Accepter placeholders + +### Risque 2: Combat Balance Difficile +**Probabilité**: Moyenne +**Impact**: Moyen +**Mitigation**: +- Formules simples (linear > complex) +- Paramètres exposés en JSON +- Cheat codes pour tests + +### Risque 3: Hot-Reload Bugs +**Probabilité**: Faible +**Impact**: Moyen +**Mitigation**: +- State serialization stricte +- Tests de reload fréquents +- Logs détaillés + +### Risque 4: GroveEngine Immaturité +**Probabilité**: Moyenne +**Impact**: Critique +**Mitigation**: +- Fallback: modules statiques +- GroveEngine = nice-to-have, pas bloquant +- Tests sans hot-reload aussi + +--- + +## Notes Techniques + +### Configuration Files +``` +config/ +├── game.json # GameModule settings +├── resources.json # ResourceModule data +├── train.json # TrainBuilderModule wagons +├── combat.json # CombatModule formulas +├── events.json # EventModule scripts +├── expeditions.json # ExpeditionModule destinations +└── storage.json # StorageModule paths +``` + +### Data Files +``` +data/ +├── saves/ # Save games +│ ├── autosave.json +│ └── quicksave.json +└── logs/ # Debug logs + └── game.log +``` + +### Module Communication Example +```cpp +// ResourceModule crafts drone +auto craftData = std::make_unique("craft"); +craftData->setString("result", "drone_recon"); +craftData->setInt("quantity", 1); +io->publish("resource:craft_complete", std::move(craftData)); + +// ExpeditionModule receives notification +void onCraftComplete(const IDataNode& data) { + string result = data.getString("result", ""); + if (result == "drone_recon") { + m_availableDrones["recon"]++; + } +} +``` + +--- + +## Conclusion + +**Prototype = Validation des mécaniques, pas un jeu fini.** + +Focus absolu sur: +1. ✅ Loop de jeu complet +2. ✅ Décisions significatives +3. ✅ Code réutilisable (WarFactory) +4. ✅ Hot-reload workflow + +**Success metric final**: 30 minutes de gameplay où le joueur prend 10+ décisions impactantes. + +--- + +*Plan créé le 1er décembre 2025* +*Prochaine review: Fin Phase 1 (Semaine 2)* diff --git a/plans/SHARED_MODULES_PLAN.md b/plans/SHARED_MODULES_PLAN.md new file mode 100644 index 0000000..55b8aec --- /dev/null +++ b/plans/SHARED_MODULES_PLAN.md @@ -0,0 +1,635 @@ +# Plan de Modules Partagés - Mobile Command & WarFactory + +**Objectif**: Créer une bibliothèque de modules GroveEngine réutilisables entre les deux projets. + +**Date**: 1er décembre 2025 +**Version**: grove-modules v0.1.0 + +--- + +## Vision + +### Problème +- Mobile Command et WarFactory partagent de nombreux systèmes (ressources, économie, combat) +- Dupliquer le code = 2x bugs, 2x maintenance, 2x développement +- GroveEngine permet modules hot-reloadable indépendants + +### Solution +Créer une **bibliothèque de modules core** partagée entre les projets, avec des **adaptateurs spécifiques** par jeu. + +--- + +## Architecture Proposée + +### Structure +``` +../grove-modules/ # Bibliothèque partagée +├── core/ # Modules 100% réutilisables +│ ├── ResourceModule/ +│ ├── StorageModule/ +│ ├── EconomyModule/ +│ └── EventModule/ +├── common/ # Modules 60-80% réutilisables +│ ├── CombatModule/ +│ ├── TransportModule/ +│ ├── TechTreeModule/ +│ └── MapModule/ +├── CMakeLists.txt +└── README.md + +../mobilecommand/ +├── src/modules/ +│ ├── mc_adapters/ # Adaptateurs MC-spécifiques +│ │ ├── MCResourceAdapter.cpp +│ │ └── MCCombatAdapter.cpp +│ ├── TrainBuilderModule/ # MC-only +│ ├── ExpeditionModule/ # MC-only +│ └── DroneModule/ # MC-only +└── external/ + ├── GroveEngine/ # Symlink + └── grove-modules/ # Symlink + +../warfactoryracine/ +├── modules/ +│ ├── wf_adapters/ # Adaptateurs WF-spécifiques +│ │ ├── WFResourceAdapter.cpp +│ │ └── WFCombatAdapter.cpp +│ ├── factory/ # WF-only +│ ├── vehicle_design/ # WF-only +│ └── doctrine/ # WF-only +└── external/ + └── grove-modules/ # Symlink +``` + +--- + +## Modules Core (grove-modules/core/) + +### ResourceModule +**Réutilisabilité: 90%** + +**Responsabilités communes**: +- Inventaire (add/remove/query) +- Stack management +- Quality grades (poor/normal/good/excellent) +- Craft system (inputs → outputs) +- Resource constraints + +**Interface commune**: +```cpp +class IResourceManager { + virtual bool addResource(string id, int quantity, Quality quality) = 0; + virtual bool removeResource(string id, int quantity) = 0; + virtual int getResourceCount(string id) = 0; + virtual bool canCraft(string recipe_id) = 0; + virtual void craft(string recipe_id) = 0; +}; +``` + +**Configuration commune**: +```json +{ + "resources": { + "resource_id": { + "name": "Display Name", + "maxStack": 100, + "weight": 1.5, + "baseValue": 10, + "category": "material" + } + }, + "recipes": { + "recipe_id": { + "inputs": {"resource_a": 2, "resource_b": 1}, + "outputs": {"resource_c": 1}, + "craftTime": 30.0 + } + } +} +``` + +**Adaptateurs spécifiques**: +- **MC**: Scavenge, munitions, fuel, timeline evolution (2022→2025) +- **WF**: Minerais, composants industriels, quality impact production + +**Fichiers**: +- `grove-modules/core/ResourceModule/ResourceModule.cpp` +- `grove-modules/core/ResourceModule/ResourceModule.h` +- `grove-modules/core/ResourceModule/IResourceManager.h` + +--- + +### StorageModule +**Réutilisabilité: 95%** + +**Responsabilités communes**: +- Save game complet (JSON) +- Load game complet +- Auto-save périodique +- Versioning +- State serialization + +**Interface commune**: +```cpp +class IStorageManager { + virtual bool saveGame(string filename) = 0; + virtual bool loadGame(string filename) = 0; + virtual void collectModuleStates(vector states) = 0; + virtual void restoreModuleStates(const IDataNode& saveData) = 0; +}; +``` + +**Format universel**: +```json +{ + "version": "1.0.0", + "game": "MobileCommand", // ou "WarFactory" + "timestamp": "2025-12-01T10:00:00Z", + "gameTime": 3600.0, + "modules": { + "ModuleName": { /* module state */ } + } +} +``` + +**Adaptateurs spécifiques**: +- **MC**: Expedition history, commander deaths +- **WF**: Factory blueprints, tech tree progress + +**Fichiers**: +- `grove-modules/core/StorageModule/StorageModule.cpp` +- `grove-modules/core/StorageModule/IStorageManager.h` + +--- + +### EconomyModule +**Réutilisabilité: 85%** + +**Responsabilités communes**: +- Prix dynamiques (offre/demande) +- Marchés/trading +- Inflation/deflation +- Transaction history + +**Interface commune**: +```cpp +class IEconomyManager { + virtual float getPrice(string resource_id) = 0; + virtual void updateMarket(string resource_id, int supply_delta) = 0; + virtual bool buy(string resource_id, int quantity, float& total_cost) = 0; + virtual bool sell(string resource_id, int quantity, float& total_revenue) = 0; +}; +``` + +**Modèle économique**: +```cpp +// Prix = base * (demand / supply)^elasticity +float price = basePrice * pow(demand / supply, elasticity); + +// Avec bounds +price = clamp(price, basePrice * 0.1, basePrice * 10.0); +``` + +**Adaptateurs spécifiques**: +- **MC**: Marché noir, dons, fame impact prices +- **WF**: Contracts PMC, military-industrial complex + +**Fichiers**: +- `grove-modules/core/EconomyModule/EconomyModule.cpp` +- `grove-modules/core/EconomyModule/IEconomyManager.h` + +--- + +### EventModule +**Réutilisabilité: 80%** + +**Responsabilités communes**: +- Event scripting (JSON) +- Condition evaluation +- Choice handling +- Outcome application + +**Interface commune**: +```cpp +class IEventManager { + virtual void checkTriggers() = 0; + virtual void triggerEvent(string event_id) = 0; + virtual void handleChoice(string event_id, string choice_id) = 0; + virtual bool evaluateConditions(const IDataNode& conditions) = 0; +}; +``` + +**Format événement universel**: +```json +{ + "event_id": "unique_id", + "title": "Event Title", + "description": "Event description text", + "conditions": { + "game_time_min": 600, + "resource_min": {"fuel": 50}, + "custom_flag": "value" + }, + "choices": [ + { + "id": "choice_1", + "text": "Choice text", + "requirements": {"reputation": 20}, + "outcomes": { + "resources": {"fuel": -10, "ammo": +50}, + "flags": {"quest_complete": true}, + "trigger_event": "next_event_id" + } + } + ] +} +``` + +**Adaptateurs spécifiques**: +- **MC**: Survival events, moral impact, commander death +- **WF**: Diplomatic events, faction relations + +**Fichiers**: +- `grove-modules/core/EventModule/EventModule.cpp` +- `grove-modules/core/EventModule/IEventManager.h` + +--- + +## Modules Common (grove-modules/common/) + +### CombatModule +**Réutilisabilité: 60%** + +**Responsabilités communes**: +- Damage calculations +- Armor/penetration +- Hit probability +- Unit health +- Combat resolution + +**Interface commune**: +```cpp +class ICombatResolver { + virtual CombatResult resolveCombat( + const CombatSetup& setup, + int maxRounds + ) = 0; + + virtual float calculateDamage( + float firepower, + float armor, + float penetration + ) = 0; + + virtual bool checkHit( + float accuracy, + float evasion, + float cover + ) = 0; +}; + +struct CombatResult { + bool victory; + vector casualties; + vector loot; + int roundsElapsed; +}; +``` + +**Formules partagées**: +```cpp +// Hit chance +float hit = base_accuracy * (1.0 - cover) * (1.0 - evasion); + +// Damage +float damage = max(0, firepower * penetration - armor); + +// Casualty check +if (unit_health <= 0) { + casualties.push_back(unit); +} +``` + +**Adaptateurs spécifiques**: +- **MC**: Pertes permanentes, moral, drones vs humans +- **WF**: Auto-battler, frontlines, doctrine modifiers + +**Fichiers**: +- `grove-modules/common/CombatModule/CombatModule.cpp` +- `grove-modules/common/CombatModule/ICombatResolver.h` + +--- + +### TransportModule +**Réutilisabilité: 70%** + +**Responsabilités communes**: +- Pathfinding (A*) +- Route optimization +- Travel time calculation +- Convoy management + +**Interface commune**: +```cpp +class ITransportManager { + virtual Path findPath(Point from, Point to) = 0; + virtual float calculateTravelTime(Path path, float speed) = 0; + virtual bool moveConvoy(string convoy_id, Point destination) = 0; +}; + +struct Path { + vector waypoints; + float totalDistance; + float estimatedTime; + int dangerLevel; +}; +``` + +**Adaptateurs spécifiques**: +- **MC**: Train movement, expedition routes +- **WF**: Supply chains, factory logistics + +**Fichiers**: +- `grove-modules/common/TransportModule/TransportModule.cpp` +- `grove-modules/common/TransportModule/ITransportManager.h` + +--- + +### TechTreeModule +**Réutilisabilité: 75%** + +**Responsabilités communes**: +- Tech progression +- Unlock system +- Dependencies +- Research time/cost + +**Interface commune**: +```cpp +class ITechTreeManager { + virtual bool canResearch(string tech_id) = 0; + virtual void startResearch(string tech_id) = 0; + virtual bool isUnlocked(string tech_id) = 0; + virtual vector getAvailableTechs() = 0; +}; +``` + +**Configuration universelle**: +```json +{ + "technologies": { + "tech_id": { + "name": "Technology Name", + "cost": {"research_points": 100, "credits": 1000}, + "time": 3600.0, + "prerequisites": ["tech_a", "tech_b"], + "unlocks": ["feature_x", "recipe_y"] + } + } +} +``` + +**Adaptateurs spécifiques**: +- **MC**: Timeline 2022→2025 (forced progression) +- **WF**: 3000+ techs, player choice + +**Fichiers**: +- `grove-modules/common/TechTreeModule/TechTreeModule.cpp` +- `grove-modules/common/TechTreeModule/ITechTreeManager.h` + +--- + +### MapModule +**Réutilisabilité: 50%** + +**Responsabilités communes**: +- Chunk system (64x64 tiles) +- Streaming/loading +- Multi-scale (world/regional/local) +- Tile properties + +**Interface commune**: +```cpp +class IMapManager { + virtual Chunk* getChunk(int x, int y) = 0; + virtual void loadChunk(int x, int y) = 0; + virtual void unloadChunk(int x, int y) = 0; + virtual Tile getTile(int x, int y) = 0; +}; + +struct Chunk { + int x, y; + Tile tiles[64][64]; + bool loaded; + bool modified; +}; +``` + +**Adaptateurs spécifiques**: +- **MC**: Ukraine map statique, expedition sites +- **WF**: Procedural generation, geological sim + +**Fichiers**: +- `grove-modules/common/MapModule/MapModule.cpp` +- `grove-modules/common/MapModule/IMapManager.h` + +--- + +## Roadmap de Développement + +### Phase 1: Mobile Command Prototype (Mois 1-3) +**Objectif**: Créer modules pour MC, les garder réutilisables + +1. **ResourceModule** - Développer pour MC avec interface claire +2. **StorageModule** - Format universel dès le départ +3. **EventModule** - Scripting JSON générique +4. **CombatModule** - Formulas paramétrées + +**Livrable**: MC prototype fonctionnel, code dans `src/modules/` + +### Phase 2: Extraction Core Library (Mois 4) +**Objectif**: Identifier et extraire le core stable + +1. **Audit code MC** - Identifier parties 100% réutilisables +2. **Créer grove-modules/** - Structure de base +3. **Extraire ResourceModule** - Première extraction +4. **Tester réintégration** - MC utilise grove-modules/ResourceModule + +**Livrable**: grove-modules/ avec 1 module stable + +### Phase 3: Stabilisation Core (Mois 5-6) +**Objectif**: Tous les core modules extraits et stables + +1. **Extraire StorageModule** - Save/load universel +2. **Extraire EconomyModule** - Marché dynamique +3. **Extraire EventModule** - Event system +4. **Versioning v1.0.0** - Premier release stable + +**Livrable**: grove-modules/core/ complet et versionné + +### Phase 4: Common Modules (Mois 7-9) +**Objectif**: Modules partagés avec adaptateurs + +1. **CombatModule** - Combat resolver + adaptateurs MC/WF +2. **TransportModule** - Pathfinding + logistics +3. **TechTreeModule** - Progression system +4. **MapModule** - Chunk system base + +**Livrable**: grove-modules/common/ complet + +### Phase 5: WarFactory Integration (Mois 10-12) +**Objectif**: WF utilise grove-modules + +1. **WF setup** - Symlink grove-modules/ +2. **Adaptateurs WF** - wf_adapters/ pour customisation +3. **Tests cross-projet** - Valider compatibilité +4. **CI/CD** - Tests automatiques MC + WF + +**Livrable**: Les deux projets partagent grove-modules/ + +--- + +## Conventions de Code + +### Namespaces +```cpp +namespace grove::modules::core { + class ResourceModule { }; +} + +namespace grove::modules::common { + class CombatModule { }; +} +``` + +### Versioning +```cpp +// ResourceModule v1.2.3 +#define RESOURCE_MODULE_VERSION_MAJOR 1 +#define RESOURCE_MODULE_VERSION_MINOR 2 +#define RESOURCE_MODULE_VERSION_PATCH 3 +``` + +### Configuration +```json +{ + "module_version": "1.2.3", + "game_specific": { + "mobile_command": { /* MC config */ }, + "war_factory": { /* WF config */ } + }, + "common": { /* Shared config */ } +} +``` + +### Topics Pub/Sub +```cpp +// Namespace par module +"resource:craft_complete" +"storage:save_complete" +"economy:price_changed" +"event:triggered" +"combat:ended" +``` + +--- + +## Tests Cross-Projet + +### Test Framework +```cpp +// grove-modules/tests/ResourceModuleTest.cpp +TEST_CASE("ResourceModule - MC Scenario") { + ResourceModule module; + // Test MC-specific behavior +} + +TEST_CASE("ResourceModule - WF Scenario") { + ResourceModule module; + // Test WF-specific behavior +} +``` + +### CI/CD Pipeline +```yaml +# .github/workflows/grove-modules.yml +jobs: + test-mobile-command: + runs-on: ubuntu-latest + steps: + - Checkout grove-modules + - Checkout mobilecommand + - Build & test MC with grove-modules + + test-war-factory: + runs-on: ubuntu-latest + steps: + - Checkout grove-modules + - Checkout warfactoryracine + - Build & test WF with grove-modules +``` + +--- + +## Maintenance + +### Semantic Versioning +- **Major**: Breaking changes (interface changes) +- **Minor**: New features (backward compatible) +- **Patch**: Bug fixes + +### Release Process +1. Tests passent (MC + WF) +2. Update CHANGELOG.md +3. Tag version (v1.2.3) +4. Update both projects + +### Bug Fixes +1. Fix in grove-modules/ +2. Test MC +3. Test WF +4. Release patch version + +--- + +## Metrics de Succès + +### Court Terme (6 mois) +- [ ] 4 core modules extraits +- [ ] MC utilise grove-modules/ +- [ ] 0 duplication code entre MC et grove-modules/ + +### Moyen Terme (12 mois) +- [ ] 8 modules total (core + common) +- [ ] WF utilise grove-modules/ +- [ ] CI/CD tests cross-projet +- [ ] Documentation API complète + +### Long Terme (18+ mois) +- [ ] grove-modules/ stable (v2.0+) +- [ ] 3rd party usage possible (open source?) +- [ ] Community contributions +- [ ] Grove ecosystem + +--- + +## Conclusion + +**Objectif**: Ne pas réinventer la roue deux fois. + +**Stratégie**: +1. Développer pour MC d'abord (focus prototype) +2. Identifier patterns réutilisables +3. Extraire core library progressivement +4. WF bénéficie du travail MC + +**Bénéfices**: +- ✅ Moins de code à maintenir +- ✅ Bugs fixés une seule fois +- ✅ Features profitent aux deux projets +- ✅ Validation GroveEngine en production + +--- + +*Plan créé le 1er décembre 2025* +*Prochaine review: Fin MC Prototype (Mois 3)*