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 uses a revolutionary 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

📋 Implementation Status

ALWAYS CHECK: TODO.md at project root for current implementation roadmap and tasks.

Current Phase: PRODUCTION-READY Hot-Reload System - 0.4ms average reload time achieved!

Documentation Architecture

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

📋 00-overview/

• README.md - Main developer guide and navigation
• vue-ensemble.md - Vision, philosophy, and design principles
• contexte-narratif.md - Background and universe
• dlc-prevus.md - Planned expansions

🏗️ 01-architecture/

• architecture-technique.md - CORE: Complete modular architecture
• claude-code-integration.md - ESSENTIAL: Claude Code development optimization
• behavior-composition-patterns.md - Modular AI behavior patterns
• player-integration.md - Client/server integration

⚙️ 02-systems/

• gameplay-industriel.md - Factory/production systems
• systeme-militaire.md - Vehicle design with grid-based component placement
• economie-logistique.md - Market simulation, supply chains, pricing
• map-system.md - Procedural generation with 218+ elements
• factory-architecture-post-player.md - Advanced production architecture

🔧 03-implementation/

• testing-strategy.md - AI-optimized testing approach
• systemes-techniques.md - Low-level technical specifications
• configuration/ - Complete configuration system

📚 04-reference/

• INTEGRATION-MASTER-LIST.md - CRITICAL: 570+ technical specifications catalog
• arbre-technologique.md - 3000+ technology tree
• metriques-joueur.md - Comprehensive analytics (3.1GB per game)
• coherence-problem.md - Resolved design contradictions
• questions-ouvertes.md - Open technical questions
• updates-long-terme.md - Future evolution roadmap

Key Technical Concepts

Core Interface Architecture (COMPLETED - PHASE 1)

• Quadruple Interface Pattern: IEngine, IModuleSystem, IModule, IIO + ITaskScheduler
• CRITICAL: Core interfaces are IMMUTABLE - Never modify once finalized
• 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

Interface Specifications (NEVER MODIFY THESE)

• IEngine: Engine orchestration, module loading, client/coordinator socket management
• IModuleSystem: Execution strategy + task scheduling (inherits ITaskScheduler)
• IModule: Pure business logic + pub/sub communication + task delegation
• IIO: Pull-based pub/sub with low-frequency batching and health monitoring
• ITaskScheduler: Task delegation interface for module → execution system

Module Frequencies & Isolation

• ProductionModule: 60Hz (frame-perfect factory operations)
• TankModule: 0.1-60Hz (Targeting 60Hz → Movement 30Hz → Tactical 1Hz → Analytics 0.1Hz)
• EconomyModule: 0.01-0.1Hz (economic cycles)
• War Isolation: ZERO interaction ProductionModule ↔ WarModule
• Supply Chain: Factory → LogisticModule → War (unidirectional flow)

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

Current Status

• Phase: INTERFACES COMPLETE - All core interfaces finalized and production-ready
• Core Architecture: 4 interfaces completed with full specifications
• Development Ready: Hot-reload modules, pub/sub messaging, task delegation
• Integration: Interface design phase complete (Phase 1 TODO finished)
• Next Steps: Phase 2 - Initial implementations (DebugEngine, SequentialModuleSystem, IntraIO)

Resolved Issues

Most coherence problems resolved through systematic analysis in 04-reference/coherence-problem.md:

• Architecture scales properly with smart resource management
• Interface complexity is standard for genre (comparable to Factorio, Tarkov inventory)
• Performance targets achievable with proper optimization
• Legacy engine system completely replaced by modular architecture

Working with This Project

Essential Reading Order

1. First Time: 00-overview/vue-ensemble.md - Project vision
2. Architecture: 01-architecture/architecture-technique.md - Core technical architecture
3. Development: 01-architecture/claude-code-integration.md - AI development workflow
4. Reference: 04-reference/INTEGRATION-MASTER-LIST.md - Complete specifications

