warfactoryracine/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Warfactory is a Factorio-inspired industrial military simulation game combining factory management with strategic military doctrine. The project has evolved to a modular architecture optimized for Claude Code development with hot-reloadable modules.

Core Philosophy:

• Factory assembly lines as gameplay foundation
• Player-driven military doctrine development
• Progression from PMC operations to conventional warfare
• Choice and complexity balanced with accessible presentation

Documentation Architecture

The project uses a modular documentation system in /docs/:

Core Design Documents

• vue-ensemble.md - Vision, philosophy, and design principles
• architecture-modulaire.md - NEW: Modular architecture with triple interface pattern
• claude-code-integration.md - NEW: Claude Code development optimization
• architecture-technique.md - Multi-server architecture, performance specs
• systemes-techniques.md - Tile system, memory management, chunks
• map-system.md - Procedural generation with 218+ elements, budget system (-10 to +10)

Gameplay Systems

• gameplay-industriel.md - Resource flow, production, factory optimization
• systeme-militaire.md - Vehicle design with grid-based component placement
• economie-logistique.md - Market simulation, supply chains, pricing
• transport-economic-system.md - NEW: Transport hierarchy and economic optimization
• mecaniques-jeu.md - Research systems, breakthrough mechanics, administration

Advanced Systems

• arbre-technologique.md - 3000+ technology tree with prerequisites gating
• metriques-joueur.md - Comprehensive analytics (3.1GB per game, adaptive scaling)
• coherence-problem.md - Resolved design contradictions and technical challenges

Key Technical Concepts

Modular Architecture (NEW)

• Triple Interface Pattern: IEngine, IModuleSystem, IModule(process(), initialize(), shutdown()), IIO
• Autonomous Modules: Small (200-300 lines) hot-reloadable modules (.so files)
• Claude Code Optimized: Each module is a micro-context for AI development
• Performance Targets: V1 Client 30+ fps, V2 Client 60+ fps, V1 Server 10+ players, V2 Server 100+ players (Points 98-103)
• Implementation Status: Transitioning from 10 engines to modular system

Map System

• Multi-scale: World (diplomatic) → Regional (logistics) → Local (factory) → Detail (combat)
• Procedural Generation: 218 elements with budget scoring, millions of combinations
• Chunk System: 64x64 tiles, streaming on demand, persistent storage

Military Design

• Grid-based Vehicle Design: Irregular chassis shapes with component placement
• Interface: Pick/place with A/E rotation, R for snap toggle, template support
• Combat: Multi-chunk battles, persistent frontlines, auto-battler with player oversight

Development Context

Resolved Issues

Most initial "coherence problems" (P1-P30) were invalidated through clarification:

• Architecture scales properly with smart resource management
• Interface complexity is standard for genre (comparable to Factorio, Tarkov inventory)
• Performance targets achievable with proper optimization
• Only P7 (engine responsibilities) requires further analysis

Current Status

• Phase: Architecture Migration - Transitioning from 10 engines to modular architecture
• Build System: Module-based CMake with autonomous builds per module
• Development Ready: Hot-reload modules, 5-second iteration cycles
• Next Steps: Module implementations (TankModule, EconomyModule, FactoryModule)
• Questions Open: 11 items in questions-ouvertes.md for future resolution

Working with This Project

Documentation Updates

• Cross-reference systems when making changes (especially architecture ↔ gameplay)
• Maintain coherence between technical specs and game design
• Update coherence-problem.md if new conflicts emerge

Key Design Constraints

• Skip-ability: All systems must be automatable for accessibility
• Depth vs Accessibility: Complex systems with simple interfaces
• Performance: Real-time constraints with large-scale simulation
• Realism: Military authenticity balanced with gameplay fun

Module Constraints (CRITICAL)

• NEVER #include "../" ou cmake ..
• JSON only communication entre modules
• Build autonome : cd modules/X/ && cmake .
• Exception ProductionModule : Belt+Inserter+Factory MUST cohabiter (500-800 lignes acceptées)
• ISocket Overhead : >1ms INACCEPTABLE pour ProductionModule (Point 104)

