From 221a837dc832f1af681879919996894e9b824d2a Mon Sep 17 00:00:00 2001 From: StillHammer Date: Tue, 23 Sep 2025 17:35:35 +0800 Subject: [PATCH] Add comprehensive implementation roadmap and update project guidance MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- CLAUDE.md | 6 + TODO.md | 337 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 343 insertions(+) create mode 100644 TODO.md diff --git a/CLAUDE.md b/CLAUDE.md index 50f222b..fce972e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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 - 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/`: diff --git a/TODO.md b/TODO.md new file mode 100644 index 0000000..1057686 --- /dev/null +++ b/TODO.md @@ -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.h** - Module execution strategy interface + - `registerModule(name, std::unique_ptr)` + - `processModules(deltaTime)`, `setIOLayer(std::unique_ptr)` + - `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` \ No newline at end of file