# 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<IDataNode> getState() override {
    auto state = std::make_unique<JsonDataNode>("state");
    // Serialize inventory
    auto inventory = std::make_unique<JsonDataNode>("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<JsonDataNode>("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)*