warfactoryracine/docs/01-architecture/player-integration.md

# Intégration du Joueur dans l'Architecture Modulaire

## 🎯 Problème Identifié

**Architecture modulaire parfaite... mais où est le joueur ?**

L'architecture triple interface actuelle gère brillamment la logique métier et la performance, mais il manque un élément crucial : **l'interaction humaine**.

### Gaps Actuels
- ❌ **Pas d'inputs** clavier/souris
- ❌ **Pas de réactivité UI** temps réel
- ❌ **Client/Server separation** manquante
- ❌ **Multiplayer architecture** non définie

## 📋 Solution : Client/Server Modulaire

### Architecture Duale Proposée

```
ClientEngine (Local, Réactif)    ←→    ServerEngine (Distribué, Autoritaire)
├─ InputModule                          ├─ TankModule
├─ UIModule                            ├─ CombatModule
├─ RenderModule                        ├─ EconomyModule
└─ NetworkModule                       └─ NetworkModule
```

### Principe : Même Architecture, Contexte Différent

**Client Modules** : Focus UX, réactivité, prédiction
**Server Modules** : Focus logique, autorité, performance

**Code Sharing** : Logique métier identique, contexte d'exécution différent

## 🚀 Plan de Développement : 2 Phases Progressives

### **Phase 1 : V1 - Thin Client (Validation Rapide)**

#### Objectifs V1
- ✅ **Validation architecture** : Prouver que l'approche modulaire fonctionne
- ✅ **Focus core logic** : TankModule, CombatModule opérationnels
- ✅ **Gameplay jouable** : Latence acceptable pour validation concept
- ✅ **Claude Code friendly** : Développement parallèle client/server

#### Architecture V1 : Simple & Efficace

```
ClientEngine (Thin)
├─ InputModule     → Capture inputs → JSON messages
├─ NetworkModule   → WebSocket client → Send to server
└─ RenderModule    → Display server state → Simple rendering

ServerEngine (All Logic)
├─ TankModule      → Authoritative tank logic
├─ CombatModule    → Game mechanics & physics
├─ EconomyModule   → Market simulation
└─ NetworkModule   → WebSocket server → Broadcast state
```

#### Flow V1 : Server-Authoritative

```
Player Input → ClientEngine → Network → ServerEngine → Game Logic → Network → ClientEngine → Display
     50ms           5ms         30ms        20ms         30ms        5ms         10ms
Total : ~150ms latency (acceptable pour validation)
```

#### Développement V1 : Claude Code Parallel

```bash
# Instance Claude A : Client Input
cd modules/client/input/
cmake . && make input-module     # → input.so

# Instance Claude B : Server Logic
cd modules/server/tank/
cmake . && make tank-module      # → tank.so

# Instance Claude C : Network
cd modules/shared/network/
cmake . && make network-module   # → network.so
```

#### Modules V1 Implementation

##### InputModule (Client)
```cpp
class InputModule : public ModuleBase {
    json process(const json& input) override {
        // Keyboard/mouse events → Structured commands
        if(input["type"] == "keydown") {
            if(input["key"] == "w") return {{"command", "move"}, {"direction", "north"}};
            if(input["key"] == "space") return {{"command", "attack"}};
        }
        return {{"command", "idle"}};
    }
};
```

##### NetworkModule (Client)
```cpp
class ClientNetworkModule : public ModuleBase {
    json process(const json& input) override {
        // Send commands to server via WebSocket
        if(input["command"] != "idle") {
            webSocketClient.send(input.dump());
        }

        // Receive server state updates
        if(webSocketClient.hasMessage()) {
            return json::parse(webSocketClient.receive());
        }

        return {{"status", "connected"}};
    }
};
```

##### TankModule (Server) - **Même logique qu'avant !**
```cpp
class TankModule : public ModuleBase {
    json process(const json& input) override {
        // IDENTICAL logic to single-player version
        if(input["command"] == "move") return handleMovement(input);
        if(input["command"] == "attack") return handleCombat(input);
        return getCurrentState();
    }
};
```

### **Phase 2 : V2 - Client Prediction (Polish UX)**

#### Objectifs V2
- ✅ **Réactivité client** : Illusion 0ms lag via prédiction
- ✅ **Code sharing** : Logique métier partagée client/server
- ✅ **Smooth gameplay** : Corrections invisibles, UX fluide
- ✅ **Competitive ready** : Performance multijoueur AAA

#### Architecture V2 : Shared Logic + Prediction

