project-mobile-command/CLAUDE.md

# Claude - Mobile Command Development

## Rôle
Je suis l'assistant de développement pour le projet Mobile Command.

## Contexte du Projet

**Mobile Command** est un jeu de gestion/survie où le joueur commande un train blindé mobile à travers l'Ukraine en guerre (2022-2025).

### Stack Technique
- **Engine**: GroveEngine (C++17 hot-reload module system)
- **Build**: CMake 3.20+ avec MinGW/GCC
- **Architecture**: Modules game-agnostic + adapters game-specific

### Architecture Game-Agnostic

**PRINCIPE CLÉ** : Les systèmes core sont réutilisables entre Mobile Command et WarFactory.

```
┌──────────────────────────────────────┐
│  GameModule (MC-specific)            │  ← Pilote et orchestration
│  - State machine du jeu              │
│  - Flow spécifique MC                │
└────────────┬─────────────────────────┘
             │ pub/sub via IIO
┌────────────▼─────────────────────────┐
│  Core Modules (Game-Agnostic)        │  ← Réutilisables MC/WF
│  - ResourceModule                     │
│  - StorageModule                      │
│  - CombatModule                       │
│  - EventModule                        │
│  → Aucune logique MC/WF hardcodée    │
└──────────────────────────────────────┘
```

### Structure du Projet
```
mobilecommand/
├── external/GroveEngine/        # Lien symbolique vers ../groveengine
├── src/
│   ├── main.cpp                 # Boucle principale
│   └── modules/
│       ├── core/                # Game-agnostic (réutilisables)
│       │   ├── ResourceModule.*
│       │   ├── StorageModule.*
│       │   ├── CombatModule.*
│       │   └── EventModule.*
│       ├── mc_specific/         # Mobile Command only
│       │   ├── TrainBuilderModule.*
│       │   ├── ExpeditionModule.*
│       │   └── DroneModule.*
│       └── GameModule.*         # Orchestrateur MC-specific
├── config/
│   ├── game.json                # Config MC
│   ├── resources.json           # Ressources MC
│   └── ...
└── build/                       # Dossier de build
```

## Workflow de Développement

### Build Initial
```bash
cmake -B build -G "MinGW Makefiles"
cmake --build build -j4
```

### Hot-Reload Workflow
1. Le jeu tourne: `./build/mobilecommand.exe`
2. Éditer un module: `src/modules/GameModule.cpp`
3. Rebuild: `cmake --build build --target modules`
4. Le module se recharge automatiquement avec préservation d'état

### Commandes Utiles
```bash
# Build complet
cmake --build build -j4

# Build modules seulement (rapide)
cmake --build build --target modules

# Run
cd build && ./mobilecommand.exe
```

## Principes GroveEngine

### Modules
- Héritent de `grove::IModule`
- Implémentent: `process()`, `getState()`, `setState()`, `shutdown()`
- Chargés dynamiquement (.dll/.so)
- Hot-reload < 1ms avec état préservé

### Communication Pub/Sub (IIO)
**CRITIQUE pour architecture game-agnostic** : Les modules ne se connaissent pas directement.

```cpp
// Core module publie (game-agnostic)
io->publish("resource:craft_complete", craftData);

// GameModule MC subscribe (MC-specific)
io->subscribe("resource:craft_complete", [this](const IDataNode& data) {
    string recipe = data.getString("recipe");
    if (recipe == "drone_recon") {
        // Logique MC : ajouter drone aux expéditions
        io->publish("expedition:drone_available", droneData);
    }
});

// Future: GameModule WF subscribe (WF-specific)
io->subscribe("resource:craft_complete", [this](const IDataNode& data) {
    // Logique WF : ajouter à factory output
    io->publish("factory:production_complete", productData);
});
```

**Topics Convention** : `module:event`
- `resource:craft_complete`, `resource:inventory_low`
- `combat:started`, `combat:ended`
- `event:triggered`, `event:choice_made`
- `storage:save_complete`