Documentation Updates

• Cross-reference systems when making changes (especially architecture ↔ gameplay)
• Maintain coherence between technical specs and game design
• Update 04-reference/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/ALWAYS Rules

• INTERFACE STABILITY: NEVER modify core interfaces - only implement them
• NEVER cd ..: Jamais référence directories parent modules
• ALWAYS cmake .: Builds autonomes par module (NEVER cmake ..)
• NEVER #include "../": Isolation modules stricte
• PUB/SUB Communication: Communication via IIO publish/subscribe only
• TASK DELEGATION: Use ITaskScheduler for module → execution system tasks
• ZERO Infrastructure Code: Aucun code infrastructure dans contexts modules

Special Cases

• Exception ProductionModule: Belt+Inserter+Factory MUST cohabiter (500-800 lignes acceptées)
• ISocket Overhead: >1ms INACCEPTABLE pour ProductionModule
• Module Frequencies: Each module operates at different frequencies (see architecture-technique.md)
• War Isolation: NO inserters towards turrets - supply via LogisticModule only

Build System and Development

Build Commands

# CRITICAL: Module autonome uniquement
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 implementations
│   ├── include/warfactory/     # IMMUTABLE core interfaces (IEngine, IModuleSystem, IModule, IIO)
│   ├── implementations/        # Engine and ModuleSystem implementations
│   └── 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/                       # Hierarchical documentation system
    ├── 00-overview/            # Vision & context
    ├── 01-architecture/        # Architecture modulaire
    ├── 02-systems/            # Game systems
    ├── 03-implementation/     # Testing & configuration
    └── 04-reference/          # Technical reference

Development Workflow ⚡ HOT-RELOAD REVOLUTIONIZED

1. Module isolation: Work in modules/*/ with autonomous builds
2. 🔥 BLAZING Hot-reload: 0.4ms average - 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. ⚡ SUB-SECOND iteration: Edit → cmake . → make → hot-reload < 1 second total
6. State Preservation: Module state (chunks, configs, metrics) persists across reloads
7. Testing: Lightweight focused tests, 5000x faster than target performance

Claude Code Development Practices

Interface Management (ABSOLUTELY CRITICAL)

• IMMUTABLE INTERFACES: Core interfaces (IEngine, IModuleSystem, IModule, IIO, ITaskScheduler) are FROZEN
• NEVER MODIFY: Once interfaces are finalized, they become the architectural foundation
• Extension Only: New functionality via new implementations, not interface changes
• Breaking Changes: Modifying core interfaces breaks ALL existing modules and systems
• Documentation: Interface changes require complete system redesign - avoid at all costs

Context Management (REVOLUTIONARY RESULTS)

• Small Modules: Compact modules for focused development (micro-contexts)
• Context Optimization: Massive context reduction through modular design
• 🚀 BLAZING Iteration Speed: 5-10 min → 0.4ms (750,000x faster!)
• Development Velocity: Theoretical maximum achieved - sub-millisecond hot-reload

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

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

Quick Reference

For Understanding the Project

1. 00-overview/vue-ensemble.md - Project vision
2. 01-architecture/architecture-technique.md - Core architecture
3. 02-systems/gameplay-industriel.md - Core gameplay

For Development

1. CLAUDE-HOT-RELOAD-GUIDE.md - ESSENTIAL: Blazing 0.4ms hot-reload system guide
2. 01-architecture/claude-code-integration.md - AI development workflow
3. 03-implementation/testing-strategy.md - Testing approach
4. 04-reference/INTEGRATION-MASTER-LIST.md - Complete specifications

For Technical Reference

1. 04-reference/arbre-technologique.md - Complete tech tree
2. 04-reference/coherence-problem.md - Technical analyses
3. DocToDispatch.md - Exhaustive reference document

---

Status: CORE INTERFACES COMPLETE - Phase 1 finished. Ready for Phase 2 implementations with immutable interface foundation established.