project-mobile-command/plans/SHARED_MODULES_PLAN.md

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:

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:

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

class IStorageManager {
    virtual bool saveGame(string filename) = 0;
    virtual bool loadGame(string filename) = 0;
    virtual void collectModuleStates(vector<IDataNode*> states) = 0;
    virtual void restoreModuleStates(const IDataNode& saveData) = 0;
};

Format universel:

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

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:

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

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:

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

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<Casualty> casualties;
    vector<Resource> loot;
    int roundsElapsed;
};

Formules partagées:

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

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

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<string> getAvailableTechs() = 0;
};

Configuration universelle:

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

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

namespace grove::modules::core {
    class ResourceModule { };
}

namespace grove::modules::common {
    class CombatModule { };
}

Versioning

// ResourceModule v1.2.3
#define RESOURCE_MODULE_VERSION_MAJOR 1
#define RESOURCE_MODULE_VERSION_MINOR 2
#define RESOURCE_MODULE_VERSION_PATCH 3

Configuration

{
  "module_version": "1.2.3",
  "game_specific": {
    "mobile_command": { /* MC config */ },
    "war_factory": { /* WF config */ }
  },
  "common": { /* Shared config */ }
}

Topics Pub/Sub

// Namespace par module
"resource:craft_complete"
"storage:save_complete"
"economy:price_changed"
"event:triggered"
"combat:ended"

---

Tests Cross-Projet

Test Framework

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

# .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)