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

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

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)

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 !

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

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

modules/client/
├─ input/                    # InputModule : Clavier/souris → JSON
├─ render/                   # RenderModule : Server state → Display
└─ network/                  # NetworkModule : WebSocket client

2. Server Modules (Extension Actuelle)

modules/server/
├─ tank/                     # TankModule : Combat logic (EXISTING)
├─ economy/                  # EconomyModule : Market logic (EXISTING)
├─ network/                  # NetworkModule : WebSocket server
└─ persistence/              # PersistenceModule : Save/load state

3. Shared Infrastructure

modules/shared/
├─ protocol/                 # ProtocolModule : Client/server messages
├─ serialization/            # SerializationModule : JSON optimization
└─ compression/              # CompressionModule : Network optimization

Développement V2 : Shared Logic

1. Logic Extraction

modules/shared/logic/
├─ tank-logic/               # SharedTankLogic.so
├─ combat-logic/             # SharedCombatLogic.so
└─ physics-logic/            # SharedPhysicsLogic.so

2. Client Prediction

modules/client/prediction/
├─ tank-prediction/          # ClientTankModule with prediction
├─ sync/                     # SyncModule : Reconciliation
└─ interpolation/            # InterpolationModule : Smooth corrections

3. Server Authority

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

🎮 Claude Code Development Workflow

V1 Development : Parallel Instances

# 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

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

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