project-mobile-command/plans/PROTOTYPE_PLAN.md

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:

// 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:

{
  "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:

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:

// 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:

{
  "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

• 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:

// 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:

{
  "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:

// 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:

{
  "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:

{
  "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:

// 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:

{
  "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é):

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:

// 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:

{
  "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:

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:

// 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:

{
  "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

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

// 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)