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: Core Implementation & Module System (post-documentation completion)

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

Modular Architecture (PRODUCTION-READY)

• 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
• 570+ Specifications: Complete technical catalog in INTEGRATION-MASTER-LIST.md

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: PRODUCTION-READY - Modular architecture fully specified
• Build System: Module-based CMake with autonomous builds per module
• Development Ready: Hot-reload modules, 5-second iteration cycles
• Integration: 85% complete (487/570 specifications integrated)
• Next Steps: Module implementations (TankModule, EconomyModule, FactoryModule)

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

• 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

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

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

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

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. 01-architecture/claude-code-integration.md - AI development workflow
2. 03-implementation/testing-strategy.md - Testing approach
3. 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: PRODUCTION-READY modular architecture with 570+ technical specifications integrated and hierarchical documentation system.