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 from design/documentation phase to functional implementation with a complete 10-engine architecture and comprehensive build system.

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-technique.md - Multi-server architecture, engines, 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
• 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

Engine Architecture

• Autonomous Engines: 10 specialized engines (Designer, Economy, Event, Factory, Intelligence, Logistic, MacroEntity, Map, Operation, War)
• Smart Client: Request/response pattern, no streaming, FOW at chunk granularity
• Performance Target: 60fps with 1000+ AI companies, 1-2 vehicle designs/tick globally
• Implementation Status: All engines have functional stub implementations with threading and main loops

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: Implementation active - All 10 engines functional with CMake build system
• Build System: Comprehensive CMake with defensive programming, sanitizers, and 16 C++ libraries
• Development Ready: Fast/full build presets, optimized workflow for daily iteration
• Next Steps: Engine logic expansion, inter-engine communication, gameplay features
• 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

Important Files for Context

• Start with vue-ensemble.md for project vision
• Reference architecture-technique.md for technical decisions
• Check coherence-problem.md for resolved design challenges
• Use questions-ouvertes.md for known open issues

Build System and Development

Build Commands

# Fast development build (minimal sanitizers, ~30s)
cmake -DFAST_BUILD=ON .. && make claude-workflow-fast

# Full validation build (all sanitizers + static analysis)
cmake -DCMAKE_BUILD_TYPE=Debug .. && make

# Release build (optimized, stack protection)
cmake .. && make

# Single engine development
make economy-engine && ./bin/economy-engine

Project Structure

├── engines/                    # 10 autonomous engines
│   ├── Designer-Engine/        # Vehicle design with AI assistance
│   ├── Economy-Engine/         # Market simulation, pricing
│   ├── Event-Engine/           # Breakthrough system, global events
│   ├── Factory-Engine/         # Factorio-like production
│   ├── Intelligence-Engine/    # Metrics collection, reconnaissance
│   ├── Logistic-Engine/        # Supply chains, transport
│   ├── MacroEntity-Engine/     # Companies, diplomacy, administration
│   ├── Map-Engine/             # Procedural generation, chunks, FOW
│   ├── Operation-Engine/       # Military strategy, AI generals
│   └── War-Engine/             # Combat simulation, frontlines
├── 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. Fast iteration: Use FAST_BUILD=ON for daily development
2. Single engine: make economy-engine for focused work
3. Full validation: Debug build with all sanitizers before commit
4. Engine-specific development: Work directly in engines/*/ directories
5. Incremental builds: CMake rebuilds only modified files (~2-5s)

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