Important Files for Context

• Start with architecture-modulaire.md for new modular architecture
• Read claude-code-integration.md for AI-optimized development
• Reference vue-ensemble.md for project vision
• Check coherence-problem.md for resolved design challenges
• Use questions-ouvertes.md for known open issues

Build System and Development

Build Commands

# CRITICAL: Module autonome uniquement (Point 87)
cd modules/tank/ && cmake .    # NEVER cmake ..
make tank-module               # Builds tank.so
./build/tank-module           # Test standalone

# Core system
cmake . && make warfactory-core # Build core engine

# All modules
make warfactory-modules         # Build all modules

Project Structure

├── modules/                    # Autonomous hot-reloadable modules
│   ├── tank/                   # Tank behavior module (200 lines)
│   ├── economy/                # Market simulation module
│   ├── factory/                # Production module
│   ├── transport/              # Transport optimization module
│   └── [each with CLAUDE.md, CMakeLists.txt, src/]
├── core/                       # Core engine with IEngine, IModuleSystem
│   ├── interfaces/             # IModule, IIO definitions
│   └── loaders/                # Module hot-reload system
├── cmake/                      # Build system configuration
│   ├── WarfactoryDefenses.cmake    # Defensive programming
│   ├── WarfactoryAutomation.cmake  # 16 C++ libraries
│   └── WarfactoryAdvancedTools.cmake # Static analysis, testing
├── build/                      # Build artifacts (git ignored)
│   └── bin/                    # Final executables
└── docs/                       # Complete design documentation

Development Workflow

1. Module isolation: Work in modules/*/ with autonomous builds
2. Hot-reload: Edit module → Save → Instant reload with state preservation
3. Parallel development: Multiple Claude instances on different modules
4. Config-driven: Most gameplay tweaks via JSON configs
5. 5-second iteration: Edit → cmake . → make → test
6. Testing: #ifdef TESTING validation autonome, standalone testing

Claude Code Development Practices (Points 351-390)

Context Management (CRITICAL)

• Small Modules: Compact modules for focused development (micro-contexts)
• Context Optimization: Massive context reduction through modular design
• Iteration Speed: 5-10 min → 5 sec (60-120x faster)
• Development Velocity: 10x improvement through module isolation

Parallel Development Patterns

• Multiple Instances: 3+ Claude Code instances simultaneous development
• Zero Conflicts: Independent module development without merge conflicts
• Git-Friendly: Isolated commits per module
• Non-Blocking: Developers work on different modules without coordination

Build Constraints (NEVER/ALWAYS Rules)

• NEVER cd ..: Jamais référence directories parent modules
• ALWAYS cmake .: Builds autonomes par module (NEVER cmake ..)
• NEVER #include "../": Isolation modules stricte
• ONLY JSON Communication: Communication entre modules via JSON uniquement
• ZERO Infrastructure Code: Aucun code infrastructure dans contexts modules

Testing Strategy (AI-Optimized)

• Simple Tests: Tests unitaires légers, pas infrastructure complexe
• Standalone Testing: Test modules sans engine complet
• #ifdef TESTING: Validation autonome intégrée modules
• Quick Feedback: Tests rapides pour iteration loops Claude Code

Dependencies and Libraries

The project includes 16 C++ libraries via FetchContent:

• Networking: zeromq, cppzmq, redis-plus-plus, cpprestsdk
• Logging: spdlog, fmt
• Memory: Microsoft GSL, foonathan/memory
• Testing: Catch2, Google Test, Google Benchmark
• Utilities: nlohmann/json, fifo_map, junction+turf, pcg-cpp
• Navigation: recastnavigation, abseil-cpp
• Graphics: imgui, sqlite

Defensive Programming Features

• Sanitizers: AddressSanitizer, UndefinedBehaviorSanitizer, LeakSanitizer
• Static Analysis: Clang Static Analyzer, Cppcheck, PVS-Studio integration
• Contract Programming: GSL contracts, custom assertion macros
• Compiler Hardening: Stack protection, frame pointers, maximum debug info
• Memory Safety: Smart pointers, RAII patterns, leak detection