```
SharedGameLogic.so (Code Commun)
├─ TankLogic.cpp
├─ CombatLogic.cpp
└─ PhysicsLogic.cpp

ClientEngine (Predictive)                ServerEngine (Authoritative)
├─ ClientTankModule (Shared + prediction) ├─ ServerTankModule (Shared + validation)
├─ SyncModule (reconciliation)            ├─ ValidationModule (anti-cheat)
└─ PredictionModule (client-side)         └─ PersistenceModule (save/load)
```

#### Flow V2 : Client Prediction + Server Authority

```
Player Input → Immediate Client Prediction + Network to Server → Server Validation → Client Reconciliation
     0ms              5ms                      30ms                20ms              5ms
User Experience : 0ms (predicted), Corrections invisibles
```

#### Migration V1 → V2 : Zero-Risk Evolution

```cpp
// 1. Extract Shared Logic (TankModule → SharedTankLogic.so)
class SharedTankLogic {
    static json CalculateMovement(const json& tank, const json& input) {
        // SINGLE SOURCE OF TRUTH for both client & server
        return processMovement(tank, input);
    }
};

// 2. Client Prediction (ClientTankModule)
class ClientTankModule : public ModuleBase {
    json process(const json& input) override {
        // Immediate prediction using shared logic
        auto predicted = SharedTankLogic::CalculateMovement(currentState, input);

        // Send to server for validation
        networkModule.send(input);

        return predicted;  // Display immediately
    }
};

// 3. Server Validation (ServerTankModule)
class ServerTankModule : public ModuleBase {
    json process(const json& input) override {
        // Authoritative calculation using SAME shared logic
        auto authoritative = SharedTankLogic::CalculateMovement(serverState, input);

        // Anti-cheat validation
        if(validateInput(input)) {
            return authoritative;
        }

        return {{"error", "invalid_input"}};
    }
};
```

## 🛠️ Implementation Strategy

### Développement V1 : Thin Client

#### 1. Client Modules
```bash
modules/client/
├─ input/                    # InputModule : Clavier/souris → JSON
├─ render/                   # RenderModule : Server state → Display
└─ network/                  # NetworkModule : WebSocket client
```

#### 2. Server Modules (Extension Actuelle)
```bash
modules/server/
├─ tank/                     # TankModule : Combat logic (EXISTING)
├─ economy/                  # EconomyModule : Market logic (EXISTING)
├─ network/                  # NetworkModule : WebSocket server
└─ persistence/              # PersistenceModule : Save/load state
```

#### 3. Shared Infrastructure
```bash
modules/shared/
├─ protocol/                 # ProtocolModule : Client/server messages
├─ serialization/            # SerializationModule : JSON optimization
└─ compression/              # CompressionModule : Network optimization
```

### Développement V2 : Shared Logic

#### 1. Logic Extraction
```bash
modules/shared/logic/
├─ tank-logic/               # SharedTankLogic.so
├─ combat-logic/             # SharedCombatLogic.so
└─ physics-logic/            # SharedPhysicsLogic.so
```

#### 2. Client Prediction
```bash
modules/client/prediction/
├─ tank-prediction/          # ClientTankModule with prediction
├─ sync/                     # SyncModule : Reconciliation
└─ interpolation/            # InterpolationModule : Smooth corrections
```

#### 3. Server Authority
```bash
modules/server/authority/
├─ validation/               # ValidationModule : Anti-cheat
├─ simulation/               # SimulationModule : Server-side physics
└─ persistence/              # PersistenceModule : World state
```

## 🎮 Claude Code Development Workflow

### V1 Development : Parallel Instances

```bash
# Claude Instance A : Client Input
cd modules/client/input/
# Context : 200 lignes input handling
# Focus : Keyboard/mouse → JSON commands
# Build : cmake . && make input-module

# Claude Instance B : Server Tank Logic
cd modules/server/tank/
# Context : 250 lignes tank logic (EXISTING)
# Focus : Command processing, game state
# Build : cmake . && make tank-module

# Claude Instance C : Network Protocol
cd modules/shared/protocol/
# Context : 180 lignes network messages
# Focus : JSON serialization, WebSocket
# Build : cmake . && make protocol-module
```

### V2 Development : Shared Logic Focus

