Add comprehensive implementation roadmap and update project guidance
- Create TODO.md with complete 11-phase implementation roadmap - Add Configuration System as prerequisite for all modules - Add Coordination System for inter-module communication - Add Logging & Monitoring for development debugging - Structure phases from core interfaces to advanced features - Update CLAUDE.md to reference TODO.md for current tasks Phase progression: 1. Core Interfaces → 2. Config/Coordination/Logging → 3. Infrastructure 4. Module System → 5. WorldGen → 6. Map+Client+ImGUI 7. MacroEntity → 8. Economy(barebone) → 9. Player 10. LocalMap+Client → 11. Advanced Config Foundation: Config → Coordination → Logging → Modules Implementation ready with clear development path 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
parent
57f1c5ad3e
commit
221a837dc8
@ -12,6 +12,12 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
|
|||||||
- Progression from PMC operations to conventional warfare
|
- Progression from PMC operations to conventional warfare
|
||||||
- Choice and complexity balanced with accessible presentation
|
- 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
|
## Documentation Architecture
|
||||||
|
|
||||||
The project uses a **hierarchical documentation system** in `/docs/`:
|
The project uses a **hierarchical documentation system** in `/docs/`:
|
||||||
|
|||||||
337
TODO.md
Normal file
337
TODO.md
Normal file
@ -0,0 +1,337 @@
|
|||||||
|
# Warfactory - Implementation Roadmap
|
||||||
|
|
||||||
|
## Current Status
|
||||||
|
✅ **Documentation Phase Complete** (51,335 words, 9.5/10 quality)
|
||||||
|
🚀 **Next Phase**: Core Implementation & Module System
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Phase 1: Core Interfaces 🏗️
|
||||||
|
|
||||||
|
### Interface Definitions
|
||||||
|
- [ ] **IEngine.h** - Engine orchestration interface
|
||||||
|
- `initialize()`, `update(deltaTime)`, `shutdown()`
|
||||||
|
- `setModuleSystem(std::unique_ptr<IModuleSystem>)`
|
||||||
|
|
||||||
|
- [ ] **IModuleSystem.h** - Module execution strategy interface
|
||||||
|
- `registerModule(name, std::unique_ptr<IModule>)`
|
||||||
|
- `processModules(deltaTime)`, `setIOLayer(std::unique_ptr<IIO>)`
|
||||||
|
- `queryModule(name, json input) -> json`
|
||||||
|
|
||||||
|
- [ ] **IModule.h** - Pure business logic interface
|
||||||
|
- `json process(const json& input)` // PURE FUNCTION
|
||||||
|
- `initialize(const json& config)`, `shutdown()`
|
||||||
|
- `getState()`, `setState(const json& state)` // Hot-reload support
|
||||||
|
|
||||||
|
- [ ] **IIO.h** - Communication transport interface
|
||||||
|
- `json send(target, message)`, `json receive(source)`
|
||||||
|
- `broadcast(const json& message)`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Phase 2: Initial Implementations ⚙️
|
||||||
|
|
||||||
|
### Core Engine Components
|
||||||
|
- [ ] **DebugEngine** - Development/testing engine
|
||||||
|
- Step-by-step execution, verbose logging
|
||||||
|
- Module isolation for debugging
|
||||||
|
|
||||||
|
- [ ] **SequentialModuleSystem** - Simple execution strategy
|
||||||
|
- Process modules one at a time (debug/test mode)
|
||||||
|
- Perfect for initial development
|
||||||
|
|
||||||
|
- [ ] **IntraIO** - Direct communication layer
|
||||||
|
- Same-process direct function calls
|
||||||
|
- Zero network overhead for local development
|
||||||
|
|
||||||
|
### Configuration System Setup (PREREQUISITE)
|
||||||
|
- [ ] **Basic configuration framework** - BEFORE FIRST MODULE
|
||||||
|
- JSON-based configuration loading
|
||||||
|
- Module-specific config files in `config/` directory
|
||||||
|
- Configuration validation and error handling
|
||||||
|
- Essential for module parameterization
|
||||||
|
|
||||||
|
### Coordination System (CRITICAL FOUNDATION)
|
||||||
|
- [ ] **Module coordination framework** - AFTER CONFIG, BEFORE MODULES
|
||||||
|
- Inter-module communication orchestration
|
||||||
|
- Message routing and delivery system
|
||||||
|
- Module dependency management and ordering
|
||||||
|
- Event system for module coordination
|
||||||
|
|
||||||
|
- [ ] **JSON coordination interface**
|
||||||
|
- Input: `{"type": "coordinate", "source": "ModuleA", "target": "ModuleB", "message": {...}}`
|
||||||
|
- Output: `{"status": "delivered", "response": {...}, "timing": "5ms"}`
|
||||||
|
|
||||||
|
- [ ] **Coordination services**
|
||||||
|
- Module discovery and registration
|
||||||
|
- Health monitoring and failure detection
|
||||||
|
- Load balancing for module requests
|
||||||
|
- Debugging and logging coordination activities
|
||||||
|
|
||||||
|
### Logging & Monitoring System (DEVELOPMENT ESSENTIAL)
|
||||||
|
- [ ] **Basic logging infrastructure** - WITH COORDINATION SYSTEM
|
||||||
|
- Module-specific log channels
|
||||||
|
- Configurable log levels (DEBUG, INFO, WARN, ERROR)
|
||||||
|
- JSON-structured logging for parsing
|
||||||
|
- Log file rotation and management
|
||||||
|
|
||||||
|
- [ ] **Performance monitoring**
|
||||||
|
- Module execution time tracking
|
||||||
|
- JSON message processing metrics
|
||||||
|
- Memory usage per module (basic)
|
||||||
|
- Hot-reload performance measurement
|
||||||
|
|
||||||
|
- [ ] **Development debugging**
|
||||||
|
- Real-time log streaming to ImGUI
|
||||||
|
- Module communication visualization
|
||||||
|
- Performance dashboard integration
|
||||||
|
- Error alerting and notification
|
||||||
|
|
||||||
|
### First Module Implementation
|
||||||
|
- [ ] **DebugWorldGenModule.cpp** - FIRST MODULE (200-300 lines max)
|
||||||
|
- Critical: No world exists without this module
|
||||||
|
- Uses configuration system for world parameters
|
||||||
|
- Minimal world generation for development/testing
|
||||||
|
- JSON input/output validation
|
||||||
|
- State preservation testing
|
||||||
|
- Hot-reload capability verification
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Phase 3: Fixes & Infrastructure Setup 🛠️
|
||||||
|
|
||||||
|
### Legacy System Repairs
|
||||||
|
- [ ] **Fix defense mode** - Adapt from engines → modules
|
||||||
|
- Update apply_defenses_to_all_engines.sh
|
||||||
|
- Migrate defense configurations to modular system
|
||||||
|
- Verify sanitizer compatibility with new architecture
|
||||||
|
|
||||||
|
### Project Structure Setup
|
||||||
|
- [ ] **Setup modules/ directory structure**
|
||||||
|
```
|
||||||
|
modules/
|
||||||
|
├── test/ # TestModule for validation
|
||||||
|
├── tank/ # TankModule (future)
|
||||||
|
├── economy/ # EconomyModule (future)
|
||||||
|
├── factory/ # FactoryModule (future)
|
||||||
|
└── shared/ # Common interfaces
|
||||||
|
```
|
||||||
|
|
||||||
|
- [ ] **CMake per-module autonomous builds**
|
||||||
|
- `cd modules/X/ && cmake .` builds independently
|
||||||
|
- No parent directory dependencies
|
||||||
|
- Module-specific CMakeLists.txt files
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Phase 4: Module System Implementation 🚀
|
||||||
|
|
||||||
|
### Hot-Reload System
|
||||||
|
- [ ] **Module loader** - Dynamic library loading (.so files)
|
||||||
|
- File change detection
|
||||||
|
- Safe unload/reload with state preservation
|
||||||
|
- Error handling and rollback
|
||||||
|
|
||||||
|
- [ ] **State preservation system**
|
||||||
|
- Implement getState()/setState() pattern
|
||||||
|
- JSON state serialization
|
||||||
|
- Seamless hot-reload without game interruption
|
||||||
|
|
||||||
|
### Communication & Validation
|
||||||
|
- [ ] **JSON communication pipeline**
|
||||||
|
- Message format standardization
|
||||||
|
- Input/output validation
|
||||||
|
- Error handling and logging
|
||||||
|
|
||||||
|
- [ ] **Module integration testing**
|
||||||
|
- End-to-end communication tests
|
||||||
|
- Performance validation (target <5s iteration cycle)
|
||||||
|
- Hot-reload stress testing
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Phase 5: World Generation System 🌍
|
||||||
|
|
||||||
|
### DebugWorldGenModule (IMPLEMENTED IN PHASE 2)
|
||||||
|
- [ ] **Already implemented as FIRST MODULE** - See Phase 2 above
|
||||||
|
- [ ] **Enhanced features** (if needed after Phase 2 implementation)
|
||||||
|
- Performance optimization
|
||||||
|
- Extended terrain types
|
||||||
|
- Resource balancing tweaks
|
||||||
|
|
||||||
|
### Working World Generation
|
||||||
|
- [ ] **Procedural terrain generation** (based on docs/02-systems/map-system.md)
|
||||||
|
- 218+ terrain elements implementation
|
||||||
|
- Budget system (-10 to +10) for biome balance
|
||||||
|
- Realistic geographical features
|
||||||
|
|
||||||
|
- [ ] **Advanced resource placement**
|
||||||
|
- Geological realism for deposits
|
||||||
|
- Economic balance considerations
|
||||||
|
- Strategic resource distribution
|
||||||
|
|
||||||
|
- [ ] **Infrastructure generation**
|
||||||
|
- Road networks and transport routes
|
||||||
|
- Initial settlements and facilities
|
||||||
|
- Regional specialization setup
|
||||||
|
|
||||||
|
## Phase 6: Map System & Basic Client 🗺️
|
||||||
|
|
||||||
|
### MapModule Implementation (ESSENTIAL SECOND MODULE)
|
||||||
|
- [ ] **Map management system** (200-300 lines max)
|
||||||
|
- Terrain data management and chunk loading
|
||||||
|
- Coordinate system and spatial queries
|
||||||
|
- Resource location tracking
|
||||||
|
- Map state persistence and hot-reload
|
||||||
|
|
||||||
|
- [ ] **JSON interface for map operations**
|
||||||
|
- Input: `{"type": "get_chunk", "coords": [x, y]}`
|
||||||
|
- Output: `{"chunk_data": [...], "resources": [...], "terrain": [...]}`
|
||||||
|
|
||||||
|
### Basic Client Implementation
|
||||||
|
- [ ] **Minimal rendering client**
|
||||||
|
- Display generated world from WorldGenModule
|
||||||
|
- Show terrain and resource data from MapModule
|
||||||
|
- Basic camera movement and zoom
|
||||||
|
- Connection to module system via JSON
|
||||||
|
|
||||||
|
- [ ] **ImGUI integration**
|
||||||
|
- ImGUI interface for development tools
|
||||||
|
- Module status display and controls
|
||||||
|
- Hot-reload visualization interface
|
||||||
|
- Debug information panels
|
||||||
|
- Performance metrics dashboard
|
||||||
|
|
||||||
|
## Phase 7: Core Gameplay Modules 🎯
|
||||||
|
|
||||||
|
### MacroEntityModule Implementation (THIRD MODULE)
|
||||||
|
- [ ] **Macro entity management** (200-300 lines max)
|
||||||
|
- High-level entity tracking and coordination
|
||||||
|
- Company/state/faction entity management
|
||||||
|
- Macro-scale interactions and behaviors
|
||||||
|
- Entity lifecycle and evolution
|
||||||
|
|
||||||
|
- [ ] **JSON interface for macro entities**
|
||||||
|
- Input: `{"type": "create_entity", "entity_type": "company", "config": {...}}`
|
||||||
|
- Output: `{"entity_id": "comp_001", "status": "created", "properties": {...}}`
|
||||||
|
|
||||||
|
- [ ] **Integration with map system**
|
||||||
|
- Entity positioning and territorial control
|
||||||
|
- Resource access and territorial claims
|
||||||
|
- Influence zones and interaction ranges
|
||||||
|
|
||||||
|
## Phase 8: Economic Systems 💰
|
||||||
|
|
||||||
|
### EconomyModule Implementation (FOURTH MODULE - BAREBONE)
|
||||||
|
- [ ] **Basic market system** (200-300 lines max)
|
||||||
|
- Simple supply/demand tracking
|
||||||
|
- Basic price calculation (no complex dynamics initially)
|
||||||
|
- Essential resource trading only
|
||||||
|
- Foundation for future expansion
|
||||||
|
|
||||||
|
- [ ] **JSON interface for basic operations**
|
||||||
|
- Input: `{"type": "trade", "item": "steel", "quantity": 100, "action": "buy"}`
|
||||||
|
- Output: `{"status": "executed", "price": 5.0, "total": 500.0}`
|
||||||
|
|
||||||
|
- [ ] **Minimal integration**
|
||||||
|
- Basic resource flow between entities
|
||||||
|
- Simple trading mechanics
|
||||||
|
- Foundation for complex features (Points 272-296 for later phases)
|
||||||
|
|
||||||
|
## Phase 9: Player Systems 🎮
|
||||||
|
|
||||||
|
### PlayerModule Implementation (FIFTH MODULE)
|
||||||
|
- [ ] **Player entity management** (200-300 lines max)
|
||||||
|
- Player state tracking and persistence
|
||||||
|
- Player actions and command processing
|
||||||
|
- Inventory and resource management
|
||||||
|
- Player-world interaction systems
|
||||||
|
|
||||||
|
- [ ] **JSON interface for player operations**
|
||||||
|
- Input: `{"type": "player_action", "action": "move", "target": [x, y]}`
|
||||||
|
- Output: `{"status": "success", "new_position": [x, y], "resources_gathered": {...}}`
|
||||||
|
|
||||||
|
- [ ] **Integration with existing modules**
|
||||||
|
- Player interaction with map system
|
||||||
|
- Player participation in economy
|
||||||
|
- Player entity registration with MacroEntityModule
|
||||||
|
|
||||||
|
## Phase 10: Local Map & Client Enhancement 🗺️🖥️
|
||||||
|
|
||||||
|
### LocalMap Loading System
|
||||||
|
- [ ] **Local map management** (200-300 lines max)
|
||||||
|
- Detailed local area loading around player
|
||||||
|
- Higher resolution terrain and object data
|
||||||
|
- Local resource and entity tracking
|
||||||
|
- Smooth transitions between local and global map
|
||||||
|
|
||||||
|
- [ ] **JSON interface for local map operations**
|
||||||
|
- Input: `{"type": "load_local_area", "center": [x, y], "radius": 50}`
|
||||||
|
- Output: `{"local_data": {...}, "entities": [...], "detailed_terrain": [...]}`
|
||||||
|
|
||||||
|
### Enhanced Client Features
|
||||||
|
- [ ] **Local map rendering**
|
||||||
|
- Detailed local area visualization
|
||||||
|
- Zoom levels and level-of-detail management
|
||||||
|
- Local entity rendering and animation
|
||||||
|
- Smooth camera transitions
|
||||||
|
|
||||||
|
- [ ] **Advanced ImGUI interfaces**
|
||||||
|
- Local map debug tools
|
||||||
|
- Entity inspection panels
|
||||||
|
- Local area performance metrics
|
||||||
|
- Map loading/unloading controls
|
||||||
|
|
||||||
|
- [ ] **Client-Map integration**
|
||||||
|
- Efficient local data streaming
|
||||||
|
- Background loading of adjacent areas
|
||||||
|
- Memory management for map data
|
||||||
|
- Performance optimization for rendering
|
||||||
|
|
||||||
|
## Phase 11: Advanced Configuration ⚙️
|
||||||
|
|
||||||
|
### Enhanced Configuration Features (POST-BASIC MODULES)
|
||||||
|
- [ ] **Advanced configuration management**
|
||||||
|
- Hot-reload configuration changes during runtime
|
||||||
|
- Configuration versioning and migration
|
||||||
|
- Environment-specific configurations (dev/prod)
|
||||||
|
- Configuration inheritance and overrides
|
||||||
|
|
||||||
|
- [ ] **Configuration tooling**
|
||||||
|
- Configuration validation tools
|
||||||
|
- Configuration documentation generation
|
||||||
|
- Configuration diff and merge utilities
|
||||||
|
- Configuration backup and restore
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Development Guidelines
|
||||||
|
|
||||||
|
### Module Constraints (CRITICAL)
|
||||||
|
- **NEVER** `#include "../"` or `cmake ..`
|
||||||
|
- **JSON only** communication between modules
|
||||||
|
- **Build autonome**: `cd modules/X/ && cmake .`
|
||||||
|
- **200-300 lines max** per module (except ProductionModule: 500-800 lines)
|
||||||
|
- **Hot-reload ready**: Always implement getState()/setState()
|
||||||
|
|
||||||
|
### Performance Targets
|
||||||
|
- **V1 Client**: 30+ fps
|
||||||
|
- **V2 Client**: 60+ fps
|
||||||
|
- **V1 Server**: 10+ players
|
||||||
|
- **V2 Server**: 100+ players
|
||||||
|
- **Iteration cycle**: <5 seconds (edit → reload → test)
|
||||||
|
|
||||||
|
### Testing Strategy
|
||||||
|
- **#ifdef TESTING** validation in modules
|
||||||
|
- **Standalone testing**: Test modules without full engine
|
||||||
|
- **AI-optimized**: Simple tests for Claude Code development
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Notes
|
||||||
|
- **Architecture Status**: Transitioning from 10 engines to modular system
|
||||||
|
- **Documentation**: See `docs/01-architecture/architecture-modulaire.md` for complete specification
|
||||||
|
- **Claude Code Optimization**: Each module = micro-context for AI development
|
||||||
|
- **Exception**: ProductionModule (Belt+Inserter+Factory) requires 500-800 lines for performance
|
||||||
|
- **World Generation**: Critical for testing - no initial world exists without DebugWorldGenModule
|
||||||
|
- **World Gen Reference**: Complete procedural generation system documented in `docs/02-systems/map-system.md`
|
||||||
Loading…
Reference in New Issue
Block a user