StillHammer
bbc811c151
- Restructure docs/ into hierarchical organization (00-overview → 04-reference) - Eliminate duplicate global/ directory (-16 files) - Integrate toCheck/ content into main structure - Update CLAUDE.md with new documentation architecture - Remove legacy engine references - Consolidate 53 → 32 documentation files (-40% reduction) - Add proper navigation README.md with clear entry points New structure: 📁 00-overview/ - Vision & context 📁 01-architecture/ - Technical architecture 📁 02-systems/ - Game systems 📁 03-implementation/ - Testing & configuration 📁 04-reference/ - Technical reference 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
232 lines
11 KiB
Markdown
232 lines
11 KiB
Markdown
# 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
|
|
|
|
## 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
|
|
```bash
|
|
# 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. |