```bash
# Claude Instance A : Shared Tank Logic
cd modules/shared/logic/tank/
# Context : 200 lignes pure tank logic
# Focus : Movement, combat calculations
# Used by : BOTH client prediction AND server authority

# Claude Instance B : Client Prediction
cd modules/client/prediction/tank/
# Context : 150 lignes prediction + SharedTankLogic
# Focus : Immediate response, reconciliation
# Build : Links SharedTankLogic.so

# Claude Instance C : Server Authority
cd modules/server/authority/tank/
# Context : 180 lignes validation + SharedTankLogic
# Focus : Anti-cheat, persistence
# Build : Links SharedTankLogic.so
```

## 📊 Success Metrics & Validation

### V1 Success Criteria
- [ ] **Player Control** : Tank respond to WASD + mouse
- [ ] **Multiplayer** : 2+ players see synchronized world
- [ ] **Hot-Reload** : Server modules reload without client disconnect
- [ ] **Latency** : <150ms acceptable for core gameplay validation
- [ ] **Claude Code** : 3+ parallel development instances

### V2 Success Criteria
- [ ] **Instant Response** : Input feels 0ms via client prediction
- [ ] **Smooth Corrections** : No jittering during server reconciliation
- [ ] **Logic Sync** : Client/server calculations stay identical
- [ ] **Hot-Reload** : Both engines support module hot-reload
- [ ] **Performance** : 60fps client, server handles 100+ concurrent players

### Performance Targets

#### V1 Targets (Validation)
- **Client FPS** : 30+ fps stable
- **Server Capacity** : 10+ concurrent players
- **Network** : 150ms acceptable latency
- **Development** : Claude Code 200-line contexts

#### V2 Targets (Production)
- **Client FPS** : 60+ fps with prediction
- **Server Capacity** : 100+ concurrent players
- **Network** : 30ms server latency, 0ms perceived client latency
- **Development** : Shared logic reduces duplication by 80%

## 🎯 Development Priority & Timeline

### Immediate : Start V1 (80% effort)
1. **Week 1-2** : InputModule + NetworkModule basique
2. **Week 3-4** : Server TankModule integration + basic rendering
3. **Week 5-6** : Multi-player testing + hot-reload validation
4. **Week 7-8** : Polish V1 + documentation

### Future : V2 When V1 Stable (20% effort)
1. **Extract** : Shared logic from working V1 modules
2. **Implement** : Client prediction with shared logic
3. **Test** : Prediction accuracy vs server authority
4. **Deploy** : Seamless V1 → V2 migration

### Development Philosophy
- **V1 first** : Prove architecture works end-to-end
- **Claude Code optimized** : 200-line contexts maintained
- **Hot-reload everywhere** : Both client and server modules
- **Progressive enhancement** : V1 → V2 without code rewrite

## 🔄 Integration avec Architecture Existante

### Extension Naturelle
L'architecture modulaire actuelle **s'étend parfaitement** pour supporter client/server :

```cpp
// EXISTING : Single-player modules
TankModule.so → Pure tank logic

// V1 EXTENSION : Server-side modules
ServerTankModule.so → Same logic + network authority

// V2 EVOLUTION : Client + Server + Shared
SharedTankLogic.so → Pure logic (used by both)
ClientTankModule.so → SharedLogic + prediction
ServerTankModule.so → SharedLogic + validation
```

### Code Reuse Maximized
- **0% rewrite** : TankModule.cpp devient ServerTankModule.cpp
- **Logic preserved** : Même algorithmes, contexte d'exécution différent
- **Claude Code contexts** : Toujours 200-300 lignes par module
- **Hot-reload maintained** : Architecture triple interface intacte

## 🎮 User Experience Vision

### V1 Experience : Functional
- **Responsive** : 150ms latency acceptable pour validation
- **Multiplayer** : Joueurs voient le même monde
- **Development** : Hot-reload permet iteration rapide

### V2 Experience : Polished
- **Instant** : Inputs feel immediate via prediction
- **Smooth** : Corrections invisibles à l'utilisateur
- **Competitive** : Prêt pour gameplay multijoueur sérieux

**Résultat** : Architecture modulaire + Player integration = **Jeu AAA développé avec Claude Code** à vitesse révolutionnaire ! 🚀

---

## Conclusion

L'intégration du joueur dans l'architecture modulaire suit la même philosophie :

**"Complexity through Simplicity"** : Chaque module (client ou server) reste simple (200 lignes), mais l'ensemble crée une expérience multijoueur complexe et performante.

**Claude Code** continue à travailler sur des contextes micro-simples, mais produit maintenant un **jeu multijoueur complet** !