### Configuration
- Fichiers JSON dans `config/`
- Chargés via `grove::JsonDataNode`
- Hot-reload de config supporté
- **Config spécifique par jeu** : `config/resources.json` différent pour MC/WF

## Roadmap

### Phase 1 - Setup (COMPLÉTÉ)
- [x] Structure projet
- [x] GroveEngine intégré
- [x] Build system
- [x] Hot-reload validé

### Phase 2 - Prototype Gameplay (EN COURS)
- [ ] Train basique (3 wagons)
- [ ] Système de craft simple
- [ ] 1 mission de combat
- [ ] 3-5 événements
- [ ] Boucle de jeu complète

### Phase 3 - MVP
- [ ] Train complet
- [ ] Système d'expéditions
- [ ] Campagne Act 1

## Conventions de Code

### Modules Core (Game-Agnostic)
**RÈGLES STRICTES** :
- ❌ JAMAIS de référence à "Mobile Command", "WarFactory", "train", "factory"
- ❌ JAMAIS de hardcoded game logic
- ✅ Interface pure avec pub/sub
- ✅ Configuration JSON pour tout comportement spécifique
- ✅ Commentaires expliquant l'usage MC ET WF

**Exemple** :
```cpp
// ResourceModule.h - GAME-AGNOSTIC
class ResourceModule : public grove::IModule {
public:
    // Interface pure
    bool addResource(string id, int quantity);
    bool canCraft(string recipeId);
    void startCraft(string recipeId);

    // Pub/sub pour logique game-specific
    void process(float dt) override;

private:
    // Data pure - pas de logique game
    map<string, int> m_inventory;
    // PAS DE: TrainCargo, FactoryOutput, etc.
};
```

### Modules MC-Specific
- Nom: `XyzModule` (PascalCase)
- Fichiers: `mc_specific/XyzModule.cpp` + `.h`
- Peut référencer concepts MC (train, expedition, drones)
- Exports: `createModule()` et `destroyModule()`

### Logging
```cpp
#include <spdlog/spdlog.h>
spdlog::info("[ModuleName] Message");
spdlog::debug("[ModuleName] Debug info");
spdlog::error("[ModuleName] Error message");
```

### Configuration
```cpp
auto config = loadConfig("config/module.json");
int value = config->getInt("key", defaultValue);
```

## Objectifs du Projet

### Primaire
Créer un jeu de gestion/survie autour d'un train blindé mobile

### Secondaire
1. Valider GroveEngine en conditions réelles de production
2. **Créer une bibliothèque de modules réutilisables** pour WarFactory

### Tertiaire
Extraire modules core vers `grove-modules/` library partagée (Phase 2)

## Notes Importantes

- **Phase prototype** : Focus validation mécaniques
- **Architecture game-agnostic dès le début** : Modules core réutilisables
- **Hot-reload essentiel** : Development velocity
- **Simplicité > Complexité** : Valider concepts avant d'optimiser
- **Pub/sub strict** : Modules ne se couplent jamais directement

## Checklist Modules Core

Avant de commiter un module core, vérifier :
- [ ] Aucune référence MC/WF dans le code
- [ ] Interface pure (pas de logique hardcodée)
- [ ] Configuration JSON pour comportements spécifiques
- [ ] Topics pub/sub documentés
- [ ] Exemples d'usage MC ET WF en commentaires
- [ ] Tests basiques fonctionnent

## Ressources

- **Plans détaillés**: `plans/PROTOTYPE_PLAN.md` et `plans/SHARED_MODULES_PLAN.md`
- **Architecture modules**: `docs/MODULES_ARCHITECTURE.md`
- **Concept complet**: `../couple-repo/Projects/CONCEPT/mobile_command_v2.md`
- **GroveEngine docs**: `external/GroveEngine/README.md`